Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
232 lines (164 sloc) 7.55 KB
* About CastOff
CastOff is a compiler for Ruby1.9.3.
CastOff compiles Ruby method (method written in Ruby) into C extension (method written in C)
by using given information such as class information of variables.
CastOff can reduce Ruby virtual machine overhead, so by use of CastOff,
the performance of compilation target method can improve.
This README document introduce basic functionality of CastOff.
If you have any questions, comments, or suggestions please send email to shiba@rvm.jp,
or use http://github.com/soba1104/CastOff/issues.
* License
Same as the license of Ruby1.9.3 runtime.
* Installation
$gem install cast_off
Currently, CastOff supports Ruby1.9.3 only.
So, if you attempt to use CastOff, please install CastOff under Ruby1.9.3 runtime.
* Attention
** Incompatibility
-Continuation
CastOff causes problem about capture of continuation (callcc).
So, you should not use CastOff to your program which uses Continuation.
-Constant redefinition
<<<Sorry, not yet documented.>>>
-Built-in functions related with Method and Proc
CastOff compiles Ruby method and proc into C extension.
So, built-in functions related with Method and Proc (such as Method#arity, Proc#arity)
return different values.
# example
class Foo
def foo(a, b = :b, *c); end
end
f = Foo.new
puts (f.method(:foo).arity) # => -2
CastOff.compile(Foo, :foo)
puts (f.method(:foo).arity) # => -1
** Startup time
<<<Sorry, not yet documented.>>>
** Compilation time
<<<Sorry, not yet documented.>>>
** Load of compiled method
CastOff needs definition of compilation target method to load compiled method.
If compilation target method is not defined, CastOff cannot load compiled method.
When you use CastOff from command line, CastOff hooks class definition statement
to check method definition. And load compiled method if compilation target method is defined.
So, if you want to compile method outer class definition statement (such as following bar method),
you need call CastOff.autoload or CastOff.load after method definition explicitly.
-----------------------------------------------------
class Foo # Compiled Foo#foo is loaded after class definition of Foo
def foo
...
end
end
def bar() # There are no class definition after definition of bar,
# so Compiled bar method is not loaded.
...
end
# If you want to load compiled bar method,
# you should call CastOff.autoload or CastOff.load after definition of bar method.
...
-----------------------------------------------------
* Usage
** Use CastOff from command line
By use of command line tool cast_off, you can improve performance of your Ruby program easily.
If you want to improve performance of your Ruby program, you should execute following command repeatedly.
-----------------------------------------------------
$cast_off PathOfTargetProgram ArgumentsOfTargetProgram
-----------------------------------------------------
For example, when you want to improve performance of Ruby program "foo.rb"
(in this example, "foo.rb" recieves one argument "bar" or "baz"), you should execute following commands.
-----------------------------------------------------
$cast_off foo.rb bar
$cast_off foo.rb baz
-----------------------------------------------------
When you execute these commands, CastOff does followings to compile foo.rb and related libraries.
1: Executes "foo.rb" with argument "bar" to get profile information.
2: Compiles "foo.rb" and related libraries.
3: Executes "foo.rb" with argument "baz" to get and update profile information.
4: Compiles "foo.rb" and related libraries.
After CastOff finishes compilation, you can run target program with --run option.
In above example, you can run target program with compiled codes by use of following command.
$cast_off --run foo.rb bar
*** Command line arguments
cast_off [options] PathOfTargetProgram ArgumentsOfTargetProgram
*** Command line options
--run
Execute target program with compiled methods.
--deoptimize
Enable deoptimization.
--clear
Clear profile information and delete compiled methods.
If you want to clear profile information and compiled methods of target name "foo",
you should execute following command.
$cast_off --clear --name=foo
--threshold=COUNT
Compile method which is executed more than COUNT.
Default value is 100.
--name=NAME
Name compiled methods NAME.
This name is used for search of compiled methods.
If you don't use this option, CastOff uses File.basename([programfile]) as name.
--verbose
Show compilation progress and internal information.
-h, --help
Show help.
--version
Show version number of CastOff.
** Use CastOff from script
<<<Sorry, not yet documented. >>>
*** Specify class information to CastOff
You can specify class information to CastOff by followings.
-Specify class of variables:
--local variables, arguments
:local_variable_name => class_name
:local_variable_name => [class_name1, class_name2, ...]
[:local_variable_name1, :local_variable_name2, ...] => class_name
[:local_variable_name1, :local_variable_name2, ...] => [class_name1, class_name2, ...]
--instance variables
:@instance_variable_name => class_name
:@instance_variable_name => [class_name1, class_name2, ...]
[:@instance_variable_name1, :@instance_variable_name2, ...] => class_name
[:@instance_variable_name1, :@instance_variable_name2, ...] => [class_name1, class_name2, ...]
--class variables
:@@class_variable_name => class_name
:@@class_variable_name => [class_name1, class_name2, ...]
[:@@class_variable_name1, :@@class_variable_name2, ...] => class_name
[:@@class_variable_name1, :@@class_variable_name2, ...] => [class_name1, class_name2, ...]
--global variables
:$global_variable_name => class_name
:$global_variable_name => [class_name1, class_name2, ...]
[:$global_variable_name1, :$global_variable_name2, ...] => class_name
[:$global_variable_name1, :$global_variable_name2, ...] => [class_name1, class_name2, ...]
-Specify class of method return values:
class_name => {:method_name1 => class_of_return_value, :method_name2 => [class_of_return_value1, class_of_return_value2, ...], ...}
-Specify class of constants:
<<<Sorry, not yet documented. >>>
*** Compilation
You can compile Ruby method into C extension by followings.
-Compile instance method
--API
CastOff.compile(target(Class or Module), method_name(Symbol))
CastOff.compile(target(Class or Module), method_name(Symbol), class_information(Hash))
CastOff.compile(target(Class or Module), method_name(Symbol), binding(Binding))
CastOff.compile(target(Class or Module), method_name(Symbol), binding(Binding), class_information(Hash))
--Notes
This API compiles Ruby instance method into C extension and loads compiled method.
You should specify method_name(second argument) by Symbol class.
CastOff uses binding(third argument) to resolve Ruby constants.
-Compile singleton method
--API
CastOff.compile_singleton_method(target(Any Object), method_name(Symbol))
CastOff.compile_singleton_method(target(Any Object), method_name(Symbol), class_information(Hash))
CastOff.compile_singleton_method(target(Any Object), method_name(Symbol), binding(Binding))
CastOff.compile_singleton_method(target(Any Object), method_name(Symbol), binding(Binding), class_information(Hash))
--Notes
This API compiles Ruby singleton method into C extension and loads compiled method.
You should not use CastOff.compile when compile singleton method.
You should specify method_name(second argument) by Symbol class.
CastOff uses binding(third argument) to resolve Ruby constants.
-Compile Ruby code and execute
--API
CastOff.execute(class_information(Hash)) { target code }
--Notes
This API compiles passed block and executes.
*** Compile options
<<<Sorry, not yet documented. >>>