From: Nobuyoshi Nakada <nobu@...>
Date: 2008-04-03T22:06:32+09:00
Subject: [ruby-dev:34239] MVM interface draft

なかだです。

先々週になりますが、ささださんといろいろ話し合いしてきました。そ
のうち、MVMのCインターフェースに付いての件です。

まだ漏れなどあるかもしれませんが、とりあえず。


= VM C API案

== 用語
とりあえず以下の用語を使うことにします。

--- エンジン
    ドライバから呼び出されて、rubyの処理を行なうライブラリ。
--- ドライバ
    エンジンを利用するアプリケーション。
    rubyコマンド、erubyコマンド、mod_rubyなど。

== 初期化/実行

初期化処理は、プロセス全体に対するものと、VM単位に対するものに分
けられます。前者は、一プロセスで一回だけ、メインネイディブスレッ
ドで呼び出さなければなりません。

=== プロセス初期化
--- ruby_sysinit(int **argc, char ***argv)
    システムごとに必要な初期化を行なう。

--- RUBY_INIT_STACK
    メインネイディブスレッドのスタック情報を保存する。

=== VM初期化
--- ruby_vm_new(void)
    新しいVMを作成する。ruby_init()は、新しいVMを作成した後、そ
    の上のメインrubyスレッドも同時に作成する。

--- ruby_vm_parse_option(rb_vm_t *vm, int argc, const char *argv)
    コマンドラインオプションをパースして、結果をvm内に保存する。
    -eオプションまたはスクリプトをコンパイルして、メインスレッド
    が最初に実行するコードとして保存する。

=== VM実行
--- ruby_vm_run(rb_vm_t *vm)
    VMの実行を開始する。
    exit statusを返す。

== 属性その他

ruby_vm_parse_option()はrubyコマンドの仕様にあわせているため、他
のドライバの目的には合うとは限りません。そのような場合、VMの作成
と実行の間に、必要なパラメータをセットすることになります。

--- ruby_vm_get_argv(VALUE vm)
    vmに保存されたARGVを取り出す。

--- ruby_vm_set_argv(VALUE vm, int argc, VALUE *argv)
    vmで使用されるARGVを設定する。

--- ruby_vm_init_env(VALUE vm, char **envp)
    vmで使用される環境変数を設定する。

--- ruby_vm_getenv(VALUE vm, const char *name)
    vm中の環境変数を取り出す。

--- ruby_vm_setenv(VALUE vm, const char *name, const char *value)
    vm中の環境変数を設定する。

--- ruby_vm_get_pwd(VALUE vm)
    vmのカレントディレクトリを取り出す。

--- ruby_vm_set_pwd(VALUE vm, const char *pwd)
    vmのカレントディレクトリを設定する。

== ObjectSpace

各VMがネイティブスレッドで並行動作できるようにするため、それぞれ
独立したObjectSpaceを持ちます。結果として、あるVMで作られたオブ
ジェクトを別のVMに渡すことはできません。

== ネイティブスレッドインターフェース

ruby以外で作成されたネイティブスレッドからエンジンを実行するため
には、そのスレッドがruby VMのいずれかに登録されている必要があり
ます。一つのスレッドを複数のVMに登録することも可能ですが、同時に
実行できるのは一つのVMだけです。複数VM上で同時に動作することはで
きません。

また、同じネイティブスレッド上であっても、異なるVMのオブジェクト
を混ぜて使用することもできません。

--- ruby_vm_register_thread(VALUE vm)
    ネイティブスレッドに対応するThreadインスタンスを作成して、VMに登録する。

--- ruby_vm_release_thread(VALUE vm)
    Threadインスタンスからネイティブスレッドを解放する。

--- ruby_vm_enter_thread(VALUE vm)
    rubyスレッドとしての動作を開始する。

--- ruby_vm_leave_thread(VALUE vm)
    rubyスレッドとしての動作を終了する。

名前は未定ですが、ruby_vm_enter_thread()した状態でコールバックを
呼び出して、終了後にruby_vm_leave_thread()を実行するものも予定し
ています。

== プリコンパイル

--- ruby_vm_compile_file(const char *filename)
--- ruby_vm_compile_cstr(const char *src)
--- ruby_vm_compile_string(VALUE srcstring)
    スクリプトをコンパイル済みデータに変換する。

--- ruby_vm_run_file(rb_vm_t *vm, const char *filename)
--- ruby_vm_run_cstr(rb_vm_t *vm, const char *src)
--- ruby_vm_run_string(rb_vm_t *vm, VALUE srcstring)
    スクリプトをvm上で実行する。

--- ruby_vm_run_compiled(rb_vm_t *vm, compiled...)
    コンパイル済みデータをvm上で実行する。

--- ruby_vm_run_cfun(rb_vm_t *vm, (*func)(), void*)
    funcをvm上で実行する。


-- 
--- 僕の前にBugはない。
--- 僕の後ろにBugはできる。
    中田 伸悦