script_core 0.2.3 → 0.3.0

data/ext/enterprise_script_service/mruby/doc/guides/gc-arena-howto.md

@@ -3,7 +3,7 @@
 _This is an English translation of [Matz's blog post][matz blog post]
 written in Japanese._
 _Some parts are updated to reflect recent changes._
-[matz blog post]: http://www.rubyist.net/~matz/20130731.html
+[matz blog post]: https://www.rubyist.net/~matz/20130731.html
 
 When you are extending mruby using C language, you may encounter
 mysterious "arena overflow error" or memory leak or very slow

data/ext/enterprise_script_service/mruby/doc/guides/mrbconf.md

@@ -1,7 +1,9 @@
 # mruby configuration macros.
 
 ## How to use these macros.
+
 You can use mrbconfs with following ways:
+
 * Write them in `mrbconf.h`.
  * Using compiler flags is preferred  when building a cross binaries or multiple mruby binaries
  since it's easier to use different mrbconf per each `MRuby::Build`.
@@ -11,7 +13,9 @@ You can use mrbconfs with following ways:
  changes `struct` layout and cause memory access error when C and other language(e.g., C++) is mixed.
 
 ## stdio setting.
-`MRB_DISABLE_STDIO`
+
+`MRB_NO_STDIO`
+
 * When defined `<stdio.h>` functions won't be used.
 * Some features will be disabled when this is enabled:
   * `mrb_irep` load/dump from/to file.
@@ -19,84 +23,97 @@ You can use mrbconfs with following ways:
   * Printing features in **src/print.c**.
 
 ## Debug macros.
-`MRB_ENABLE_DEBUG_HOOK`
+
+`MRB_USE_DEBUG_HOOK`
+
 * When defined code fetch hook and debug OP hook will be enabled.
 * When using any of the hook set function pointer `code_fetch_hook` and/or `debug_op_hook` of `mrb_state`.
 * Fetch hook will be called before any OP.
 * Debug OP hook will be called when dispatching `OP_DEBUG`.
 
 `MRB_DEBUG`
+
 * When defined `mrb_assert*` macro will be defined with macros from `<assert.h>`.
 * Could be enabled via `enable_debug` method of `MRuby::Build`.
 
 ## Stack configuration
 
 `MRB_STACK_EXTEND_DOUBLING`
+
 * If defined doubles the stack size when extending it.
 * Else extends stack with `MRB_STACK_GROWTH`.
 
 `MRB_STACK_GROWTH`
+
 * Default value is `128`.
 * Used in stack extending.
 * Ignored when `MRB_STACK_EXTEND_DOUBLING` is defined.
 
 `MRB_STACK_MAX`
+
 * Default value is `0x40000 - MRB_STACK_GROWTH`.
 * Raises `RuntimeError` when stack size exceeds this value.
 
 ## Primitive type configuration.
 
-`MRB_USE_FLOAT`
+`MRB_USE_FLOAT32`
+
 * When defined single precision floating point type(C type `float`) is used as `mrb_float`.
-* Else double precision floating point type(C type `double`) is used as `mrb_float`.
+* Otherwise double precision floating point type(C type `double`) is used as `mrb_float`.
+
+`MRB_NO_FLOAT`
 
-`MRB_WITHOUT_FLOAT`
 * When defined removes floating point numbers from mruby.
 * It makes mruby easier to handle in "Microcontroller without FPU" and "Kernel Space".
 
-`MRB_INT16`
-* When defined `int16_t` will be defined as `mrb_int`.
-* Conflicts with `MRB_INT32` and `MRB_INT64`.
-
 `MRB_INT32`
-* When defined, or both `MRB_INT16` and `MRB_INT64` are not defined on 32-bit CPU mode, `int32_t` will be defined as `mrb_int`.
-* Conflicts with `MRB_INT16` and `MRB_INT64`.
+
+* When defined, or `MRB_INT64` are not defined on 32-bit CPU mode, `mrb_int` will be defined as `int32_t`.
+* Conflicts with `MRB_INT64`.
 
 `MRB_INT64`
-* When defined, or both `MRB_INT16` and `MRB_INT32` are not defined on 64-bit CPU mode, `int64_t` will be defined as `mrb_int`.
-* Conflicts with `MRB_INT16` and `MRB_INT32`.
+
+* When defined, or `MRB_INT32` are not defined on 64-bit CPU mode, `mrb_int` will be defined as `int64_t`.
+* Conflicts with `MRB_INT32`.
 
 ## Garbage collector configuration.
 
 `MRB_GC_STRESS`
+
 * When defined full GC is emitted per each `RBasic` allocation.
 * Mainly used in memory manager debugging.
 
 `MRB_GC_TURN_OFF_GENERATIONAL`
+
 * When defined turns generational GC by default.
 
 `MRB_GC_FIXED_ARENA`
+
 * When defined used fixed size GC arena.
 * Raises `RuntimeError` when this is defined and GC arena size exceeds `MRB_GC_ARENA_SIZE`.
 * Useful tracking unnecessary mruby object allocation.
 
 `MRB_GC_ARENA_SIZE`
+
 * Default value is `100`.
 * Ignored when `MRB_GC_FIXED_ARENA` isn't defined.
 * Defines fixed GC arena size.
 
 `MRB_HEAP_PAGE_SIZE`
+
 * Defines value is `1024`.
 * Specifies number of `RBasic` per each heap page.
 
 ## Memory pool configuration.
 
 `POOL_ALIGNMENT`
+
 * Default value is `4`.
 * If you're allocating data types that requires alignment more than default value define the
 largest value of required alignment.
 
 `POOL_PAGE_SIZE`
+
 * Default value is `16000`.
 * Specifies page size of pool page.
 * Smaller the value is increases memory overhead.
@@ -104,37 +121,38 @@ largest value of required alignment.
 ## State atexit configuration.
 
 `MRB_FIXED_STATE_ATEXIT_STACK`
+
 * If defined enables fixed size `mrb_state` atexit stack.
 * Raises `RuntimeError` when `mrb_state_atexit` call count to same `mrb_state` exceeds
 `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`'s value.
 
 `MRB_FIXED_STATE_ATEXIT_STACK_SIZE`
+
 * Default value is `5`.
 * If `MRB_FIXED_STATE_ATEXIT_STACK` isn't defined this macro is ignored.
 
 ## `mrb_value` configuration.
 
 `MRB_ENDIAN_BIG`
+
 * If defined compiles mruby for big endian machines.
 * Used in `MRB_NAN_BOXING`.
 * Some mrbgem use this mrbconf.
 
 `MRB_NAN_BOXING`
+
 * If defined represent `mrb_value` in boxed `double`.
-* Conflicts with `MRB_USE_FLOAT` and `MRB_WITHOUT_FLOAT`.
+* Conflicts with `MRB_USE_FLOAT32` and `MRB_NO_FLOAT`.
 
 `MRB_WORD_BOXING`
+
 * If defined represent `mrb_value` as a word.
 * If defined `Float` will be a mruby object with `RBasic`.
 
-## Instance variable configuration.
-`MRB_IV_SEGMENT_SIZE`
-* Default value is `4`.
-* Specifies size of each segment in segment list.
-
 ## Reduce heap memory configuration.
 
 `MRB_USE_LINK_TIME_RO_DATA_P`
+
 * Only available on ELF platforms.
 * If you specify the address of a read-only section when creating a symbol or string, that string will be used as it is.
 * Heap memory can be saved.
@@ -142,6 +160,7 @@ largest value of required alignment.
 * It must be `__ehdr_start < data_addr < __init_array_start`.
 
 `MRB_USE_CUSTOM_RO_DATA_P`
+
 * Takes precedence over `MRB_USE_LINK_TIME_RO_DATA_P`.
 * Please try if `MRB_USE_LINK_TIME_RO_DATA_P` is not available.
 * The `mrb_ro_data_p()` function is implemented by the user in an arbitrary file.
@@ -149,37 +168,41 @@ largest value of required alignment.
 * Return `TRUE` if `ptr` is in read-only section, otherwise return `FALSE`.
 
 ## Other configuration.
+
 `MRB_UTF8_STRING`
+
 * Adds UTF-8 encoding support to character-oriented String instance methods.
 * If it isn't defined, they only support the US-ASCII encoding.
 
 `MRB_FUNCALL_ARGC_MAX`
+
 * Default value is `16`.
 * Specifies 4th argument(`argc`) max value of `mrb_funcall`.
 * Raises `ArgumentError` when the `argc` argument is bigger then this value `mrb_funcall`.
 
 `KHASH_DEFAULT_SIZE`
+
 * Default value is `32`.
 * Specifies default size of khash table bucket.
 * Used in `kh_init_ ## name` function.
 
-`MRB_STR_BUF_MIN_SIZE`
-* Default value is `128`.
-* Specifies initial capacity of `RString` created by `mrb_str_buf_new` function..
+`MRB_NO_METHOD_CACHE`
 
-`MRB_METHOD_CACHE`
-* Improve performance for method dispatch.
+* Disable method cache to save memory.
 
 `MRB_METHOD_CACHE_SIZE`
-* Default value is `128`.
-* Ignored if `MRB_METHOD_CACHE` is not defined.
+
+* Default value is `256`.
+* Ignored if `MRB_NO_METHOD_CACHE` is defined.
 * Need to be the power of 2.
 
-`MRB_METHOD_T_STRUCT`
+`MRB_USE_METHOD_T_STRUCT`
+
 * Use C struct to represent `mrb_method_t`
-* No `MRB_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero
+* No `MRB_USE_METHOD_T_STRUCT` requires highest 2 bits of function pointers to be zero
 * Define this macro on machines that use higher bits of pointers
 
-`MRB_ENABLE_ALL_SYMBOLS`
-* Make it available `Symbols.all_symbols` in `mrbgems/mruby-symbol-ext`
+`MRB_USE_ALL_SYMBOLS`
+
+* Make it available `Symbol.all_symbols` in `mrbgems/mruby-symbol-ext`
 * Increase heap memory usage.

data/ext/enterprise_script_service/mruby/doc/guides/mrbgems.md

@@ -5,21 +5,27 @@ standardised way into mruby.
 
 ## Usage
 
-By default mrbgems is currently deactivated. As soon as you add a GEM to your
-build configuration (i.e. *build_config.rb*), mrbgems will be activated and the
-extension integrated.
+You have to activate mrbgems explicitly in your build configuration.  To add
+a GEM, add the following line to your build configuration file, for example:
 
-To add a GEM into the *build_config.rb* add the following line for example:
 ```ruby
 conf.gem '/path/to/your/gem/dir'
 ```
 
-You can also use a relative path which would be relative from the mruby root:
+You can also use a relative path to specify a gem.
+
 ```ruby
 conf.gem 'examples/mrbgems/ruby_extension_example'
 ```
 
+In that case,
+
+* if your build configuration file is in the `build_config` directory, it's
+  relative from `MRUBY_ROOT`.
+* otherwise, it is relative from the directory where your build configuration is.
+
 A remote GIT repository location for a GEM is also supported:
+
 ```ruby
 conf.gem :git => 'https://github.com/masuidrive/mrbgems-example.git', :branch => 'master'
 conf.gem :github => 'masuidrive/mrbgems-example', :branch => 'master'
@@ -27,17 +33,20 @@ conf.gem :bitbucket => 'mruby/mrbgems-example', :branch => 'master'
 ```
 
 You can specify the sub directory of the repository with `:path` option:
+
 ```ruby
 conf.gem github: 'mruby/mruby', path: 'mrbgems/mruby-socket'
 ```
 
 To use mrbgem from [mgem-list](https://github.com/mruby/mgem-list) use `:mgem` option:
+
 ```ruby
 conf.gem :mgem => 'mruby-yaml'
 conf.gem :mgem => 'yaml' # 'mruby-' prefix could be omitted
 ```
 
 For specifying commit hash to checkout use `:checksum_hash` option:
+
 ```ruby
 conf.gem mgem: 'mruby-redis', checksum_hash: '3446d19fc4a3f9697b5ddbf2a904f301c42f2f4e'
 ```
@@ -54,13 +63,14 @@ NOTE: `:bitbucket` option supports only git. Hg is unsupported in this version.
 
 There are instances when you wish to add a collection of mrbgems into mruby at
 once, or be able to substitute mrbgems based on configuration, without having to
-add each gem to the *build_config.rb* file.  A packaged collection of mrbgems
+add each gem to your build configuration file.  A packaged collection of mrbgems
 is called a GemBox.  A GemBox is a file that contains a list of mrbgems to load
-into mruby, in the same format as if you were adding them to *build_config.rb*
+into mruby, in the same format as if you were adding them to the build config
 via `config.gem`, but wrapped in an `MRuby::GemBox` object.  GemBoxes are
 loaded into mruby via `config.gembox 'boxname'`.
 
 Below we have created a GemBox containing *mruby-time* and *mrbgems-example*:
+
 ```ruby
 MRuby::GemBox.new do |conf|
   conf.gem "#{root}/mrbgems/mruby-time"
@@ -73,16 +83,19 @@ must be saved with a *.gembox* extension inside the *mrbgems* directory to to be
 picked up by mruby.
 
 To use this example GemBox, we save it as `custom.gembox` inside the *mrbgems*
-directory in mruby, and add the following to our *build_config.rb* file inside
+directory in mruby, and add the following to your build configuration file inside
 the build block:
+
 ```ruby
 conf.gembox 'custom'
 ```
+
 This will cause the *custom* GemBox to be read in during the build process,
 adding *mruby-time* and *mrbgems-example* to the build.
 
 If you want, you can put GemBox outside of mruby directory. In that case you must
 specify an absolute path like below.
+
 ```ruby
 conf.gembox "#{ENV["HOME"]}/mygemboxes/custom"
 ```
@@ -120,6 +133,7 @@ to compile C and Ruby files. *README.md* is a short description of your GEM.
 
 mrbgems expects a specification file called *mrbgem.rake* inside of your
 GEM directory. A typical GEM specification could look like this for example:
+
 ```ruby
 MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec|
   spec.license = 'MIT'
@@ -149,6 +163,7 @@ The `license` and `author` properties are required in every GEM!
 
 In case your GEM is depending on other GEMs please use
 `spec.add_dependency(gem, *requirements[, default_get_info])` like:
+
 ```ruby
 MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec|
   spec.license = 'MIT'
@@ -158,10 +173,10 @@ MRuby::Gem::Specification.new('c_and_ruby_extension_example') do |spec|
   # The version must be between 1.0.0 and 1.5.2 .
   spec.add_dependency('mruby-parser', '>= 1.0.0', '<= 1.5.2')
 
-  # Use any version of mruby-uv from github.
+  # Use any version of mruby-uv from GitHub.
   spec.add_dependency('mruby-uv', '>= 0.0.0', :github => 'mattn/mruby-uv')
 
-  # Use latest mruby-onig-regexp from github. (version requirements can be omitted)
+  # Use latest mruby-onig-regexp from GitHub. (version requirements can be omitted)
   spec.add_dependency('mruby-onig-regexp', :github => 'mattn/mruby-onig-regexp')
 
   # You can add extra mgems active only on test
@@ -172,6 +187,7 @@ end
 The version requirements and default gem information are optional.
 
 Version requirement supports following operators:
+
 * '=': is equal
 * '!=': is not equal
 * '>': is greater
@@ -184,18 +200,20 @@ Version requirement supports following operators:
 
 When more than one version requirements is passed, the dependency must satisfy all of it.
 
-You can have default gem to use as dependency when it's not defined in *build_config.rb*.
+You can have default gem to use as dependency when it's not defined in your build configuration.
 When the last argument of `add_dependency` call is `Hash`, it will be treated as default gem information.
 Its format is same as argument of method `MRuby::Build#gem`, expect that it can't be treated as path gem location.
 
 When a special version of dependency is required,
-use `MRuby::Build#gem` in *build_config.rb* to override default gem.
+use `MRuby::Build#gem` in the build configuration to override default gem.
 
 If you have conflicting GEMs use the following method:
+
 * `spec.add_conflict(gem, *requirements)`
     * The `requirements` argument is same as in `add_dependency` method.
 
 like following code:
+
 ```ruby
 MRuby::Gem::Specification.new 'some-regexp-binding' do |spec|
   spec.license = 'BSD'
@@ -238,7 +256,6 @@ For example: when B depends to C and A depends to B, A will get include paths ex
 Exported include_paths are automatically appended to GEM local include_paths by rake.
 You can use `spec.export_include_paths` accessor if you want more complex build.
 
-
 ## C Extension
 
 mruby can be extended with C. This is possible by using the C API to
@@ -250,6 +267,7 @@ mrbgems expects that you have implemented a C method called
 `mrb_YOURGEMNAME_gem_init(mrb_state)`. `YOURGEMNAME` will be replaced
 by the name of your GEM. If you call your GEM *c_extension_example*, your
 initialisation method could look like this:
+
 ```C
 void
 mrb_c_extension_example_gem_init(mrb_state* mrb) {
@@ -294,7 +312,6 @@ mruby can be extended with pure Ruby. It is possible to override existing
 classes or add new ones in this way. Put all Ruby files into the *mrblib*
 folder.
 
-
 ### Pre-Conditions
 
 none

data/ext/enterprise_script_service/mruby/doc/guides/symbol.md

@@ -0,0 +1,83 @@
+# Symbols
+
+Symbols in `mruby` C source code is represented by `mrb_sym` which is alias of
+`uint32_t`.  Lower 30 bits are used for symbols so that higher 2 bits can be
+used as flags, e.g. `struct mt_elem` in `class.c`.
+
+```C
+struct mt_elem {
+  union mt_ptr ptr;
+  size_t func_p:1;
+  size_t noarg_p:1;
+  mrb_sym key:sizeof(mrb_sym)*8-2;
+};
+```
+
+## C API
+
+We provide following C API for symbols.
+
+### Generate Symbols
+
+#### `mrb_sym mrb_intern(mrb_state*,const char*,size_t)`
+
+Get a symbol from a string.
+
+#### `mrb_sym mrb_intern_check_cstr(mrb_state*,const char*)`
+
+Get a symbol from a NULL terminated (C) string.
+
+#### `mrb_sym mrb_intern_str(mrb_state*,mrb_value)`
+
+Get a symbol from a Ruby string object.
+
+#### `mrb_intern_lit(mrb_state*,const char*)`
+
+Get a symbol from a C string literal. The second argument should be a C string
+literal, otherwise you will get a compilation error. It does not copy C string
+given the fact it's a literal.
+
+#### `mrb_sym mrb_intern_check(mrb_state*,const char*,size_t)`
+
+Get a symbol from a string if the string has been already registered as a
+symbol, otherwise return `0`. We also provide variants `mrb_intern_check_str()`
+(from Ruby string) and `mrb_intern_check_cstr()` (from C string).
+
+#### `const char *mrb_sym_name(mrb_state*,mrb_sym)`
+
+Get a string representation of a symbol as a C string.
+
+#### `const char *mrb_sym_name_len(mrb_state*,mrb_sym,mrb_int*)`
+
+Get a string representation of a symbol, and its length.
+
+## Preallocate Symbols
+
+To save RAM, `mruby` can use compile-time allocation of some symbols. You can
+use following macros to get preallocated symbols by including `mruby/presym.h`
+header.
+
+ * `MRB_SYM(xor)`    //=> xor    (Word characters)
+ * `MRB_SYM_B(xor)`  //=> xor!   (Method with Bang)
+ * `MRB_SYM_Q(xor)`  //=> xor?   (Method with Question mark)
+ * `MRB_SYM_E(xor)`  //=> xor=   (Method with Equal)
+ * `MRB_CVSYM(xor)`  //=> @@xor  (Class Variable)
+ * `MRB_IVSYM(xor)`  //=> @xor   (Instance Variable)
+ * `MRB_OPSYM(xor)`  //=> ^      (Operator)
+
+For `MRB_OPSYM()`, specify the names corresponding to operators (see
+`MRuby::Presym::OPERATORS` in `lib/mruby/presym.rb` for the names that
+can be specified for it). Other than that, describe only word characters
+excluding leading and ending punctuations.
+
+These macros are converted to static symbol IDs at compile time, unless
+preallocate symbols are disabled by  `conf.disable_presym`. In that case,
+these macros are expanded to `mrb_intern_lit` calls, therefore the mruby state
+variable is required. The above macros assume the variable name is `mrb`.  If
+its name is not `mrb`, you need to use macros with `_2` suffix, such as
+`MRB_SYM_2` to specify `mrb_state*` variable.
+
+### Disabling Preallocated Symbols
+
+You can disable preallocated symbols by specifying `conf.disable_presym` in the
+configuration file.