mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
* 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
This commit is contained in:
zzak
parent
8818a574a1
commit
8baab38ad2
2 changed files with 121 additions and 76 deletions
|
|
@ -1,3 +1,8 @@
|
|||
Thu Nov 29 17:15:00 2012 Zachary Scott <zachary@zacharyscott.net>
|
||||
|
||||
* 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@ruby-lang.org>
|
||||
|
||||
* tool/generic_erb.rb, tool/id2token.rb: add --path-separator option
|
||||
|
|
|
|||
192
gc.c
192
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 <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,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, ...}
|
||||
* 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.
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
@ -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 <code>true</code> 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 <code>true</code> 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 <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+::
|
||||
*
|
||||
*/
|
||||
|
||||
|
|
@ -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 <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 @@ 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 <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 @@ rb_gcdebug_sentinel(VALUE obj, const char *name)
|
|||
/*
|
||||
* 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 @@ 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 <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.
|
||||
|
|
|
|||
Loading…
Reference in a new issue