diff --git a/ext/objspace/objspace.c b/ext/objspace/objspace.c index b12f5cb7c8c80e..457ffc278915e2 100644 --- a/ext/objspace/objspace.c +++ b/ext/objspace/objspace.c @@ -108,28 +108,24 @@ each_object_with_flags(each_obj_with_flags cb, void *ctx) /* * call-seq: - * ObjectSpace.memsize_of_all([klass]) -> Integer + * ObjectSpace.memsize_of_all(klass = nil) -> integer * - * Return consuming memory size of all living objects in bytes. + * Returns the total memory size of all living objects in bytes. * - * If +klass+ (should be Class object) is given, return the total memory size - * of instances of the given class. + * ObjectSpace.memsize_of_all # => 12502001 * - * Note that the returned size is incomplete. You need to deal with this - * information as only a *HINT*. Especially, the size of +T_DATA+ may not be - * correct. - * - * Note that this method does *NOT* return total malloc'ed memory size. + * If +klass+ is given (which must be a Class or Module), returns the total + * memory size of objects whose class is, or is a subclass, of +klass+. * - * This method can be defined by the following Ruby code: + * class MyClass; end + * ObjectSpace.memsize_of_all(MyClass) # => 0 + * o = MyClass.new + * ObjectSpace.memsize_of_all(MyClass) # => 40 * - * def memsize_of_all klass = false - * total = 0 - * ObjectSpace.each_object{|e| - * total += ObjectSpace.memsize_of(e) if klass == false || e.kind_of?(klass) - * } - * total - * end + * Note that the value returned may be an underestimate of the actual amount + * of memory used. Therefore, the value returned should only be used as a hint, + * rather than a source of truth. In particular, the size of +T_DATA+ objects may + * not be correct. * * This method is only expected to work with C Ruby. */ diff --git a/lib/timeout.rb b/lib/timeout.rb index 5d1f61d8af2421..e293e3be7c9eea 100644 --- a/lib/timeout.rb +++ b/lib/timeout.rb @@ -212,17 +212,17 @@ def self.synchronize(mutex, &block) # value of 0 or +nil+ will execute the block without any timeout. # Any negative number will raise an ArgumentError. # +klass+:: Exception Class to raise if the block fails to terminate - # in +sec+ seconds. Omitting will use the default, Timeout::Error + # in +sec+ seconds. Omitting will use the default, Timeout::Error. # +message+:: Error message to raise with Exception Class. - # Omitting will use the default, "execution expired" + # Omitting will use the default, "execution expired". # # Returns the result of the block *if* the block completed before # +sec+ seconds, otherwise raises an exception, based on the value of +klass+. # # The exception raised to terminate the given block is the given +klass+, or # Timeout::ExitException if +klass+ is not given. The reason for that behavior - # is that Timeout::Error inherits from RuntimeError and might be caught unexpectedly by `rescue`. - # Timeout::ExitException inherits from Exception so it will only be rescued by `rescue Exception`. + # is that Timeout::Error inherits from RuntimeError and might be caught unexpectedly by +rescue+. + # Timeout::ExitException inherits from Exception so it will only be rescued by rescue Exception. # Note that the Timeout::ExitException is translated to a Timeout::Error once it reaches the Timeout.timeout call, # so outside that call it will be a Timeout::Error. # @@ -231,7 +231,7 @@ def self.synchronize(mutex, &block) # For those reasons, this method cannot be relied on to enforce timeouts for untrusted blocks. # # If a scheduler is defined, it will be used to handle the timeout by invoking - # Scheduler#timeout_after. + # Fiber::Scheduler#timeout_after. # # 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 @@ -239,13 +239,13 @@ def self.synchronize(mutex, &block) # # ==== Ensuring the exception does not fire inside ensure blocks # - # When using Timeout.timeout it can be desirable to ensure the timeout exception does not fire inside an +ensure+ block. - # The simplest and best way to do so it to put the Timeout.timeout call inside the body of the begin/ensure/end: + # When using Timeout.timeout, it can be desirable to ensure the timeout exception does not fire inside an +ensure+ block. + # The simplest and best way to do so is to put the Timeout.timeout call inside the body of the +begin+/+ensure+/+end+: # # begin # Timeout.timeout(sec) { some_long_operation } # ensure - # cleanup # safe, cannot be interrupt by timeout + # cleanup # safe, cannot be interrupted by timeout # end # # If that is not feasible, e.g. if there are +ensure+ blocks inside +some_long_operation+, @@ -263,17 +263,17 @@ def self.synchronize(mutex, &block) # end # } # - # An important thing to note is the need to pass an exception klass to Timeout.timeout, - # otherwise it does not work. Specifically, using +Thread.handle_interrupt(Timeout::ExitException => ...)+ + # An important thing to note is the need to pass an exception +klass+ to Timeout.timeout, + # otherwise it does not work. Specifically, using Thread.handle_interrupt(Timeout::ExitException => ...) # is unsupported and causes subtle errors like raising the wrong exception outside the block, do not use that. # # Note that Thread.handle_interrupt is somewhat dangerous because if setup or cleanup hangs # then the current thread will hang too and the timeout will never fire. # Also note the block might run for longer than +sec+ seconds: - # e.g. some_long_operation executes for +sec+ seconds + whatever time cleanup takes. + # e.g. +some_long_operation+ executes for +sec+ seconds + whatever time cleanup takes. # - # If you want the timeout to only happen on blocking operations one can use :on_blocking - # instead of :immediate. However, that means if the block uses no blocking operations after +sec+ seconds, + # If you want the timeout to only happen on blocking operations, one can use +:on_blocking+ + # instead of +:immediate+. However, that means if the block uses no blocking operations after +sec+ seconds, # the block will not be interrupted. def self.timeout(sec, klass = nil, message = nil, &block) #:yield: +sec+ return yield(sec) if sec == nil or sec.zero?