summaryrefslogtreecommitdiff
path: root/README.EXT
diff options
context:
space:
mode:
authornobu <nobu@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-12-24 05:01:05 (GMT)
committernobu <nobu@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2013-12-24 05:01:05 (GMT)
commit474e5bd0de719bdcb1410f8ed6f58e479974d734 (patch)
treef04f7340767aaa661d8e45026db709094c8fc99a /README.EXT
parent215c40b8130df5f5cbd4ffcfda9c263e68e4462f (diff)
* remove trailing spaces.
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@44375 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'README.EXT')
-rw-r--r--README.EXT74
1 files changed, 37 insertions, 37 deletions
diff --git a/README.EXT b/README.EXT
index 01518a0..4cd3a63 100644
--- a/README.EXT
+++ b/README.EXT
@@ -1493,25 +1493,25 @@ RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
See documentation for {mkmf}[rdoc-ref:MakeMakefile].
= Appendix D. Generational GC
-Ruby 2.1 introduced a generational garbage collector (called RGenGC).
+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
-(http://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29).
+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
+
+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
+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) ::
@@ -1526,65 +1526,65 @@ VALUE rb_obj_reveal(VALUE obj, VALUE klass) ::
== Write barriers
-RGenGC doesn't require write barriers to support generational GC.
-However, caring about write barrier can improve the performance of
+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(),
+
+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
+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
+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
+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.
+
+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
+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
+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
+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
+[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
+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 [...].