normal	2014-08-15 05:55:27 +0900 (Fri, 15 Aug 2014)

  New Revision: 47180

  http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=revision&revision=47180

  Log:
    README.EXT: preliminary documentation for RB_GC_GUARD
    
    [Bug #10100] [ruby-core:60741]

  Modified files:
    trunk/ChangeLog
    trunk/README.EXT
Index: README.EXT
===================================================================
--- README.EXT	(revision 47179)
+++ README.EXT	(revision 47180)
@@ -1622,6 +1622,56 @@ available in in include/ruby/ruby.h. An https://github.com/ruby/ruby/blob/trunk/README.EXT#L1622
 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
Index: ChangeLog
===================================================================
--- ChangeLog	(revision 47179)
+++ ChangeLog	(revision 47180)
@@ -1,3 +1,8 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1
+Fri Aug 15 05:53:59 2014  Eric Wong  <e@8...>
+
+	* README.EXT: preliminary documentation for RB_GC_GUARD
+	  [Bug #10100] [ruby-core:60741]
+
 Thu Aug 14 00:26:19 2014  Masaki Suketa <masaki.suketa@n...>
 
 	* ext/win32ole/win32ole.c: separate WIN32OLE_RECORD src from

--
ML: ruby-changes@q...
Info: http://www.atdot.net/~ko1/quickml/