Ruby/Ruby V1.9 C Extension - Revision history

Zelenka: /* write C code */

2008-05-10T10:05:19Z

write C code

← Older revision		Revision as of 10:05, 10 May 2008
Line 400:		Line 400:

	==write C code==		==write C code==
-	You need to write C code for your extension library. If your library	+	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 preferred. On the other hand, in case your library has multiple source files, avoid choosing ``LIBRARY.c'' for a file name. It may conflict with an intermediate file ``LIBRARY.o'' on some platforms.
-	has only one source file, choosing ``LIBRARY.c'' as a file name is	+
-	preferred. On the other hand, in case your library has multiple source	+
-	files, avoid choosing ``LIBRARY.c'' for a file name. It may conflict	+
-	with an intermediate file ``LIBRARY.o'' on some platforms.	+

-	Ruby will execute the initializing function named ``Init_LIBRARY'' in	+	Ruby will execute the initializing function named ``Init_LIBRARY'' in the library. For example, ``Init_dbm()'' will be executed when loading the library.
-	the library. For example, ``Init_dbm()'' will be executed when loading	+
-	the library.	+

	Here's the example of an initializing function.		Here's the example of an initializing function.
-	~~----~~
	Init_dbm()		Init_dbm()
	{		{
Line 431:		Line 424:
	id_dbm = rb_intern("dbm");		id_dbm = rb_intern("dbm");
	}		}
-	~~----~~
-	~~The dbm extension wraps the dbm struct in the C environment using Data_Make_Struct.~~

-	~~----~~	+
		+	The dbm extension wraps the dbm struct in the C environment using Data_Make_Struct.
	struct dbmdata {		struct dbmdata {
	int di_size;		int di_size;
Line 442:		Line 434:

	obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);		obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);
-	~~----~~	+	This code wraps the dbmdata structure into a Ruby object. We avoid wrapping DBM* directly, because we want to cache size information.

-	~~This code wraps the dbmdata structure into a Ruby object. We avoid wrapping~~
-	~~DBM* directly, because we want to cache size information.~~

	To retrieve the dbmdata structure from a Ruby object, we define the		To retrieve the dbmdata structure from a Ruby object, we define the
	following macro:		following macro:
-
-	~~----~~
	#define GetDBM(obj, dbmp) {\		#define GetDBM(obj, dbmp) {\
	Data_Get_Struct(obj, struct dbmdata, dbmp);\		Data_Get_Struct(obj, struct dbmdata, dbmp);\
	if (dbmp->di_dbm == 0) closed_dbm();\		if (dbmp->di_dbm == 0) closed_dbm();\
	}		}
-	~~----~~	+	This sort of complicated macro does the retrieving and close checking for the DBM.
-		+
-	This sort of complicated macro does the retrieving and close checking for	+
-	the DBM.	+

-	~~There are three kinds of way to receive method arguments. First,~~
-	~~methods with a fixed number of arguments receive arguments like this:~~

-	~~----~~	+	There are three kinds of way to receive method arguments. First, methods with a fixed number of arguments receive arguments like this:
	static VALUE		static VALUE
	fdbm_delete(obj, keystr)		fdbm_delete(obj, keystr)
Line 470:		Line 453:
	:		:
	}		}
-	~~----~~	+	The first argument of the C function is the self, the rest are the arguments to the method.

-	~~The first argument of the C function is the self, the rest are the~~
-	~~arguments to the method.~~

-	Second, methods with an arbitrary number of arguments receive	+	Second, methods with an arbitrary number of arguments receive arguments like this:
-	arguments like this:	+
-		+
-	~~----~~	+
	static VALUE		static VALUE
	fdbm_s_open(argc, argv, klass)		fdbm_s_open(argc, argv, klass)
Line 491:		Line 469:
	:		:
	}		}
-		+	The first argument is the number of method arguments, the second argument is the C array of the method arguments, and the third argument is the receiver of the method. You can use the function rb_scan_args() to check and retrieve the arguments. For example, "11" means that the method requires at least one argument, and at most receives two arguments.
-	The first argument is the number of method arguments, the second	+
-	argument is the C array of the method arguments, and the third	+
-	argument is the receiver of the method.	+
-		+
-	You can use the function rb_scan_args() to check and retrieve the	+
-	arguments. For example, "11" means that the method requires at least one	+
-	argument, and at most receives two arguments.	+

	Note: "11" means exactly 1 mandatory and 1 optional argument		Note: "11" means exactly 1 mandatory and 1 optional argument

-	~~Methods with an arbitrary number of arguments can receive arguments~~
-	~~by Ruby's array, like this:~~

-	~~----~~	+	Methods with an arbitrary number of arguments can receive arguments by Ruby's array, like this:
	static VALUE		static VALUE
	fdbm_indexes(obj, args)		fdbm_indexes(obj, args)
Line 512:		Line 481:
	:		:
	}		}
-	~~----~~	+	The first argument is the receiver, the second one is the Ruby array which contains the arguments to the method.

-	~~The first argument is the receiver, the second one is the Ruby array~~
-	~~which contains the arguments to the method.~~

	;Notice		;Notice
	:GC should know about global variables which refer to Ruby's objects, but are not exported to the Ruby world. You need to protect them by		:GC should know about global variables which refer to Ruby's objects, but are not exported to the Ruby world. You need to protect them by
-
	void rb_global_variable(VALUE *var)		void rb_global_variable(VALUE *var)

Zelenka: /* Defining Global Variables */

2008-05-10T09:58:27Z

Defining Global Variables

← Older revision		Revision as of 09:58, 10 May 2008
Line 736:		Line 736:
	\|\|<code style="color:gray; white-space:nowrap;">void rb_define_readonly_variable(const char name, VALUE var)</code> \|\|Defines a read-only global variable. Works just like rb_define_variable(), except defined variable is read-only.		\|\|<code style="color:gray; white-space:nowrap;">void rb_define_readonly_variable(const char name, VALUE var)</code> \|\|Defines a read-only global variable. Works just like rb_define_variable(), except defined variable is read-only.
	\|------------		\|------------
-	\|\|<code style="color:gray; white-space:nowrap;">void rb_define_virtual_variable(const char name, VALUE (getter)(), VALUE (*setter)())</code> \|\|Defines a virtual variable, whose behavior is defined by a pair of C functions. The getter function is called when the variable is referred. The setter function is called when the value is set to the variable. The prototype for getter/setter functions are:	+	\|\|<code style="color:gray; white-space:nowrap;">void rb_define_virtual_variable(const char name, <br>           VALUE (getter)(), VALUE (*setter)())</code>
		+	\|\|Defines a virtual variable, whose behavior is defined by a pair of C functions. The getter function is called when the variable is referred. The setter function is called when the value is set to the variable. The prototype for getter/setter functions are:
	{\| class="eqqon_table2"		{\| class="eqqon_table2"
	\|------------		\|------------
Line 745:		Line 746:
	The getter function must return the value for the access.		The getter function must return the value for the access.
	\|------------		\|------------
-	\|\|<code style="color:gray; white-space:nowrap;">void rb_define_hooked_variable(const char name,VALUE var, VALUE (getter)(), VALUE (setter)())</code> \|\|Defines hooked variable. It's a virtual variable with a C variable. The getter is called as VALUE getter(ID id, VALUE var) returning a new value. The setter is called as void setter(VALUE val, ID id, VALUE var). GC requires C global variables which hold Ruby values to be marked.	+	\|\|<code style="color:gray; white-space:nowrap;">void rb_define_hooked_variable(const char name,VALUE var, <br>           VALUE (getter)(), VALUE (setter)())</code>
		+	\|\|Defines hooked variable. It's a virtual variable with a C variable. The getter is called as ''VALUE getter(ID id, VALUE var)'' returning a new value. The setter is called as ''void setter(VALUE val, ID id, VALUE var)''. GC requires C global variables which hold Ruby values to be marked.
	\|------------		\|------------
	\|\|<code style="color:gray; white-space:nowrap;">void rb_global_variable(VALUE *var)</code> \|\|Tells GC to protect these variables.		\|\|<code style="color:gray; white-space:nowrap;">void rb_global_variable(VALUE *var)</code> \|\|Tells GC to protect these variables.

Zelenka: /* write C code */

2008-05-10T09:47:18Z

write C code

← Older revision		Revision as of 09:47, 10 May 2008
Line 426:		Line 426:
	/* DBM instance method []: 1 argument */		/* DBM instance method []: 1 argument */
	rb_define_method(cDBM, "[]", fdbm_fetch, 1);		rb_define_method(cDBM, "[]", fdbm_fetch, 1);
-	:	+	:
-		+	:
	/* ID for a instance variable to store DBM data */		/* ID for a instance variable to store DBM data */
	id_dbm = rb_intern("dbm");		id_dbm = rb_intern("dbm");

Zelenka at 10:12, 6 May 2008

2008-05-06T10:12:03Z

← Older revision		Revision as of 10:12, 6 May 2008
Line 881:		Line 881:
	\|\|<code style="color:gray; white-space:nowrap;">pkg_config(pkg)</code> \|\|Obtains the information of pkg by pkg-config command. The actual command name can be overriden by --with-pkg-config command line option.		\|\|<code style="color:gray; white-space:nowrap;">pkg_config(pkg)</code> \|\|Obtains the information of pkg by pkg-config command. The actual command name can be overriden by --with-pkg-config command line option.
	\|}		\|}
		+
		+	=see also=
		+	*[[Ruby C Extension API Documentation (Ruby 1.8)\| Ruby V1.8 C extension]]

Zelenka: /* Types */

2008-05-05T23:10:57Z

Types

← Older revision		Revision as of 23:10, 5 May 2008
Line 648:		Line 648:

	==Types==		==Types==
-		+	{\| class="eqqon_table2" width=100%
-	VALUE	+	\|------------
-		+	\|\|<code style="color:gray; white-space:nowrap;">VALUE</code> \|\|The type for the Ruby object. Actual structures are defined in ruby.h, such as struct RString, etc. To refer the values in structures, use casting macros like RSTRING(obj).
-	The type for the Ruby object. Actual structures are defined in ruby.h,	+	\|}
-	such as struct RString, etc. To refer the values in structures, use	+
-	casting macros like RSTRING(obj).	+

	==Variables and constants==		==Variables and constants==

Zelenka: /* Variables and constants */

2008-05-05T23:09:23Z

Variables and constants

← Older revision		Revision as of 23:09, 5 May 2008
Line 656:		Line 656:

	==Variables and constants==		==Variables and constants==
-		+	{\| class="eqqon_table2" width=100%
-	Qnil const: nil object	+	\|------------
-	Qtrue const: true object(default true value)	+	\|\|<code style="color:gray; white-space:nowrap;">Qnil</code> \|\|const: nil object
-	Qfalse const: false object	+	\|------------
		+	\|\|<code style="color:gray; white-space:nowrap;">Qtrue</code> \|\|const: true object(default true value)
		+	\|------------
		+	\|\|<code style="color:gray; white-space:nowrap;">Qfalse</code> \|\|const: false object
		+	\|}

	==C pointer wrapping==		==C pointer wrapping==

Zelenka: /* C pointer wrapping */

2008-05-05T23:07:58Z

C pointer wrapping

← Older revision		Revision as of 23:07, 5 May 2008
Line 662:		Line 662:

	==C pointer wrapping==		==C pointer wrapping==
-	{\| class="eqqon_table2"	+	{\| class="eqqon_table2" width=100%
	\|------------		\|------------
	\|\|<code style="color:gray; white-space:nowrap;">Data_Wrap_Struct(VALUE klass, void (mark)(), void (free)(), void *sval)</code> \|\|Wrap a C pointer into a Ruby object. If object has references to other Ruby objects, they should be marked by using the mark function during the GC process. Otherwise, mark should be 0. When this object is no longer referred by anywhere, the pointer will be discarded by free function.		\|\|<code style="color:gray; white-space:nowrap;">Data_Wrap_Struct(VALUE klass, void (mark)(), void (free)(), void *sval)</code> \|\|Wrap a C pointer into a Ruby object. If object has references to other Ruby objects, they should be marked by using the mark function during the GC process. Otherwise, mark should be 0. When this object is no longer referred by anywhere, the pointer will be discarded by free function.

Zelenka: /* Checking data types */

2008-05-05T23:07:36Z

Checking data types

← Older revision		Revision as of 23:07, 5 May 2008
Line 674:		Line 674:

	==Checking data types==		==Checking data types==
-	{\| class="eqqon_table2"	+	{\| class="eqqon_table2" width=100%
	\|------------		\|------------
	\|\|<code style="color:gray; white-space:nowrap;">TYPE(value)</code> \|\|		\|\|<code style="color:gray; white-space:nowrap;">TYPE(value)</code> \|\|

Zelenka: /* Data type conversion */

2008-05-05T23:07:20Z

Data type conversion

← Older revision		Revision as of 23:07, 5 May 2008
Line 688:		Line 688:

	==Data type conversion==		==Data type conversion==
-	{\| class="eqqon_table2"	+	{\| class="eqqon_table2" width=100%
	\|------------		\|------------
	\|\|<code style="color:gray; white-space:nowrap;">FIX2INT(value)</code> \|\|		\|\|<code style="color:gray; white-space:nowrap;">FIX2INT(value)</code> \|\|

Zelenka: /* defining class/module */

2008-05-05T23:07:00Z

defining class/module

← Older revision		Revision as of 23:07, 5 May 2008
Line 712:		Line 712:

	==defining class/module==		==defining class/module==
-	{\| class="eqqon_table2"	+	{\| class="eqqon_table2" width=100%
	\|------------		\|------------
	\|\|<code style="color:gray; white-space:nowrap;">VALUE rb_define_class(const char *name, VALUE super)</code> \|\|Defines a new Ruby class as a subclass of super.		\|\|<code style="color:gray; white-space:nowrap;">VALUE rb_define_class(const char *name, VALUE super)</code> \|\|Defines a new Ruby class as a subclass of super.