gc.c: rb_gc_adjust_memory_usage

* gc.c (rb_gc_adjust_memory_usage): notify memory usage to the GC
  engine by extension libraries, to trigger GC.  [Feature #12690]

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

1 files changed, 12 insertions, 0 deletions

diff --git a/doc/extension.rdoc b/doc/extension.rdoc
index 7eb173debe..b8fbb787ba 100644
--- a/doc/extension.rdoc
+++ b/doc/extension.rdoc
@@ -1652,6 +1652,18 @@ int rb_remove_event_hook(rb_event_hook_func_t func) ::
 
   Removes the specified hook function.
 
+== Memory usage
+
+void rb_gc_adjust_memory_usage(ssize_t diff) ::
+
+  Adjusts the amount of registered external memory.  You can tell GC how
+  much memory is used by an external library by this function.  Calling
+  this function with positive diff means the memory usage is increased;
+  new memory block is allocated or a block is reallocated as larger
+  size.  Calling this function with negative diff means the memory usage
+  is decreased; a memory block is freed or a block is reallocated as
+  smaller size.  This function may trigger the GC.
+
 == Macros for Compatibility
 
 Some macros to check API compatibilities are available by default.