* array.c: replace rb_protect_inspect() and rb_inspecting_p() by

  rb_exec_recursive() in eval.c.

* eval.c (rb_exec_recursive): new function.

* array.c (rb_ary_join): use rb_exec_recursive().

* array.c (rb_ary_inspect, rb_ary_hash): ditto.

* file.c (rb_file_join): ditto.

* hash.c (rb_hash_inspect, rb_hash_to_s, rb_hash_hash): ditto.

* io.c (rb_io_puts): ditto.

* object.c (rb_obj_inspect): ditto

* struct.c (rb_struct_inspect): ditto.

* lib/set.rb (SortedSet::setup): a hack to shut up warning.
  [ruby-talk:132866]

* lib/time.rb (Time::strptime): add new function.  inspired by
  [ruby-talk:132815].

* lib/parsedate.rb (ParseDate::strptime): ditto.

* regparse.c: move st_*_strend() functions from st.c.  fixed some
  potential memory leaks.

* exception error messages updated.  [ruby-core:04497]

* ext/socket/socket.c (Init_socket): add bunch of Socket
  constants.  Patch from Sam Roberts <sroberts@uniserve.com>.
  [ruby-core:04409]

* array.c (rb_ary_s_create): no need for negative argc check.
  [ruby-core:04463]

* array.c (rb_ary_unshift_m): ditto.

* lib/xmlrpc/parser.rb (XMLRPC::FaultException): make it subclass
  of StandardError class, not Exception class.  [ruby-core:04429]

* parse.y (fcall_gen): lvar(arg) will be evaluated as
  lvar.call(arg) when lvar is a defined local variable. [new]

* object.c (rb_class_initialize): call inherited method before
  calling initializing block.

* eval.c (rb_thread_start_1): initialize newly pushed frame.

* lib/open3.rb (Open3::popen3): $? should not be EXIT_FAILURE.
  fixed: [ruby-core:04444]

* eval.c (is_defined): NODE_IASGN is an assignment.

* ext/readline/readline.c (Readline.readline): use rl_outstream
  and rl_instream.  [ruby-dev:25699]

* ext/etc/etc.c (Init_etc): sGroup needs HAVE_ST_GR_PASSWD check
  [ruby-dev:25675]

* misc/ruby-mode.el: [ruby-core:04415]

* lib/rdoc/generators/html_generator.rb: [ruby-core:04412]

* lib/rdoc/generators/ri_generator.rb: ditto.

* struct.c (make_struct): fixed: [ruby-core:04402]

* ext/curses/curses.c (window_color_set): [ruby-core:04393]

* ext/socket/socket.c (Init_socket): SO_REUSEPORT added.
  [ruby-talk:130092]

* object.c: [ruby-doc:818]

* parse.y (open_args): fix too verbose warnings for the space
  before argument parentheses.  [ruby-dev:25492]

* parse.y (parser_yylex): ditto.

* parse.y (parser_yylex): the first expression in the parentheses
  should not be a command.  [ruby-dev:25492]

* lib/irb/context.rb (IRB::Context::initialize): [ruby-core:04330]

* object.c (Init_Object): remove Object#type.  [ruby-core:04335]

* st.c (st_foreach): report success/failure by return value.
  [ruby-Bugs-1396]

* parse.y: forgot to initialize parser struct.  [ruby-dev:25492]

* parse.y (parser_yylex): no tLABEL on EXPR_BEG.
  [ruby-talk:127711]

* document updates - [ruby-core:04296], [ruby-core:04301],
  [ruby-core:04302], [ruby-core:04307]

* dir.c (rb_push_glob): should work for NUL delimited patterns.

* dir.c (rb_glob2): should aware of offset in the pattern.

* string.c (rb_str_new4): should propagate taintedness.

* env.h: rename member names in struct FRAME; last_func -> callee,
  orig_func -> this_func, last_class -> this_class.

* struct.c (rb_struct_set): use original method name, not callee
  name, to retrieve member slot.  [ruby-core:04268]

* time.c (time_strftime): protect from format modification from GC
  finalizers.

* object.c (Init_Object): remove rb_obj_id_obsolete()

* eval.c (rb_mod_define_method): incomplete subclass check.
  [ruby-dev:25464]

* gc.c (rb_data_object_alloc): klass may be NULL.
  [ruby-list:40498]

* bignum.c (rb_big_rand): should return positive random number.
  [ruby-dev:25401]

* bignum.c (rb_big_rand): do not use rb_big_modulo to generate
  random bignums.  [ruby-dev:25396]

* variable.c (rb_autoload): [ruby-dev:25373]

* eval.c (svalue_to_avalue): [ruby-dev:25366]

* string.c (rb_str_justify): [ruby-dev:25367]

* io.c (rb_f_select): [ruby-dev:25312]

* ext/socket/socket.c (sock_s_getservbyport): [ruby-talk:124072]

* struct.c (make_struct): [ruby-dev:25249]

* dir.c (dir_open_dir): new function.  [ruby-dev:25242]

* io.c (rb_f_open): add type check for return value from to_open.

* lib/pstore.rb (PStore#transaction): Use the empty content when a
  file is not found.  [ruby-dev:24561]


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

1 files changed, 31 insertions, 21 deletions

diff --git a/lib/timeout.rb b/lib/timeout.rb
index 7e3ee81ed0..36811a1040 100644
--- a/lib/timeout.rb
+++ b/lib/timeout.rb
@@ -1,38 +1,39 @@
+# = timeout.rb
 #
-# timeout.rb -- execution timeout
+# execution timeout
 #
-# Copyright (C) 2000  Network Applied Communication Laboratory, Inc.
-# Copyright (C) 2000  Information-technology Promotion Agency, Japan
-#
-#= SYNOPSIS
+# = Synopsis
 #
 #   require 'timeout'
-#   status = timeout(5) {
-#     # something may take time
+#   status = Timeout::timeout(5) {
+#     # Something that should be interrupted if it takes too much time...
 #   }
 #
-#= DESCRIPTION
-#
-# timeout executes the block.  If the block execution terminates successfully
-# before timeout, it returns true.  If not, it terminates the execution and
-# raise TimeoutError exception.
-#
-#== Parameters
-#
-#  : timout
+# = Description
 #
-#    The time in seconds to wait for block termination.   
+# A way of performing a potentially long-running operation in a thread, and terminating
+# it's execution if it hasn't finished by a fixed amount of time.
 #
-#  : [exception]
+# Previous versions of timeout didn't provide use a module for namespace. This version
+# provides both Timeout.timeout, and a backwards-compatible #timeout.
 #
-#    The exception class to be raised on timeout.
+# = Copyright
 #
-#=end
+# Copyright:: (C) 2000  Network Applied Communication Laboratory, Inc.
+# Copyright:: (C) 2000  Information-technology Promotion Agency, Japan
 
 module Timeout
+  # Raised by Timeout#timeout when the block times out.
   class Error<Interrupt
   end
 
+  # Executes the method's block. If the block execution terminates before +sec+
+  # seconds has passed, it returns true. If not, it terminates the execution
+  # and raises +exception+ (which defaults to Timeout::Error).
+  #
+  # Note that this is both a method of module Timeout, so you can 'include Timeout'
+  # into your classes so they have a #timeout method, as well as a module method,
+  # so you can call it directly as Timeout.timeout().
   def timeout(sec, exception=Error)
     return yield if sec == nil or sec.zero?
     raise ThreadError, "timeout within critical session" if Thread.critical
@@ -48,13 +49,22 @@ module Timeout
       y.kill if y and y.alive?
     end
   end
+
   module_function :timeout
 end
 
-# compatible
+# Identical to:
+#
+#   Timeout::timeout(n, e, &block).
+#
+# Defined for backwards compatibility with earlier versions of timeout.rb, see
+# Timeout#timeout.
 def timeout(n, e=Timeout::Error, &block)
   Timeout::timeout(n, e, &block)
 end
+
+# Another name for Timeout::Error, defined for backwards compatibility with
+# earlier versions of timeout.rb.
 TimeoutError = Timeout::Error
 
 if __FILE__ == $0