Bug #6785 » 0001-Documentation-for-RubyVM-InstructionSequence-draft-2.patch
| iseq.c | ||
|---|---|---|
|
return iseqval;
|
||
|
}
|
||
|
/*
|
||
|
* :nodoc:
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_s_load(int argc, VALUE *argv, VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
return rb_iseq_compile_with_option(src, file, Qnil, line, base_block, Qnil);
|
||
|
}
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* InstructionSequence.compile(source[, file[, path[, line[, options]]]]) -> iseq
|
||
|
* InstructionSequence.new(source[, file[, path[, line[, options]]]]) -> iseq
|
||
|
*
|
||
|
* Takes _source_, a +String+ of Ruby code and compiles it to an
|
||
|
* +InstructionSequence+. Optionally takes _file_, a filename, _path_, the
|
||
|
* absolute path to _file_, _line_, the first line number of the Ruby code in
|
||
|
* _source_, and _options_, which can be +true+, +false+ or a +Hash+, to
|
||
|
* modify the default behavior of the Ruby iseq compiler. _file_, _path_ and
|
||
|
* _line_ are metadata attached to the returned _iseq_. For details regarding
|
||
|
* _options_, see InstructionSequence.compile_option=.
|
||
|
*
|
||
|
* RubyVM::InstructionSequence.compile("a = 1 + 2")
|
||
|
* #=> <RubyVM::InstructionSequence:<compiled>@<compiled>>
|
||
|
*
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_s_compile(int argc, VALUE *argv, VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
return rb_iseq_compile_with_option(src, file, path, line, 0, opt);
|
||
|
}
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* InstructionSequence.compile_file(file[, options]) -> iseq
|
||
|
*
|
||
|
* Takes _file_, a +String+ with the location of a Ruby source file, reads,
|
||
|
* parses and compiles the file, and returns _iseq_, the compiled
|
||
|
* +InstructionSequence+ with source location metadata set. Optionally takes
|
||
|
* _options_, which can be +true+, +false+ or a +Hash+, to modify the default
|
||
|
* behavior of the Ruby iseq compiler (for details see
|
||
|
* InstructionSequence.compile_option=).
|
||
|
*
|
||
|
* # /tmp/hello.rb
|
||
|
* puts "Hello, world!"
|
||
|
*
|
||
|
* # elsewhere
|
||
|
* RubyVM::InstructionSequence.compile_file("/tmp/hello.rb")
|
||
|
* #=> <RubyVM::InstructionSequence:<main>@/tmp/hello.rb>
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_s_compile_file(int argc, VALUE *argv, VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
ISEQ_TYPE_TOP, &option);
|
||
|
}
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* InstructionSequence.compile_option = options -> options
|
||
|
*
|
||
|
* The +compile_option+ attribute lets you set the default values for various
|
||
|
* optimizations in the Ruby iseq compiler. Possible values for _options_
|
||
|
* include +true+, which enables all options, +false+ which disables all
|
||
|
* options, a +Hash+ of options that you want to change (options not present
|
||
|
* in the hash will be left unchanged), and +nil+ which leaves all options
|
||
|
* unchanged.
|
||
|
*
|
||
|
* Possible option names (which are keys in _options_) include
|
||
|
* +:inline_const_cache+, +:peephole_optimization+, +:tailcall_optimization+,
|
||
|
* +:specialized_instruction+, +:operands_unification+,
|
||
|
* +:instructions_unification+, +:stack_caching+, and +:trace_instruction+,
|
||
|
* which can be +true+ or +false+, and +:debug_level+, which is an integer.
|
||
|
*
|
||
|
* These default options can be overwritten for a single run of the iseq
|
||
|
* compiler by passing any of the above values as the _options_ parameter to
|
||
|
* InstructionSequence.new, InstructionSequence.compile and
|
||
|
* InstructionSequence.compile_file.
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_s_compile_option_set(VALUE self, VALUE opt)
|
||
|
{
|
||
| ... | ... | |
|
return opt;
|
||
|
}
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* InstructionSequence.compile_option -> options
|
||
|
*
|
||
|
* Returns a hash of default options used by the Ruby iseq compiler.
|
||
|
* For details, see InstructionSequence.compile_option=.
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_s_compile_option_get(VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
return iseq;
|
||
|
}
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* iseq.eval -> obj
|
||
|
*
|
||
|
* Evaluates the contained instructions and returns the result.
|
||
|
*
|
||
|
* RubyVM::InstructionSequence.compile("1 + 2").eval #=> 3
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_eval(VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
return rb_iseq_eval(self);
|
||
|
}
|
||
|
/*
|
||
|
* :nodoc:
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_inspect(VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
static
|
||
|
VALUE iseq_data_to_ary(rb_iseq_t *iseq);
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* iseq.to_a -> ary
|
||
|
*
|
||
|
* Returns an +Array+ of size 14 representing the instruction sequence with
|
||
|
* the following data:
|
||
|
*
|
||
|
* [magic] A string identifying the data format. Always
|
||
|
* "YARVInstructionSequence/SimpleDataFormat".
|
||
|
*
|
||
|
* [major_version] The major version of the instruction sequence.
|
||
|
*
|
||
|
* [minor_version] The minor version of the instruction sequence.
|
||
|
*
|
||
|
* [format_type] A number identifying the data format. Always 1.
|
||
|
*
|
||
|
* [misc] A hash containing +:arg_size+, the total number of arguments taken
|
||
|
* by the method or the block (0 if _iseq_ doesn't represent a method
|
||
|
* or block), +:local_size+, the number of local variables + 1, and
|
||
|
* +:stack_max+, used in calculating the stack depth at which a
|
||
|
* +SystemStackError+ is thrown.
|
||
|
*
|
||
|
* [name] The name of the context (block, method, class, module, etc.) that
|
||
|
* this instruction sequence belongs to. <code><main></code> if it's
|
||
|
* at the top level, <code><compiled></code> if it was evaluated from
|
||
|
* a string.
|
||
|
*
|
||
|
* [path] The relative path to the Ruby file where the instruction sequence
|
||
|
* was loaded from. <code><compiled></code> if the iseq was evaluated
|
||
|
* from a string.
|
||
|
*
|
||
|
* [absolute_path] The absolute path to the Ruby file where the instruction
|
||
|
* sequence was loaded from. +nil+ if the iseq was evaluated
|
||
|
* from a string.
|
||
|
*
|
||
|
* [start_lineno] The number of the first source line where the instruction
|
||
|
* sequence was loaded from.
|
||
|
*
|
||
|
* [type] The type of the instruction sequence. Valid values are +:top+,
|
||
|
* +:method+, +:block+, +:class+, +:rescue+, +:ensure+, +:eval+,
|
||
|
* +:main+, and +:defined_guard+.
|
||
|
*
|
||
|
* [locals] An array containing the names of all arguments and local
|
||
|
* variables as symbols.
|
||
|
*
|
||
|
* [args] The arity if the method or block only has required arguments.
|
||
|
* Otherwise an array of <code>[required_argc, [optional_arg_labels,
|
||
|
* ...], splat_index, post_splat_argc, post_splat_index, block_index,
|
||
|
* simple]</code>. More info about these values can be found in
|
||
|
* +vm_core.h+.
|
||
|
*
|
||
|
* [catch_table] A list of exceptions and control flow operators (rescue,
|
||
|
* next, redo, break, etc.).
|
||
|
*
|
||
|
* [bytecode] An array of arrays containing the instruction names and
|
||
|
* operands that make up the body of the instruction sequence.
|
||
|
*
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_to_a(VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
}
|
||
|
}
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* iseq.disasm -> str
|
||
|
* iseq.disassemble -> str
|
||
|
*
|
||
|
* Returns the instruction sequence as a +String+ in human readable form.
|
||
|
*
|
||
|
* puts RubyVM::InstructionSequence.compile('1 + 2').disasm
|
||
|
*
|
||
|
* <em>produces</em>:
|
||
|
*
|
||
|
* == disasm: <RubyVM::InstructionSequence:<compiled>@<compiled>>==========
|
||
|
* 0000 trace 1 ( 1)
|
||
|
* 0002 putobject 1
|
||
|
* 0004 putobject 2
|
||
|
* 0006 opt_plus <ic:1>
|
||
|
* 0008 leave
|
||
|
*/
|
||
|
VALUE
|
||
|
rb_iseq_disasm(VALUE self)
|
||
|
{
|
||
| ... | ... | |
|
return str;
|
||
|
}
|
||
|
/*
|
||
|
* call-seq:
|
||
|
* InstructionSequence.disasm(body) -> str
|
||
|
* InstructionSequence.disassemble(body) -> str
|
||
|
*
|
||
|
* Takes _body_, a +Method+ or +Proc+ object, and returns a +String+ with the
|
||
|
* human readable instructions for _body_.
|
||
|
*
|
||
|
* For a +Method+ object:
|
||
|
*
|
||
|
* # /tmp/method.rb
|
||
|
* def hello
|
||
|
* puts "hello, world"
|
||
|
* end
|
||
|
*
|
||
|
* puts RubyVM::InstructionSequence.disasm(method(:hello))
|
||
|
*
|
||
|
* <em>produces:</em>
|
||
|
*
|
||
|
* == disasm: <RubyVM::InstructionSequence:hello@/tmp/method.rb>============
|
||
|
* 0000 trace 8 ( 1)
|
||
|
* 0002 trace 1 ( 2)
|
||
|
* 0004 putself
|
||
|
* 0005 putstring "hello, world"
|
||
|
* 0007 send :puts, 1, nil, 8, <ic:0>
|
||
|
* 0013 trace 16 ( 3)
|
||
|
* 0015 leave ( 2)
|
||
|
*
|
||
|
* For a +Proc+:
|
||
|
*
|
||
|
* # /tmp/proc.rb
|
||
|
* p = proc { num = 1 + 2 }
|
||
|
* puts RubyVM::InstructionSequence.disasm(p)
|
||
|
*
|
||
|
* <em>produces:</em>
|
||
|
*
|
||
|
* == disasm: <RubyVM::InstructionSequence:block in <main>@/tmp/proc.rb>===
|
||
|
* == catch table
|
||
|
* | catch type: redo st: 0000 ed: 0012 sp: 0000 cont: 0000
|
||
|
* | catch type: next st: 0000 ed: 0012 sp: 0000 cont: 0012
|
||
|
* |------------------------------------------------------------------------
|
||
|
* local table (size: 2, argc: 0 [opts: 0, rest: -1, post: 0, block: -1] s1)
|
||
|
* [ 2] num
|
||
|
* 0000 trace 1 ( 1)
|
||
|
* 0002 putobject 1
|
||
|
* 0004 putobject 2
|
||
|
* 0006 opt_plus <ic:1>
|
||
|
* 0008 dup
|
||
|
* 0009 setdynamic num, 0
|
||
|
* 0012 leave
|
||
|
*
|
||
|
*/
|
||
|
static VALUE
|
||
|
iseq_s_disasm(VALUE klass, VALUE body)
|
||
|
{
|
||
| ... | ... | |
|
return iseqval;
|
||
|
}
|
||
|
/*
|
||
|
* Document-class: RubyVM::InstructionSequence
|
||
|
*
|
||
|
* The +InstructionSequence+ class represents a compiled sequence of
|
||
|
* instructions for the Ruby Virtual Machine. With it, you can get a handle to
|
||
|
* the instructions that make up a method or a proc, compile strings of Ruby
|
||
|
* code down to VM instructions, and disassemble instruction sequences to
|
||
|
* strings for easy inspection. It is mostly useful if you want to learn how
|
||
|
* the Ruby VM works, but it also lets you control various settings for the
|
||
|
* Ruby iseq compiler. You can find the source for the VM instructions in
|
||
|
* +insns.def+ in the Ruby source.
|
||
|
*
|
||
|
* The instruction sequence that results from a given piece of Ruby code will
|
||
|
* almost certainly change as Ruby changes, so the example output below may be
|
||
|
* different from what you see.
|
||
|
*/
|
||
|
void
|
||
|
Init_ISeq(void)
|
||
|
{
|
||