Ruby » Ruby master

# extension.ja.rdoc - -*- RDoc -*- created at: Mon Aug 7 16:45:54 JST 1995

Rubyの拡張ライブラリの作り方を説明します．

Cの変数には型があり，データには型がありません．ですから，た

とえばポインタをintの変数に代入すると，その値は整数として取

の両方が必要です．(1)を忘れると間違ったデータの変換が行われ

て，最悪プログラムがcore dumpします．

Rubyにはユーザが使う可能性のある以下のタイプがあります．

ほとんどのタイプはCの構造体で実装されています．

ruby.hではTYPE()というマクロが定義されていて，VALUEのデータ

タイプを知ることが出来ます．TYPE()マクロは上で紹介したT_XXXX

FIXNUM_P(obj)

NIL_P(obj)

データタイプがT_NIL，T_FALSE，T_TRUEである時，データはそれぞ

れnil，false，trueです．このデータタイプのオブジェクトはひと

ないことです．直接変更した場合，オブジェクトの内容の整合性が

とれなくなって，思わぬバグの原因になります．

VALUEの実際の構造は

INT2NUM()は整数がFIXNUMの範囲に収まらない場合，Bignumに変換

してくれます(が，少し遅い)．

先程も述べた通り，Rubyの構造体をアクセスする時に内容の更新を

行うことは勧められません．で，Rubyのデータを操作する時には

ここではもっとも使われるであろう文字列と配列の生成/操作を行

う関数をあげます(全部ではないです)．

rb_str_new(const char *ptr, long len) ::

lenバイトまでの内容は保存される．lenはstrの容量を越えてい

てはならない．

rb_ary_new() ::

配列aryにptrからlen個のオブジェクトを追加する．

原理的にRubyで書けることはCでも書けます．RubyそのものがCで記

述されているんですから，当然といえば当然なんですけど．ここで

はRubyの拡張に使うことが多いだろうと予測される機能を中心に紹

介します．

Rubyで提供されている関数を使えばRubyインタプリタに新しい機能

を追加することができます．Rubyでは以下の機能を追加する関数が

では順に紹介します．

クラスやモジュールを定義するためには，以下の関数を使います．

VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)

VALUE rb_define_module_under(VALUE outer, const char *name)

メソッドや特異メソッドを定義するには以下の関数を使います．

VALUE rb_current_receiver(void)

拡張ライブラリが必要な定数はあらかじめ定義しておいた方が良い

でしょう．定数を定義する関数は二つあります．

前者は特定のクラス/モジュールに属する定数を定義するもの，後

者はグローバルな定数を定義するものです．

既に『1.5 Rubyのデータを操作する』で一部紹介したような関数を

使えば，Rubyの機能を実現している関数を直接呼び出すことが出来

それ以外にもRubyの機能を呼び出す方法はいくつかあります．

CからRubyの機能を呼び出すもっとも簡単な方法として，文字列で

与えられたRubyのプログラムを評価する以下の関数があります．

この関数はエラーが発生するとnilを返します．そして，成功時には

*stateはゼロに，さもなくば非ゼロになります．

Cから文字列を経由せずにRubyのメソッドを呼び出すこともできま

す．その前に，Rubyインタプリタ内でメソッドや変数名を指定する

これらの関数は，IDの代わりにシンボルを返すことを除けば上記の

関数と同じです．

Cから文字列を経由せずにRubyのメソッドを呼び出すためには以下

の関数を使います．

applyには引数としてRubyの配列を与えます．

Cから関数を使って参照・更新できるのは，定数，インスタンス変

数です．大域変数は一部のものはCの大域変数としてアクセスでき

定数を新しく定義するためには『2.1.3 定数定義』で紹介さ

れている関数を使ってください．

C言語とRubyの間で情報を共有する方法について解説します．

以下のRubyの定数はCのレベルから参照できます．

C言語から見た「nil」．

CとRubyで大域変数を使って情報を共有できます．共有できる大域

変数にはいくつかの種類があります．そのなかでもっとも良く使わ

(*getter)(ID id);

(*setter)(VALUE val, ID id);

Cの世界で定義されたデータ(構造体)をRubyのオブジェクトとして

取り扱いたい場合がありえます．このような場合はTypedData_XXX

があります．

++

構造体へのポインタsvalをRubyオブジェクトに変換するには次のマ

クロを使います。

は割り当てるC構造体の型です．割り当てられた構造体は変数sval

に代入されます．この変数の型は (type*) である必要があります．

TypedData_Wrap_StructやTypedData_Make_Structで生成したオブジェ

クトから構造体へのポインタを復元するには以下のマクロを用いま

これらのマクロの使い方はちょっと分かりにくいので，後で説明す

る例題を参照してください．

% mkdir ext/dbm

ライブラリ用のディレクトリを作る必要があります．名前は適当に

選んで構いません．

まあ，当然なんですけど，どういう機能を実現するかどうかまず設

計する必要があります．どんなクラスをつくるか，そのクラスには

どんなメソッドがあるか，クラスが提供する定数などについて設計

します．

拡張ライブラリ本体となるC言語のソースを書きます．C言語のソー

スがひとつの時には「ライブラリ名.c」を選ぶと良いでしょう．C

void rb_global_variable(VALUE *var)

Makefileを作る場合の雛型になるextconf.rbというファイルを作り

ます．extconf.rbはライブラリのコンパイルに必要な条件のチェッ

パイルしない時にはcreate_makefileを呼ばなければMakefileは生

成されず，コンパイルも行われません．

もし，ディレクトリにdependというファイルが存在すれば，

Makefileが依存関係をチェックしてくれます．

などで作ることが出来ます．あって損は無いでしょう．

Makefileを実際に生成するためには

ディレクトリをext以下に用意した場合にはRuby全体のmakeの時に

自動的にMakefileが生成されますので，このステップは不要です．

動的リンクライブラリを生成する場合にはその場でmakeしてくださ

い．必要であれば make install でインストールされます．

を作り，そこに 拡張子 .rb のファイルを置いておけば同時にイン

ストールされます．

まあ，デバッグしないと動かないでしょうね．ext/Setupにディレ

クトリ名を書くと静的にリンクするのでデバッガが使えるようにな

ります．その分コンパイルが遅くなりますけど．

後はこっそり使うなり，広く公開するなり，売るなり，ご自由にお

使いください．Rubyの作者は拡張ライブラリに関して一切の権利を

主張しません．

Rubyのソースはいくつかに分類することが出来ます．このうちクラ

スライブラリの部分は基本的に拡張ライブラリと同じ作り方になっ

ています．これらのソースは今までの説明でほとんど理解できると

思います．

class.c :: クラスとモジュール

error.c :: 例外クラスと例外機構

object.c :: オブジェクト

variable.c :: 変数と定数

parse.y :: 字句解析器と構文定義

parse.c :: 自動生成

defs/keywords :: 予約語

lex.c :: 自動生成

compile.c

eval.c

-> opt*.inc : 自動生成

-> vm.inc : 自動生成

regex.c

regcomp.c

regparse.c

regsyntax.c

debug.c :: Cデバッガ用のデバッグシンボル

dln.c :: 動的ローディング

strftime.c :: 時刻整形

util.c :: その他のユーティリティ

dmyext.c

dmydln.c

gem_prelude.rb

prelude.rb

array.c :: Array

bignum.c :: Bignum

defs/known_errors.def :: 例外クラス Errno::*

-> known_errors.inc :: 自動生成

encoding.c :: Encoding

transcode.c :: Encoding::Converter

enc/*.c :: エンコーディングクラス群

enc/trans/* :: コードポイント対応表

goruby.c

golf_prelude.rb : goruby固有のライブラリ

-> golf_prelude.c : 自動生成

C言語からRubyの機能を利用するAPIは以下の通りである．

VALUE ::

体である．VALUE型をこれらにキャストするためにRで始まる構造体

名を全て大文字にした名前のマクロが用意されている．

Qnil ::

定数: falseオブジェクト

Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ::

dataからtype型のポインタを取り出し変数svalに代入するマクロ．

RB_TYPE_P(value, type)

TYPE(value)

void Check_Type(VALUE value, int type)

SafeStringValue(value)

FIX2INT(value), INT2FIX(i)

FIX2LONG(value), LONG2FIX(l)

StringValueCStr(value)

rb_str_new2(s)

VALUE rb_define_class(const char *name, VALUE super) ::

オブジェクトをモジュール(で定義されているメソッド)で拡張する．

void rb_define_variable(const char *name, VALUE *var) ::

GCのため，Rubyプログラムからはアクセスされないが, Rubyオブ

ジェクトを含む大域変数をマークする．

void rb_define_const(VALUE klass, const char *name, VALUE val) ::

と同じ意味．

rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ::

先には，元のHashがSymbol以外のキーを含んでいた場合はそれらが

コピーされた別の新しいHash，そうでなければ0が保存されます．

VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::

objがidで示されるメソッドを持つかどうかを返す．

VALUE rb_iv_get(VALUE obj, const char *name) ::

objのインスタンス変数をvalにセットする．

VALUE rb_block_call(VALUE obj, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) ::

現在の最も内側のブロックをvalueで終了する．ブロックは引数で

与えられたvalueを返す．この関数は直接の呼び出し元に戻らない．

void rb_warning(const char *fmt, ...) ::

きはObject#inspect)を使ったVALUEの出力に利用できる．これは

"%i"と衝突するため，整数には"%d"を使用すること．

Rubyをアプリケーションに埋め込む場合には以下のインタフェース

を使う．通常の拡張ライブラリには必要ない．

Rubyのスクリプト名($0)を設定する．

void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) ::

指定されたフック関数を削除します．

void rb_gc_adjust_memory_usage(ssize_t diff) ::

す．メモリブロックが解放されたり，メモリブロックがより小さいサイズで再

確保されたりした場合などです．この関数はGCを引き起こすかもしれません．

APIの互換性をチェックするために以下のマクロがデフォルトで定義されています．

rb_add_event_hook() がフック関数に渡す data を第3引数として

受け取ることを意味する．

extconf.rbの中では利用可能なコンパイル条件チェックの関数は以

下の通りである．

optionが指定された場合は，上記の配列の代わりにそのオプションを

指定して得られた出力をstripしたものを返す．

Ruby 2.1から世代別GCに対応しました．我々はこれをRGenGCと呼んでいます．

RGenGCは，過去の拡張ライブラリに（ほぼ）互換性を保つように開発されている

# extension.rdoc - -*- RDoc -*- created at: Mon Aug 7 16:45:54 JST 1995

This document explains how to make extension libraries for Ruby.

In C, variables have types and data do not have types. In contrast,

Ruby variables do not have a static type, and data themselves have

Converting to the wrong data type may cause serious problems.

The Ruby interpreter has the following data types:

Most of the types are represented by C structures.

The macro TYPE() defined in ruby.h shows the data type of the VALUE.

TYPE() returns the constant number T_XXXX described above. To handle

FIXNUM_P(obj)

NIL_P(obj)

The data for type T_NIL, T_FALSE, T_TRUE are nil, false, true

respectively. They are singletons for the data type.

are responsible for the result. This ends up being the cause of

interesting bugs.

To convert C data to Ruby values:

INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM

range, but is a bit slower.

As I already mentioned, it is not recommended to modify an object's

internal structure. To manipulate objects, use the functions supplied

by the Ruby interpreter. Some (not all) of the useful functions are

listed below:

rb_str_new(const char *ptr, long len) ::

up to len bytes, regardless RSTRING_LEN(str). len must not exceed

the capacity of str.

rb_ary_new() ::

Appends len elements of objects from ptr to the array.

You can add new features (classes, methods, etc.) to the Ruby

interpreter. Ruby provides APIs for defining the following things:

- Methods, Singleton Methods

- Constants

To define a class or module, use the functions below:

VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)

VALUE rb_define_module_under(VALUE outer, const char *name)

To define methods or singleton methods, use these functions:

VALUE rb_current_receiver(void)

We have 2 functions to define constants:

The former is to define a constant under specified class/module. The

latter is to define a global constant.

There are several ways to invoke Ruby's features from C code.

The easiest way to use Ruby's functionality from a C program is to

evaluate the string as Ruby program. This function will do the job:

It returns nil when an error occurred. Moreover, *state is zero if str was

successfully evaluated, or nonzero otherwise.

You can invoke methods directly, without parsing the string. First I

need to explain about ID. ID is the integer number to represent

ID SYM2ID(VALUE symbol)

To invoke methods directly, you can use the function below

This function invokes a method on the recv, with the method name

specified by the symbol mid.

You can access class variables and instance variables using access

functions. Also, global variables can be shared between both

See also Constant Definition above.

=== Ruby Constants That Can Be Accessed From C

Ruby nil in C scope.

Information can be shared between the two environments using shared global

variables. To define them, you can use functions listed below:

VALUE (*getter)(ID id);

void (*setter)(VALUE val, ID id);

Sometimes you need to expose your struct in the C world as a Ruby

object.

work.

++

You can convert sval, a pointer to your struct, into a Ruby object

with the next macro.

TypedData_Wrap_Struct(). A pointer to the allocated structure will

be assigned to sval, which should be a pointer of the type specified.

To retrieve the C pointer from the Data object, use the macro

Data_Get_Struct().

See the example below for details.

OK, here's the example of making an extension library. This is the

extension to access DBMs. The full source is included in the ext/

directory in the Ruby's source tree.

% mkdir ext/dbm

Make a directory for the extension library under ext directory.

You need to design the library features, before making it.

You need to write C code for your extension library. If your library

has only one source file, choosing ``LIBRARY.c'' as a file name is

void rb_global_variable(VALUE *var)

If the file named extconf.rb exists, it will be executed to generate

Makefile.

``create_makefile''. The Makefile will not be generated, compilation will

not be done.

If the file named depend exists, Makefile will include that file to

check dependencies. You can make this file by invoking

It's harmless. Prepare it.

Try generating the Makefile by:

directory of the ruby source tree. In that case, compilation of the

interpreter will do this step for you.

Type

to compile your extension. You don't need this step either if you have

put the extension library under the ext directory of the ruby source tree.

You may need to rb_debug the extension. Extensions can be linked

statically by adding the directory name in the ext/Setup file so that

you can inspect the extension with the debugger.

You can do anything you want with your library. The author of Ruby

will not claim any restrictions on your code depending on the Ruby API.

Feel free to use, modify, distribute or sell your program.

class.c :: classes and modules

error.c :: exception classes and exception mechanism

object.c :: objects

variable.c :: variables and constants

parse.y :: grammar definition

parse.c :: automatically generated from parse.y

defs/keywords :: reserved keywords

lex.c :: automatically generated from keywords

compile.c

eval.c

-> opt*.inc : automatically generated

-> vm.inc : automatically generated

regex.c

regcomp.c

regparse.c

regsyntax.c

debug.c :: debug symbols for C debugger

dln.c :: dynamic loading

strftime.c :: formatting times

util.c :: misc utilities

dmyext.c

dmydln.c

gem_prelude.rb

prelude.rb

array.c :: Array

bignum.c :: Bignum

defs/known_errors.def :: Errno::* exception classes

-> known_errors.inc :: automatically generated

encoding.c :: Encoding

transcode.c :: Encoding::Converter

enc/*.c :: encoding classes

enc/trans/* :: codepoint mapping tables

goruby.c

golf_prelude.rb : goruby specific libraries.

-> golf_prelude.c : automatically generated

VALUE ::

such as struct RString, etc. To refer the values in structures, use

casting macros like RSTRING(obj).

Qnil ::

false object

Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ::

This macro retrieves the pointer value from DATA, and assigns it to

the variable sval.

RB_TYPE_P(value, type) ::

Checks that +value+ is a String and is not tainted

FIX2INT(value), INT2FIX(i) ::

char * -> String

VALUE rb_define_class(const char *name, VALUE super) ::

Extend the object with the module's attributes.

void rb_define_variable(const char *name, VALUE *var) ::

GC requires C global variables which hold Ruby values to be marked.

rb_global_variable tells GC to protect these variables.

void rb_define_const(VALUE klass, const char *name, VALUE val) ::

rb_define_const(rb_cObject, name, val)

rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ::

non-symbol keys, then they are copied to another hash and the new hash

is stored through +original_hash+, else 0 is stored.

VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::

Returns true if the object responds to the message specified by id.

VALUE rb_iv_get(VALUE obj, const char *name) ::

Sets the value of the instance variable.

VALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) ::

return the given argument value. This function never return to the

caller.

void rb_warn(const char *fmt, ...) ::

must be a VALUE). Since it conflicts with "%i", for integers in

format strings, use "%d".

The embedding API functions are below (not needed for extension libraries):

Specifies the name of the script ($0).

void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) ::

Removes the specified hook function.

void rb_gc_adjust_memory_usage(ssize_t diff) ::

is decreased; a memory block is freed or a block is reallocated as

smaller size. This function may trigger the GC.

Some macros to check API compatibilities are available by default.

Means that rb_add_event_hook() takes the third argument `data', to be

passed to the given event hook function.

See documentation for {mkmf}[rdoc-ref:MakeMakefile].

Ruby 2.1 introduced a generational garbage collector (called RGenGC).

RGenGC (mostly) keeps compatibility.

be further improved. Especially, the "Don't touch pointers directly" section is

important.

You can't write RBASIC(obj)->klass field directly because it is const

value now.

Reset RBasic::klass to be klass.

We expect the `klass' is hidden class by rb_obj_hide().

RGenGC doesn't require write barriers to support generational GC.

However, caring about write barrier can improve the performance of

RGenGC. Please check the following tips.

In MRI (include/ruby/ruby.h), some macros to acquire pointers to the

internal data structures are supported such as RARRAY_PTR(),

DO NOT USE THESE MACROS and instead use the corresponding C-APIs such as

rb_ary_aref(), rb_ary_store() and so on.

You don't need to care about write barriers if you only use built-in

types.

of overhead. Basically we don't recommend you insert write barriers.

Please carefully consider the risks.

Please consider utilizing built-in types. Most built-in types support

write barrier, so you can use them to avoid manually inserting write

With use of such techniques, you don't need to insert write barriers

anymore.

\[AGAIN] Inserting write barriers is a very difficult hack, and it is

easy to introduce critical bugs. And inserting write barriers has

For a complete guide for RGenGC and write barriers, please refer to

<https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RGenGC>.

C Ruby currently uses conservative garbage collection, thus VALUE

variables must remain visible on the stack or registers to ensure any