path: root/README.EXT
diff options
Diffstat (limited to 'README.EXT')
1 files changed, 32 insertions, 53 deletions
diff --git a/README.EXT b/README.EXT
index 297b31b..2f90c69 100644
@@ -109,25 +109,21 @@ bugs.
1.4 Convert C data into VALUE
+To convert C data to the values of Ruby:
- * FIXNUMの場合
- 1bit右シフトして,LSBを立てる.
+ right shift 1 bit, and turn on LSB.
- * その他のポインタの場合
+ * Other pointer values
- そのままVALUEにキャストする.
+ cast to VALUE.
+You can determine whether VALUE is pointer or not, by checking LSB.
-はRubyの知っている構造体(ruby.hで定義されているstruct RXxxx
+Notice Ruby does not allow arbitrary pointer value to be VALUE. They
+should be pointers to the structures which Ruby knows. The known
+structures are defined in <ruby.h>.
To convert C numbers to Ruby value, use these macros.
@@ -356,9 +352,8 @@ Ruby nil in C scope.
3.2 Global variables shared between C and Ruby
+Information can be shared between two worlds, using shared global
+variables. To define them, you can use functions listed below:
void rb_define_variable(char *name, VALUE *var)
@@ -371,28 +366,21 @@ function below.
void rb_define_readonly_variable(char *name, VALUE *var)
+You can defined hooked variables. The accessor functions (getter and
+setter) are called on access to the hooked variables.
void rb_define_hooked_variable(char *name, VALUE *var,
VALUE (*getter)(), VALUE (*setter)())
-# getterもsetterも0ならばrb_define_variable()と同じになる.
+If you need to supply either setter or getter, just supply 0 for the
+hook you don't need. If both hooks are 0, rb_define_hooked_variable()
+works just like rb_define_variable().
void rb_define_virtual_variable(char *name,
VALUE (*getter)(), VALUE (*setter)())
+This function defines the Ruby global variable without corresponding C
+variable. The value of the variable will be set/get only by hooks.
The prototypes of the getter and setter functions are as following:
@@ -401,34 +389,25 @@ The prototypes of the getter and setter functions are as following:
3.3 Encapsulate C data into Ruby object
-To wrapping and objectify the C pointer, use Data_Wrap_Struct().
+To wrapping and objectify the C pointer as Ruby object (so called
+DATA), use Data_Wrap_Struct().
-Data_Wrap_Struct() returns a created Data object.
+Data_Wrap_Struct() returns a created DATA object. The class argument
+is the class for the DATA object. The mark argument is the function
+to mark Ruby objects pointed by this data. The free argument is the
+function to free the pointer allocation. The functions, mark and
+free, will be called from garbage collector.
-# そのような参照は勧められません.
+You can allocate and wrap the structure in one step.
Data_Make_Struct(class, type, mark, free, sval)
This macro returns an allocated Data object, wrapping the pointer to
-the structure, which is also allocated.
+the structure, which is also allocated. This macro works like:
+ (sval = ALLOC(type), Data_Wrap_Struct(class, mark, free, sval))
Arguments, class, mark, free, works like thier counterpart of
Data_Wrap_Struct(). The pointer to allocated structure will be
@@ -445,9 +424,9 @@ See example below for detail.
4.Example - Create dbm module
+OK, here's the example to make extension library. This is the
+extension to access dbm. The full source is included in ext/
+directory in the Ruby's source tree.
(1) make the directory