From 4e040aa6ac4cc4f3b00007b8635a990ef36526c4 Mon Sep 17 00:00:00 2001 From: zzak Date: Wed, 27 Feb 2013 20:36:59 +0000 Subject: [PATCH] * 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 --- ChangeLog | 4 + thread.c | 229 ++++++++++++++++++++++++++++++------------------------ 2 files changed, 132 insertions(+), 101 deletions(-) diff --git a/ChangeLog b/ChangeLog index 07499bdc0c..7beeeb33c6 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Thu Feb 28 05:57:00 2013 Zachary Scott + + * thread.c: rdoc formatting for Thread, ThreadGroup, and ThreadError + Thu Feb 28 02:42:00 2013 Zachary Scott * vm.c: Typo in overview for example of Thread#status returning false diff --git a/thread.c b/thread.c index b674577676..ed6e61b040 100644 --- a/thread.c +++ b/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 thr. Does not - * return until thr exits or until limit seconds have passed. If - * the time limit expires, nil will be returned, otherwise - * thr 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 - * thr had previously raised an exception and the - * abort_on_exception and $DEBUG 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" * - * produces: - * - * axyz - * - * The following example illustrates the limit 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) * - * produces: + * 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 thr to complete (via Thread#join) 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 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. + * 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 thread to exit (see Thread::exit). + * 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, exit - * returns the Thread. 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 thr, 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 * - * produces: + * 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 - * - * produces: - * - * 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 Thread 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} * - * produces: + * This will produce: * * # * # @@ -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 false. When set to true, or if the - * global $DEBUG flag is true (perhaps because the - * command line option -d was specified) all threads will abort - * (the process will exit(0)) if an exception is raised in any - * thread. See also Thread::abort_on_exception=. + * 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 + * exit(0)) 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 true, 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" * - * produces: + * 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 - * thr. The default is false. See also - * Thread::abort_on_exception=. + * 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 true, causes all threads (including the main - * program) to abort if an exception is raised in thr. The process will - * effectively exit(0). + * When set to +true+, all threads (including the main program) will abort if + * an exception is raised in this +thr+. + * + * The process will effectively exit(0). + * + * 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 thr: ``sleep'' if thr is - * sleeping or waiting on I/O, ``run'' if thr is executing, - * ``aborting'' if thr is aborting, false if - * thr terminated normally, and nil if thr - * terminated with an exception. + * Returns the status of +thr+. + * + * ["sleep"] + * Returned if this thread is sleeping or waiting on I/O + * ["run"] + * When this thread is executing + * ["aborting"] + * 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 true if thr is running or sleeping. + * Returns +true+ if +thr+ is running or sleeping. * * thr = Thread.new { } * thr.join #=> # * 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 true if thr 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 nil. + * 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 * - * produces: + * This will produce: * * #: A * #: 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 Thread#thread_local_get - * and Thread#thread_local_set. + * 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 Thread#[]. For - * thread-local variables, please see Thread#thread_variable_set - * and Thread#thread_variable_get. + * 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 true 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 true 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 * - * ThreadGroup provides a means of keeping track of a number of - * threads as a group. A Thread can belong to only one - * ThreadGroup 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 Thread objects that belong to - * this group. + * Returns an array of all existing Thread objects that belong to this group. * * ThreadGroup::Default.list #=> [#] */ @@ -3941,17 +3979,15 @@ thgroup_list(VALUE group) * thgrp.enclose -> thgrp * * Prevents threads from being added to or removed from the receiving - * ThreadGroup. New threads can still be started in an enclosed - * ThreadGroup. + * ThreadGroup. + * + * New threads can still be started in an enclosed ThreadGroup. * * ThreadGroup::Default.enclose #=> # * thr = Thread::new { Thread.stop } #=> # * tg = ThreadGroup::new #=> # * tg.add thr - * - * produces: - * - * 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 true if thgrp 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 thread 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}" * - * produces: + * This will produce: * * Initial group is # * t1 is # @@ -4898,18 +4933,10 @@ rb_thread_backtrace_locations_m(int argc, VALUE *argv, VALUE thval) * * Thread.stop * - * raises the exception: + * 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 :name). + * note: use sleep to stop forever */ void