class ObjectSpace::WeakKeyMap

ObjectSpace::WeakKeyMap 是一个键值映射，它对其键持有弱引用，因此当不再有引用时，它们可以被垃圾回收。

与 ObjectSpace::WeakMap 不同的是：

值的引用是强引用，因此当它们在映射中时不会被垃圾回收；
键按值比较（使用 Object#eql?），而不是按标识比较；

只有可以被垃圾回收的对象才能用作键。

map = ObjectSpace::WeakKeyMap.new
val = Time.new(2023, 12, 7)
key = "name"
map[key] = val

# Value is fetched by equality: the instance of string "name" is
# different here, but it is equal to the key
map["name"] #=> 2023-12-07 00:00:00 +0200

val = nil
GC.start
# There are no more references to `val`, yet the pair isn't
# garbage-collected.
map["name"] #=> 2023-12-07 00:00:00 +0200

key = nil
GC.start
# There are no more references to `key`, key and value are
# garbage-collected.
map["name"] #=> nil

（请注意，此处使用 GC.start 仅用于演示目的，可能并不总是能得到演示的结果。）

该集合特别适用于实现轻量级值对象的缓存，这样每个值的表示形式在内存中只会存储一份，而不再使用的副本将被垃圾回收。

CACHE = ObjectSpace::WeakKeyMap

def make_value(**)
   val = ValueObject.new(**)
   if (existing = @cache.getkey(val))
      # if the object with this value exists, we return it
      existing
   else
      # otherwise, put it in the cache
      @cache[val] = true
      val
   end
end

这将导致 make_value 始终为同一组属性返回相同的对象，但不再需要的值不会永远保留在缓存中。

公共实例方法

map[key] → value

源代码

static VALUE
wkmap_aref(VALUE self, VALUE key)
{
    VALUE obj = wkmap_lookup(self, key);
    return !UNDEF_P(obj) ? obj : Qnil;
}

如果找到，则返回与给定 key 关联的值。

如果未找到 key，则返回 nil。

map[key] = value → value

源代码

static VALUE
wkmap_aset(VALUE self, VALUE key, VALUE val)
{
    struct weakkeymap *w;
    TypedData_Get_Struct(self, struct weakkeymap, &weakkeymap_type, w);

    if (!FL_ABLE(key) || SYMBOL_P(key) || RB_BIGNUM_TYPE_P(key) || RB_TYPE_P(key, T_FLOAT)) {
        rb_raise(rb_eArgError, "WeakKeyMap must be garbage collectable");
        UNREACHABLE_RETURN(Qnil);
    }

    struct wkmap_aset_args args = {
        .new_key = key,
        .new_val = val,
    };

    st_update(w->table, (st_data_t)&key, wkmap_aset_replace, (st_data_t)&args);

    RB_OBJ_WRITTEN(self, Qundef, key);
    RB_OBJ_WRITTEN(self, Qundef, val);

    return val;
}

将给定的 value 与给定的 key 关联。

对 key 的引用是弱引用，因此当没有其他对 key 的引用时，它可能会被垃圾回收。

如果给定的 key 存在，则将其值替换为给定的 value；顺序不受影响。

clear → self

源代码

static VALUE
wkmap_clear(VALUE self)
{
    struct weakkeymap *w;
    TypedData_Get_Struct(self, struct weakkeymap, &weakkeymap_type, w);

    st_foreach(w->table, wkmap_clear_i, (st_data_t)self);
    st_clear(w->table);

    return self;
}

删除所有映射条目；返回 self。

delete(key) → value or nil

delete(key) {|key| ... } → object

源代码

static VALUE
wkmap_delete(VALUE self, VALUE key)
{
    struct weakkeymap *w;
    TypedData_Get_Struct(self, struct weakkeymap, &weakkeymap_type, w);

    VALUE orig_key = key;
    st_data_t orig_key_data = (st_data_t)&orig_key;
    st_data_t orig_val_data;
    if (st_delete(w->table, &orig_key_data, &orig_val_data)) {
        VALUE orig_val = (VALUE)orig_val_data;

        rb_gc_remove_weak(self, (VALUE *)orig_key_data);

        ruby_sized_xfree((VALUE *)orig_key_data, sizeof(VALUE));

        return orig_val;
    }

    if (rb_block_given_p()) {
        return rb_yield(key);
    }
    else {
        return Qnil;
    }
}

删除给定 key 的条目并返回其关联的值。

如果没有给出块且找到了 key，则删除该条目并返回关联的值。

m = ObjectSpace::WeakKeyMap.new
key = "foo" # to hold reference to the key
m[key] = 1
m.delete("foo") # => 1
m["foo"] # => nil

如果没有给出块且未找到 key，则返回 nil。

如果给出了块且找到了 key，则忽略该块，删除该条目，并返回关联的值。

m = ObjectSpace::WeakKeyMap.new
key = "foo" # to hold reference to the key
m[key] = 2
m.delete("foo") { |key| raise 'Will never happen'} # => 2

如果给出了块且未找到 key，则将 key 传递给该块，并返回该块的返回值。

m = ObjectSpace::WeakKeyMap.new
m.delete("nosuch") { |key| "Key #{key} not found" } # => "Key nosuch not found"

getkey(key) → existing_key or nil

源代码

static VALUE
wkmap_getkey(VALUE self, VALUE key)
{
    struct weakkeymap *w;
    TypedData_Get_Struct(self, struct weakkeymap, &weakkeymap_type, w);

    st_data_t orig_key;
    if (!st_get_key(w->table, (st_data_t)&key, &orig_key)) return Qnil;

    return *(VALUE *)orig_key;
}

如果存在，则返回现有的相等键，否则返回 nil。

这对于实现缓存可能很有用，这样程序中只会使用某个对象的单个副本。

value = {amount: 1, currency: 'USD'}

# Now if we put this object in a cache:
cache = ObjectSpace::WeakKeyMap.new
cache[value] = true

# ...we can always extract from there and use the same object:
copy = cache.getkey({amount: 1, currency: 'USD'})
copy.object_id == value.object_id #=> true

inspect → new_string

源代码

static VALUE
wkmap_inspect(VALUE self)
{
    struct weakkeymap *w;
    TypedData_Get_Struct(self, struct weakkeymap, &weakkeymap_type, w);

    st_index_t n = st_table_size(w->table);

#if SIZEOF_ST_INDEX_T <= SIZEOF_LONG
    const char * format = "#<%"PRIsVALUE":%p size=%lu>";
#else
    const char * format = "#<%"PRIsVALUE":%p size=%llu>";
#endif

    VALUE str = rb_sprintf(format, rb_class_name(CLASS_OF(self)), (void *)self, n);
    return str;
}

返回一个新的 String，其中包含有关映射的信息。

m = ObjectSpace::WeakKeyMap.new
m[key] = value
m.inspect # => "#<ObjectSpace::WeakKeyMap:0x00000001028dcba8 size=1>"

key?(key) → true or false

源代码

static VALUE
wkmap_has_key(VALUE self, VALUE key)
{
    return RBOOL(!UNDEF_P(wkmap_lookup(self, key)));
}

如果 key 是 self 中的键，则返回 true，否则返回 false。