Project

General

Profile

Bug #13229 » doc_extension_title.patch

stomar (Marcus Stollsteimer), 02/18/2017 02:59 PM

View differences:

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

  
3
= Creating Extension Libraries for Ruby
4

  
3 5
Rubyの拡張ライブラリの作り方を説明します.
4 6

  
5
= 基礎知識
7
== 基礎知識
6 8

  
7 9
Cの変数には型があり,データには型がありません.ですから,た
8 10
とえばポインタをintの変数に代入すると,その値は整数として取
......
23 25
の両方が必要です.(1)を忘れると間違ったデータの変換が行われ
24 26
て,最悪プログラムがcore dumpします.
25 27

  
26
== データタイプ
28
=== データタイプ
27 29

  
28 30
Rubyにはユーザが使う可能性のある以下のタイプがあります.
29 31

  
......
57 59

  
58 60
ほとんどのタイプはCの構造体で実装されています.
59 61

  
60
== VALUEのデータタイプをチェックする
62
=== VALUEのデータタイプをチェックする
61 63

  
62 64
ruby.hではTYPE()というマクロが定義されていて,VALUEのデータ
63 65
タイプを知ることが出来ます.TYPE()マクロは上で紹介したT_XXXX
......
94 96
  FIXNUM_P(obj)
95 97
  NIL_P(obj)
96 98

  
97
== VALUEをCのデータに変換する
99
=== VALUEをCのデータに変換する
98 100

  
99 101
データタイプがT_NIL,T_FALSE,T_TRUEである時,データはそれぞ
100 102
れnil,false,trueです.このデータタイプのオブジェクトはひと
......
155 157
ないことです.直接変更した場合,オブジェクトの内容の整合性が
156 158
とれなくなって,思わぬバグの原因になります.
157 159

  
158
== CのデータをVALUEに変換する
160
=== CのデータをVALUEに変換する
159 161

  
160 162
VALUEの実際の構造は
161 163

  
......
188 190
INT2NUM()は整数がFIXNUMの範囲に収まらない場合,Bignumに変換
189 191
してくれます(が,少し遅い).
190 192

  
191
== Rubyのデータを操作する
193
=== Rubyのデータを操作する
192 194

  
193 195
先程も述べた通り,Rubyの構造体をアクセスする時に内容の更新を
194 196
行うことは勧められません.で,Rubyのデータを操作する時には
......
197 199
ここではもっとも使われるであろう文字列と配列の生成/操作を行
198 200
う関数をあげます(全部ではないです).
199 201

  
200
=== 文字列に対する関数
202
==== 文字列に対する関数
201 203

  
202 204
rb_str_new(const char *ptr, long len) ::
203 205

  
......
295 297
  lenバイトまでの内容は保存される.lenはstrの容量を越えてい
296 298
  てはならない.
297 299

  
298
=== 配列に対する関数
300
==== 配列に対する関数
299 301

  
300 302
rb_ary_new() ::
301 303

  
......
353 355

  
354 356
  配列aryにptrからlen個のオブジェクトを追加する.
355 357

  
356
= Rubyの機能を使う
358
== Rubyの機能を使う
357 359

  
358 360
原理的にRubyで書けることはCでも書けます.RubyそのものがCで記
359 361
述されているんですから,当然といえば当然なんですけど.ここで
360 362
はRubyの拡張に使うことが多いだろうと予測される機能を中心に紹
361 363
介します.
362 364

  
363
== Rubyに機能を追加する
365
=== Rubyに機能を追加する
364 366

  
365 367
Rubyで提供されている関数を使えばRubyインタプリタに新しい機能
366 368
を追加することができます.Rubyでは以下の機能を追加する関数が
......
372 374

  
373 375
では順に紹介します.
374 376

  
375
=== クラス/モジュール定義
377
==== クラス/モジュール定義
376 378

  
377 379
クラスやモジュールを定義するためには,以下の関数を使います.
378 380

  
......
389 391
  VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
390 392
  VALUE rb_define_module_under(VALUE outer, const char *name)
391 393

  
392
=== メソッド/特異メソッド定義
394
==== メソッド/特異メソッド定義
393 395

  
394 396
メソッドや特異メソッドを定義するには以下の関数を使います.
395 397

  
......
483 485

  
484 486
  VALUE rb_current_receiver(void)
485 487

  
486
=== 定数定義
488
==== 定数定義
487 489

  
488 490
拡張ライブラリが必要な定数はあらかじめ定義しておいた方が良い
489 491
でしょう.定数を定義する関数は二つあります.
......
494 496
前者は特定のクラス/モジュールに属する定数を定義するもの,後
495 497
者はグローバルな定数を定義するものです.
496 498

  
497
== Rubyの機能をCから呼び出す
499
=== Rubyの機能をCから呼び出す
498 500

  
499 501
既に『1.5 Rubyのデータを操作する』で一部紹介したような関数を
500 502
使えば,Rubyの機能を実現している関数を直接呼び出すことが出来
......
505 507

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

  
508
=== Rubyのプログラムをevalする
510
==== Rubyのプログラムをevalする
509 511

  
510 512
CからRubyの機能を呼び出すもっとも簡単な方法として,文字列で
511 513
与えられたRubyのプログラムを評価する以下の関数があります.
......
523 525
この関数はエラーが発生するとnilを返します.そして,成功時には
524 526
*stateはゼロに,さもなくば非ゼロになります.
525 527

  
526
=== IDまたはシンボル
528
==== IDまたはシンボル
527 529

  
528 530
Cから文字列を経由せずにRubyのメソッドを呼び出すこともできま
529 531
す.その前に,Rubyインタプリタ内でメソッドや変数名を指定する
......
566 568
これらの関数は,IDの代わりにシンボルを返すことを除けば上記の
567 569
関数と同じです.
568 570

  
569
=== CからRubyのメソッドを呼び出す
571
==== CからRubyのメソッドを呼び出す
570 572

  
571 573
Cから文字列を経由せずにRubyのメソッドを呼び出すためには以下
572 574
の関数を使います.
......
582 584

  
583 585
applyには引数としてRubyの配列を与えます.
584 586

  
585
=== 変数/定数を参照/更新する
587
==== 変数/定数を参照/更新する
586 588

  
587 589
Cから関数を使って参照・更新できるのは,定数,インスタンス変
588 590
数です.大域変数は一部のものはCの大域変数としてアクセスでき
......
603 605
定数を新しく定義するためには『2.1.3 定数定義』で紹介さ
604 606
れている関数を使ってください.
605 607

  
606
= RubyとCとの情報共有
608
== RubyとCとの情報共有
607 609

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

  
610
== Cから参照できるRubyの定数
612
=== Cから参照できるRubyの定数
611 613

  
612 614
以下のRubyの定数はCのレベルから参照できます.
613 615

  
......
620 622

  
621 623
  C言語から見た「nil」.
622 624

  
623
== CとRubyで共有される大域変数
625
=== CとRubyで共有される大域変数
624 626

  
625 627
CとRubyで大域変数を使って情報を共有できます.共有できる大域
626 628
変数にはいくつかの種類があります.そのなかでもっとも良く使わ
......
672 674
  (*getter)(ID id);
673 675
  (*setter)(VALUE val, ID id);
674 676

  
675
== CのデータをRubyオブジェクトにする
677
=== CのデータをRubyオブジェクトにする
676 678

  
677 679
Cの世界で定義されたデータ(構造体)をRubyのオブジェクトとして
678 680
取り扱いたい場合がありえます.このような場合はTypedData_XXX
......
685 687
があります.
686 688
++
687 689

  
688
=== 構造体からオブジェクトへ
690
==== 構造体からオブジェクトへ
689 691

  
690 692
構造体へのポインタsvalをRubyオブジェクトに変換するには次のマ
691 693
クロを使います。
......
793 795
は割り当てるC構造体の型です.割り当てられた構造体は変数sval
794 796
に代入されます.この変数の型は (type*) である必要があります.
795 797

  
796
=== オブジェクトから構造体へ
798
==== オブジェクトから構造体へ
797 799

  
798 800
TypedData_Wrap_StructやTypedData_Make_Structで生成したオブジェ
799 801
クトから構造体へのポインタを復元するには以下のマクロを用いま
......
806 808
これらのマクロの使い方はちょっと分かりにくいので,後で説明す
807 809
る例題を参照してください.
808 810

  
809
== ディレクトリを作る
811
== Example - Creating the dbm Extension
812

  
813
=== ディレクトリを作る
810 814

  
811 815
  % mkdir ext/dbm
812 816

  
......
816 820
ライブラリ用のディレクトリを作る必要があります.名前は適当に
817 821
選んで構いません.
818 822

  
819
== 設計する
823
=== 設計する
820 824

  
821 825
まあ,当然なんですけど,どういう機能を実現するかどうかまず設
822 826
計する必要があります.どんなクラスをつくるか,そのクラスには
823 827
どんなメソッドがあるか,クラスが提供する定数などについて設計
824 828
します.
825 829

  
826
== Cコードを書く
830
=== Cコードを書く
827 831

  
828 832
拡張ライブラリ本体となるC言語のソースを書きます.C言語のソー
829 833
スがひとつの時には「ライブラリ名.c」を選ぶと良いでしょう.C
......
960 964

  
961 965
  void rb_global_variable(VALUE *var)
962 966

  
963
== extconf.rbを用意する
967
=== extconf.rbを用意する
964 968

  
965 969
Makefileを作る場合の雛型になるextconf.rbというファイルを作り
966 970
ます.extconf.rbはライブラリのコンパイルに必要な条件のチェッ
......
991 995
パイルしない時にはcreate_makefileを呼ばなければMakefileは生
992 996
成されず,コンパイルも行われません.
993 997

  
994
== dependを用意する
998
=== dependを用意する
995 999

  
996 1000
もし,ディレクトリにdependというファイルが存在すれば,
997 1001
Makefileが依存関係をチェックしてくれます.
......
1000 1004

  
1001 1005
などで作ることが出来ます.あって損は無いでしょう.
1002 1006

  
1003
== Makefileを生成する
1007
=== Makefileを生成する
1004 1008

  
1005 1009
Makefileを実際に生成するためには
1006 1010

  
......
1022 1026
ディレクトリをext以下に用意した場合にはRuby全体のmakeの時に
1023 1027
自動的にMakefileが生成されますので,このステップは不要です.
1024 1028

  
1025
== makeする
1029
=== makeする
1026 1030

  
1027 1031
動的リンクライブラリを生成する場合にはその場でmakeしてくださ
1028 1032
い.必要であれば make install でインストールされます.
......
1040 1044
を作り,そこに 拡張子 .rb のファイルを置いておけば同時にイン
1041 1045
ストールされます.
1042 1046

  
1043
== デバッグ
1047
=== デバッグ
1044 1048

  
1045 1049
まあ,デバッグしないと動かないでしょうね.ext/Setupにディレ
1046 1050
クトリ名を書くと静的にリンクするのでデバッガが使えるようにな
1047 1051
ります.その分コンパイルが遅くなりますけど.
1048 1052

  
1049
== できあがり
1053
=== できあがり
1050 1054

  
1051 1055
後はこっそり使うなり,広く公開するなり,売るなり,ご自由にお
1052 1056
使いください.Rubyの作者は拡張ライブラリに関して一切の権利を
1053 1057
主張しません.
1054 1058

  
1055
= Appendix A. Rubyのソースコードの分類
1059
== Appendix A. Rubyのソースコードの分類
1056 1060

  
1057 1061
Rubyのソースはいくつかに分類することが出来ます.このうちクラ
1058 1062
スライブラリの部分は基本的に拡張ライブラリと同じ作り方になっ
1059 1063
ています.これらのソースは今までの説明でほとんど理解できると
1060 1064
思います.
1061 1065

  
1062
== Ruby言語のコア
1066
=== Ruby言語のコア
1063 1067

  
1064 1068
class.c    :: クラスとモジュール
1065 1069
error.c    :: 例外クラスと例外機構
......
1068 1072
object.c   :: オブジェクト
1069 1073
variable.c :: 変数と定数
1070 1074

  
1071
== Rubyの構文解析器
1075
=== Rubyの構文解析器
1072 1076

  
1073 1077
parse.y       :: 字句解析器と構文定義
1074 1078
parse.c       :: 自動生成
1075 1079
defs/keywords :: 予約語
1076 1080
lex.c         :: 自動生成
1077 1081

  
1078
== Rubyの評価器 (通称YARV)
1082
=== Rubyの評価器 (通称YARV)
1079 1083

  
1080 1084
  compile.c
1081 1085
  eval.c
......
1101 1105
    -> opt*.inc            : 自動生成
1102 1106
    -> vm.inc              : 自動生成
1103 1107

  
1104
== 正規表現エンジン (鬼車)
1108
=== 正規表現エンジン (鬼車)
1105 1109

  
1106 1110
  regex.c
1107 1111
  regcomp.c
......
1111 1115
  regparse.c
1112 1116
  regsyntax.c
1113 1117

  
1114
== ユーティリティ関数
1118
=== ユーティリティ関数
1115 1119

  
1116 1120
debug.c    :: Cデバッガ用のデバッグシンボル
1117 1121
dln.c      :: 動的ローディング
......
1119 1123
strftime.c :: 時刻整形
1120 1124
util.c     :: その他のユーティリティ
1121 1125

  
1122
== Rubyコマンドの実装
1126
=== Rubyコマンドの実装
1123 1127

  
1124 1128
  dmyext.c
1125 1129
  dmydln.c
......
1133 1137
  gem_prelude.rb
1134 1138
  prelude.rb
1135 1139

  
1136
== クラスライブラリ
1140
=== クラスライブラリ
1137 1141

  
1138 1142
array.c      :: Array
1139 1143
bignum.c     :: Bignum
......
1165 1169
defs/known_errors.def :: 例外クラス Errno::*
1166 1170
-> known_errors.inc   :: 自動生成
1167 1171

  
1168
== 多言語化
1172
=== 多言語化
1169 1173

  
1170 1174
encoding.c  :: Encoding
1171 1175
transcode.c :: Encoding::Converter
1172 1176
enc/*.c     :: エンコーディングクラス群
1173 1177
enc/trans/* :: コードポイント対応表
1174 1178

  
1175
== gorubyコマンドの実装
1179
=== gorubyコマンドの実装
1176 1180

  
1177 1181
  goruby.c
1178 1182
  golf_prelude.rb      : goruby固有のライブラリ
1179 1183
    -> golf_prelude.c  : 自動生成
1180 1184

  
1181
= Appendix B. 拡張用関数リファレンス
1185
== Appendix B. 拡張用関数リファレンス
1182 1186

  
1183 1187
C言語からRubyの機能を利用するAPIは以下の通りである.
1184 1188

  
1185
==
1189
===
1186 1190

  
1187 1191
VALUE ::
1188 1192

  
......
1191 1195
  体である.VALUE型をこれらにキャストするためにRで始まる構造体
1192 1196
  名を全て大文字にした名前のマクロが用意されている.
1193 1197

  
1194
== 変数・定数
1198
=== 変数・定数
1195 1199

  
1196 1200
Qnil ::
1197 1201

  
......
1205 1209

  
1206 1210
  定数: falseオブジェクト
1207 1211

  
1208
== Cデータのカプセル化
1212
=== Cデータのカプセル化
1209 1213

  
1210 1214
Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ::
1211 1215

  
......
1224 1228

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

  
1227
== 型チェック
1231
=== 型チェック
1228 1232

  
1229 1233
  RB_TYPE_P(value, type)
1230 1234
  TYPE(value)
......
1235 1239
  void Check_Type(VALUE value, int type)
1236 1240
  SafeStringValue(value)
1237 1241

  
1238
== 型変換
1242
=== 型変換
1239 1243

  
1240 1244
  FIX2INT(value), INT2FIX(i)
1241 1245
  FIX2LONG(value), LONG2FIX(l)
......
1258 1262
  StringValueCStr(value)
1259 1263
  rb_str_new2(s)
1260 1264

  
1261
== クラス/モジュール定義
1265
=== クラス/モジュール定義
1262 1266

  
1263 1267
VALUE rb_define_class(const char *name, VALUE super) ::
1264 1268

  
......
1286 1290

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

  
1289
== 大域変数定義
1293
=== 大域変数定義
1290 1294

  
1291 1295
void rb_define_variable(const char *name, VALUE *var) ::
1292 1296

  
......
1318 1322
  GCのため,Rubyプログラムからはアクセスされないが, Rubyオブ
1319 1323
  ジェクトを含む大域変数をマークする.
1320 1324

  
1321
== 定数
1325
=== 定数
1322 1326

  
1323 1327
void rb_define_const(VALUE klass, const char *name, VALUE val) ::
1324 1328

  
......
1332 1336

  
1333 1337
  と同じ意味.
1334 1338

  
1335
== メソッド定義
1339
=== メソッド定義
1336 1340

  
1337 1341
rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ::
1338 1342

  
......
1421 1425
  先には,元のHashがSymbol以外のキーを含んでいた場合はそれらが
1422 1426
  コピーされた別の新しいHash,そうでなければ0が保存されます.
1423 1427

  
1424
== Rubyメソッド呼び出し
1428
=== Rubyメソッド呼び出し
1425 1429

  
1426 1430
VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::
1427 1431

  
......
1461 1465

  
1462 1466
  objがidで示されるメソッドを持つかどうかを返す.
1463 1467

  
1464
== インスタンス変数
1468
=== インスタンス変数
1465 1469

  
1466 1470
VALUE rb_iv_get(VALUE obj, const char *name) ::
1467 1471

  
......
1474 1478

  
1475 1479
  objのインスタンス変数をvalにセットする.
1476 1480

  
1477
== 制御構造
1481
=== 制御構造
1478 1482

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

  
......
1536 1540
  現在の最も内側のブロックをvalueで終了する.ブロックは引数で
1537 1541
  与えられたvalueを返す.この関数は直接の呼び出し元に戻らない.
1538 1542

  
1539
== 例外・エラー
1543
=== 例外・エラー
1540 1544

  
1541 1545
void rb_warning(const char *fmt, ...) ::
1542 1546

  
......
1568 1572
きはObject#inspect)を使ったVALUEの出力に利用できる.これは
1569 1573
"%i"と衝突するため,整数には"%d"を使用すること.
1570 1574

  
1571
== Rubyの初期化・実行
1575
=== Rubyの初期化・実行
1572 1576

  
1573 1577
Rubyをアプリケーションに埋め込む場合には以下のインタフェース
1574 1578
を使う.通常の拡張ライブラリには必要ない.
......
1592 1596

  
1593 1597
  Rubyのスクリプト名($0)を設定する.
1594 1598

  
1595
== インタプリタのイベントのフック
1599
=== インタプリタのイベントのフック
1596 1600

  
1597 1601
void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) ::
1598 1602

  
......
1622 1626

  
1623 1627
  指定されたフック関数を削除します.
1624 1628

  
1625
== メモリ使用量
1629
=== メモリ使用量
1626 1630

  
1627 1631
void rb_gc_adjust_memory_usage(ssize_t diff) ::
1628 1632

  
......
1634 1638
  す.メモリブロックが解放されたり,メモリブロックがより小さいサイズで再
1635 1639
  確保されたりした場合などです.この関数はGCを引き起こすかもしれません.
1636 1640

  
1637
== 互換性のためのマクロ
1641
=== 互換性のためのマクロ
1638 1642

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

  
......
1676 1680
  rb_add_event_hook() がフック関数に渡す data を第3引数として
1677 1681
  受け取ることを意味する.
1678 1682

  
1679
= Appendix C. extconf.rbで使える関数たち
1683
== Appendix C. extconf.rbで使える関数たち
1680 1684

  
1681 1685
extconf.rbの中では利用可能なコンパイル条件チェックの関数は以
1682 1686
下の通りである.
......
1802 1806
  optionが指定された場合は,上記の配列の代わりにそのオプションを
1803 1807
  指定して得られた出力をstripしたものを返す.
1804 1808

  
1805
= Appendix D. 世代別GC
1809
== Appendix D. 世代別GC
1806 1810

  
1807 1811
Ruby 2.1から世代別GCに対応しました.我々はこれをRGenGCと呼んでいます.
1808 1812
RGenGCは,過去の拡張ライブラリに(ほぼ)互換性を保つように開発されている
doc/extension.rdoc
1 1
# extension.rdoc -  -*- RDoc -*- created at: Mon Aug  7 16:45:54 JST 1995
2 2

  
3
= Creating Extension Libraries for Ruby
4

  
3 5
This document explains how to make extension libraries for Ruby.
4 6

  
5
= Basic Knowledge
7
== Basic Knowledge
6 8

  
7 9
In C, variables have types and data do not have types.  In contrast,
8 10
Ruby variables do not have a static type, and data themselves have
......
18 20

  
19 21
Converting to the wrong data type may cause serious problems.
20 22

  
21
== Data Types
23
=== Data Types
22 24

  
23 25
The Ruby interpreter has the following data types:
24 26

  
......
52 54

  
53 55
Most of the types are represented by C structures.
54 56

  
55
== Check Data Type of the VALUE
57
=== Check Data Type of the VALUE
56 58

  
57 59
The macro TYPE() defined in ruby.h shows the data type of the VALUE.
58 60
TYPE() returns the constant number T_XXXX described above.  To handle
......
86 88
  FIXNUM_P(obj)
87 89
  NIL_P(obj)
88 90

  
89
== Convert VALUE into C Data
91
=== Convert VALUE into C Data
90 92

  
91 93
The data for type T_NIL, T_FALSE, T_TRUE are nil, false, true
92 94
respectively.  They are singletons for the data type.
......
139 141
are responsible for the result.  This ends up being the cause of
140 142
interesting bugs.
141 143

  
142
== Convert C Data into VALUE
144
=== Convert C Data into VALUE
143 145

  
144 146
To convert C data to Ruby values:
145 147

  
......
165 167
INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM
166 168
range, but is a bit slower.
167 169

  
168
== Manipulating Ruby Data
170
=== Manipulating Ruby Data
169 171

  
170 172
As I already mentioned, it is not recommended to modify an object's
171 173
internal structure.  To manipulate objects, use the functions supplied
172 174
by the Ruby interpreter. Some (not all) of the useful functions are
173 175
listed below:
174 176

  
175
=== String Functions
177
==== String Functions
176 178

  
177 179
rb_str_new(const char *ptr, long len) ::
178 180

  
......
273 275
  up to len bytes, regardless RSTRING_LEN(str).  len must not exceed
274 276
  the capacity of str.
275 277

  
276
=== Array Functions
278
==== Array Functions
277 279

  
278 280
rb_ary_new() ::
279 281

  
......
330 332

  
331 333
  Appends len elements of objects from ptr to the array.
332 334

  
333
= Extending Ruby with C
335
== Extending Ruby with C
334 336

  
335
== Adding New Features to Ruby
337
=== Adding New Features to Ruby
336 338

  
337 339
You can add new features (classes, methods, etc.) to the Ruby
338 340
interpreter.  Ruby provides APIs for defining the following things:
......
341 343
- Methods, Singleton Methods
342 344
- Constants
343 345

  
344
=== Class and Module Definition
346
==== Class and Module Definition
345 347

  
346 348
To define a class or module, use the functions below:
347 349

  
......
356 358
  VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
357 359
  VALUE rb_define_module_under(VALUE outer, const char *name)
358 360

  
359
=== Method and Singleton Method Definition
361
==== Method and Singleton Method Definition
360 362

  
361 363
To define methods or singleton methods, use these functions:
362 364

  
......
449 451

  
450 452
  VALUE rb_current_receiver(void)
451 453

  
452
=== Constant Definition
454
==== Constant Definition
453 455

  
454 456
We have 2 functions to define constants:
455 457

  
......
459 461
The former is to define a constant under specified class/module.  The
460 462
latter is to define a global constant.
461 463

  
462
== Use Ruby Features from C
464
=== Use Ruby Features from C
463 465

  
464 466
There are several ways to invoke Ruby's features from C code.
465 467

  
466
=== Evaluate Ruby Programs in a String
468
==== Evaluate Ruby Programs in a String
467 469

  
468 470
The easiest way to use Ruby's functionality from a C program is to
469 471
evaluate the string as Ruby program.  This function will do the job:
......
481 483
It returns nil when an error occurred. Moreover, *state is zero if str was
482 484
successfully evaluated, or nonzero otherwise.
483 485

  
484
=== ID or Symbol
486
==== ID or Symbol
485 487

  
486 488
You can invoke methods directly, without parsing the string.  First I
487 489
need to explain about ID.  ID is the integer number to represent
......
532 534

  
533 535
  ID SYM2ID(VALUE symbol)
534 536

  
535
=== Invoke Ruby Method from C
537
==== Invoke Ruby Method from C
536 538

  
537 539
To invoke methods directly, you can use the function below
538 540

  
......
541 543
This function invokes a method on the recv, with the method name
542 544
specified by the symbol mid.
543 545

  
544
=== Accessing the Variables and Constants
546
==== Accessing the Variables and Constants
545 547

  
546 548
You can access class variables and instance variables using access
547 549
functions.  Also, global variables can be shared between both
......
560 562

  
561 563
See also Constant Definition above.
562 564

  
563
= Information Sharing Between Ruby and C
565
== Information Sharing Between Ruby and C
564 566

  
565 567
=== Ruby Constants That Can Be Accessed From C
566 568

  
......
576 578

  
577 579
  Ruby nil in C scope.
578 580

  
579
== Global Variables Shared Between C and Ruby
581
=== Global Variables Shared Between C and Ruby
580 582

  
581 583
Information can be shared between the two environments using shared global
582 584
variables.  To define them, you can use functions listed below:
......
618 620
  VALUE (*getter)(ID id);
619 621
  void (*setter)(VALUE val, ID id);
620 622

  
621
== Encapsulate C Data into a Ruby Object
623
=== Encapsulate C Data into a Ruby Object
622 624

  
623 625
Sometimes you need to expose your struct in the C world as a Ruby
624 626
object.
......
632 634
work.
633 635
++
634 636

  
635
=== C struct to Ruby object
637
==== C struct to Ruby object
636 638

  
637 639
You can convert sval, a pointer to your struct, into a Ruby object
638 640
with the next macro.
......
735 737
TypedData_Wrap_Struct().  A pointer to the allocated structure will
736 738
be assigned to sval, which should be a pointer of the type specified.
737 739

  
738
=== Ruby object to C struct
740
==== Ruby object to C struct
739 741

  
740 742
To retrieve the C pointer from the Data object, use the macro
741 743
Data_Get_Struct().
......
746 748

  
747 749
See the example below for details.
748 750

  
749
= Example - Creating the dbm Extension
751
== Example - Creating the dbm Extension
750 752

  
751 753
OK, here's the example of making an extension library.  This is the
752 754
extension to access DBMs.  The full source is included in the ext/
753 755
directory in the Ruby's source tree.
754 756

  
755
== Make the Directory
757
=== Make the Directory
756 758

  
757 759
  % mkdir ext/dbm
758 760

  
759 761
Make a directory for the extension library under ext directory.
760 762

  
761
== Design the Library
763
=== Design the Library
762 764

  
763 765
You need to design the library features, before making it.
764 766

  
765
== Write the C Code
767
=== Write the C Code
766 768

  
767 769
You need to write C code for your extension library.  If your library
768 770
has only one source file, choosing ``LIBRARY.c'' as a file name is
......
887 889

  
888 890
  void rb_global_variable(VALUE *var)
889 891

  
890
== Prepare extconf.rb
892
=== Prepare extconf.rb
891 893

  
892 894
If the file named extconf.rb exists, it will be executed to generate
893 895
Makefile.
......
936 938
``create_makefile''.  The Makefile will not be generated, compilation will
937 939
not be done.
938 940

  
939
== Prepare Depend (Optional)
941
=== Prepare Depend (Optional)
940 942

  
941 943
If the file named depend exists, Makefile will include that file to
942 944
check dependencies.  You can make this file by invoking
......
945 947

  
946 948
It's harmless.  Prepare it.
947 949

  
948
== Generate Makefile
950
=== Generate Makefile
949 951

  
950 952
Try generating the Makefile by:
951 953

  
......
960 962
directory of the ruby source tree.  In that case, compilation of the
961 963
interpreter will do this step for you.
962 964

  
963
== Run make
965
=== Run make
964 966

  
965 967
Type
966 968

  
......
969 971
to compile your extension.  You don't need this step either if you have
970 972
put the extension library under the ext directory of the ruby source tree.
971 973

  
972
== Debug
974
=== Debug
973 975

  
974 976
You may need to rb_debug the extension.  Extensions can be linked
975 977
statically by adding the directory name in the ext/Setup file so that
976 978
you can inspect the extension with the debugger.
977 979

  
978
== Done! Now You Have the Extension Library
980
=== Done! Now You Have the Extension Library
979 981

  
980 982
You can do anything you want with your library.  The author of Ruby
981 983
will not claim any restrictions on your code depending on the Ruby API.
982 984
Feel free to use, modify, distribute or sell your program.
983 985

  
984
= Appendix A. Ruby Source Files Overview
986
== Appendix A. Ruby Source Files Overview
985 987

  
986
== Ruby Language Core
988
=== Ruby Language Core
987 989

  
988 990
class.c    :: classes and modules
989 991
error.c    :: exception classes and exception mechanism
......
992 994
object.c   :: objects
993 995
variable.c :: variables and constants
994 996

  
995
== Ruby Syntax Parser
997
=== Ruby Syntax Parser
996 998

  
997 999
parse.y       :: grammar definition
998 1000
parse.c       :: automatically generated from parse.y
999 1001
defs/keywords :: reserved keywords
1000 1002
lex.c         :: automatically generated from keywords
1001 1003

  
1002
== Ruby Evaluator (a.k.a. YARV)
1004
=== Ruby Evaluator (a.k.a. YARV)
1003 1005

  
1004 1006
  compile.c
1005 1007
  eval.c
......
1025 1027
    -> opt*.inc            : automatically generated
1026 1028
    -> vm.inc              : automatically generated
1027 1029

  
1028
== Regular Expression Engine (Oniguruma)
1030
=== Regular Expression Engine (Oniguruma)
1029 1031

  
1030 1032
  regex.c
1031 1033
  regcomp.c
......
1035 1037
  regparse.c
1036 1038
  regsyntax.c
1037 1039

  
1038
== Utility Functions
1040
=== Utility Functions
1039 1041

  
1040 1042
debug.c    :: debug symbols for C debugger
1041 1043
dln.c      :: dynamic loading
......
1043 1045
strftime.c :: formatting times
1044 1046
util.c     :: misc utilities
1045 1047

  
1046
== Ruby Interpreter Implementation
1048
=== Ruby Interpreter Implementation
1047 1049

  
1048 1050
  dmyext.c
1049 1051
  dmydln.c
......
1057 1059
  gem_prelude.rb
1058 1060
  prelude.rb
1059 1061

  
1060
== Class Library
1062
=== Class Library
1061 1063

  
1062 1064
array.c      :: Array
1063 1065
bignum.c     :: Bignum
......
1089 1091
defs/known_errors.def :: Errno::* exception classes
1090 1092
-> known_errors.inc   :: automatically generated
1091 1093

  
1092
== Multilingualization
1094
=== Multilingualization
1093 1095

  
1094 1096
encoding.c  :: Encoding
1095 1097
transcode.c :: Encoding::Converter
1096 1098
enc/*.c     :: encoding classes
1097 1099
enc/trans/* :: codepoint mapping tables
1098 1100

  
1099
== goruby Interpreter Implementation
1101
=== goruby Interpreter Implementation
1100 1102

  
1101 1103
  goruby.c
1102 1104
  golf_prelude.rb     : goruby specific libraries.
1103 1105
    -> golf_prelude.c : automatically generated
1104 1106

  
1105
= Appendix B. Ruby Extension API Reference
1107
== Appendix B. Ruby Extension API Reference
1106 1108

  
1107
== Types
1109
=== Types
1108 1110

  
1109 1111
VALUE ::
1110 1112

  
......
1112 1114
  such as struct RString, etc.  To refer the values in structures, use
1113 1115
  casting macros like RSTRING(obj).
1114 1116

  
1115
== Variables and Constants
1117
=== Variables and Constants
1116 1118

  
1117 1119
Qnil ::
1118 1120

  
......
1126 1128

  
1127 1129
  false object
1128 1130

  
1129
== C Pointer Wrapping
1131
=== C Pointer Wrapping
1130 1132

  
1131 1133
Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ::
1132 1134

  
......
1146 1148
  This macro retrieves the pointer value from DATA, and assigns it to
1147 1149
  the variable sval.
1148 1150

  
1149
== Checking Data Types
1151
=== Checking Data Types
1150 1152

  
1151 1153
RB_TYPE_P(value, type) ::
1152 1154

  
......
1180 1182

  
1181 1183
  Checks that +value+ is a String and is not tainted
1182 1184

  
1183
== Data Type Conversion
1185
=== Data Type Conversion
1184 1186

  
1185 1187
FIX2INT(value), INT2FIX(i) ::
1186 1188

  
......
1264 1266

  
1265 1267
  char * -> String
1266 1268

  
1267
== Defining Classes and Modules
1269
=== Defining Classes and Modules
1268 1270

  
1269 1271
VALUE rb_define_class(const char *name, VALUE super) ::
1270 1272

  
......
1291 1293

  
1292 1294
  Extend the object with the module's attributes.
1293 1295

  
1294
== Defining Global Variables
1296
=== Defining Global Variables
1295 1297

  
1296 1298
void rb_define_variable(const char *name, VALUE *var) ::
1297 1299

  
......
1332 1334
  GC requires C global variables which hold Ruby values to be marked.
1333 1335
  rb_global_variable tells GC to protect these variables.
1334 1336

  
1335
== Constant Definition
1337
=== Constant Definition
1336 1338

  
1337 1339
void rb_define_const(VALUE klass, const char *name, VALUE val) ::
1338 1340

  
......
1344 1346

  
1345 1347
    rb_define_const(rb_cObject, name, val)
1346 1348

  
1347
== Method Definition
1349
=== Method Definition
1348 1350

  
1349 1351
rb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ::
1350 1352

  
......
1447 1449
  non-symbol keys, then they are copied to another hash and the new hash
1448 1450
  is stored through +original_hash+, else 0 is stored.
1449 1451

  
1450
== Invoking Ruby method
1452
=== Invoking Ruby method
1451 1453

  
1452 1454
VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ::
1453 1455

  
......
1485 1487

  
1486 1488
  Returns true if the object responds to the message specified by id.
1487 1489

  
1488
== Instance Variables
1490
=== Instance Variables
1489 1491

  
1490 1492
VALUE rb_iv_get(VALUE obj, const char *name) ::
1491 1493

  
......
1496 1498

  
1497 1499
  Sets the value of the instance variable.
1498 1500

  
1499
== Control Structure
1501
=== Control Structure
1500 1502

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

  
......
1562 1564
  return the given argument value.  This function never return to the
1563 1565
  caller.
1564 1566

  
1565
== Exceptions and Errors
1567
=== Exceptions and Errors
1566 1568

  
1567 1569
void rb_warn(const char *fmt, ...) ::
1568 1570

  
......
1597 1599
must be a VALUE).  Since it conflicts with "%i", for integers in
1598 1600
format strings, use "%d".
1599 1601

  
1600
== Initialize and Start the Interpreter
1602
=== Initialize and Start the Interpreter
1601 1603

  
1602 1604
The embedding API functions are below (not needed for extension libraries):
1603 1605

  
......
1622 1624

  
1623 1625
  Specifies the name of the script ($0).
1624 1626

  
1625
== Hooks for the Interpreter Events
1627
=== Hooks for the Interpreter Events
1626 1628

  
1627 1629
void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) ::
1628 1630

  
......
1652 1654

  
1653 1655
  Removes the specified hook function.
1654 1656

  
1655
== Memory usage
1657
=== Memory usage
1656 1658

  
1657 1659
void rb_gc_adjust_memory_usage(ssize_t diff) ::
1658 1660

  
......
1664 1666
  is decreased; a memory block is freed or a block is reallocated as
1665 1667
  smaller size.  This function may trigger the GC.
1666 1668

  
1667
== Macros for Compatibility
1669
=== Macros for Compatibility
1668 1670

  
1669 1671
Some macros to check API compatibilities are available by default.
1670 1672

  
......
1704 1706
  Means that rb_add_event_hook() takes the third argument `data', to be
1705 1707
  passed to the given event hook function.
1706 1708

  
1707
= Appendix C. Functions available for use in extconf.rb
1709
== Appendix C. Functions available for use in extconf.rb
1708 1710

  
1709 1711
See documentation for {mkmf}[rdoc-ref:MakeMakefile].
1710 1712

  
1711
= Appendix D. Generational GC
1713
== Appendix D. Generational GC
1712 1714

  
1713 1715
Ruby 2.1 introduced a generational garbage collector (called RGenGC).
1714 1716
RGenGC (mostly) keeps compatibility.
......
1722 1724
be further improved. Especially, the "Don't touch pointers directly" section is
1723 1725
important.
1724 1726

  
1725
== Incompatibility
1727
=== Incompatibility
1726 1728

  
1727 1729
You can't write RBASIC(obj)->klass field directly because it is const
1728 1730
value now.
......
1741 1743
  Reset RBasic::klass to be klass.
1742 1744
  We expect the `klass' is hidden class by rb_obj_hide().
1743 1745

  
1744
== Write barriers
1746
=== Write barriers
1745 1747

  
1746 1748
RGenGC doesn't require write barriers to support generational GC.
1747 1749
However, caring about write barrier can improve the performance of
1748 1750
RGenGC. Please check the following tips.
1749 1751

  
1750
=== Don't touch pointers directly
1752
==== Don't touch pointers directly
1751 1753

  
1752 1754
In MRI (include/ruby/ruby.h), some macros to acquire pointers to the
1753 1755
internal data structures are supported such as RARRAY_PTR(),
......
1756 1758
DO NOT USE THESE MACROS and instead use the corresponding C-APIs such as
1757 1759
rb_ary_aref(), rb_ary_store() and so on.
1758 1760

  
1759
=== Consider whether to insert write barriers
1761
==== Consider whether to insert write barriers
1760 1762

  
1761 1763
You don't need to care about write barriers if you only use built-in
1762 1764
types.
......
1778 1780
of overhead. Basically we don't recommend you insert write barriers.
1779 1781
Please carefully consider the risks.
1780 1782

  
1781
=== Combine with built-in types
1783
==== Combine with built-in types
1782 1784

  
1783 1785
Please consider utilizing built-in types. Most built-in types support
1784 1786
write barrier, so you can use them to avoid manually inserting write
......
1793 1795
With use of such techniques, you don't need to insert write barriers
1794 1796
anymore.
1795 1797

  
1796
=== Insert write barriers
1798
==== Insert write barriers
1797 1799

  
1798 1800
\[AGAIN] Inserting write barriers is a very difficult hack, and it is
1799 1801
easy to introduce critical bugs. And inserting write barriers has
......
1807 1809
For a complete guide for RGenGC and write barriers, please refer to
1808 1810
<https://bugs.ruby-lang.org/projects/ruby-trunk/wiki/RGenGC>.
1809 1811

  
1810
= Appendix E. RB_GC_GUARD to protect from premature GC
1812
== Appendix E. RB_GC_GUARD to protect from premature GC
1811 1813

  
1812 1814
C Ruby currently uses conservative garbage collection, thus VALUE
1813 1815
variables must remain visible on the stack or registers to ensure any