ruby-changes:27480
From: zzak <ko1@a...>
Date: Thu, 28 Feb 2013 05:42:24 +0900 (JST)
Subject: [ruby-changes:27480] zzak:r39532 (trunk): * thread.c: rdoc formatting for Thread, ThreadGroup, and ThreadError
zzak 2013-02-28 05:36:59 +0900 (Thu, 28 Feb 2013) New Revision: 39532 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=39532 Log: * thread.c: rdoc formatting for Thread, ThreadGroup, and ThreadError Modified files: trunk/ChangeLog trunk/thread.c Index: ChangeLog =================================================================== --- ChangeLog (revision 39531) +++ ChangeLog (revision 39532) @@ -1,3 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Thu Feb 28 05:57:00 2013 Zachary Scott <zachary@z...> + + * thread.c: rdoc formatting for Thread, ThreadGroup, and ThreadError + Thu Feb 28 02:42:00 2013 Zachary Scott <zachary@z...> * vm.c: Typo in overview for example of Thread#status returning false Index: thread.c =================================================================== --- thread.c (revision 39531) +++ thread.c (revision 39532) @@ -822,38 +822,37 @@ thread_join(rb_thread_t *target_th, doub https://github.com/ruby/ruby/blob/trunk/thread.c#L822 * 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. - * - * 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. + * The calling thread will suspend execution and run this +thr+. + * + * 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, VAL https://github.com/ruby/ruby/blob/trunk/thread.c#L877 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2062 * 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, VA https://github.com/ruby/ruby/blob/trunk/thread.c#L2092 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2134 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2156 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2184 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2216 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2224 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2254 * 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 v https://github.com/ruby/ruby/blob/trunk/thread.c#L2292 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2361 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2388 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2399 * 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, VA https://github.com/ruby/ruby/blob/trunk/thread.c#L2427 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2450 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2527 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2550 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2575 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2600 * 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 https://github.com/ruby/ruby/blob/trunk/thread.c#L2692 * * 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 https://github.com/ruby/ruby/blob/trunk/thread.c#L2703 * 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 https://github.com/ruby/ruby/blob/trunk/thread.c#L2741 * #=> 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 https://github.com/ruby/ruby/blob/trunk/thread.c#L2780 * 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, VAL https://github.com/ruby/ruby/blob/trunk/thread.c#L2872 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L2990 * 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 https://github.com/ruby/ruby/blob/trunk/thread.c#L3903 /* * 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 https://github.com/ruby/ruby/blob/trunk/thread.c#L3956 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L3979 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L4006 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L4025 * 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) https://github.com/ruby/ruby/blob/trunk/thread.c#L4038 * 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 https://github.com/ruby/ruby/blob/trunk/thread.c#L4933 * * 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 -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/