The Kernel#binding entry was treating "feature provided by mrbgem"
as a per-method limitation, which does not scale. mruby implements
much of Ruby's standard surface area through mrbgems, so listing
each one would grow without bound.
Replace it with a single top-level note explaining the general
pattern: which features are available depends on the linked gems,
and a NoMethodError on a familiar Ruby method usually points to a
missing gem rather than a true mruby gap.
Refs #6861.
Co-authored-by: Claude <noreply@anthropic.com>
Add a section on the `ports/<name>/` mechanism (`conf.ports`
selection, fallback chain) and on the external HAL provider
naming convention (`hal-<short>-<conf>` overrides the bundled
ports/* of the gem whose name ends in `-<short>`).
Also add `ports/<name>/` to the GEM structure tree.
ref #6825
Co-authored-by: Claude <noreply@anthropic.com>
The HAL was integrated into mruby-task/ports/{posix,win}/ in
be6413f0d8 and the function names were updated in 610ff67906, but
the docs and one header still described the old separate-gem layout:
- mrbgems/mruby-task/README.md described hal-posix-task and
hal-win-task as separate gems, used the pre-rename function
names (mrb_task_hal_*), and omitted mrb_hal_task_sleep_us.
Rewrote the HAL section to match the current ports/ model.
- mrbgems/mruby-task/include/task.h had three orphan declarations
(mrb_task_hal_init / _final / _idle_cpu) from before the
rename. Removed; the real declarations are in task_hal.h.
- mrbgems/mruby-task/include/task_hal.h had a comment referring
to the removed hal-* gems.
- doc/guides/amalgamation.md listed hal-posix-io and hal-posix-task
as platform-specific gems alongside mruby-io and mruby-task; both
are now ports under the parent gem.
Reported by Asmod4n in #6825.
Co-authored-by: Claude <noreply@anthropic.com>
mruby's Class#initialize accepts re-invocation through __send__
silently, while CRuby raises TypeError. The superclass argument is
ignored on re-invocation, so no destructive side effect is possible.
Reported on Twitter by cacao_soft.
Co-authored-by: Claude <noreply@anthropic.com>
A copied Proc now always carries `MRB_PROC_ORPHAN`, so calling a
`dup`'d block that contains `break` or `return` raises
`LocalJumpError` even while the original yielding method is still on
the stack.
This is stricter than CRuby — which only marks the copy orphan once
the original yielding method returns — but matches mruby's
memory-first design: tracking the original via a back pointer in
RProc would also enlarge the GC mark set. dearblue's option (1) in
the linked issue, accepted for the simpler RProc layout.
Document the divergence in `doc/limitations.md` and add a regression
test in `test/t/proc.rb`.
close#6345
Co-authored-by: Claude <noreply@anthropic.com>
The `dfree` callback registered via `mrb_data_type.dfree` runs from
inside GC sweep, so allocating Ruby objects, calling `mrb_funcall` /
`mrb_yield`, raising exceptions, or otherwise re-entering the VM
can trigger a recursive GC that revisits the same object and causes
double-free (see #6316). Make the rule explicit in the "Wrapping C
Structures" section.
close#6316
Co-authored-by: Claude <noreply@anthropic.com>
mruby places `def` written inside `def self.foo` on the receiver's
singleton class (making it a class method of the enclosing class).
CRuby places it as an instance method of the lexical enclosing
class. This is a long-standing divergence that we've chosen to
document rather than change.
close#1536
Co-authored-by: Claude <noreply@anthropic.com>
Add a section explaining that mruby intentionally does not consult
to_int/to_str/to_ary/to_hash for implicit type coercion in built-in
operations, even though identity versions remain defined on the
corresponding built-in types. Note that Float#to_int and Array#to_ary
are not defined, and contrast with explicit conversion methods
(to_i, to_s, to_a) which do work.
ref #2979
Co-authored-by: Claude <noreply@anthropic.com>
Per gemini-code-assist review on #6790: the documentation still
showed the pre-#6790 union mrb_mt_ptr member order (proc first)
and the C99 designated-initializer form of MRB_MT_ENTRY. Update
both to match the merged code, and add a note explaining why func
must come first in the union.
Co-authored-by: Claude <noreply@anthropic.com>
add workload-specific GC tuning advice based on benchmark data:
- allocation-heavy: interval_ratio 400 for ~12% improvement
- real-time: step_limit for bounded pause times
- large buffers: malloc_threshold
- diagnosing GC overhead with GC.stat
Co-authored-by: Claude <noreply@anthropic.com>
Decrement gc_debt by the actual number of objects processed
instead of the fixed GC_STEP_SIZE. This makes step_ratio
directly affect debt repayment: larger steps repay more debt,
naturally reducing GC invocation frequency.
Co-authored-by: Claude <noreply@anthropic.com>
Expose gc_debt directly as :debt in GC.stat without sign negation.
The debt model has no threshold ceiling, so :threshold was a
misleading name. Negative debt means credit, positive means GC
is behind on collection work.
Co-authored-by: Claude <noreply@anthropic.com>
Commit 250bf6edd renamed KHASH_DEFAULT_SIZE to KHASH_INITIAL_SIZE but
missed updating build_config files and documentation. Also restore the
default value in khash.h to 32, consistent with the documented default
and the profile hierarchy (MRB_CONSTRAINED_BASELINE_PROFILE reduces it
to 16).
Since presym is now mandatory, mruby.h includes presym.h so that
MRB_SYM() macros are available everywhere without explicit include.
Remove redundant #include <mruby/presym.h> from all source files.
Co-authored-by: Claude <noreply@anthropic.com>
Amalgamated files include HAL gem source code selected at build time,
making them platform-specific. Document this as expected behavior.
Ref #6726.
Co-authored-by: Claude <noreply@anthropic.com>
Organizes 22 doc files by audience (getting started, embedders,
contributors) so visitors can find the right document quickly.
Rendered automatically by GitHub when browsing the doc/ directory.
Co-authored-by: Claude <noreply@anthropic.com>
limitations.md: use consistent CRuby/mruby labels for remaining
entries that still had specific version strings.
language.md: add upfront summary of major CRuby differences so
porting developers see the key gotchas before reading the full doc.
capi.md: add table of contents for navigating the 800+ line
reference.
Co-authored-by: Claude <noreply@anthropic.com>
language.md: reorganize stdlib tables by class name instead of gem
name so users can quickly find "does mruby have Time/File/Set?"
capi.md: fix mrb_protect example (mrb->exc is cleared after protect,
so mrb_print_error does not work; show mrb_inspect instead); fix
fiber yield example to show correct usage as return value.
gc.md, compiler.md, vm.md: add "read this if" guidance paragraphs
to help developers decide whether they need each document.
Co-authored-by: Claude <noreply@anthropic.com>
Replace duplicated GC, compiler, and VM details with concise
summaries linking to gc.md, compiler.md, and vm.md.
Co-authored-by: Claude <noreply@anthropic.com>
Update CRuby/mruby version labels to generic names. Add sections for
refinements, Encoding, integer precision by boxing mode, and
ObjectSpace limitations.
Co-authored-by: Claude <noreply@anthropic.com>
Covers supported syntax, numeric types by boxing mode, core classes,
standard library gemboxes, and key differences from CRuby.
Co-authored-by: Claude <noreply@anthropic.com>
The old inspect_ary() function no longer exists. Replace with the
current mrb_ary_to_s() implementation from src/array.c.
Co-authored-by: Claude <noreply@anthropic.com>
Add sections on 64-bit inline float rotation encoding and 32-bit
RFloat heap allocation with char[] buffer for alignment safety.
Add comparison table of all three boxing modes and ABI note.
Co-authored-by: Claude <noreply@anthropic.com>
The old name referred to "truncation" of float precision, which no
longer happens with rotation encoding. The new name describes the
actual behavior: disabling inline float encoding in word boxing.
The old name is kept as an obsolete alias for backward compatibility.
Co-authored-by: Claude <noreply@anthropic.com>
Three new documents:
- doc/guides/getting-started.md: building, running, and embedding mruby
- doc/guides/capi.md: C API reference for values, classes, methods, etc.
- doc/internal/architecture.md: internal architecture for developers
Co-authored-by: Claude <noreply@anthropic.com>
ROM method tables used static mrb_mt_tbl variables shared
across the process. The next pointer in each wrapper was
mutated by mrb_mt_init_rom(), causing cross-state
contamination when multiple mrb_state instances existed.
Allocate mrb_mt_tbl wrappers per-state via mrb_malloc().
The const mrb_mt_entry[] arrays remain static and shared.
Wrappers are tracked in mrb->rom_mt and freed at mrb_close().
Remove MRB_MT_ROM_TAB macro; add MRB_MT_INIT_ROM macro that
auto-computes size and calls the new mrb_mt_init_rom().
Co-authored-by: Claude <noreply@anthropic.com>
Move MRB_METHOD_FUNC_FL to bit 24 and visibility flags to
bits 25-26 so that MRB_ARGS_*() values (bits 0-23) can be
stored directly without shifting. This makes MRB_MT_PRIVATE
and MRB_METHOD_PRIVATE_FL the same value, eliminating the
dual-constant confusion and simplifying the MRB_MT_ENTRY()
macro to a single OR operation.
Co-authored-by: Claude <noreply@anthropic.com>
The NOARG flag (bit 2) is now redundant since the full aspec is
stored in bits 4+ of the flags field. Replace the dedicated bit
check with aspec==0 check. Store aspec in define_method_id() for
dynamically defined methods too.
Co-authored-by: Claude <noreply@anthropic.com>
Restore MRB_ARGS_* argument specs and ISO section comments to all
709 ROM method table entries. The aspec is encoded in bits 4-27 of
the flags field; MRB_MT_NOARG is now auto-derived from aspec==0.
Add MRB_MT_ENTRY_PRIVATE() macro for private methods (53 entries)
and MRB_MT_ASPEC() accessor for extracting aspec from flags.
Co-authored-by: Claude <noreply@anthropic.com>
Move conditional mrb_define_method_id() calls into ROM entry
arrays using #ifdef guards. With linear search, sizeof in
MRB_MT_ROM_TAB() adjusts automatically after preprocessing.
Cross-class ROM tables (methods a gem defines on a class it does
not own) are reverted to mrb_define_method_id(). Multiple gems
should not add ROM table layers to the same class; each layer
costs a 16-byte mrb_mt_tbl struct in RAM and deepens the lookup
chain. Use mrb_define_method_id() for cross-class methods.
Co-authored-by: Claude <noreply@anthropic.com>
Since ROM table entries are always C functions, have the
MRB_MT_ENTRY() macro set MRB_MT_FUNC automatically. This
simplifies entry definitions across all 32 source files.
Co-authored-by: Claude <noreply@anthropic.com>
Replace binary search with linear scan in mt_get(), mt_put(),
mt_del(), mt_chain_has(), and mrb_mt_foreach(). The method cache
makes repeated lookups O(1), so linear scan on cache misses is
acceptable.
This removes the sorting requirement, allowing ROM entry arrays
to be declared const. On embedded systems, const static data
resides in flash/ROM instead of RAM, saving ~8.4KB for ~700
method entries on 32-bit MCUs.
Co-authored-by: Claude <noreply@anthropic.com>
Add a dedicated uint32_t flags field to mrb_mt_entry instead of
packing flags into the lower bits of mrb_sym via MRB_MT_KEY().
The key field now stores the pure symbol ID with no shift.
On 64-bit, the flags field fills the alignment gap after mrb_sym,
so entry size remains 16 bytes (zero overhead). On 32-bit, entry
size grows from 8 to 12 bytes.
This eliminates the risk of symbol ID overflow from the 4-bit
shift, and the flags field can later store aspec (MRB_ARGS_*)
information that was previously discarded.
Co-authored-by: Claude <noreply@anthropic.com>
Yukihiro "Matz" Matsumoto