diff --git a/RGenGC.md b/RGenGC.md deleted file mode 100644 index 20bc95e..0000000 --- a/RGenGC.md +++ /dev/null @@ -1,119 +0,0 @@ -# RGenGC - -RGenGC is generational garbage collection algorithm arranged for MRI/CRuby introduced from Ruby 2.1. -RGenGC (mostly) keeps compatibility. - -# For extension writes - -Generally, the use of the technique called write barriers is required in -extension libraries for generational GC -(http://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29). -RGenGC works fine without write barriers in extension libraries. - -If your library adheres to the following tips, performance can -be further improved. Especially, the "Don't touch pointers directly" section is -important. - -## Incompatibility - -You can't write RBASIC(obj)->klass field directly because it is const -value now. - -Basically you should not write this field because MRI expects it to be -an immutable field, but if you want to do it in your extension you can -use the following functions: - -``` -VALUE rb_obj_hide(VALUE obj) :: - - Clear RBasic::klass field. The object will be an internal object. - ObjectSpace::each_object can't find this object. - -VALUE rb_obj_reveal(VALUE obj, VALUE klass) :: - - Reset RBasic::klass to be klass. - We expect the `klass' is hidden class by rb_obj_hide(). -``` - -## Write barriers - -RGenGC doesn't require write barriers to support generational GC. -However, caring about write barrier can improve the performance of -RGenGC. Please check the following tips. - -### Don't touch pointers directly - -In MRI (include/ruby/ruby.h), some macros to acquire pointers to the -internal data structures are supported such as RARRAY_PTR(), -RSTRUCT_PTR() and so on. - -DO NOT USE THESE MACROS and instead use the corresponding C-APIs such as -rb_ary_aref(), rb_ary_store() and so on. - -### Consider whether to insert write barriers - -You don't need to care about write barriers if you only use built-in -types. - -If you support T_DATA objects, you may consider using write barriers. - -Inserting write barriers into T_DATA objects only works with the -following type objects: (a) long-lived objects, (b) when a huge number -of objects are generated and (c) container-type objects that have -references to other objects. If your extension provides such a type of -T_DATA objects, consider inserting write barriers. - -* (a): short-lived objects don't become old generation objects. -* (b): only a few oldgen objects don't have performance impact. -* (c): only a few references don't have performance impact. - -Inserting write barriers is a very difficult hack, it is easy to -introduce critical bugs. And inserting write barriers has several areas -of overhead. Basically we don't recommend you insert write barriers. -Please carefully consider the risks. - -### Combine with built-in types - -Please consider utilizing built-in types. Most built-in types support -write barrier, so you can use them to avoid manually inserting write -barriers. - -For example, if your T_DATA has references to other objects, then you -can move these references to Array. A T_DATA object only has a reference -to an array object. Or you can also use a Struct object to gather a -T_DATA object (without any references) and an that Array contains -references. - -With use of such techniques, you don't need to insert write barriers -anymore. - -### Insert write barriers - -*AGAIN* Inserting write barriers is a very difficult hack, and it is -easy to introduce critical bugs. And inserting write barriers has -several areas of overhead. Basically we don't recommend you insert write -barriers. Please carefully consider the risks. - -Before inserting write barriers, you need to know about RGenGC algorithm -(gc.c will help you). Macros and functions to insert write barriers are -available in in include/ruby/ruby.h. An example is available in iseq.c. - -NOTE: The following core interfaces can be changed in the future. Please catch up if you want to insert WB into C-extensions correctly. - -Write barrier macros: - -``` -RB_OBJ_WRITE(a, slot, b) :: - - WB for new reference from `a' to `b'. - Write `b' into `*slot'. `slot' is a pointer in `a'. - -RB_OBJ_WRITTEN(a, oldv, b):: - - WB for new reference from `a' to `b'. - This doesn't write any values, but only a WB declaration. - `oldv' is replaced value with `b' (not used in current Ruby). -``` - -See source code carefully to insert write barriers. -