class ObjectSpace::WeakMap - Documentation for Ruby 3.2

# class ObjectSpace::WeakMap

An `ObjectSpace::WeakMap` object holds references to any objects, but those objects can get garbage collected.

This class is mostly used internally by `WeakRef`, please use `lib/weakref.rb` for the public interface.

### Public Instance Methods

[](p1) click to toggle source

Retrieves a weakly referenced object with the given key

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

[]=(p1, p2) click to toggle source

Creates a weak reference from the given key to the given value

    static VALUE
    wmap_aset(VALUE self, VALUE key, VALUE value)
    {
        struct weakmap *w;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        if (FL_ABLE(value)) {
            define_final0(value, w->final);
        }
        if (FL_ABLE(key)) {
            define_final0(key, w->final);
        }

        struct wmap_aset_replace_args aset_args = {
            .new_value = value,
            .old_value = Qundef,
        };
        st_update(w->wmap2obj, (st_data_t)key, wmap_aset_replace_value, (st_data_t)&aset_args);

        // If the value is unchanged, we have nothing to do.
        if (value != aset_args.old_value) {
            if (!UNDEF_P(aset_args.old_value) && FL_ABLE(aset_args.old_value)) {
                // That key existed and had an inverse reference, we need to clear the outdated inverse reference.
                st_update(w->obj2wmap, (st_data_t)aset_args.old_value, wmap_remove_inverse_ref, key);
            }

            if (FL_ABLE(value)) {
                // If the value has no finalizer, we don't need to keep the inverse reference
                st_update(w->obj2wmap, (st_data_t)value, wmap_aset_update, key);
            }
        }

        return nonspecial_obj_id(value);
    }

each() click to toggle source

Iterates over keys and objects in a weakly referenced object

    static VALUE
    wmap_each(VALUE self)
    {
        struct weakmap *w;
        rb_objspace_t *objspace = &rb_objspace;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        st_foreach(w->wmap2obj, wmap_each_i, (st_data_t)objspace);
        return self;
    }

Also aliased as: each_pair
each_key() click to toggle source

Iterates over keys and objects in a weakly referenced object

    static VALUE
    wmap_each_key(VALUE self)
    {
        struct weakmap *w;
        rb_objspace_t *objspace = &rb_objspace;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        st_foreach(w->wmap2obj, wmap_each_key_i, (st_data_t)objspace);
        return self;
    }

each_pair()

Iterates over keys and objects in a weakly referenced object

Alias for: each
each_value() click to toggle source

Iterates over keys and objects in a weakly referenced object

    static VALUE
    wmap_each_value(VALUE self)
    {
        struct weakmap *w;
        rb_objspace_t *objspace = &rb_objspace;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        st_foreach(w->wmap2obj, wmap_each_value_i, (st_data_t)objspace);
        return self;
    }

include?(p1) click to toggle source

Returns `true` if `key` is registered

    static VALUE
    wmap_has_key(VALUE self, VALUE key)
    {
        return RBOOL(!UNDEF_P(wmap_lookup(self, key)));
    }

Also aliased as: member?, key?
inspect() click to toggle source

    static VALUE
    wmap_inspect(VALUE self)
    {
        VALUE str;
        VALUE c = rb_class_name(CLASS_OF(self));
        struct weakmap *w;
        struct wmap_iter_arg args;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        str = rb_sprintf("-<%"PRIsVALUE":%p", c, (void *)self);
        if (w->wmap2obj) {
            args.objspace = &rb_objspace;
            args.value = str;
            st_foreach(w->wmap2obj, wmap_inspect_i, (st_data_t)&args);
        }
        RSTRING_PTR(str)[0] = '#';
        rb_str_cat2(str, ">");
        return str;
    }

key?(p1)

Returns `true` if `key` is registered

Alias for: include?
keys() click to toggle source

Iterates over keys and objects in a weakly referenced object

    static VALUE
    wmap_keys(VALUE self)
    {
        struct weakmap *w;
        struct wmap_iter_arg args;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        args.objspace = &rb_objspace;
        args.value = rb_ary_new();
        st_foreach(w->wmap2obj, wmap_keys_i, (st_data_t)&args);
        return args.value;
    }

length()

Returns the number of referenced objects

Alias for: size
member?(p1)

Returns `true` if `key` is registered

Alias for: include?
size() click to toggle source

Returns the number of referenced objects

    static VALUE
    wmap_size(VALUE self)
    {
        struct weakmap *w;
        st_index_t n;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        n = w->wmap2obj->num_entries;
    #if SIZEOF_ST_INDEX_T <= SIZEOF_LONG
        return ULONG2NUM(n);
    #else
        return ULL2NUM(n);
    #endif
    }

Also aliased as: length
values() click to toggle source

Iterates over values and objects in a weakly referenced object

    static VALUE
    wmap_values(VALUE self)
    {
        struct weakmap *w;
        struct wmap_iter_arg args;

        TypedData_Get_Struct(self, struct weakmap, &weakmap_type, w);
        args.objspace = &rb_objspace;
        args.value = rb_ary_new();
        st_foreach(w->wmap2obj, wmap_values_i, (st_data_t)&args);
        return args.value;
    }