diff options
authorko1 <ko1@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-12-24 05:00:37 (GMT)
committerko1 <ko1@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-12-24 05:00:37 (GMT)
commit215c40b8130df5f5cbd4ffcfda9c263e68e4462f (patch)
parentf7979abc845a869c01f15c2e287c710ffb620dc9 (diff)
* README.EXT: add a document about RGenGC.
Reviewed by havenwood. [misc #8962] * README.EXT.ja: ditto. git-svn-id: svn+ssh:// b2dd03c8-39d4-4d8f-98ff-823fe69b080e
3 files changed, 121 insertions, 0 deletions
diff --git a/ChangeLog b/ChangeLog
index 9b52a9a..872cf03 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+Tue Dec 24 13:48:45 2013 Koichi Sasada <>
+ * README.EXT: add a document about RGenGC.
+ Reviewed by havenwood.
+ [misc #8962]
+ * README.EXT.ja: ditto.
Tue Dec 24 12:11:43 2013 Koichi Sasada <>
* include/ruby/ruby.h (RARRAY_ASET): try to avoid compiler warning.
diff --git a/README.EXT b/README.EXT
index b7a1728..01518a0 100644
@@ -1491,6 +1491,103 @@ RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
= Appendix C. Functions available for use in extconf.rb
See documentation for {mkmf}[rdoc-ref:MakeMakefile].
+= Appendix D. Generational GC
+Ruby 2.1 introduced a generational garbage collector (called RGenGC).
+RGenGC (mostly) keeps compatibility.
+Generally, the use of the technique called write barriers is required in
+extension libraries for generational GC
+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
+== 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
+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
+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
+With use of such techniques, you don't need to insert write barriers
+=== 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.
+For a complete guide for RGenGC and write barriers, please refer to [...].
* Local variables:
diff --git a/README.EXT.ja b/README.EXT.ja
index 9bba51a..f869b47 100644
--- a/README.EXT.ja
+++ b/README.EXT.ja
@@ -1627,6 +1627,22 @@ pkg_config(pkg, option=nil) ::
+= Appendix D. 世代別GC
+Ruby 2.1から世代別GCに対応しました。我々はこれをRGenGCと呼んでいます。
+rb_ary_store() などの、適切な API 関数を利用するようにして下さい。
+そのほか、対応についての詳細は README.ext の「Appendix D. Generational
* Local variables:
* fill-column: 60