ruby-changes:25930
From: zzak <ko1@a...>
Date: Thu, 29 Nov 2012 17:17:30 +0900 (JST)
Subject: [ruby-changes:25930] zzak:r37987 (trunk): * gc.c: Documentation for GC, GC::Profiler, ObjectSpace, and
zzak 2012-11-29 17:15:53 +0900 (Thu, 29 Nov 2012) New Revision: 37987 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=37987 Log: * gc.c: Documentation for GC, GC::Profiler, ObjectSpace, and ObjectSpace::WeakMap [ruby-core:50245] [Bug #7449] Modified files: trunk/ChangeLog trunk/gc.c Index: ChangeLog =================================================================== --- ChangeLog (revision 37986) +++ ChangeLog (revision 37987) @@ -1,3 +1,8 @@ +Thu Nov 29 17:15:00 2012 Zachary Scott <zachary@z...> + + * gc.c: Documentation for GC, GC::Profiler, ObjectSpace, and + ObjectSpace::WeakMap [ruby-core:50245] [Bug #7449] + Thu Nov 29 17:12:26 2012 Nobuyoshi Nakada <nobu@r...> * tool/generic_erb.rb, tool/id2token.rb: add --path-separator option Index: gc.c =================================================================== --- gc.c (revision 37986) +++ gc.c (revision 37987) @@ -1669,26 +1669,33 @@ * Document-method: object_id * * call-seq: - * obj.__id__ -> fixnum - * obj.object_id -> fixnum + * obj.__id__ -> integer + * obj.object_id -> integer * - * Returns an integer identifier for <i>obj</i>. The same number will - * be returned on all calls to <code>id</code> for a given object, and - * no two active objects will share an id. - * <code>Object#object_id</code> is a different concept from the - * <code>:name</code> notation, which returns the symbol id of - * <code>name</code>. Replaces the deprecated <code>Object#id</code>. + * Returns an integer identifier for +obj+. + * + * The same number will be returned on all calls to +id+ for a given object, + * and no two active objects will share an id. + * + * Object#object_id is a different concept from the +:name+ notation, which + * returns the symbol id of +name+. + * + * Replaces the deprecated Object#id. */ /* * call-seq: * obj.hash -> fixnum * - * Generates a <code>Fixnum</code> hash value for this object. This - * function must have the property that <code>a.eql?(b)</code> implies - * <code>a.hash == b.hash</code>. The hash value is used by class - * <code>Hash</code>. Any hash value that exceeds the capacity of a - * <code>Fixnum</code> will be truncated before being used. + * Generates a Fixnum hash value for this object. + * + * This function must have the property that <code>a.eql?(b)</code> implies + * <code>a.hash == b.hash</code>. + * + * The hash value is used by Hash class. + * + * Any hash value that exceeds the capacity of a Fixnum will be truncated + * before being used. */ VALUE @@ -1753,18 +1760,23 @@ * * Counts objects for each type. * - * It returns a hash as: - * {:TOTAL=>10000, :FREE=>3011, :T_OBJECT=>6, :T_CLASS=>404, ...} + * It returns a hash, such as: + * { + * :TOTAL=>10000, + * :FREE=>3011, + * :T_OBJECT=>6, + * :T_CLASS=>404, + * # ... + * } * - * If the optional argument, result_hash, is given, - * it is overwritten and returned. - * This is intended to avoid probe effect. - * - * The contents of the returned hash is implementation defined. + * The contents of the returned hash are implementation specific. * It may be changed in future. * - * This method is not expected to work except C Ruby. + * If the optional argument +result_hash+ is given, + * it is overwritten and returned. This is intended to avoid probe effect. * + * This method is only expected to work on C Ruby. + * */ static VALUE @@ -3136,18 +3148,19 @@ * * The hash includes information about internal statistics about GC such as: * - * { :count=>0, - * :heap_used=>12, - * :heap_length=>12, - * :heap_increment=>0, - * :heap_live_num=>7539, - * :heap_free_num=>88, - * :heap_final_num=>0, - * :total_allocated_object=>7630, - * :total_freed_object=>88 - * } + * { + * :count=>0, + * :heap_used=>12, + * :heap_length=>12, + * :heap_increment=>0, + * :heap_live_num=>7539, + * :heap_free_num=>88, + * :heap_final_num=>0, + * :total_allocated_object=>7630, + * :total_freed_object=>88 + * } * - * The contents of the hash are implementation defined and may be changed in + * The contents of the hash are implementation specific and may be changed in * the future. * * This method is only expected to work on C Ruby. @@ -3202,9 +3215,9 @@ /* * call-seq: - * GC.stress -> true or false + * GC.stress -> true or false * - * returns current status of GC stress mode. + * Returns current status of GC stress mode. */ static VALUE @@ -3220,10 +3233,10 @@ * * Updates the GC stress mode. * - * When stress mode is enabled the GC is invoked at every GC opportunity: + * When stress mode is enabled, the GC is invoked at every GC opportunity: * all memory and object allocations. * - * Enabling stress mode makes Ruby very slow, it is only for debugging. + * Enabling stress mode will degrade performance, it is only for debugging. */ static VALUE @@ -3239,7 +3252,7 @@ * call-seq: * GC.enable -> true or false * - * Enables garbage collection, returning <code>true</code> if garbage + * Enables garbage collection, returning +true+ if garbage * collection was previously disabled. * * GC.disable #=> false @@ -3262,7 +3275,7 @@ * call-seq: * GC.disable -> true or false * - * Disables garbage collection, returning <code>true</code> if garbage + * Disables garbage collection, returning +true+ if garbage * collection was already disabled. * * GC.disable #=> false @@ -3661,8 +3674,9 @@ * call-seq: * GC.malloc_allocated_size -> Integer * - * Returns the size of memory allocated by malloc(). Only available if ruby - * was built with CALC_EXACT_MALLOC_SIZE. + * Returns the size of memory allocated by malloc(). + * + * Only available if ruby was built with +CALC_EXACT_MALLOC_SIZE+. */ static VALUE @@ -3675,8 +3689,9 @@ * call-seq: * GC.malloc_allocations -> Integer * - * Returns the number of malloc() allocations. Only available if ruby was - * built with CALC_EXACT_MALLOC_SIZE. + * Returns the number of malloc() allocations. + * + * Only available if ruby was built with +CALC_EXACT_MALLOC_SIZE+. */ static VALUE @@ -3809,6 +3824,7 @@ return self; } +/* Creates a weak reference from the given key to the given value */ static VALUE wmap_aset(VALUE self, VALUE wmap, VALUE orig) { @@ -3831,6 +3847,7 @@ return nonspecial_obj_id(orig); } +/* Retrieves a weakly referenced object with the given key */ static VALUE wmap_aref(VALUE self, VALUE wmap) { @@ -4101,29 +4118,52 @@ /* * call-seq: - * GC::Profiler.raw_data -> [Hash, ...] + * GC::Profiler.raw_data -> [Hash, ...] * * Returns an Array of individual raw profile data Hashes ordered - * from earliest to latest by <tt>:GC_INVOKE_TIME</tt>. For example: + * from earliest to latest by +:GC_INVOKE_TIME+. * - * [{:GC_TIME=>1.3000000000000858e-05, - * :GC_INVOKE_TIME=>0.010634999999999999, - * :HEAP_USE_SIZE=>289640, - * :HEAP_TOTAL_SIZE=>588960, - * :HEAP_TOTAL_OBJECTS=>14724, - * :GC_IS_MARKED=>false}, - * ... + * For example: + * + * [ + * { + * :GC_TIME=>1.3000000000000858e-05, + * :GC_INVOKE_TIME=>0.010634999999999999, + * :HEAP_USE_SIZE=>289640, + * :HEAP_TOTAL_SIZE=>588960, + * :HEAP_TOTAL_OBJECTS=>14724, + * :GC_IS_MARKED=>false + * }, + * # ... * ] * * The keys mean: * - * +:GC_TIME+:: Time taken for this run in seconds - * +:GC_INVOKE_TIME+:: Time the GC was invoked since startup in seconds - * +:HEAP_USE_SIZE+:: Bytes of heap used - * +:HEAP_TOTAL_SIZE+:: Size of heap in bytes - * +:HEAP_TOTAL_OBJECTS+:: Number of objects - * +:GC_IS_MARKED+:: Is the GC in the mark phase + * +:GC_TIME+:: + * Time elapsed in seconds for this GC run + * +:GC_INVOKE_TIME+:: + * Time elapsed in seconds from startup to when the GC was invoked + * +:HEAP_USE_SIZE+:: + * Total bytes of heap used + * +:HEAP_TOTAL_SIZE+:: + * Total size of heap in bytes + * +:HEAP_TOTAL_OBJECTS+:: + * Total number of objects + * +:GC_IS_MARKED+:: + * Returns +true+ if the GC is in mark phase * + * If ruby was built with +GC_PROFILE_MORE_DETAIL+, you will also have access + * to the following hash keys: + * + * +:GC_MARK_TIME+:: + * +:GC_SWEEP_TIME+:: + * +:ALLOCATE_INCREASE+:: + * +:ALLOCATE_LIMIT+:: + * +:HEAP_USE_SLOTS+:: + * +:HEAP_LIVE_OBJECTS+:: + * +:HEAP_FREE_OBJECTS+:: + * +:HAVE_FINALIZE+:: + * */ static VALUE @@ -4204,7 +4244,7 @@ /* * call-seq: - * GC::Profiler.result -> String + * GC::Profiler.result -> String * * Returns a profile data report such as: * @@ -4224,9 +4264,9 @@ /* * call-seq: * GC::Profiler.report - * GC::Profiler.report io + * GC::Profiler.report(io) * - * Writes the GC::Profiler#result to <tt>$stdout</tt> or the given IO object. + * Writes the GC::Profiler.result to <tt>$stdout</tt> or the given IO object. * */ @@ -4248,7 +4288,7 @@ /* * call-seq: - * GC::Profiler.total_time -> float + * GC::Profiler.total_time -> float * * The total time used for garbage collection in seconds */ @@ -4270,7 +4310,7 @@ /* * call-seq: - * GC::Profiler.enabled? -> true or false + * GC::Profiler.enabled? -> true or false * * The current status of GC profile mode. */ @@ -4284,7 +4324,7 @@ /* * call-seq: - * GC::Profiler.enable -> nil + * GC::Profiler.enable -> nil * * Starts the GC profiler. * @@ -4301,7 +4341,7 @@ /* * call-seq: - * GC::Profiler.disable -> nil + * GC::Profiler.disable -> nil * * Stops the GC profiler. * @@ -4364,27 +4404,25 @@ /* * Document-class: ObjectSpace * - * The <code>ObjectSpace</code> module contains a number of routines + * The ObjectSpace module contains a number of routines * that interact with the garbage collection facility and allow you to * traverse all living objects with an iterator. * - * <code>ObjectSpace</code> also provides support for object - * finalizers, procs that will be called when a specific object is - * about to be destroyed by garbage collection. + * ObjectSpace also provides support for object finalizers, procs that will be + * called when a specific object is about to be destroyed by garbage + * collection. * * include ObjectSpace * - * * a = "A" * b = "B" * c = "C" * - * * define_finalizer(a, proc {|id| puts "Finalizer one on #{id}" }) * define_finalizer(a, proc {|id| puts "Finalizer two on #{id}" }) * define_finalizer(b, proc {|id| puts "Finalizer three on #{id}" }) * - * <em>produces:</em> + * _produces:_ * * Finalizer three on 537763470 * Finalizer one on 537763480 @@ -4395,7 +4433,7 @@ /* * Document-class: ObjectSpace::WeakMap * - * An <code>ObjectSpace::WeakMap</code> object holds references to + * An ObjectSpace::WeakMap object holds references to * any objects, but those objects can get disposed by GC. */ @@ -4410,7 +4448,7 @@ * * require 'rdoc/rdoc' * - * puts GC::Profiler.result + * GC::Profiler.report * * GC::Profiler.disable * @@ -4418,10 +4456,12 @@ */ /* - * The <code>GC</code> module provides an interface to Ruby's mark and - * sweep garbage collection mechanism. Some of the underlying methods - * are also available via the ObjectSpace module. + * The GC module provides an interface to Ruby's mark and + * sweep garbage collection mechanism. * + * Some of the underlying methods are also available via the ObjectSpace + * module. + * * You may obtain information about the operation of the GC through * GC::Profiler. */ -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/