Issue #19406 has been updated by nobu (Nobuyoshi Nakada). `rb_random_interface_t` uses `rb_data_type_struct::data`. ---------------------------------------- Feature #19406: Allow declarative reference definition for rb_typed_data_struct https://bugs.ruby-lang.org/issues/19406#change-102165 * 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:  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/