Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions include/mruby/gc.h
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,19 @@ typedef struct mrb_gc_prof_hist {
} mrb_gc_prof_hist;
#endif

/* A table that holds objects weakly: what it holds is not marked through
it, and `clear` is called once marking is complete, before the sweep, to
drop each object mrb_gc_weak_dead_p() reports. `clear` may neither
allocate nor run Ruby code. The table owns the node and links it with
mrb_gc_weak_add(), and unlinks it before the node is freed. */
struct mrb_gc_weak {
struct mrb_gc_weak *prev, *next;
void (*clear)(mrb_state *mrb, struct mrb_gc_weak *weak);
};

typedef struct mrb_gc {
struct kh_gcroot *root; /* mrb_gc_register()ed objects -> pin count */
struct mrb_gc_weak *weaks; /* mrb_gc_weak_add()ed tables */
struct mrb_heap_page *heaps; /* all heaps pages */
struct mrb_heap_page *free_heaps;/* heaps for allocation */
struct mrb_heap_page *sweeps; /* page where sweep starts */
Expand Down Expand Up @@ -118,6 +129,11 @@ typedef struct mrb_gc {
} mrb_gc;

MRB_API mrb_bool mrb_object_dead_p(mrb_state *mrb, struct RBasic *object);
MRB_API void mrb_gc_weak_add(mrb_state *mrb, struct mrb_gc_weak *weak);
MRB_API void mrb_gc_weak_remove(mrb_state *mrb, struct mrb_gc_weak *weak);
/* Only in a `clear` callback: whether `v`, which the table holds, is to be
freed by this sweep. An immediate value never is. */
MRB_API mrb_bool mrb_gc_weak_dead_p(mrb_state *mrb, mrb_value v);
MRB_API int mrb_gc_add_region(mrb_state *mrb, void *start, size_t size);

/* Task-scheduled GC control.
Expand Down
59 changes: 59 additions & 0 deletions mrbgems/mruby-objectspace-weakmap/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# mruby-objectspace-weakmap

`ObjectSpace::WeakMap` and `ObjectSpace::WeakKeyMap`, for a build that asks
for them:

```ruby
conf.gem core: 'mruby-objectspace-weakmap'
```

## `ObjectSpace::WeakMap`

A map whose keys and values are held weakly: an entry is dropped when its
key or its value is collected. Keys are compared by identity.

```ruby
m = ObjectSpace::WeakMap.new
k = "key"
m[k] = "value"
m[k] # => "value"
m["key"] # => nil, another object
```

It has `[]`, `[]=`, `delete`, `key?` (`include?`, `member?`), `keys`,
`values`, `size` (`length`), `each` (`each_pair`), `each_key`,
`each_value` and `inspect`, and includes Enumerable. An immediate value,
such as an Integer or a Symbol, is never collected, and an entry of one
stays.

## `ObjectSpace::WeakKeyMap`

A map whose keys are held weakly, compared by `eql?` and `hash`, and whose
values are held as long as their keys are. A key that is never collected
raises `ArgumentError`.

```ruby
m = ObjectSpace::WeakKeyMap.new
k = "key"
m[k] = 1
m["key"] # => 1
m.getkey("key") # => k
```

It has `[]`, `[]=`, `delete`, `getkey`, `key?`, `clear` and `inspect`.

As in CRuby:

- entries are in the order they were added;
- a copy made by `dup` or `clone` is empty;
- a frozen map still takes entries;
- WeakMap's `each` also yields the entries its block adds;
- a value that refers to its key keeps the key, and its entry, alive.

## How

The maps keep their entries in tables the GC does not mark through, and
link each table into the GC with `mrb_gc_weak_add()` (`mruby/gc.h`). Once
marking is complete, before the sweep, the GC calls the table back, and it
drops each entry `mrb_gc_weak_dead_p()` reports. WeakKeyMap's values are
kept in an Array the map holds.
5 changes: 5 additions & 0 deletions mrbgems/mruby-objectspace-weakmap/mrbgem.rake
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
MRuby::Gem::Specification.new('mruby-objectspace-weakmap') do |spec|
spec.license = 'MIT'
spec.author = 'mruby developers'
spec.summary = 'ObjectSpace::WeakMap and ObjectSpace::WeakKeyMap'
end
Loading
Loading