From 5c6e8b32a3aaaf4ec34f6e1335e1050ffe7232b2 Mon Sep 17 00:00:00 2001 From: "Yukihiro \"Matz\" Matsumoto" Date: Sun, 24 Oct 2021 13:21:53 +0900 Subject: doc/mruby3.1.h: separate mruby3.0 changes and mruby3.1 changes. --- doc/mruby3.0.md | 162 ++++++++++++++++++++++++++++++++++++++++++++++++++ doc/mruby3.1.md | 99 +++++++++++++++++++++++++++++++ doc/mruby3.md | 181 -------------------------------------------------------- 3 files changed, 261 insertions(+), 181 deletions(-) create mode 100644 doc/mruby3.0.md create mode 100644 doc/mruby3.1.md delete mode 100644 doc/mruby3.md (limited to 'doc') diff --git a/doc/mruby3.0.md b/doc/mruby3.0.md new file mode 100644 index 000000000..09d2c4af9 --- /dev/null +++ b/doc/mruby3.0.md @@ -0,0 +1,162 @@ +# User visible changes in `mruby3.0` + +# Build System + +## `build_config` directory + +Typical build configuration files are located in `build_config` +directory. For examples: + +* `default`: the default configuration +* `host-gprof`: compiles with `gprof` for performance tuning +* `host-m32`: compiles in gcc 32bit mode on 64bit platforms +* `boxing`: compiles all three boxing options +* `clang-asan`: compiles with `clang`'s Address Sanitizer + +You can specify the build configuration file with the +`MRUBY_CONFIG` environment variable (or `CONFIG` in short). +If the value specified by `MRUBY_CONFIG` is not the path to +the configuration file, `build_config/${MRUBY_CONFIG}.rb` is +used. So you can specify it as `rake MRUBY_CONFIG=boxing`, +for example. + +# Build Configuration Contribution + +When you write a new build configuration description, please +contribute. We welcome your contribution as a GitHub +pull-request. + +# Language Changes + +## New Syntax + +We have ported some new syntax from CRuby. + +* Single line pattern matching (`12 => x`); + mruby matches only with local variables at the moment +* Numbered block parameter (`x.map{_1 * 2}`) +* End-less `def` (`def double(x) = x*2`) + +# Configuration Options Changed + +## Renamed for consistency + +Some configuration macro names are changed for consistency (use `MRB_USE_XXX` + or `MRB_NO_XXX`). + +| mruby2 | mruby3 | +|--------------------------------|---------------------------| +| `MRB_ENABLE_ALL_SYMBOLS` | `MRB_USE_ALL_SYMBOLS` | +| `MRB_ENABLE_CXX_ABI` | `MRB_USE_CXX_ABI` | +| `MRB_ENABLE_CXX_EXCEPTION` | `MRB_USE_CXX_EXCEPTION` | +| `MRB_ENABLE_DEBUG_HOOK` | `MRB_USE_DEBUG_HOOK` | +| `MRB_DISABLE_DIRECT_THREADING` | `MRB_NO_DIRECT_THREADING` | +| `MRB_DISABLE_STDIO` | `MRB_NO_STDIO` | +| `MRB_METHOD_T_STRUCT` | `MRB_USE_METHOD_T_STRUCT` | +| `MRB_USE_FLOAT` | `MRB_USE_FLOAT32` | +| `MRB_WITHOUT_FLOAT` | `MRB_NO_FLOAT` | +| `ENABLE_LINENOISE` | `MRB_USE_LINENOISE` | +| `ENABLE_READLINE` | `MRB_USE_READLINE` | +| `DISABLE_MIRB_UNDERSCORE` | `MRB_NO_MIRB_UNDERSCORE` | + +* `MRB_USE_FLOAT32` is changed from `MRB_USE_FLOAT` to make sure `float` here + means using single precision float, and not the opposite of `MRB_NO_FLOAT`. +* `MRB_USE_METHOD_T_STRUCT` uses `struct` version of `mrb_method_t`. More + portable but consumes more memory. Turned on by default on 32bit platforms. +* `MRB_` prefix is added to those without. + +## `MRB_NO_BOXING` + +Uses `struct` to represent `mrb_value`. Consumes more memory +but easier to investigate the internal and to debug. It used +to be default `mrb_value` representation. Now the default is +`MRB_WORD_BOXING`. + +## `MRB_WORD_BOXING` + +Pack `mrb_value` in an `intptr_t` integer. Consumes less +memory compared to `MRB_NO_BOXING` especially on 32 bit +platforms. `Fixnum` size is 31 bits so some integer values +does not fit in `Fixnum` integers. + +## `MRB_NAN_BOXING` + +Pack `mrb_value` in a floating pointer number. Nothing +changed from previous versions. + +## `MRB_USE_MALLOC_TRIM` + +Call `malloc_trim(0)` from mrb_full_gc() if this macro is defined. +If you are using glibc malloc, this macro could reduce memory consumption. + +# Command Line Program + +## `bin/mruby` (by mrbgems/mruby-bin-mruby) + +The mruby3 now automatically detects `*.mrb` files without the `-b` +switch. Therefore, it can be mixed with the `*.rb` file in combination +with the `-r` switch and specified at the same time. +Here's an example that works fine: + +```console +$ bin/mruby app.mrb +$ bin/mruby -r lib1.mrb -r lib2.rb app.rb +$ bin/mruby -r lib1.rb -r lib2.rb < app.mrb +``` + +# Internal Changes + +## New Instructions + +`mruby3` introduces a few new instructions. + +Instructions that access pool[i]/syms[i] where i>255. + +* `OP_LOADL16` +* `OP_STRING16` +* `OP_LOADSYM16` + +Instructions that load a 32 bit integer. + +* `OP_LOADI32` + +Instruction that unwinds jump table for rescue/ensure. + +* `OP_JMPUW` + +Renamed from `OP_RAISE` + +* `OP_RAISEIF` + +Instruction that is reserved for the future keyword argument support. + +* OP_SENDVK + +## Removed Instructions + +Instructions for old exception handling + +* `OP_ONERR` +* `OP_POPERR` +* `OP_EPUSH` +* `OP_EPOP` + +No more operand extension + +* `OP_EXT1` +* `OP_EXT2` +* `OP_EXT3` + +## Changed Instructions + +Jump addresses used to be specified by absolute offset from the start of `iseq`. Now they are relative offset from the address of the next instruction. + +## `Random` now use `xoshiro128++`. + +For better and faster random number generation. + +## Preallocated Symbol + +Preallocated symbols are interned at compile-time. They can be accessed via symbols macros (e.g. `MRB_SYM()`). + +See [Symbols](https://github.com/mruby/mruby/blob/master/doc/guides/symbol.md). diff --git a/doc/mruby3.1.md b/doc/mruby3.1.md new file mode 100644 index 000000000..1a8c621a9 --- /dev/null +++ b/doc/mruby3.1.md @@ -0,0 +1,99 @@ +# User visible changes in `mruby3.1` from `mruby3.0` + +# Build System + +## `build_config` directory + +Several configurations for new platforms are added: + +* `cross-mingw-winetest.rb` +* `cross-mingw.rb` +* `nintendo_switch.rb` +* `serenity.rb` + +Some new configurations for added for convenience. + +* `minimal`: minimal configuration +* `host-f32`: compiles with `mrb_float` as 32 bit `float` +* `host-nofloat`: compiles with no float configuration + +And `android_arm64-v8a.rb` was renamed to `android_arm64_v8a.rb` for consistency. + +# Language Changes + +## Keyword Arguments + +CRuby3.0 compatible keyword arguments are introduced. +Keyword arguments are basically separated from ordinal arguments + +# Configuration Options Changed + +Some configuration macros are available: + +* `MRB_WORDBOX_NO_FLOAT_TRUNCATE`: by default, float values are packed in the word if possible, but define this macro to allocate float values in the heap. +* `MRB_USE_RO_DATA_P_ETEXT`: define this macro if `_etext` is available on your platform. +* `MRB_NO_DEFAULT_RO_DATA_P`: define this macro to avoid using predefined `mrb_ro_data_p()` function + +# Internal Changes + +## Reintroduced Instructions + +`mruby3.0` removed `OP_EXT1`, `OP_EXT2`, `OP_EXT3` for operand extension. But the operand size limitations was too tight for real-world application. +`mruby3.1` reintroduces those extension instructions. + +## Removed Instructions + +`mruby3.1` removed following instructions. + +* `OP_LOADL16` +* `OP_LOADSYM16` +* `OP_STRING16` +* `OP_LAMBDA16` +* `OP_BLOCK16` +* `OP_METHOD16` +* `OP_EXEC16` + +Those instructions are no longer needed by reintroduction of extension instructions. + +* `OP_SENDV` +* `OP_SENDVB` + +Those instructions for method calls with variable number of arguments are no longer needed. They are covered by `OP_SEND` instruction with `n=15`. + +## New Instructions + +`mruby3.1` introduces following new instructions. + +* `OP_GETIDX`: takes 2 operands `a[b]` +* `OP_SETIDX`: takes 3 operands `a[b]=c` +* `OP_SSEND`: takes 3 operands `a=self.b(c...)`; see `OP_SEND` +* `OP_SSENDB`: takes 3 operands `a=self.b(c...){...}`; see `OP_SEND` + +### `OP_GETIDX` and `OP_SETIDX` + +Execute `obj[int]` and `obj[int] = value` respectively, where `obj` is `string|array|hash`. + +### `OP_SSEND` and `OP_SSENDB` + +They are similar to `OP_SEND` and `OP_SENDB` respectively. They initialize the `R[a]` by `self` first so that we can skip one `OP_LOADSELF` instruction for each call. + +## Changed Instructions + +### `OP_SEND` and `OP_SENDB` + +Method calling instructions are unified. Now `OP_SEND` and `OP_SENDB` (method call with a block) can support both splat arguments and keyword arguments as well. + +The brief description of the instructions: + +|`OP_SEND` | BBB | `R(a) = call(R(a),Syms(b),R(a+1..n),R(a+n+1),R(a+n+2)..nk) c=n|nk<<4` | +|`OP_SENDB` | BBB | `R(a) = call(R(a),Syms(b),R(a+1..n),R(a+n+1..nk),R(a+n+2..nk),&R(a+n+2*nk+2)) c=n|nk<<4` | + +When `n == 15`, the method takes arguments packed in an array. When `nk == 15`, the method takes keyword arguments packed in a hash. + +### `OP_ARYPUSH` + +Now takes 2 operands and pushes multiple entries to an array. + +## `String#hash` now use `FNV1a` algorithm + +For better and faster hash values. diff --git a/doc/mruby3.md b/doc/mruby3.md deleted file mode 100644 index 30c982644..000000000 --- a/doc/mruby3.md +++ /dev/null @@ -1,181 +0,0 @@ -# User visible changes in `mruby3` from `mruby2` (as of `mruby3.1`) - -# Build System - -## `build_config` directory - -Typical build configuration files are located in `build_config` -directory. For examples: - -* `default`: the default configuration -* `host-gprof`: compiles with `gprof` for performance tuning -* `host-m32`: compiles in gcc 32bit mode on 64bit platforms -* `boxing`: compiles all three boxing options -* `clang-asan`: compiles with `clang`'s Address Sanitizer - -You can specify the build configuration file with the -`MRUBY_CONFIG` environment variable (or `CONFIG` in short). -If the value specified by `MRUBY_CONFIG` is not the path to -the configuration file, `build_config/${MRUBY_CONFIG}.rb` is -used. So you can specify it as `rake MRUBY_CONFIG=boxing`, -for example. - -# Build Configuration Contribution - -When you write a new build configuration description, please -contribute. We welcome your contribution as a GitHub -pull-request. - -# Language Changes - -## New Syntax - -We have ported some new syntax from CRuby. - -* Single line pattern matching (`12 => x`); - mruby matches only with local variables at the moment -* Numbered block parameter (`x.map{_1 * 2}`) -* End-less `def` (`def double(x) = x*2`) - -# Configuration Options Changed - -## Renamed for consistency - -Some configuration macro names are changed for consistency (use `MRB_USE_XXX` -or `MRB_NO_XXX`). - -| mruby2 | mruby3 | -|--------------------------------|---------------------------| -| `MRB_ENABLE_ALL_SYMBOLS` | `MRB_USE_ALL_SYMBOLS` | -| `MRB_ENABLE_CXX_ABI` | `MRB_USE_CXX_ABI` | -| `MRB_ENABLE_CXX_EXCEPTION` | `MRB_USE_CXX_EXCEPTION` | -| `MRB_ENABLE_DEBUG_HOOK` | `MRB_USE_DEBUG_HOOK` | -| `MRB_DISABLE_DIRECT_THREADING` | `MRB_NO_DIRECT_THREADING` | -| `MRB_DISABLE_STDIO` | `MRB_NO_STDIO` | -| `MRB_METHOD_T_STRUCT` | `MRB_USE_METHOD_T_STRUCT` | -| `MRB_USE_FLOAT` | `MRB_USE_FLOAT32` | -| `MRB_WITHOUT_FLOAT` | `MRB_NO_FLOAT` | -| `ENABLE_LINENOISE` | `MRB_USE_LINENOISE` | -| `ENABLE_READLINE` | `MRB_USE_READLINE` | -| `DISABLE_MIRB_UNDERSCORE` | `MRB_NO_MIRB_UNDERSCORE` | - -* `MRB_USE_FLOAT32` is changed from `MRB_USE_FLOAT` to make sure `float` here - means using single precision float, and not the opposite of `MRB_NO_FLOAT`. -* `MRB_USE_METHOD_T_STRUCT` uses `struct` version of `mrb_method_t`. More - portable but consumes more memory. Turned on by default on 32bit platforms. -* `MRB_` prefix is added to those without. - -## `MRB_NO_BOXING` - -Uses `struct` to represent `mrb_value`. Consumes more memory -but easier to investigate the internal and to debug. It used -to be default `mrb_value` representation. Now the default is -`MRB_WORD_BOXING`. - -## `MRB_WORD_BOXING` - -Pack `mrb_value` in an `intptr_t` integer. Consumes less -memory compared to `MRB_NO_BOXING` especially on 32-bit -platforms. Inlined integer size is 31 bits, so some `mrb_int` -values does not fit in `mrb_value`. Those integers are allocated -in the object heap as `struct RInteger`. - -## `MRB_NAN_BOXING` - -Pack `mrb_value` in a floating-point number. Nothing -changed from previous versions. - -## `MRB_USE_MALLOC_TRIM` - -Call `malloc_trim(0)` from mrb_full_gc() if this macro is defined. -If you are using glibc malloc, this macro could reduce memory consumption. - -# Command Line Program - -## `bin/mruby` (by mrbgems/mruby-bin-mruby) - -The mruby3 now automatically detects `*.mrb` files without the `-b` -switch. Therefore, it can be mixed with the `*.rb` file in combination -with the `-r` switch and specified at the same time. -Here's an example that works fine: - -```console -$ bin/mruby app.mrb -$ bin/mruby -r lib1.mrb -r lib2.rb app.rb -$ bin/mruby -r lib1.rb -r lib2.rb < app.mrb -``` - -# Internal Changes - -## New Instructions - -`mruby3` introduces a few new instructions. - -### `OP_LOADI16` and `OP_LOADI32` - -Load a 16/32-bit integer. - -### `OP_JMPUW` - -Unwinds jump table for rescue/ensure. - -### `OP_RAISEIF` - -Renamed from `OP_RAISE` - -### `OP_SYMBOL` - -Generates a symbol from the pool string. This is a combination of `OP_STRING` and `OP_INTERN`. - -### `OP_GETIDX` and `OP_SETIDX` - -Execute `obj[int]` and `obj[int] = value` respectively, where `obj` is `string|array|hash`. - -### `OP_SSEND` and `OP_SSENDB` - -They are similar to `OP_SEND` and `OP_SENDB` respectively. They initialize the `R[a]` by `self` so that we can skip one `OP_LOADSEND` instruction for each call. - -## Changed Instructions - -### Jump instructions - -Jump addresses used to be specified by absolute offset from the start of `iseq`. Now they are relative offset from the address of the next instruction. - -### `OP_SEND` and `OP_SENDB` - -Method calling instructions are unified. Now `OP_SEND` and `OP_SENDB` (method call with a block) can support both splat arguments and keyword arguments as well. - -The brief description of the instructions: - -|`OP_SEND` | BBB | `R(a) = call(R(a),Syms(b),R(a+1..n),R(a+n+1),R(a+n+2)..nk) c=n|nk<<4` | -|`OP_SENDB` | BBB | `R(a) = call(R(a),Syms(b),R(a+1..n),R(a+n+1..nk),R(a+n+2..nk),&R(a+n+2*nk+2)) c=n|nk<<4` | - -When `n == 15`, the method takes arguments packed in an array. When `nk == 15`, the method takes keyword arguments packed in a hash. - -### `OP_ARYPUSH` - -Now takes 2 operands and pushes multiple entries to an array. - -## Removed Instructions - -Instructions for old exception handling - -* `OP_ONERR` -* `OP_POPERR` -* `OP_EPUSH` -* `OP_EPOP` - -Instructions for method calls with variable number of arguments. They are covered by `OP_SEND` instruction with `n=15`. - -* `OP_SENDV` -* `OP_SENDVB` - -## `Random` now use `xoshiro128++` - -For better and faster random number generation. - -## Preallocated Symbol - -Preallocated symbols are interned at compile-time. They can be accessed via symbols macros (e.g. `MRB_SYM()`). - -See [Symbols](./guides/symbol.md). -- cgit v1.2.3