From: "eightbitraptor (Matthew Valentine-House) via ruby-core" <ruby-core@...>
Date: 2023-02-03T10:13:46+00:00
Subject: [ruby-core:112200] [Ruby master Feature#19406] Allow declarative reference definition for rb_typed_data_struct

Issue #19406 has been reported by eightbitraptor (Matthew Valentine-House).

----------------------------------------
Feature #19406: Allow declarative reference definition for rb_typed_data_struct
https://bugs.ruby-lang.org/issues/19406

* Author: eightbitraptor (Matthew Valentine-House)
* Status: Open
* Priority: Normal
----------------------------------------
[Github PR 7153](https://github.com/ruby/ruby/pull/7153)

## Summary

This PR proposes an additional API for C extension authors to define wrapped
struct members that point to Ruby objects, when the struct being wrapped
contains only members with primitive types (ie. no arrays or unions). The new
interface passes an offset from the top of the data structure, rather than the
reference `VALUE` itself, allowing the GC to manipulate both the reference edge
(the address holding the pointer), as well as the underlying object.

This allows Ruby's GC to handle marking, object movement and reference updating
independently without calling back into user supplied code.

## Implementation

When a wrapped struct contains a simple list of members (such as the 
`struct enumerator` in `enumerator.c`). We can declare all of the struct members that
may point to valid Ruby objects as `RUBY_REF_EDGE` in a static array.

If we choose to do this, then we can mark the corresponding `rb_data_type_t` as
`RUBY_TYPED_DECL_MARKING` and pass a pointer to the references array in the
`data` field.

To avoid having to also find space in the `rb_data_type_t` to define a length for
the references list, I've chosen to require list termination
with `RUBY_REF_END` - defined as `UINTPTR_MAX`. My assumption is that no
single wrapped struct will ever be large enough that `UINTPTR_MAX` is actually a
valid reference.

We don't have to then define `dmark` or `dcompact` callback functions. Marking,
object movement, and reference updating will be handled for us by the GC.

```C
struct enumerator {
    VALUE obj;
    ID    meth;
    VALUE args;
    VALUE fib;
    VALUE dst;
    VALUE lookahead;
    VALUE feedvalue;
    VALUE stop_exc;
    VALUE size;
    VALUE procs;
    rb_enumerator_size_func *size_fn;
    int kw_splat;
};

static const size_t enumerator_refs[] = {
    RUBY_REF_EDGE(enumerator, obj),
    RUBY_REF_EDGE(enumerator, args),
    RUBY_REF_EDGE(enumerator, fib),
    RUBY_REF_EDGE(enumerator, dst),
    RUBY_REF_EDGE(enumerator, lookahead),
    RUBY_REF_EDGE(enumerator, feedvalue),
    RUBY_REF_EDGE(enumerator, stop_exc),
    RUBY_REF_EDGE(enumerator, size),
    RUBY_REF_EDGE(enumerator, procs),
    RUBY_REF_END
};

static const rb_data_type_t enumerator_data_type = {
    "enumerator",
    {
        NULL,
        enumerator_free,
        enumerator_memsize,
        NULL,
    },
    0, (void *)enumerator_refs, RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_DECL_MARKING
};
```

### Benchmarking

Benchmarking shows that this reference declaration style does not degrade
performance when compared to the callback style.

To benchmark this we created a C extension that initialized a struct with 20
`VALUE` members, all set to point to Ruby strings. We wrapped each struct using
`TypedData_Make_Struct` in an object. One object was configured with callback
functions and one was configured with declarative references.

In separate scripts we then created 500,000 of these objects, added them to a
list, so they would be marked and not swept and used
`GC.verify_compaction_references` to make sure everything that could move, did.

Finally we created a wrapper script that used seperate processes to run each GC
type (to ensure that the GC's were completely independent), ran each benchmark
50 times, and collected the results of `GC.stat[:time]`.

We did this on an M1 Pro MacBook (aarch64), and a Ryzen 3600 We then plotted the
results:

![chart showing GC time between callback and declarative marking on arm64 and
x86_64](https://user-images.githubusercontent.com/31869/216573409-ddafa3bd-9af7-4b60-ba61-355da7e71910.png)

As we can see from this, there has been no real impact to GC performance in our
benchmarks.

Benchmark code and harnesses is [available in this Github
repo](https://github.com/eightbitraptor/test_decl_marking)

## Justification

Requiring extension authors to implement seperate `dmark` and `dcompact`
callbacks can be error-prone, and pushes GC responsibilities from the GC into
user supplied code. This can be a source of bugs arising from the `dmark` and
`dcompact` functions being implemented incorrectly, or becoming out of sync with each other.

There has already been work done by @Peterzhu2118 [to try and unify these
callbacks](https://github.com/ruby/ruby/pull/7140), so that authors can define a
single function, that will be used for both marking and compacting, removing the
risk of these callbacks becoming out of sync.

This proposal works alongside Peter's earlier work to eliminate the
callbacks entirely for the "simple reference" case.

This means that extension authors with simple structs to wrap can declare which
of their struct members point to Ruby objects to get GC marking and compaction
support. And extension authors with more complex requirements will only have to
implement a single function, using Peter's work.

In addition to this, passing the GC the address of a reference rather than the
reference itself (edge based, rather than object based enqueing), allows the GC
itself to have more control over how it manipulates that reference.

This means that when considering alternative GC implementations for Ruby (such
as our [ongoing work integrating MMTk into
Ruby](https://github.com/mmtk/mmtk-ruby)[^1]), We don't need to call from Ruby
into library code, and then back into Ruby code as often; which can increase
performance, and allow more complex algorithms to be implemented.

[^1]: [MMtk](https://www.mmtk.io/) is the Memory Management Toolkit. A framework
    for implementing automatic memory management strategies

## Trade-offs

This PR provides another method for defining references in C extensions, in
addition to the callback based approach, effectively widening the extension API.
Extension authors will now need to choose whether to use the declarative
approach, or a callback based approach depending on their use case. This is more
complex for extension authors.

However because the callback's do still exist, this does mean that extension
authors can migrate their own code to this new, faster approach at their
leisure.

## Further work

As part of this work we inspected all uses of `rb_data_type_t` in the Ruby
source code and of 134 separete instances, 60 wrapped structs that contained
`VALUE` members that could point to Ruby objects. Out of these 27 were "simple"
structs that would benefit from this approach, 28 contained complex references
(unions, loops etc) that won't work with this approach, and 5 were situations
that were unsure, that we believe we could make work given some slight
refactors.




-- 
https://bugs.ruby-lang.org/
 ______________________________________________
 ruby-core mailing list -- ruby-core@ml.ruby-lang.org
 To unsubscribe send an email to ruby-core-leave@ml.ruby-lang.org
 ruby-core info -- https://ml.ruby-lang.org/mailman3/postorius/lists/ruby-core.ml.ruby-lang.org/