From 64c35be42c436538efc25db5c6e4f037f90c686a Mon Sep 17 00:00:00 2001 From: ko1 Date: Tue, 23 Sep 2008 08:51:33 +0000 Subject: [PATCH] * thread.c (rb_thread_blocking_region): write a document git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@19478 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- ChangeLog | 4 ++++ thread.c | 28 ++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+) diff --git a/ChangeLog b/ChangeLog index 6d1dfbf3a0..f9407e99da 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Tue Sep 23 17:50:35 2008 Koichi Sasada + + * thread.c (rb_thread_blocking_region): write a document + Tue Sep 23 17:14:31 2008 Koichi Sasada * thread.c, include/ruby/intern.h (rb_thread_interrupted): added. diff --git a/thread.c b/thread.c index 7416fabb25..8eb0597b83 100644 --- a/thread.c +++ b/thread.c @@ -939,6 +939,34 @@ rb_thread_schedule(void) } } +/* + * rb_thread_blocking_region - permit concurrent/parallel execution. + * + * This function does: + * (1) release GVL. + * Other Ruby threads may run in parallel. + * (2) call func with data1. + * (3) aquire GVL. + * Other Ruby threads can not run in parallel any more. + * + * If another thread interrupts this thread (Thread#kill, signal deliverly, + * VM-shutdown request, and so on), `ubf()' is called (`ubf()' means + * "un-blocking function"). `ubf()' should interrupt `func()' execution. + * There are built-in ubfs and you can specify these ubfs. + * However, we can not guarantee our built-in ubfs interrupt + * your `func()' correctly. Becareful to use rb_thread_blocking_region(). + * + * * RUBY_UBF_IO: ubf for IO operation + * * RUBY_UBF_PROCESS: ubf for process operation + * + * NOTE: You can not execute most of Ruby C API and touch Ruby objects + * in `func()' and `ubf()' 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. + * + * Safe C API: + * * rb_thread_interrupted() - check interrupt flag + */ VALUE rb_thread_blocking_region( rb_blocking_function_t *func, void *data1,