mruby-mruby/doc/guides/rom-method-table.md

ROM Method Tables

ROM method tables allow C methods to be registered using static data stored in ROM (read-only memory) rather than heap-allocated RAM. This saves significant memory on embedded systems where RAM is scarce.

Motivation

In a default mruby build, mrb_open() builds ~40 classes with ~700+ method entries at startup. Each method entry is heap-allocated via individual mrb_define_method_id() calls. On a constrained MCU, this consumes ~14KB of RAM for method table metadata alone.

ROM method tables eliminate this cost by placing method metadata in static const data at compile time. Only runtime mutations (e.g., reopening a class to add methods) trigger heap allocation.

Architecture

Chained Layers

Each class has a method table (mt) pointer to a linked list of mrb_mt_tbl layers:

String.mt -> [mutable layer] -> [string_ext ROM] -> [string_core ROM] -> NULL

Lookup walks the chain front-to-back, returning the first match. The method cache makes repeated lookups O(1), so the chain walk only occurs on cache misses.

Mutation uses copy-on-write (COW): if the top layer is read-only, a new mutable layer is created in front of it. The ROM data is never modified.

Before: String.mt -> [string_ext ROM] -> [string_core ROM] -> NULL

After String.define_method(:foo):
         String.mt -> [mutable: foo] -> [string_ext ROM] -> [string_core ROM] -> NULL

Memory Layout

Each mrb_mt_tbl stores method entries as parallel arrays in a single contiguous block:

ptr -> [ vals[0] vals[1] ... vals[N-1] | keys[0] keys[1] ... keys[N-1] ]
       |<--- union mrb_mt_ptr array ------>|<--- mrb_sym (encoded) array -->|

Values are union mrb_mt_ptr (function pointer or proc pointer). Keys are mrb_sym with flags packed into the lower bits using MRB_MT_KEY().

Keys must be sorted by symbol ID for binary search. The mrb_mt_init_rom() function handles sorting at startup, so the source code order does not matter.

How to Define a ROM Method Table

Step 1: Define the Static Data

Include <mruby/internal.h> (which provides mrb_mt_tbl, union mrb_mt_ptr, MRB_MT_KEY(), and flag constants) and define the ROM data structure:

#include <mruby/internal.h>
#include <mruby/presym.h>

#define MY_ROM_MT_SIZE 3
static struct {
  union mrb_mt_ptr vals[MY_ROM_MT_SIZE];
  mrb_sym keys[MY_ROM_MT_SIZE];
} my_rom_data = {
  .vals = {
    { .func = my_method_a },
    { .func = my_method_b },
    { .func = my_method_c },
  },
  .keys = {
    MRB_MT_KEY(MRB_SYM(method_a), MRB_MT_FUNC|MRB_MT_PUBLIC),
    MRB_MT_KEY(MRB_SYM(method_b), MRB_MT_FUNC|MRB_MT_NOARG|MRB_MT_PUBLIC),
    MRB_MT_KEY(MRB_OPSYM(eq),     MRB_MT_FUNC|MRB_MT_PUBLIC),
  }
};
static mrb_mt_tbl my_rom_mt = {
  MY_ROM_MT_SIZE, MY_ROM_MT_SIZE,
  (union mrb_mt_ptr*)&my_rom_data, NULL
};

Step 2: Register in the Init Function

Replace mrb_define_method_id() calls with a single mrb_mt_init_rom() call:

void
mrb_mruby_mygem_gem_init(mrb_state *mrb)
{
  struct RClass *c = mrb_define_class_id(mrb, MRB_SYM(MyClass), mrb->object_class);
  mrb_mt_init_rom(c, &my_rom_mt);
}

mrb_mt_init_rom() sorts the keys by symbol ID, sets the readonly flag, and pushes the ROM layer onto the class's method table chain.

Step 3: Verify

Build and run the test suite. ROM tables are semantically transparent to Ruby code.

Reference

Data Types

Defined in include/mruby/internal.h:

union mrb_mt_ptr {
  const struct RProc *proc;
  mrb_func_t func;
};

typedef struct mrb_mt_tbl {
  int             size;
  int             alloc;    /* bit 30: MRB_MT_READONLY_BIT */
  union mrb_mt_ptr   *ptr;
  struct mrb_mt_tbl  *next;     /* next (lower-priority) layer, or NULL */
} mrb_mt_tbl;

Key Encoding

#define MRB_MT_KEY(sym, flags)  ((sym) << MRB_MT_KEY_SHIFT | (flags))

Flags

Flag	Value	Description
MRB_MT_FUNC	8	Entry is a C function pointer (not an RProc)
MRB_MT_NOARG	4	Method takes no arguments (optimization hint)
MRB_MT_PUBLIC	0	Public visibility
MRB_MT_PRIVATE	1	Private visibility

Most ROM entries use MRB_MT_FUNC|MRB_MT_PUBLIC or MRB_MT_FUNC|MRB_MT_NOARG|MRB_MT_PUBLIC.

How to choose flags:

• MRB_MT_FUNC: Always set for C function methods. Omit only for RProc-based methods (rare in ROM tables).
• MRB_MT_NOARG: Set when the original mrb_define_method_id() used MRB_ARGS_NONE(). This enables an optimized call path in the VM.
• MRB_MT_PUBLIC / MRB_MT_PRIVATE: Match the intended visibility. Almost all methods are public.

Symbol Macros

Use the presym macros for keys. See doc/guides/symbol.md for the full list:

MRB_SYM(size)       /* size */
MRB_SYM_B(chomp)    /* chomp! */
MRB_SYM_Q(frozen)   /* frozen? */
MRB_SYM_E(name)     /* name= */
MRB_OPSYM(add)      /* + */
MRB_OPSYM(eq)       /* == */
MRB_OPSYM(aref)     /* [] */
MRB_OPSYM(aset)     /* []= */
MRB_OPSYM(cmp)      /* <=> */
MRB_IVSYM(name)     /* @name */

API

void mrb_mt_init_rom(struct RClass *c, mrb_mt_tbl *rom);

Sorts the ROM table, sets the readonly flag, and pushes it onto the class's method table chain. Multiple calls push additional layers, which is how extension gems add methods to core classes.

Vals and Keys Correspondence

Each vals[i] corresponds to keys[i]. The function pointer in vals[i] is the C implementation of the method identified by keys[i]. Their order in the source code does not matter (they are sorted at init time), but keeping them in the same order improves readability.

Method aliases (two names for the same function) are expressed as separate entries sharing the same function pointer:

.vals = {
  { .func = mrb_str_size },   /* size */
  { .func = mrb_str_size },   /* length (alias) */
},
.keys = {
  MRB_MT_KEY(MRB_SYM(size),   MRB_MT_FUNC|MRB_MT_NOARG|MRB_MT_PUBLIC),
  MRB_MT_KEY(MRB_SYM(length), MRB_MT_FUNC|MRB_MT_NOARG|MRB_MT_PUBLIC),
}

Conditional Methods

Methods that depend on build configuration (e.g., MRB_NO_FLOAT) can be handled in two ways:

Option A: Separate ROM table under #ifdef (preferred for large blocks):

#ifndef MRB_NO_FLOAT
#define FLOAT_ROM_MT_SIZE 29
static struct { ... } float_rom_data = { ... };
static mrb_mt_tbl float_rom_mt = { ... };
#endif

void mrb_init_numeric(mrb_state *mrb) {
  mrb_mt_init_rom(integer, &integer_rom_mt);
#ifndef MRB_NO_FLOAT
  mrb_mt_init_rom(fl, &float_rom_mt);
#endif
}

Option B: Keep as mrb_define_method_id() (preferred for a few conditional methods):

void mrb_init_numeric(mrb_state *mrb) {
  mrb_mt_init_rom(integer, &integer_rom_mt);
#ifndef MRB_NO_FLOAT
  mrb_define_method_id(mrb, integer, MRB_SYM(to_f), int_to_f, MRB_ARGS_NONE());
#endif
}

Both approaches work correctly. The ROM layer and the mrb_define_method_id() calls coexist: method lookup walks the mutable layer first, then the ROM chain.

Extension Gems

Extension gems use exactly the same pattern. Since gems are initialized after core, calling mrb_mt_init_rom() pushes the gem's ROM layer in front of the core ROM layer:

/* mrbgems/mruby-string-ext/src/string.c */

#define STRING_EXT_ROM_MT_SIZE 53
static struct { ... } string_ext_rom_data = { ... };
static mrb_mt_tbl string_ext_rom_mt = { ... };

void mrb_mruby_string_ext_gem_init(mrb_state *mrb)
{
  struct RClass *s = mrb->string_class;
  mrb_mt_init_rom(s, &string_ext_rom_mt);
}

After initialization, String's method table chain looks like:

String.mt -> [string_ext ROM, 53 methods]
          -> [string_core ROM, 46 methods]
          -> NULL

A gem may also define ROM tables for multiple classes:

void mrb_mruby_mygem_gem_init(mrb_state *mrb)
{
  mrb_mt_init_rom(mrb->string_class, &string_mygem_rom_mt);
  mrb_mt_init_rom(mrb->integer_class, &integer_mygem_rom_mt);
}

Methods That Cannot Use ROM Tables

Some methods must remain as mrb_define_method_id() calls:

• Class methods (mrb_define_class_method_id()): ROM tables register instance methods only.
• Module functions (mrb_define_module_function_id()): Same reason.
• Methods requiring mrb_state* at definition time: For example, methods that create frozen RProc objects during init.
• Methods on dynamically created classes: Classes created at init time (not stored in mrb->xxx_class) that require mrb_define_class() to obtain the class pointer.

These methods are added after mrb_mt_init_rom() and go into the mutable layer that sits in front of the ROM chain.

Runtime Behavior

Open Classes (COW)

Ruby's open classes work transparently. When a Ruby program or C code adds a method to a class with a ROM table, the COW mechanism creates a mutable layer:

class String
  def my_custom_method
    42
  end
end
"hello".my_custom_method  #=> 42
"hello".size              #=> 5 (still found in ROM layer)

Method Removal

remove_method works on ROM methods using a tombstone marker. When a method in a ROM layer is removed, a special entry (MRB_MT_FUNC flag with func=NULL) is inserted into the mutable layer. The mt_get() lookup treats this marker as "not found" and stops searching the chain, effectively hiding the ROM entry. Unlike undef_method (which blocks superclass lookup), remove_method's tombstone allows the superclass method to be found.

undef_method uses a different tombstone (proc=NULL without MRB_MT_FUNC), which is returned by mt_get() so the caller raises NoMethodError without searching the superclass.

Class Duplication

Class.dup shares the ROM chain. The duplicated class gets an empty mutable layer pointing to the same ROM layers as the original. No ROM data is copied.

Garbage Collection

ROM layers are skipped during GC mark and sweep phases. Only mutable layers are scanned for live RProc references and freed when the class is collected. This reduces GC overhead.

Memory Measurement

mrb_class_mt_memsize() reports only mutable layer memory. ROM layers are not counted since they do not consume heap memory.

Converting Existing Code

To convert existing mrb_define_method_id() calls to a ROM table:

1. Count the number of method definitions that can be converted.

2. Create the ROM data structure with #define MY_ROM_MT_SIZE N.

3. Move each mrb_define_method_id() call into the ROM table:

   • The second-to-last argument (function pointer) goes into .vals.
   • The third argument (symbol) goes into .keys via MRB_MT_KEY().
   • Map the MRB_ARGS_* macro to flags:
     • MRB_ARGS_NONE() -> MRB_MT_FUNC|MRB_MT_NOARG|MRB_MT_PUBLIC
     • Anything else -> MRB_MT_FUNC|MRB_MT_PUBLIC

4. Replace the calls with mrb_mt_init_rom(c, &my_rom_mt).

5. Keep any methods that cannot be converted (see above) as individual mrb_define_method_id() calls after the ROM init.

6. Build and test: rake CONFIG=host-debug -j24 all test:run:serial

Before

void mrb_mruby_foo_gem_init(mrb_state *mrb) {
  struct RClass *foo = mrb_define_class_id(mrb, MRB_SYM(Foo), mrb->object_class);
  mrb_define_method_id(mrb, foo, MRB_SYM(bar), foo_bar, MRB_ARGS_REQ(1));
  mrb_define_method_id(mrb, foo, MRB_SYM(baz), foo_baz, MRB_ARGS_NONE());
  mrb_define_method_id(mrb, foo, MRB_OPSYM(eq), foo_eq,  MRB_ARGS_REQ(1));
}

After

#define FOO_ROM_MT_SIZE 3
static struct {
  union mrb_mt_ptr vals[FOO_ROM_MT_SIZE];
  mrb_sym keys[FOO_ROM_MT_SIZE];
} foo_rom_data = {
  .vals = {
    { .func = foo_bar },
    { .func = foo_baz },
    { .func = foo_eq },
  },
  .keys = {
    MRB_MT_KEY(MRB_SYM(bar),   MRB_MT_FUNC|MRB_MT_PUBLIC),
    MRB_MT_KEY(MRB_SYM(baz),   MRB_MT_FUNC|MRB_MT_NOARG|MRB_MT_PUBLIC),
    MRB_MT_KEY(MRB_OPSYM(eq),  MRB_MT_FUNC|MRB_MT_PUBLIC),
  }
};
static mrb_mt_tbl foo_rom_mt = {
  FOO_ROM_MT_SIZE, FOO_ROM_MT_SIZE,
  (union mrb_mt_ptr*)&foo_rom_data, NULL
};

void mrb_mruby_foo_gem_init(mrb_state *mrb) {
  struct RClass *foo = mrb_define_class_id(mrb, MRB_SYM(Foo), mrb->object_class);
  mrb_mt_init_rom(foo, &foo_rom_mt);
}