mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
* thread.c: rdoc formatting for Thread, ThreadGroup, and ThreadError
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@39532 b2dd03c8-39d4-4d8f-98ff-823fe69b080e
This commit is contained in:
zzak
parent
0315ced9a5
commit
4e040aa6ac
2 changed files with 132 additions and 101 deletions
|
|
@ -1,3 +1,7 @@
|
|||
Thu Feb 28 05:57:00 2013 Zachary Scott <zachary@zacharyscott.net>
|
||||
|
||||
* thread.c: rdoc formatting for Thread, ThreadGroup, and ThreadError
|
||||
|
||||
Thu Feb 28 02:42:00 2013 Zachary Scott <zachary@zacharyscott.net>
|
||||
|
||||
* vm.c: Typo in overview for example of Thread#status returning false
|
||||
|
|
|
|||
229
thread.c
229
thread.c
|
|
@ -822,38 +822,37 @@ thread_join(rb_thread_t *target_th, double delay)
|
|||
* thr.join -> thr
|
||||
* thr.join(limit) -> thr
|
||||
*
|
||||
* The calling thread will suspend execution and run <i>thr</i>. Does not
|
||||
* return until <i>thr</i> exits or until <i>limit</i> seconds have passed. If
|
||||
* the time limit expires, <code>nil</code> will be returned, otherwise
|
||||
* <i>thr</i> is returned.
|
||||
* The calling thread will suspend execution and run this +thr+.
|
||||
*
|
||||
* Any threads not joined will be killed when the main program exits. If
|
||||
* <i>thr</i> had previously raised an exception and the
|
||||
* <code>abort_on_exception</code> and <code>$DEBUG</code> flags are not set
|
||||
* (so the exception has not yet been processed) it will be processed at this
|
||||
* time.
|
||||
* Does not return until +thr+ exits or until the given +limit+ seconds have
|
||||
* passed.
|
||||
*
|
||||
* If the time limit expires, +nil+ will be returned, otherwise this +thr+ is
|
||||
* returned.
|
||||
*
|
||||
* Any threads not joined will be killed when the main program exits.
|
||||
*
|
||||
* If +thr+ had previously raised an exception and the ::abort_on_exception or
|
||||
* $DEBUG flags are not set, (so the exception has not yet been processed), it
|
||||
* will be processed at this time.
|
||||
*
|
||||
* a = Thread.new { print "a"; sleep(10); print "b"; print "c" }
|
||||
* x = Thread.new { print "x"; Thread.pass; print "y"; print "z" }
|
||||
* x.join # Let x thread finish, a will be killed on exit.
|
||||
* #=> "axyz"
|
||||
*
|
||||
* <em>produces:</em>
|
||||
*
|
||||
* axyz
|
||||
*
|
||||
* The following example illustrates the <i>limit</i> parameter.
|
||||
* The following example illustrates the +limit+ parameter.
|
||||
*
|
||||
* y = Thread.new { 4.times { sleep 0.1; puts 'tick... ' }}
|
||||
* puts "Waiting" until y.join(0.15)
|
||||
*
|
||||
* <em>produces:</em>
|
||||
* This will produce:
|
||||
*
|
||||
* tick...
|
||||
* Waiting
|
||||
* tick...
|
||||
* Waitingtick...
|
||||
*
|
||||
*
|
||||
* Waiting
|
||||
* tick...
|
||||
* tick...
|
||||
*/
|
||||
|
||||
|
|
@ -878,8 +877,7 @@ thread_join_m(int argc, VALUE *argv, VALUE self)
|
|||
* call-seq:
|
||||
* thr.value -> obj
|
||||
*
|
||||
* Waits for <i>thr</i> to complete (via <code>Thread#join</code>) and returns
|
||||
* its value.
|
||||
* Waits for +thr+ to complete, using #join, and returns its value.
|
||||
*
|
||||
* a = Thread.new { 2 + 2 }
|
||||
* a.value #=> 4
|
||||
|
|
@ -2064,7 +2062,7 @@ rb_thread_fd_close(int fd)
|
|||
* a = Thread.new { sleep(200) }
|
||||
* a.raise("Gotcha")
|
||||
*
|
||||
* _produces:_
|
||||
* This will produce:
|
||||
*
|
||||
* prog.rb:3: Gotcha (RuntimeError)
|
||||
* from prog.rb:2:in `initialize'
|
||||
|
|
@ -2094,10 +2092,11 @@ thread_raise_m(int argc, VALUE *argv, VALUE self)
|
|||
* thr.kill -> thr or nil
|
||||
* thr.terminate -> thr or nil
|
||||
*
|
||||
* Terminates <i>thr</i> and schedules another thread to be run. If this thread
|
||||
* is already marked to be killed, <code>exit</code> returns the
|
||||
* <code>Thread</code>. If this is the main thread, or the last thread, exits
|
||||
* the process.
|
||||
* Terminates +thr+ and schedules another thread to be run.
|
||||
*
|
||||
* If this thread is already marked to be killed, #exit returns the Thread.
|
||||
*
|
||||
* If this is the main thread, or the last thread, exits the process.
|
||||
*/
|
||||
|
||||
VALUE
|
||||
|
|
@ -2135,7 +2134,7 @@ rb_thread_kill(VALUE thread)
|
|||
* call-seq:
|
||||
* Thread.kill(thread) -> thread
|
||||
*
|
||||
* Causes the given <em>thread</em> to exit (see <code>Thread::exit</code>).
|
||||
* Causes the given +thread+ to exit, see also Thread::exit.
|
||||
*
|
||||
* count = 0
|
||||
* a = Thread.new { loop { count += 1 } }
|
||||
|
|
@ -2157,9 +2156,11 @@ rb_thread_s_kill(VALUE obj, VALUE th)
|
|||
* Thread.exit -> thread
|
||||
*
|
||||
* Terminates the currently running thread and schedules another thread to be
|
||||
* run. If this thread is already marked to be killed, <code>exit</code>
|
||||
* returns the <code>Thread</code>. If this is the main thread, or the last
|
||||
* thread, exit the process.
|
||||
* run.
|
||||
*
|
||||
* If this thread is already marked to be killed, ::exit returns the Thread.
|
||||
*
|
||||
* If this is the main thread, or the last thread, exit the process.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2183,10 +2184,7 @@ rb_thread_exit(void)
|
|||
* sleep 0.1 while c.status!='sleep'
|
||||
* c.wakeup
|
||||
* c.join
|
||||
*
|
||||
* _produces:_
|
||||
*
|
||||
* hey!
|
||||
* #=> "hey!"
|
||||
*/
|
||||
|
||||
VALUE
|
||||
|
|
@ -2218,7 +2216,7 @@ rb_thread_wakeup_alive(VALUE thread)
|
|||
* call-seq:
|
||||
* thr.run -> thr
|
||||
*
|
||||
* Wakes up <i>thr</i>, making it eligible for scheduling.
|
||||
* Wakes up +thr+, making it eligible for scheduling.
|
||||
*
|
||||
* a = Thread.new { puts "a"; Thread.stop; puts "c" }
|
||||
* sleep 0.1 while a.status!='sleep'
|
||||
|
|
@ -2226,11 +2224,13 @@ rb_thread_wakeup_alive(VALUE thread)
|
|||
* a.run
|
||||
* a.join
|
||||
*
|
||||
* <em>produces:</em>
|
||||
* This will produce:
|
||||
*
|
||||
* a
|
||||
* Got here
|
||||
* c
|
||||
*
|
||||
* See also the instance method #wakeup.
|
||||
*/
|
||||
|
||||
VALUE
|
||||
|
|
@ -2254,10 +2254,7 @@ rb_thread_run(VALUE thread)
|
|||
* print "b"
|
||||
* a.run
|
||||
* a.join
|
||||
*
|
||||
* <em>produces:</em>
|
||||
*
|
||||
* abc
|
||||
* #=> "abc"
|
||||
*/
|
||||
|
||||
VALUE
|
||||
|
|
@ -2295,15 +2292,15 @@ thread_list_i(st_data_t key, st_data_t val, void *data)
|
|||
* call-seq:
|
||||
* Thread.list -> array
|
||||
*
|
||||
* Returns an array of <code>Thread</code> objects for all threads that are
|
||||
* either runnable or stopped.
|
||||
* Returns an array of Thread objects for all threads that are either runnable
|
||||
* or stopped.
|
||||
*
|
||||
* Thread.new { sleep(200) }
|
||||
* Thread.new { 1000000.times {|i| i*i } }
|
||||
* Thread.new { Thread.stop }
|
||||
* Thread.list.each {|t| p t}
|
||||
*
|
||||
* <em>produces:</em>
|
||||
* This will produce:
|
||||
*
|
||||
* #<Thread:0x401b3e84 sleep>
|
||||
* #<Thread:0x401b3f38 run>
|
||||
|
|
@ -2364,12 +2361,20 @@ rb_thread_s_main(VALUE klass)
|
|||
* call-seq:
|
||||
* Thread.abort_on_exception -> true or false
|
||||
*
|
||||
* Returns the status of the global ``abort on exception'' condition. The
|
||||
* default is <code>false</code>. When set to <code>true</code>, or if the
|
||||
* global <code>$DEBUG</code> flag is <code>true</code> (perhaps because the
|
||||
* command line option <code>-d</code> was specified) all threads will abort
|
||||
* (the process will <code>exit(0)</code>) if an exception is raised in any
|
||||
* thread. See also <code>Thread::abort_on_exception=</code>.
|
||||
* Returns the status of the global ``abort on exception'' condition.
|
||||
*
|
||||
* The default is +false+.
|
||||
*
|
||||
* When set to +true+, all threads will abort (the process will
|
||||
* <code>exit(0)</code>) if an exception is raised in any thread.
|
||||
*
|
||||
* Can also be specified by the global $DEBUG flag or command line option
|
||||
* +-d+.
|
||||
*
|
||||
* See also ::abort_on_exception=.
|
||||
*
|
||||
* There is also an instance level method to set this for a specific thread,
|
||||
* see #abort_on_exception.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2383,8 +2388,8 @@ rb_thread_s_abort_exc(void)
|
|||
* call-seq:
|
||||
* Thread.abort_on_exception= boolean -> true or false
|
||||
*
|
||||
* When set to <code>true</code>, all threads will abort if an exception is
|
||||
* raised. Returns the new state.
|
||||
* When set to +true+, all threads will abort if an exception is raised.
|
||||
* Returns the new state.
|
||||
*
|
||||
* Thread.abort_on_exception = true
|
||||
* t1 = Thread.new do
|
||||
|
|
@ -2394,13 +2399,18 @@ rb_thread_s_abort_exc(void)
|
|||
* sleep(1)
|
||||
* puts "not reached"
|
||||
*
|
||||
* <em>produces:</em>
|
||||
* This will produce:
|
||||
*
|
||||
* In new thread
|
||||
* prog.rb:4: Exception from thread (RuntimeError)
|
||||
* from prog.rb:2:in `initialize'
|
||||
* from prog.rb:2:in `new'
|
||||
* from prog.rb:2
|
||||
*
|
||||
* See also ::abort_on_exception.
|
||||
*
|
||||
* There is also an instance level method to set this for a specific thread,
|
||||
* see #abort_on_exception=.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2417,8 +2427,14 @@ rb_thread_s_abort_exc_set(VALUE self, VALUE val)
|
|||
* thr.abort_on_exception -> true or false
|
||||
*
|
||||
* Returns the status of the thread-local ``abort on exception'' condition for
|
||||
* <i>thr</i>. The default is <code>false</code>. See also
|
||||
* <code>Thread::abort_on_exception=</code>.
|
||||
* this +thr+.
|
||||
*
|
||||
* The default is +false+.
|
||||
*
|
||||
* See also #abort_on_exception=.
|
||||
*
|
||||
* There is also a class level method to set this for all threads, see
|
||||
* ::abort_on_exception.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2434,9 +2450,15 @@ rb_thread_abort_exc(VALUE thread)
|
|||
* call-seq:
|
||||
* thr.abort_on_exception= boolean -> true or false
|
||||
*
|
||||
* When set to <code>true</code>, causes all threads (including the main
|
||||
* program) to abort if an exception is raised in <i>thr</i>. The process will
|
||||
* effectively <code>exit(0)</code>.
|
||||
* When set to +true+, all threads (including the main program) will abort if
|
||||
* an exception is raised in this +thr+.
|
||||
*
|
||||
* The process will effectively <code>exit(0)</code>.
|
||||
*
|
||||
* See also #abort_on_exception.
|
||||
*
|
||||
* There is also a class level method to set this for all threads, see
|
||||
* ::abort_on_exception=.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2505,11 +2527,18 @@ rb_threadptr_dead(rb_thread_t *th)
|
|||
* call-seq:
|
||||
* thr.status -> string, false or nil
|
||||
*
|
||||
* Returns the status of <i>thr</i>: ``<code>sleep</code>'' if <i>thr</i> is
|
||||
* sleeping or waiting on I/O, ``<code>run</code>'' if <i>thr</i> is executing,
|
||||
* ``<code>aborting</code>'' if <i>thr</i> is aborting, <code>false</code> if
|
||||
* <i>thr</i> terminated normally, and <code>nil</code> if <i>thr</i>
|
||||
* terminated with an exception.
|
||||
* Returns the status of +thr+.
|
||||
*
|
||||
* [<tt>"sleep"</tt>]
|
||||
* Returned if this thread is sleeping or waiting on I/O
|
||||
* [<tt>"run"</tt>]
|
||||
* When this thread is executing
|
||||
* [<tt>"aborting"</tt>]
|
||||
* If this thread is aborting
|
||||
* [+false+]
|
||||
* When this thread is terminated normally
|
||||
* [+nil+]
|
||||
* If terminated with an exception.
|
||||
*
|
||||
* a = Thread.new { raise("die now") }
|
||||
* b = Thread.new { Thread.stop }
|
||||
|
|
@ -2521,6 +2550,8 @@ rb_threadptr_dead(rb_thread_t *th)
|
|||
* c.status #=> false
|
||||
* d.status #=> "aborting"
|
||||
* Thread.current.status #=> "run"
|
||||
*
|
||||
* See also the instance methods #alive? and #stop?
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2544,12 +2575,14 @@ rb_thread_status(VALUE thread)
|
|||
* call-seq:
|
||||
* thr.alive? -> true or false
|
||||
*
|
||||
* Returns <code>true</code> if <i>thr</i> is running or sleeping.
|
||||
* Returns +true+ if +thr+ is running or sleeping.
|
||||
*
|
||||
* thr = Thread.new { }
|
||||
* thr.join #=> #<Thread:0x401b3fb0 dead>
|
||||
* Thread.current.alive? #=> true
|
||||
* thr.alive? #=> false
|
||||
*
|
||||
* See also #stop? and #status.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2567,12 +2600,14 @@ rb_thread_alive_p(VALUE thread)
|
|||
* call-seq:
|
||||
* thr.stop? -> true or false
|
||||
*
|
||||
* Returns <code>true</code> if <i>thr</i> is dead or sleeping.
|
||||
* Returns +true+ if +thr+ is dead or sleeping.
|
||||
*
|
||||
* a = Thread.new { Thread.stop }
|
||||
* b = Thread.current
|
||||
* a.stop? #=> true
|
||||
* b.stop? #=> false
|
||||
*
|
||||
* See also #alive? and #status.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2657,7 +2692,7 @@ rb_thread_local_aref(VALUE thread, ID id)
|
|||
*
|
||||
* Attribute Reference---Returns the value of a fiber-local variable (current thread's root fiber
|
||||
* if not explicitely inside a Fiber), using either a symbol or a string name.
|
||||
* If the specified variable does not exist, returns <code>nil</code>.
|
||||
* If the specified variable does not exist, returns +nil+.
|
||||
*
|
||||
* [
|
||||
* Thread.new { Thread.current["name"] = "A" },
|
||||
|
|
@ -2668,7 +2703,7 @@ rb_thread_local_aref(VALUE thread, ID id)
|
|||
* puts "#{th.inspect}: #{th[:name]}"
|
||||
* end
|
||||
*
|
||||
* <em>produces:</em>
|
||||
* This will produce:
|
||||
*
|
||||
* #<Thread:0x00000002a54220 dead>: A
|
||||
* #<Thread:0x00000002a541a8 dead>: B
|
||||
|
|
@ -2706,8 +2741,8 @@ rb_thread_local_aref(VALUE thread, ID id)
|
|||
* #=> nil if fiber-local
|
||||
* #=> 2 if thread-local (The value 2 is leaked to outside of meth method.)
|
||||
*
|
||||
* For thread-local variables, please see <code>Thread#thread_local_get</code>
|
||||
* and <code>Thread#thread_local_set</code>.
|
||||
* For thread-local variables, please see #thread_variable_get and
|
||||
* #thread_variable_set.
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
@ -2745,9 +2780,12 @@ rb_thread_local_aset(VALUE thread, ID id, VALUE val)
|
|||
* thr[sym] = obj -> obj
|
||||
*
|
||||
* Attribute Assignment---Sets or creates the value of a fiber-local variable,
|
||||
* using either a symbol or a string. See also <code>Thread#[]</code>. For
|
||||
* thread-local variables, please see <code>Thread#thread_variable_set</code>
|
||||
* and <code>Thread#thread_variable_get</code>.
|
||||
* using either a symbol or a string.
|
||||
*
|
||||
* See also Thread#[].
|
||||
*
|
||||
* For thread-local variables, please see #thread_variable_set and
|
||||
* #thread_variable_get.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -2834,8 +2872,8 @@ rb_thread_variable_set(VALUE thread, VALUE id, VALUE val)
|
|||
* call-seq:
|
||||
* thr.key?(sym) -> true or false
|
||||
*
|
||||
* Returns <code>true</code> if the given string (or symbol) exists as a
|
||||
* fiber-local variable.
|
||||
* Returns +true+ if the given string (or symbol) exists as a fiber-local
|
||||
* variable.
|
||||
*
|
||||
* me = Thread.current
|
||||
* me[:oliver] = "a"
|
||||
|
|
@ -2952,8 +2990,8 @@ rb_thread_variables(VALUE thread)
|
|||
* call-seq:
|
||||
* thr.thread_variable?(key) -> true or false
|
||||
*
|
||||
* Returns <code>true</code> if the given string (or symbol) exists as a
|
||||
* thread-local variable.
|
||||
* Returns +true+ if the given string (or symbol) exists as a thread-local
|
||||
* variable.
|
||||
*
|
||||
* me = Thread.current
|
||||
* me.thread_variable_set(:oliver, "a")
|
||||
|
|
@ -3865,10 +3903,11 @@ static const rb_data_type_t thgroup_data_type = {
|
|||
/*
|
||||
* Document-class: ThreadGroup
|
||||
*
|
||||
* <code>ThreadGroup</code> provides a means of keeping track of a number of
|
||||
* threads as a group. A <code>Thread</code> can belong to only one
|
||||
* <code>ThreadGroup</code> at a time; adding a thread to a new group will
|
||||
* remove it from any previous group.
|
||||
* ThreadGroup provides a means of keeping track of a number of threads as a
|
||||
* group.
|
||||
*
|
||||
* A given Thread object can only belong to one ThreadGroup at a time; adding
|
||||
* a thread to a new group will remove it from any previous group.
|
||||
*
|
||||
* Newly created threads belong to the same group as the thread from which they
|
||||
* were created.
|
||||
|
|
@ -3917,8 +3956,7 @@ thgroup_list_i(st_data_t key, st_data_t val, st_data_t data)
|
|||
* call-seq:
|
||||
* thgrp.list -> array
|
||||
*
|
||||
* Returns an array of all existing <code>Thread</code> objects that belong to
|
||||
* this group.
|
||||
* Returns an array of all existing Thread objects that belong to this group.
|
||||
*
|
||||
* ThreadGroup::Default.list #=> [#<Thread:0x401bdf4c run>]
|
||||
*/
|
||||
|
|
@ -3941,17 +3979,15 @@ thgroup_list(VALUE group)
|
|||
* thgrp.enclose -> thgrp
|
||||
*
|
||||
* Prevents threads from being added to or removed from the receiving
|
||||
* <code>ThreadGroup</code>. New threads can still be started in an enclosed
|
||||
* <code>ThreadGroup</code>.
|
||||
* ThreadGroup.
|
||||
*
|
||||
* New threads can still be started in an enclosed ThreadGroup.
|
||||
*
|
||||
* ThreadGroup::Default.enclose #=> #<ThreadGroup:0x4029d914>
|
||||
* thr = Thread::new { Thread.stop } #=> #<Thread:0x402a7210 sleep>
|
||||
* tg = ThreadGroup::new #=> #<ThreadGroup:0x402752d4>
|
||||
* tg.add thr
|
||||
*
|
||||
* <em>produces:</em>
|
||||
*
|
||||
* ThreadError: can't move from the enclosed thread group
|
||||
* #=> ThreadError: can't move from the enclosed thread group
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -3970,8 +4006,7 @@ thgroup_enclose(VALUE group)
|
|||
* call-seq:
|
||||
* thgrp.enclosed? -> true or false
|
||||
*
|
||||
* Returns <code>true</code> if <em>thgrp</em> is enclosed. See also
|
||||
* ThreadGroup#enclose.
|
||||
* Returns +true+ if the +thgrp+ is enclosed. See also ThreadGroup#enclose.
|
||||
*/
|
||||
|
||||
static VALUE
|
||||
|
|
@ -3990,8 +4025,8 @@ thgroup_enclosed_p(VALUE group)
|
|||
* call-seq:
|
||||
* thgrp.add(thread) -> thgrp
|
||||
*
|
||||
* Adds the given <em>thread</em> to this group, removing it from any other
|
||||
* group to which it may have previously belonged.
|
||||
* Adds the given +thread+ to this group, removing it from any other
|
||||
* group to which it may have previously been a member.
|
||||
*
|
||||
* puts "Initial group is #{ThreadGroup::Default.list}"
|
||||
* tg = ThreadGroup.new
|
||||
|
|
@ -4003,7 +4038,7 @@ thgroup_enclosed_p(VALUE group)
|
|||
* puts "Initial group now #{ThreadGroup::Default.list}"
|
||||
* puts "tg group now #{tg.list}"
|
||||
*
|
||||
* <em>produces:</em>
|
||||
* This will produce:
|
||||
*
|
||||
* Initial group is #<Thread:0x401bdf4c>
|
||||
* t1 is #<Thread:0x401b3c90>
|
||||
|
|
@ -4898,18 +4933,10 @@ rb_thread_backtrace_locations_m(int argc, VALUE *argv, VALUE thval)
|
|||
*
|
||||
* Thread.stop
|
||||
*
|
||||
* <em>raises the exception:</em>
|
||||
* This will raises the following exception:
|
||||
*
|
||||
* ThreadError: stopping only thread
|
||||
*/
|
||||
|
||||
/*
|
||||
* +Thread+ encapsulates the behavior of a thread of
|
||||
* execution, including the main thread of the Ruby script.
|
||||
*
|
||||
* In the descriptions of the methods in this class, the parameter _sym_
|
||||
* refers to a symbol, which is either a quoted string or a
|
||||
* +Symbol+ (such as <code>:name</code>).
|
||||
* note: use sleep to stop forever
|
||||
*/
|
||||
|
||||
void
|
||||
|
|
|
|||
Loading…
Reference in a new issue