Skip to content
gc-trigger is a Ruby library for extension libraries that use many memories in external libraries.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
doc/text
ext/gc_trigger
lib
sample
.gitignore
Gemfile
README.md
Rakefile
gc-trigger.gemspec

README.md

README

Name

gc-trigger

Description

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.

Effect

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.

Install

% gem install gc-trigger

Usage

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

C API usage

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);
}

Ruby API usage

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

Author

Kouhei Sutou <kou@clear-code.com>

License

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

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

You can’t perform that action at this time.