GC documentation update

* gc.c (GC_HEAP_FREE_SLOTS): move definition to match use order
  (RUBY_GC_HEAP_GROWTH_SLOTS): s/factor/number of slots/

* man/ruby.1: add section for GC environment variables
  [Feature #10197]

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

ChangeLog

@@ -1,3 +1,11 @@
+Tue Dec 16 07:37:18 2014  Eric Wong  <e@80x24.org>
+
+	* gc.c (GC_HEAP_FREE_SLOTS): move definition to match use order
+	  (RUBY_GC_HEAP_GROWTH_SLOTS): s/factor/number of slots/
+
+	* man/ruby.1: add section for GC environment variables
+	  [Feature #10197]
+
 Tue Dec 16 05:41:46 2014  Eric Wong  <e@80x24.org>
 
 	* tool/vcs.rb: fix Ruby 1.8 compatibility

gc.c

@@ -101,12 +101,12 @@ rb_gc_guarded_ptr_val(volatile VALUE *ptr, VALUE val)
 }
 #endif
 
-#ifndef GC_HEAP_FREE_SLOTS
-#define GC_HEAP_FREE_SLOTS  4096
-#endif
 #ifndef GC_HEAP_INIT_SLOTS
 #define GC_HEAP_INIT_SLOTS 10000
 #endif
+#ifndef GC_HEAP_FREE_SLOTS
+#define GC_HEAP_FREE_SLOTS  4096
+#endif
 #ifndef GC_HEAP_GROWTH_FACTOR
 #define GC_HEAP_GROWTH_FACTOR 1.8
 #endif
@@ -6970,7 +6970,7 @@ gc_set_initial_pages(void)
  *   - Allocate slots by this factor.
  *   - (next slots number) = (current slots number) * (this factor)
  * * RUBY_GC_HEAP_GROWTH_MAX_SLOTS (new from 2.1)
- *   - Allocation rate is limited to this factor.
+ *   - Allocation rate is limited to this number of slots.
  * * RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR (new from 2.1.1)
  *   - Do full GC when the number of old objects is more than R * N
  *     where R is this factor and

man/ruby.1

@@ -482,6 +482,95 @@ as below.
 % gem help
 .Ed
 .Pp
+.Sh GC ENVIRONMENT
+The Ruby garbage collector (GC) tracks objects in fixed-sized slots,
+but each object may have auxillary memory allocations handled by the
+malloc family of C standard library calls (
+.Xr malloc 3 ,
+.Xr calloc 3 ,
+and
+.Xr realloc 3 ) .
+In this documentatation, the "heap" refers to the Ruby object heap
+of fixed-sized slots, while "malloc" refers to auxillary
+allocations commonly referred to as the "process heap".
+Thus there are at least two possible ways to trigger GC:
+.Bl -hang -offset indent
+.It Sy 1
+Reaching the object limit.
+.It Sy 2
+Reaching the malloc limit.
+.Pp
+.El
+In Ruby 2.1, the generational GC was introduced and the limits are divided
+into young and old generations, providing two additional ways to trigger
+a GC:
+.Bl -hang -offset indent
+.It Sy 3
+Reaching the old object limit.
+.It Sy 4
+Reaching the old malloc limit.
+.El
+.Pp
+There are currently 4 possible areas where the GC may be tuned by
+the the following 11 environment variables:
+.Bl -hang -compact -width "RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR"
+.It Ev RUBY_GC_HEAP_INIT_SLOTS
+Initial allocation slots.  Introduced in Ruby 2.1, default: 10000.
+.Pp
+.It Ev RUBY_GC_HEAP_FREE_SLOTS
+Prepare at least this amount of slots after GC.
+Allocate this number slots if there are not enough slots.
+Introduced in Ruby 2.1, default: 4096
+.Pp
+.It Ev RUBY_GC_HEAP_GROWTH_FACTOR
+Increase allocation rate of heap slots by this factor.
+Introduced in Ruby 2.1, default: 1.8, minimum: 1.0 (no growth)
+.Pp
+.It Ev RUBY_GC_HEAP_GROWTH_MAX_SLOTS
+Allocation rate is limited to this number of slots,
+preventing excessive allocation due to RUBY_GC_HEAP_GROWTH_FACTOR.
+Introduced in Ruby 2.1, default: 0 (no limit)
+.Pp
+.It Ev RUBY_GC_HEAP_OLDOBJECT_LIMIT_FACTOR
+Perform a full GC when the number of old objects is more than R * N,
+where R is this factor and N is the number of old objects after the
+last full GC.
+Introduced in Ruby 2.1.1, default: 2.0
+.Pp
+.It Ev RUBY_GC_MALLOC_LIMIT
+The initial limit of young generation allocation from the malloc-family.
+GC will start when this limit is reached.
+Default: 16MB
+.Pp
+.It Ev RUBY_GC_MALLOC_LIMIT_MAX
+The maximum limit of young generation allocation from malloc before GC starts.
+Prevents excessive malloc growth due to RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR.
+Introduced in Ruby 2.1, default: 32MB.
+.Pp
+.It Ev RUBY_GC_MALLOC_LIMIT_GROWTH_FACTOR
+Increases the limit of young generation malloc calls, reducing
+GC frequency but increasing malloc growth until RUBY_GC_MALLOC_LIMIT_MAX
+is reached.
+Introduced in Ruby 2.1, default: 1.4, minimum: 1.0 (no growth)
+.Pp
+.It Ev RUBY_GC_OLDMALLOC_LIMIT
+The initial limit of old generation allocation from malloc,
+a full GC will start when this limit is reached.
+Introduced in Ruby 2.1, default: 16MB
+.Pp
+.It Ev RUBY_GC_OLDMALLOC_LIMIT_MAX
+The maximum limit of old generation allocation from malloc before a
+full GC starts.
+Prevents excessive malloc growth due to RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR.
+Introduced in Ruby 2.1, default: 128MB
+.Pp
+.It Ev RUBY_GC_OLDMALLOC_LIMIT_GROWTH_FACTOR
+Increases the limit of old generation malloc allocation, reducing full
+GC frequency but increasing malloc growth until RUBY_GC_OLDMALLOC_LIMIT_MAX
+is reached.
+Introduced in Ruby 2.1, default: 1.2, minimum: 1.0 (no growth)
+.Pp
+.El
 .Sh STACK SIZE ENVIRONMENT
 Stack size environment variables are implementation-dependent and
 subject to change with different versions of Ruby.  The VM stack is used
@@ -510,6 +599,7 @@ default: 65536 or 131072
 Machine stack size used at fiber creation.
 default: 262144 or 524288
 .Pp
+.El
 .Sh SEE ALSO
 .Bl -hang -compact -width "http://www.ruby-lang.org/123"
 .It https://www.ruby-lang.org/