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 总是为相同属性集返回相同的对象，但不再需要的那些值不会永远保留在缓存中。
Public Instance Methods
Source
static VALUE
wkmap_aref(VALUE self, VALUE key)
{
VALUE obj = wkmap_lookup(self, key);
return !UNDEF_P(obj) ? obj : Qnil;
}
如果找到，则返回与给定 key 关联的值。
如果找不到 key，则返回 nil。
Source
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 keys 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 替换其值；顺序不受影响。
Source
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。
Source
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"
Source
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
Source
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>"
Source
static VALUE
wkmap_has_key(VALUE self, VALUE key)
{
return RBOOL(!UNDEF_P(wkmap_lookup(self, key)));
}
如果 key 在 self 中，则返回 true，否则返回 false。