Module: Mwrap

Defined in:

ext/mwrap/mwrap.c,
ext/mwrap/mwrap.c

Overview

require ‘mwrap’

Mwrap has a dual function as both a Ruby C extension and LD_PRELOAD wrapper. As a Ruby C extension, it exposes a limited Ruby API. To be effective at gathering status, mwrap must be loaded as a LD_PRELOAD (using the mwrap(1) executable makes it easy)

ENVIRONMENT

The “MWRAP” environment variable contains a comma-delimited list of key:value options for automatically dumping at program exit.

• dump_fd: a writable FD to dump to

• dump_path: a path to dump to, the file is opened in O_APPEND mode

• dump_min: the minimum allocation size (total) to dump

If both ‘dump_fd’ and ‘dump_path’ are specified, dump_path takes precedence.

Class Method Summary

• .clear ⇒ Object

  Mwrap.clear -> nil.

• .dump(*args) ⇒ Object

  Mwrap.dump([ [, min]] -> nil.

• .each([min]) {|location, total_bytes, call_count| ... } ⇒ Object

  Yields each entry of the of the table to a caller-supplied block.

• .reset ⇒ Object

  Mwrap.reset -> nil.

Class Method Details

.clear ⇒ Object

Mwrap.clear -> nil

Atomically replaces the totals table and destroys the old one. This resets all statistics. It is more expensive than ‘Mwrap.reset’ as new allocations will need to be made to repopulate the new table.

# File 'ext/mwrap/mwrap.c', line 398

static VALUE mwrap_clear(VALUE mod)
{
	rb_thread_call_without_gvl(totals_clear, 0, 0, 0);
	return Qnil;
}

.dump(*args) ⇒ Object

Mwrap.dump([ [, min]] -> nil

Dumps the current totals to io which must be an IO object (StringIO and similar are not supported). Total sizes smaller than or equal to min are skipped.

The output is space-delimited by 3 columns:

total_size call_count location

# File 'ext/mwrap/mwrap.c', line 339

static VALUE mwrap_dump(int argc, VALUE * argv, VALUE mod)
{
	VALUE io, min;
	struct dump_arg a;
	rb_io_t *fptr;

	rb_scan_args(argc, argv, "02", &io, &min);

	if (NIL_P(io))
		/* library may be linked w/o Ruby */
		io = *((VALUE *)dlsym(RTLD_DEFAULT, "rb_stderr"));

	a.min = NIL_P(min) ? 0 : NUM2SIZET(min);
	io = rb_io_get_write_io(io);
	GetOpenFile(io, fptr);
	a.fp = rb_io_stdio_file(fptr);

	rb_thread_call_without_gvl(dump_to_file, &a, 0, 0);
	RB_GC_GUARD(io);
	return Qnil;
}

.each([min]) {|location, total_bytes, call_count| ... } ⇒ Object

Yields each entry of the of the table to a caller-supplied block. min may be specified to filter out lines with total_bytes equal-to-or-smaller-than the supplied minimum.

Yields:

• (location, total_bytes, call_count)

# File 'ext/mwrap/mwrap.c', line 486

static VALUE mwrap_each(int argc, VALUE * argv, VALUE mod)
{
	VALUE min;
	struct dump_arg a;

	rb_scan_args(argc, argv, "01", &min);
	a.min = NIL_P(min) ? 0 : NUM2SIZET(min);

	++locating;
	rcu_read_lock();

	return rb_ensure(dump_each_rcu, (VALUE)&a, dump_ensure, 0);
}

.reset ⇒ Object

Mwrap.reset -> nil

Resets the the total tables by zero-ing all counters. This resets all statistics and is less costly than ‘Mwrap.clear’ but is not an atomic operation.

# File 'ext/mwrap/mwrap.c', line 429

static VALUE mwrap_reset(VALUE mod)
{
	rb_thread_call_without_gvl(totals_reset, 0, 0, 0);
	return Qnil;
}