* thread.c (rb_thread_call_without_gvl2): Note that ubf() may or may

  not be called with the GVL.  Hinted that rb_thread_call_with_gvl()
  can be used to access ruby functionality.  [ruby-trunk - #6433]


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37394 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

2 files changed, 14 insertions, 4 deletions

diff --git a/ChangeLog b/ChangeLog
index 874ab430e4..51c0c6e6e2 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,9 @@
+Wed Oct 31 09:28:24 2012  Eric Hodel  <drbrain@segment7.net>
+
+	* thread.c (rb_thread_call_without_gvl2):  Note that ubf() may or may
+	  not be called with the GVL.  Hinted that rb_thread_call_with_gvl()
+          can be used to access ruby functionality.
+
 Wed Oct 31 09:06:54 2012  Eric Hodel  <drbrain@segment7.net>
 
 	* thread.c (rb_thread_call_without_gvl2):  Update documentation to
diff --git a/thread.c b/thread.c
index 27b59bf18f..01a24ea76c 100644
--- a/thread.c
+++ b/thread.c
@@ -1100,7 +1100,9 @@ rb_thread_blocking_region_end(struct rb_blocking_region_buffer *region)
  *
  * If another thread interrupts this thread (Thread#kill, signal delivery,
  * VM-shutdown request, and so on), `ubf()' is called (`ubf()' means
- * "un-blocking function").  `ubf()' should interrupt `func()' execution.
+ * "un-blocking function").  `ubf()' should interrupt `func()' execution by
+ * toggling a cancellation flag, canceling the invocation of a call inside
+ * `func()' or similar.  Note that `ubf()' may not be called with the GVL.
  *
  * There are built-in ubfs and you can specify these ubfs:
  *
@@ -1143,15 +1145,17 @@ rb_thread_blocking_region_end(struct rb_blocking_region_buffer *region)
  * NOTE: You can not execute most of Ruby C API and touch Ruby
  *       objects in `func()' and `ubf()', including raising an
  *       exception, because current thread doesn't acquire GVL
- *       (cause synchronization problem).  If you need to do it,
- *       read source code of C APIs and confirm by yourself.
+ *       (it causes synchronization problems).  If you need to
+ *       call ruby functions either use rb_thread_call_with_gvl()
+ *       or read source code of C APIs and confirm safety by
+ *       yourself.
  *
  * NOTE: In short, this API is difficult to use safely.  I recommend you
  *       use other ways if you have.  We lack experiences to use this API.
  *       Please report your problem related on it.
  *
  * NOTE: Releasing GVL and re-acquiring GVL may be expensive operations
- *       for short running `func()'. Be sure to benchmark and use this
+ *       for a short running `func()'. Be sure to benchmark and use this
  *       mechanism when `func()' consumes enough time.
  *
  * Safe C API: