summaryrefslogtreecommitdiff
path: root/README.EXT
diff options
context:
space:
mode:
authornormal <normal@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2014-08-14 20:55:27 (GMT)
committernormal <normal@b2dd03c8-39d4-4d8f-98ff-823fe69b080e>2014-08-14 20:55:27 (GMT)
commitee4acc36aa057a20d30186fa98041d8722289863 (patch)
tree8d7dc78d5582b728ba42deb5e8c9c4426a6a0c0c /README.EXT
parent05e756f367d4e49e5da40354d6a9f2c1ea10b12c (diff)
README.EXT: preliminary documentation for RB_GC_GUARD
[Bug #10100] [ruby-core:60741] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@47180 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
Diffstat (limited to 'README.EXT')
-rw-r--r--README.EXT50
1 files changed, 50 insertions, 0 deletions
diff --git a/README.EXT b/README.EXT
index bfea600..f7ee002 100644
--- a/README.EXT
+++ b/README.EXT
@@ -1622,6 +1622,56 @@ 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
<https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RGenGC>.
+= Appendix E. RB_GC_GUARD to protect from premature GC
+
+C Ruby currently uses conservative garbage collection, thus VALUE
+variables must remain visible on the stack or registers to ensure any
+associated data remains usable. Optimizing C compilers are not designed
+with conservative garbage collection in mind, so they may optimize away
+the original VALUE even if the code depends on data associated with that
+VALUE.
+
+The following example illustrates the use of RB_GC_GUARD to ensure
+the contents of sptr remain valid while the second invocation of
+rb_str_new_cstr is running.
+
+ VALUE s, w;
+ const char *sptr;
+
+ s = rb_str_new_cstr("hello world!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!");
+ sptr = RSTRING_PTR(s);
+ w = rb_str_new_cstr(sptr + 6); /* Possible GC invocation */
+
+ RB_GC_GUARD(s); /* ensure s (and thus sptr) do not get GC-ed */
+
+In the above example, RB_GC_GUARD must be placed _after_ the last use of
+sptr. Placing RB_GC_GUARD before dereferencing sptr would be of no use.
+RB_GC_GUARD is only effective on the VALUE data type, not converted C
+data types.
+
+RB_GC_GUARD would not be necessary at all in the above example if
+non-inlined function calls are made on the `s' VALUE after sptr is
+dereferenced. Thus, in the above example, calling any un-inlined
+function on `s' such as:
+
+ rb_str_modify(s);
+
+Will ensure `s' stays on the stack or register to prevent a
+GC invocation from prematurely freeing it.
+
+Using the RB_GC_GUARD macro is preferable to using the "volatile"
+keyword in C. RB_GC_GUARD has the following advantages:
+
+1) the intent of the macro use is clear
+
+2) RB_GC_GUARD only affects its call site, "volatile" generates some
+ extra code every time the variable is used, hurting optimization.
+
+3) "volatile" implementations may be buggy/inconsistent in some
+ compilers and architectures. RB_GC_GUARD is customizable for broken
+ systems/compilers without those without negatively affecting other
+ systems.
+
/*
* Local variables:
* fill-column: 70