README

gc-trigger

gc-trigger is a library for extension libraries that use many memories in external libraries. For example, an extension library that manipulates images is a target library.

Ruby's GC doesn't care about memory usage of external libraries. It means that Ruby's GC isn't run when extension library uses huge memories in external libraries. For example, Ruby's GC isn't run when you open many images by the extension library.

Here is a sample program that shows gc-trigger effect. It just creates 1000 images. They can be GC-ed because they aren't referenced.

require "cairo"

1000.times do |i|
  Cairo::ImageSurface.new(:argb32, 6000, 6000)
end

Here is a graph that shows gc-trigger runs GC when it's needed. Memory usage is stable with gc-trigger.

% gem install gc-trigger

You can use C API and Ruby API. Normally, C API is suitable.

Add the following code to your mkmf.rb:

gc_trigger_spec = Gem::Specification.find_by_name("gc-trigger")
include_dir = File.join(gc_trigger_spec.gem_dir, "ext", "gc_trigger")
$CFLAGS << " -I#{include_dir}"

Include rb-gc-trigger.h in your C code:

#include <rb-gc-trigger.h>

Call rb_gc_trigger_update_memory_usage() with memory usage difference when memory usage is changed:

static VALUE
xxx_initialize(VALUE self)
{
  /* Allocate memory for external library. */
  DATA_PTR(self) = xxx_new();
  /* Notify added memory usage in byte. */
  rb_gc_trigger_update_memory_usage(1024);
  return Qnil;
}

static void
free_func(void *xxx)
{
  xxx_free(xxx);
  /* Notify freed memosy usage in byte. */
  rb_gc_trigger_update_memory_usage(-1024);
}

Require gc-trigger:

require "gc-trigger"

Call GCTrigger.update_memory_usage with memory usage difference when memory usage is changed:

def xxx_finalizer(size)
  lambda do |id|
    # Notify freed memory usage.
    GCTrigger.update_memory_usage(-size)
  end
end

def create_xxx
  xxx = XXX.new
  size = 1024
  # Register finalizer that notify freed memory usage.
  ObjectSpace.define_finalizer(xxx, xxx_finalizer(size))
  # Notify added memory usage.
  GCTrigger.update_memory_usage(size)
  xxx
end

Kouhei Sutou <kou@clear-code.com>

LGPLv3 or later. See doc/text/lgpl-3.0.txt for details.

(Kouhei Sutou has a right to change the license including contributed patches.)