summaryrefslogtreecommitdiff
path: root/doc/extension.ja.rdoc
diff options
context:
space:
mode:
Diffstat (limited to 'doc/extension.ja.rdoc')
-rw-r--r--doc/extension.ja.rdoc114
1 files changed, 71 insertions, 43 deletions
diff --git a/doc/extension.ja.rdoc b/doc/extension.ja.rdoc
index a6f7719792..48699ac620 100644
--- a/doc/extension.ja.rdoc
+++ b/doc/extension.ja.rdoc
@@ -617,12 +617,14 @@ C言語とRubyの間で情報を共有する方法について解説します.
Qtrue ::
Qfalse ::
- 真偽値.QfalseはC言語でも偽とみなされます(つまり0).
+ 真偽値.C言語から見た「true」と「false」.
Qnil ::
C言語から見た「nil」.
+RTEST(obj)というマクロはobjがQfalseかQnilのとき0を返します.
+
=== CとRubyで共有される大域変数
CとRubyで大域変数を使って情報を共有できます.共有できる大域
@@ -697,30 +699,28 @@ Cの世界で定義されたデータ(構造体)をRubyのオブジェクトと
このマクロの戻り値は生成されたオブジェクトを表すVALUE値です.
-klassはこのオブジェクトのクラスです.data_typeはこの構造体を
-Rubyが管理するための情報を記述したconst rb_data_type_t型への
-ポインタです.
+klassはこのオブジェクトのクラスです.klassは, Objectクラスか
+ら派生し, 必ずrb_define_alloc_funcかrb_undef_alloc_funcを呼
+び出してallocatorを設定してください.
-なお, klassは, Objectや他のクラスではなくData (rb_cData)とい
-う特別なクラスから派生することが推奨されます.
-Dataから派生しない場合には, 必ずrb_undef_alloc_func(klass)
-を呼び出してください.
+data_typeはこの構造体をRubyが管理するための情報を記述した
+const rb_data_type_t型へのポインタです.
rb_data_type_tは次のように定義されています.
typedef struct rb_data_type_struct rb_data_type_t;
struct rb_data_type_struct {
- const char *wrap_struct_name;
- struct {
- void (*dmark)(void*);
- void (*dfree)(void*);
- size_t (*dsize)(const void *);
- void *reserved[2];
- } function;
- const rb_data_type_t *parent;
- void *data;
- VALUE flags;
+ const char *wrap_struct_name;
+ struct {
+ void (*dmark)(void*);
+ void (*dfree)(void*);
+ size_t (*dsize)(const void *);
+ void *reserved[2];
+ } function;
+ const rb_data_type_t *parent;
+ void *data;
+ VALUE flags;
};
wrap_struct_nameはこの構造体を識別する名前です.主に統計情報
@@ -743,8 +743,8 @@ dmarkはガーベージコレクタがオブジェクトへの参照をマーク
++
dfreeはこの構造体がもう不要になった時に呼ばれる関数です.こ
-の関数がガーベージコレクタから呼ばれます.これが-1の場合は,
-単純に構造体が解放されます.
+の関数がガーベージコレクタから呼ばれます.これが
+RUBY_DEFAULT_FREEの場合は,単純に構造体が解放されます.
dsizeは構造体が消費しているメモリのバイト数を返す関数です.
引数として構造体へのポインタが渡されます.実装困難であれば0
@@ -780,9 +780,9 @@ RUBY_TYPED_WB_PROTECTED ::
メソッドの実装に適切にライトバリアを挿入する責任があります.
さもなくばRubyは実行時にクラッシュする可能性があります.
- ライトバリアについてはdoc/extension.ja.rdocのAppendix D
- "世代別GC"も参照してください.
-
+ ライトバリアについては{世代別
+ GC}[rdoc-ref:@Appendix+D.+-E4-B8-96-E4-BB-A3-E5-88-A5GC]
+ も参照してください.
Cの構造体の割当と対応するオブジェクトの生成を同時に行うマク
ロとして以下のものが提供されています.
@@ -888,12 +888,12 @@ dbm.cではTypedData_Make_Structを以下のように使っています.
obj = TypedData_Make_Struct(klass, struct dbmdata, &dbm_type, dbmp);
-ここではdbmdata構造体へのポインタをDataにカプセル化してい
-ます.DBM*を直接カプセル化しないのはclose()した時の処理を考
-えてのことです.
+ここではdbmdata構造体へのポインタをRubyオブジェクトにカプセ
+ル化しています.DBM*を直接カプセル化しないのはclose()した時
+の処理を考えてのことです.
-Dataオブジェクトからdbmstruct構造体のポインタを取り出すため
-に以下のマクロを使っています.
+Rubyオブジェクトからdbmdata構造体のポインタを取り出すために
+以下のマクロを使っています.
#define GetDBM(obj, dbmp) do {\
TypedData_Get_Struct((obj), struct dbmdata, &dbm_type, (dbmp));\
@@ -1066,6 +1066,20 @@ Rubyのソースはいくつかに分類することが出来ます.このう
ています.これらのソースは今までの説明でほとんど理解できると
思います.
+=== Rubyのヘッダファイル
+
+<tt>$repo_root/include/ruby</tt>以下はすべて<tt>make
+install</tt>でインストールされます.拡張ライブラリからは,
+<tt>#include <ruby.h></tt>でインクルードする必要があります.
++rbimpl_+,+RBIMPL_+のプレフィックスが付いた実装の詳細のため
+のシンボルを除き,すべてのシンボルは公開APIです.
+
+拡張ライブラリで直接インクルードできるのは,
+<tt>$repo_root/include/ruby/*.h</tt>のうち,対応する
+<tt>HAVE_RUBY_*_H</tt>マクロが
+<tt>$repo_root/include/ruby.h</tt>ヘッダーで定義されているも
+のです.
+
=== Ruby言語のコア
class.c :: クラスとモジュール
@@ -1681,6 +1695,9 @@ HAVE_RUBY_*_H ::
を意味する.たとえば,HAVE_RUBY_ST_H が定義されている場合は
単なる st.h ではなく ruby/st.h を使用する.
+ これらのマクロに対応するヘッダーファイルは,拡張ライブラリ
+ から直接インクルードしてもよい.
+
RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ::
rb_add_event_hook() がフック関数に渡す data を第3引数として
@@ -1714,7 +1731,7 @@ have_func(func, header) ::
ックする.funcが標準ではリンクされないライブラリ内のもので
ある時には先にhave_libraryでそのライブラリをチェックしてお
く事.チェックに成功すると,プリプロセッサマクロ
- `HAVE_{FUNC}` を定義し,trueを返す.
+ <tt>HAVE_{FUNC}</tt> を定義し,trueを返す.
have_var(var, header) ::
@@ -1722,41 +1739,49 @@ have_var(var, header) ::
クする.varが標準ではリンクされないライブラリ内のものであ
る時には先にhave_libraryでそのライブラリをチェックしておく
事.チェックに成功すると,プリプロセッサマクロ
- `HAVE_{VAR}` を定義し,trueを返す.
+ <tt>HAVE_{VAR}</tt> を定義し,trueを返す.
have_header(header) ::
ヘッダファイルの存在をチェックする.チェックに成功すると,
- プリプロセッサマクロ `HAVE_{HEADER_H}` を定義し,trueを返す.
+ プリプロセッサマクロ <tt>HAVE_{HEADER_H}</tt> を定義し,trueを返す.
(スラッシュやドットはアンダースコアに置換される)
find_header(header, path...) ::
ヘッダファイルheaderの存在を -Ipath を追加しながらチェック
する.チェックに成功すると,プリプロセッサマクロ
- `HAVE_{HEADER_H}` を定義し,trueを返す.
+ <tt>HAVE_{HEADER_H}</tt> を定義し,trueを返す.
(スラッシュやドットはアンダースコアに置換される)
have_struct_member(type, member[, header[, opt]]) ::
ヘッダファイルheaderをインクルードして型typeが定義され,
なおかつメンバmemberが存在するかをチェックする.チェックに
- 成功すると,プリプロセッサマクロ `HAVE_{TYPE}_{MEMBER}` を
+ 成功すると,プリプロセッサマクロ <tt>HAVE_{TYPE}_{MEMBER}</tt> を
定義し,trueを返す.
have_type(type, header, opt) ::
ヘッダファイルheaderをインクルードして型typeが存在するかを
チェックする.チェックに成功すると,プリプロセッサマクロ
- `HAVE_TYPE_{TYPE}` を定義し,trueを返す.
+ <tt>HAVE_TYPE_{TYPE}</tt> を定義し,trueを返す.
check_sizeof(type, header) ::
ヘッダファイルheaderをインクルードして型typeのchar単位サイ
ズを調べる.チェックに成功すると,プリプロセッサマクロ
- `SIZEOF_{TYPE}` を定義し,そのサイズを返す.定義されていな
+ <tt>SIZEOF_{TYPE}</tt> を定義し,そのサイズを返す.定義されていな
いときはnilを返す.
+append_cppflags(array-of-flags[, opt]) ::
+append_cflags(array-of-flags[, opt]) ::
+append_ldflags(array-of-flags[, opt]) ::
+
+ 各flagが使用可能であれば,それぞれ$CPPFLAGS, $CFLAGS,
+ $LDFLAGSに追加する.コンパイラのフラグには移植性がないので,
+ 変数に直接追加せずこれらを使うことが望ましい.
+
create_makefile(target[, target_prefix]) ::
拡張ライブラリ用のMakefileを生成する.この関数を呼ばなけれ
@@ -1825,8 +1850,9 @@ RGenGCは,過去の拡張ライブラリに(ほぼ)互換性を保つよ
スするようなコードは書かないようにして下さい.代わりに,rb_ary_aref(),
rb_ary_store() などの,適切な API 関数を利用するようにして下さい.
-そのほか,対応についての詳細は extension.rdoc の「Appendix D. Generational
-GC」を参照して下さい.
+そのほか,対応についての詳細は {Appendix D. Generational
+GC}[rdoc-ref:extension.rdoc@Appendix+D.+Generational+GC]を参
+照して下さい.
== Appendix E. Ractor サポート
@@ -1835,10 +1861,12 @@ Ruby 3.0 から、Ruby プログラムを並列に実行するための仕組み
なります。サポートしていないライブラリは、メイン Ractor 以外で実行すると
エラーになります(Ractor::UnsafeError)。
-Ractor をサポートするための詳細は、extension.rdoc の「Appendix F. Ractor
-support」を参照してください。
-
+Ractor をサポートするための詳細は、{Appendix F. Ractor
+support}[rdoc-ref:extension.rdoc@Appendix+F.+Ractor+support]
+を参照してください。
-:enddoc: Local variables:
-:enddoc: fill-column: 60
-:enddoc: end:
+--
+Local variables:
+fill-column: 60
+end:
+++