From 8baab38ad20024d1f5d248a1c97bf144bc9e39e0 Mon Sep 17 00:00:00 2001 From: zzak Date: Thu, 29 Nov 2012 08:15:53 +0000 Subject: * gc.c: Documentation for GC, GC::Profiler, ObjectSpace, and ObjectSpace::WeakMap [ruby-core:50245] [Bug #7449] git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@37987 b2dd03c8-39d4-4d8f-98ff-823fe69b080e --- gc.c | 192 ++++++++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 116 insertions(+), 76 deletions(-) (limited to 'gc.c') diff --git a/gc.c b/gc.c index 8588d5025e..515fb8cde1 100644 --- a/gc.c +++ b/gc.c @@ -1669,26 +1669,33 @@ id2ref(VALUE obj, VALUE objid) * 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 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. + * 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 Fixnum hash value for this object. This - * function must have the property that a.eql?(b) implies - * a.hash == b.hash. The hash value is used by class - * Hash. Any hash value that exceeds the capacity of a - * Fixnum will be truncated before being used. + * Generates a Fixnum hash value for this object. + * + * This function must have the property that a.eql?(b) implies + * a.hash == b.hash. + * + * 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,17 +1760,22 @@ set_zero(st_data_t key, st_data_t val, st_data_t arg) * * Counts objects for each type. * - * It returns a hash 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. + * It returns a hash, such as: + * { + * :TOTAL=>10000, + * :FREE=>3011, + * :T_OBJECT=>6, + * :T_CLASS=>404, + * # ... + * } * - * 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. * */ @@ -3136,18 +3148,19 @@ gc_count(VALUE self) * * 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 @@ gc_stat(int argc, VALUE *argv, VALUE self) /* * 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 @@ gc_stress_get(VALUE self) * * 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 @@ gc_stress_set(VALUE self, VALUE flag) * call-seq: * GC.enable -> true or false * - * Enables garbage collection, returning true if garbage + * Enables garbage collection, returning +true+ if garbage * collection was previously disabled. * * GC.disable #=> false @@ -3262,7 +3275,7 @@ rb_gc_enable(void) * call-seq: * GC.disable -> true or false * - * Disables garbage collection, returning true if garbage + * Disables garbage collection, returning +true+ if garbage * collection was already disabled. * * GC.disable #=> false @@ -3661,8 +3674,9 @@ ruby_mimmalloc(size_t size) * 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 @@ gc_malloc_allocated_size(VALUE self) * 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 @@ wmap_finalize(VALUE self, VALUE objid) 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 @@ wmap_aset(VALUE self, VALUE wmap, VALUE orig) return nonspecial_obj_id(orig); } +/* Retrieves a weakly referenced object with the given key */ static VALUE wmap_aref(VALUE self, VALUE wmap) { @@ -4101,28 +4118,51 @@ gc_profile_clear(void) /* * 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 :GC_INVOKE_TIME. For example: + * from earliest to latest by +:GC_INVOKE_TIME+. + * + * 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}, - * ... + * [ + * { + * :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+:: * */ @@ -4204,7 +4244,7 @@ gc_profile_dump_on(VALUE out, VALUE (*append)(VALUE, VALUE)) /* * call-seq: - * GC::Profiler.result -> String + * GC::Profiler.result -> String * * Returns a profile data report such as: * @@ -4224,9 +4264,9 @@ gc_profile_result(void) /* * call-seq: * GC::Profiler.report - * GC::Profiler.report io + * GC::Profiler.report(io) * - * Writes the GC::Profiler#result to $stdout or the given IO object. + * Writes the GC::Profiler.result to $stdout or the given IO object. * */ @@ -4248,7 +4288,7 @@ gc_profile_report(int argc, VALUE *argv, VALUE self) /* * 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 @@ gc_profile_total_time(VALUE self) /* * 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 @@ gc_profile_enable_get(VALUE self) /* * call-seq: - * GC::Profiler.enable -> nil + * GC::Profiler.enable -> nil * * Starts the GC profiler. * @@ -4301,7 +4341,7 @@ gc_profile_enable(void) /* * call-seq: - * GC::Profiler.disable -> nil + * GC::Profiler.disable -> nil * * Stops the GC profiler. * @@ -4364,27 +4404,25 @@ rb_gcdebug_sentinel(VALUE obj, const char *name) /* * Document-class: ObjectSpace * - * The ObjectSpace 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. * - * ObjectSpace 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}" }) * - * produces: + * _produces:_ * * Finalizer three on 537763470 * Finalizer one on 537763480 @@ -4395,7 +4433,7 @@ rb_gcdebug_sentinel(VALUE obj, const char *name) /* * Document-class: ObjectSpace::WeakMap * - * An ObjectSpace::WeakMap 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 @@ rb_gcdebug_sentinel(VALUE obj, const char *name) * * require 'rdoc/rdoc' * - * puts GC::Profiler.result + * GC::Profiler.report * * GC::Profiler.disable * @@ -4418,9 +4456,11 @@ rb_gcdebug_sentinel(VALUE obj, const char *name) */ /* - * 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. + * 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. -- cgit v1.2.3