posixlock 0.0.1
Sign up to get free protection for your applications and to get access to all the features.
- data/Makefile +126 -0
- data/README +78 -0
- data/README.EXT +1069 -0
- data/VERSION +1 -0
- data/extconf.rb +1 -0
- data/posixlock.c +289 -0
- data/posixlock.gemspec +19 -0
- metadata +46 -0
data/Makefile
ADDED
@@ -0,0 +1,126 @@
|
|
1
|
+
|
2
|
+
SHELL = /bin/sh
|
3
|
+
|
4
|
+
#### Start of system configuration section. ####
|
5
|
+
|
6
|
+
srcdir = .
|
7
|
+
topdir = $(rubylibdir)/$(arch)
|
8
|
+
hdrdir = $(rubylibdir)/$(arch)
|
9
|
+
VPATH = $(srcdir)
|
10
|
+
prefix = $(DESTDIR)/dmsp/reference/ruby-1.8.1
|
11
|
+
exec_prefix = $(prefix)
|
12
|
+
sitedir = $(prefix)/lib/ruby/site_ruby
|
13
|
+
rubylibdir = $(libdir)/ruby/$(ruby_version)
|
14
|
+
builddir = $(ac_builddir)
|
15
|
+
archdir = $(rubylibdir)/$(arch)
|
16
|
+
sbindir = $(exec_prefix)/sbin
|
17
|
+
compile_dir = $(DESTDIR)/dmsp/moby-1-1/reference/build/ruby-1.8.1
|
18
|
+
datadir = $(prefix)/share
|
19
|
+
includedir = $(prefix)/include
|
20
|
+
infodir = $(prefix)/info
|
21
|
+
top_builddir = $(ac_top_builddir)
|
22
|
+
sysconfdir = $(prefix)/etc
|
23
|
+
mandir = $(prefix)/man
|
24
|
+
libdir = $(exec_prefix)/lib
|
25
|
+
sharedstatedir = $(prefix)/com
|
26
|
+
oldincludedir = $(DESTDIR)/usr/include
|
27
|
+
sitearchdir = $(sitelibdir)/$(sitearch)
|
28
|
+
bindir = $(exec_prefix)/bin
|
29
|
+
localstatedir = $(prefix)/var
|
30
|
+
sitelibdir = $(sitedir)/$(ruby_version)
|
31
|
+
libexecdir = $(exec_prefix)/libexec
|
32
|
+
|
33
|
+
CC = gcc
|
34
|
+
LIBRUBY = $(LIBRUBY_A)
|
35
|
+
LIBRUBY_A = lib$(RUBY_SO_NAME)-static.a
|
36
|
+
LIBRUBYARG_SHARED =
|
37
|
+
LIBRUBYARG_STATIC = -l$(RUBY_SO_NAME)-static
|
38
|
+
|
39
|
+
CFLAGS = -fPIC -g -O2
|
40
|
+
CPPFLAGS = -I. -I$(topdir) -I$(hdrdir) -I$(srcdir)
|
41
|
+
CXXFLAGS = $(CFLAGS)
|
42
|
+
DLDFLAGS =
|
43
|
+
LDSHARED = gcc -shared
|
44
|
+
AR = ar
|
45
|
+
EXEEXT =
|
46
|
+
|
47
|
+
RUBY_INSTALL_NAME = ruby
|
48
|
+
RUBY_SO_NAME = $(RUBY_INSTALL_NAME)
|
49
|
+
arch = i686-linux
|
50
|
+
sitearch = i686-linux
|
51
|
+
ruby_version = 1.8
|
52
|
+
RUBY = ruby
|
53
|
+
RM = $(RUBY) -run -e rm -- -f
|
54
|
+
MAKEDIRS = $(RUBY) -run -e mkdir -- -p
|
55
|
+
INSTALL_PROG = $(RUBY) -run -e install -- -vpm 0755
|
56
|
+
INSTALL_DATA = $(RUBY) -run -e install -- -vpm 0644
|
57
|
+
|
58
|
+
#### End of system configuration section. ####
|
59
|
+
|
60
|
+
|
61
|
+
LIBPATH = -L"$(libdir)"
|
62
|
+
DEFFILE =
|
63
|
+
|
64
|
+
CLEANFILES =
|
65
|
+
DISTCLEANFILES =
|
66
|
+
|
67
|
+
target_prefix =
|
68
|
+
LOCAL_LIBS =
|
69
|
+
LIBS = -ldl -lcrypt -lm -lc
|
70
|
+
OBJS = posixlock.o
|
71
|
+
TARGET = posixlock
|
72
|
+
DLLIB = $(TARGET).so
|
73
|
+
STATIC_LIB = $(TARGET).a
|
74
|
+
|
75
|
+
RUBYCOMMONDIR = $(sitedir)$(target_prefix)
|
76
|
+
RUBYLIBDIR = $(sitelibdir)$(target_prefix)
|
77
|
+
RUBYARCHDIR = $(sitearchdir)$(target_prefix)
|
78
|
+
|
79
|
+
CLEANLIBS = "$(TARGET).{lib,exp,il?,tds,map}" $(DLLIB)
|
80
|
+
CLEANOBJS = "*.{o,a,s[ol],pdb,bak}"
|
81
|
+
|
82
|
+
all: $(DLLIB)
|
83
|
+
static: $(STATIC_LIB)
|
84
|
+
|
85
|
+
clean:
|
86
|
+
@$(RM) $(CLEANLIBS) $(CLEANOBJS) $(CLEANFILES)
|
87
|
+
|
88
|
+
distclean: clean
|
89
|
+
@$(RM) Makefile extconf.h conftest.* mkmf.log
|
90
|
+
@$(RM) core ruby$(EXEEXT) *~ $(DISTCLEANFILES)
|
91
|
+
|
92
|
+
realclean: distclean
|
93
|
+
install: $(RUBYARCHDIR)
|
94
|
+
install: $(RUBYARCHDIR)/$(DLLIB)
|
95
|
+
$(RUBYARCHDIR)/$(DLLIB): $(DLLIB) $(RUBYARCHDIR)
|
96
|
+
@$(INSTALL_PROG) $(DLLIB) $(RUBYARCHDIR)
|
97
|
+
$(RUBYARCHDIR):
|
98
|
+
@$(MAKEDIRS) $(RUBYARCHDIR)
|
99
|
+
|
100
|
+
site-install: install
|
101
|
+
|
102
|
+
.SUFFIXES: .c .cc .m .cxx .cpp .C .o
|
103
|
+
|
104
|
+
.cc.o:
|
105
|
+
$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
|
106
|
+
|
107
|
+
.cpp.o:
|
108
|
+
$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
|
109
|
+
|
110
|
+
.cxx.o:
|
111
|
+
$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
|
112
|
+
|
113
|
+
.C.o:
|
114
|
+
$(CXX) $(CXXFLAGS) $(CPPFLAGS) -c $<
|
115
|
+
|
116
|
+
.c.o:
|
117
|
+
$(CC) $(CFLAGS) $(CPPFLAGS) -c $<
|
118
|
+
|
119
|
+
$(DLLIB): $(OBJS)
|
120
|
+
@-$(RM) $@
|
121
|
+
$(LDSHARED) $(DLDFLAGS) $(LIBPATH) -o $(DLLIB) $(OBJS) $(LOCAL_LIBS) $(LIBS)
|
122
|
+
|
123
|
+
$(STATIC_LIB): $(OBJS)
|
124
|
+
$(AR) cru $@ $(OBJS)
|
125
|
+
@-ranlib $(DLLIB) 2> /dev/null || true
|
126
|
+
|
data/README
ADDED
@@ -0,0 +1,78 @@
|
|
1
|
+
= SYNOPSIS
|
2
|
+
|
3
|
+
methods to add posix (fcntl based and nfs safe) locking to the builtin File
|
4
|
+
class
|
5
|
+
|
6
|
+
= URLS:
|
7
|
+
|
8
|
+
http://raa.ruby-lang.org/project/posixlock/
|
9
|
+
http://www.codeforpeople.com/lib/ruby/posixlock/
|
10
|
+
|
11
|
+
= EXAMPLES:
|
12
|
+
|
13
|
+
1.
|
14
|
+
File.open('even_an_nfs_mounted_file','r+').posixlock File::LOCK_EX
|
15
|
+
|
16
|
+
2.
|
17
|
+
File.open('even_an_nfs_mounted_file','r+').lockf File::F_LOCK, 0
|
18
|
+
|
19
|
+
3.
|
20
|
+
open('even_an_nfs_mounted_file','r') do |f|
|
21
|
+
f.lockf File::F_LOCKR, 42
|
22
|
+
end
|
23
|
+
|
24
|
+
4.
|
25
|
+
f = open 'foo', 'r+'
|
26
|
+
|
27
|
+
if((pid = f.lockf File::F_TEST, 0))
|
28
|
+
STDERR.puts "process <#{ pid }> prevents write lock"
|
29
|
+
end
|
30
|
+
|
31
|
+
5.
|
32
|
+
f = open 'foo', 'r'
|
33
|
+
|
34
|
+
if((pid = f.lockf File::F_TESTR, 0))
|
35
|
+
STDERR.puts "process <#{ pid }> prevents read lock"
|
36
|
+
end
|
37
|
+
|
38
|
+
= DOCS
|
39
|
+
|
40
|
+
posixlock.c
|
41
|
+
|
42
|
+
File#posixlock has an identical interface to the builtin File#flock
|
43
|
+
|
44
|
+
for File#lockf see man (3) lockf
|
45
|
+
|
46
|
+
the additional flags
|
47
|
+
|
48
|
+
File::F_LOCKR
|
49
|
+
File::F_LOCKW
|
50
|
+
File::F_TLOCKR
|
51
|
+
File::F_TLOCKW
|
52
|
+
File::F_TESTR
|
53
|
+
File::F_TESTW
|
54
|
+
|
55
|
+
have the obvious meaning
|
56
|
+
|
57
|
+
|
58
|
+
= AUTHOR
|
59
|
+
|
60
|
+
ara.t.howard@noaa.gov
|
61
|
+
|
62
|
+
= BUGS
|
63
|
+
|
64
|
+
> 1
|
65
|
+
|
66
|
+
|
67
|
+
= HISTORY
|
68
|
+
|
69
|
+
1.0.0:
|
70
|
+
changed behaviour so that, instead of replacing flock, two new methods are
|
71
|
+
added: File#posixlock gives access to read/write locks with an interface
|
72
|
+
identical to File#flock, and File#lockf gives access to a lockf impl
|
73
|
+
similar to the one posix specifies with added functionality for read
|
74
|
+
locks. the biggest difference between the two methods is that lockf will
|
75
|
+
throw errors for errno's like EAGAIN, EACCESS, etc.
|
76
|
+
|
77
|
+
0.0.0:
|
78
|
+
initial version
|
data/README.EXT
ADDED
@@ -0,0 +1,1069 @@
|
|
1
|
+
.\" README.EXT - -*- Text -*- created at: Mon Aug 7 16:45:54 JST 1995
|
2
|
+
|
3
|
+
This document explains how to make extension libraries for Ruby.
|
4
|
+
|
5
|
+
1. Basic knowledge
|
6
|
+
|
7
|
+
In C, variables have types and data do not have types. In contrast,
|
8
|
+
Ruby variables do not have a static type, and data themselves have
|
9
|
+
types, so data will need to be converted between the languages.
|
10
|
+
|
11
|
+
Data in Ruby are represented by C type `VALUE'. Each VALUE data has
|
12
|
+
its data-type.
|
13
|
+
|
14
|
+
To retrieve C data from a VALUE, you need to:
|
15
|
+
|
16
|
+
(1) Identify the VALUE's data type
|
17
|
+
(2) Convert the VALUE into C data
|
18
|
+
|
19
|
+
Converting to the wrong data type may cause serious problems.
|
20
|
+
|
21
|
+
|
22
|
+
1.1 Data-types
|
23
|
+
|
24
|
+
The Ruby interpreter has the following data types:
|
25
|
+
|
26
|
+
T_NIL nil
|
27
|
+
T_OBJECT ordinary object
|
28
|
+
T_CLASS class
|
29
|
+
T_MODULE module
|
30
|
+
T_FLOAT floating point number
|
31
|
+
T_STRING string
|
32
|
+
T_REGEXP regular expression
|
33
|
+
T_ARRAY array
|
34
|
+
T_FIXNUM Fixnum(31bit integer)
|
35
|
+
T_HASH associative array
|
36
|
+
T_STRUCT (Ruby) structure
|
37
|
+
T_BIGNUM multi precision integer
|
38
|
+
T_FILE IO
|
39
|
+
T_TRUE true
|
40
|
+
T_FALSE false
|
41
|
+
T_DATA data
|
42
|
+
T_SYMBOL symbol
|
43
|
+
|
44
|
+
In addition, there are several other types used internally:
|
45
|
+
|
46
|
+
T_ICLASS
|
47
|
+
T_MATCH
|
48
|
+
T_UNDEF
|
49
|
+
T_VARMAP
|
50
|
+
T_SCOPE
|
51
|
+
T_NODE
|
52
|
+
|
53
|
+
Most of the types are represented by C structures.
|
54
|
+
|
55
|
+
1.2 Check Data Type of the VALUE
|
56
|
+
|
57
|
+
The macro TYPE() defined in ruby.h shows the data type of the VALUE.
|
58
|
+
TYPE() returns the constant number T_XXXX described above. To handle
|
59
|
+
data types, your code will look something like this:
|
60
|
+
|
61
|
+
switch (TYPE(obj)) {
|
62
|
+
case T_FIXNUM:
|
63
|
+
/* process Fixnum */
|
64
|
+
break;
|
65
|
+
case T_STRING:
|
66
|
+
/* process String */
|
67
|
+
break;
|
68
|
+
case T_ARRAY:
|
69
|
+
/* process Array */
|
70
|
+
break;
|
71
|
+
default:
|
72
|
+
/* raise exception */
|
73
|
+
rb_raise(rb_eTypeError, "not valid value");
|
74
|
+
break;
|
75
|
+
}
|
76
|
+
|
77
|
+
There is the data-type check function
|
78
|
+
|
79
|
+
void Check_Type(VALUE value, int type)
|
80
|
+
|
81
|
+
which raises an exception if the VALUE does not have the type specified.
|
82
|
+
|
83
|
+
There are also faster check macros for fixnums and nil.
|
84
|
+
|
85
|
+
FIXNUM_P(obj)
|
86
|
+
NIL_P(obj)
|
87
|
+
|
88
|
+
1.3 Convert VALUE into C data
|
89
|
+
|
90
|
+
The data for type T_NIL, T_FALSE, T_TRUE are nil, true, false
|
91
|
+
respectively. They are singletons for the data type.
|
92
|
+
|
93
|
+
The T_FIXNUM data is a 31bit length fixed integer (63bit length on
|
94
|
+
some machines), which can be convert to a C integer by using the
|
95
|
+
FIX2INT() macro. There is also NUM2INT() which converts any Ruby
|
96
|
+
numbers into C integers. The NUM2INT() macro includes a type check, so
|
97
|
+
an exception will be raised if the conversion failed. NUM2DBL() can
|
98
|
+
be used to retrieve the double float value in same way.
|
99
|
+
|
100
|
+
To get char* from a VALUE, version 1.7 recommend to use new macros
|
101
|
+
StringValue() and StringValuePtr(). StringValue(var) replaces var's
|
102
|
+
value to the result of "var.to_str()". StringValuePtr(var) does same
|
103
|
+
replacement and returns char* representation of var. These macros
|
104
|
+
will skip the replacement if var is a String. Notice that the macros
|
105
|
+
requires to take only lvalue as their argument, to change the value
|
106
|
+
of var in the replacement.
|
107
|
+
|
108
|
+
In version 1.6 or earlier, STR2CSTR() was used to do same thing
|
109
|
+
but now it is obsoleted in version 1.7 because of STR2CSTR() has
|
110
|
+
a risk of dangling pointer problem in to_str() impliclit conversion.
|
111
|
+
|
112
|
+
Other data types have corresponding C structures, e.g. struct RArray
|
113
|
+
for T_ARRAY etc. The VALUE of the type which has corresponding structure
|
114
|
+
can be cast to retrieve the pointer to the struct. The casting macro
|
115
|
+
will be of the form RXXXX for each data type; for instance, RARRAY(obj).
|
116
|
+
See "ruby.h".
|
117
|
+
|
118
|
+
For example, `RSTRING(size)->len' is the way to get the size of the
|
119
|
+
Ruby String object. The allocated region can be accessed by
|
120
|
+
`RSTRING(str)->ptr'. For arrays, use `RARRAY(ary)->len' and
|
121
|
+
`RARRAY(ary)->ptr' respectively.
|
122
|
+
|
123
|
+
Notice: Do not change the value of the structure directly, unless you
|
124
|
+
are responsible for the result. This ends up being the cause of interesting
|
125
|
+
bugs.
|
126
|
+
|
127
|
+
1.4 Convert C data into VALUE
|
128
|
+
|
129
|
+
To convert C data to Ruby values:
|
130
|
+
|
131
|
+
* FIXNUM
|
132
|
+
|
133
|
+
left shift 1 bit, and turn on LSB.
|
134
|
+
|
135
|
+
* Other pointer values
|
136
|
+
|
137
|
+
cast to VALUE.
|
138
|
+
|
139
|
+
You can determine whether a VALUE is pointer or not by checking its LSB.
|
140
|
+
|
141
|
+
Notice Ruby does not allow arbitrary pointer values to be a VALUE. They
|
142
|
+
should be pointers to the structures which Ruby knows about. The known
|
143
|
+
structures are defined in <ruby.h>.
|
144
|
+
|
145
|
+
To convert C numbers to Ruby values, use these macros.
|
146
|
+
|
147
|
+
INT2FIX() for integers within 31bits.
|
148
|
+
INT2NUM() for arbitrary sized integer.
|
149
|
+
|
150
|
+
INT2NUM() converts an integer into a Bignum if it is out of the FIXNUM
|
151
|
+
range, but is a bit slower.
|
152
|
+
|
153
|
+
1.5 Manipulating Ruby data
|
154
|
+
|
155
|
+
As I already mentioned, it is not recommended to modify an object's internal
|
156
|
+
structure. To manipulate objects, use the functions supplied by the Ruby
|
157
|
+
interpreter. Some (not all) of the useful functions are listed below:
|
158
|
+
|
159
|
+
String functions
|
160
|
+
|
161
|
+
rb_str_new(const char *ptr, long len)
|
162
|
+
|
163
|
+
Creates a new Ruby string.
|
164
|
+
|
165
|
+
rb_str_new2(const char *ptr)
|
166
|
+
|
167
|
+
Creates a new Ruby string from a C string. This is equivalent to
|
168
|
+
rb_str_new(ptr, strlen(ptr)).
|
169
|
+
|
170
|
+
rb_tainted_str_new(const char *ptr, long len)
|
171
|
+
|
172
|
+
Creates a new tainted Ruby string. Strings from external data
|
173
|
+
sources should be tainted.
|
174
|
+
|
175
|
+
rb_tainted_str_new2(const char *ptr)
|
176
|
+
|
177
|
+
Creates a new tainted Ruby string from a C string.
|
178
|
+
|
179
|
+
rb_str_cat(VALUE str, const char *ptr, long len)
|
180
|
+
|
181
|
+
Appends len bytes of data from ptr to the Ruby string.
|
182
|
+
|
183
|
+
Array functions
|
184
|
+
|
185
|
+
rb_ary_new()
|
186
|
+
|
187
|
+
Creates an array with no elements.
|
188
|
+
|
189
|
+
rb_ary_new2(long len)
|
190
|
+
|
191
|
+
Creates an array with no elements, allocating internal buffer
|
192
|
+
for len elements.
|
193
|
+
|
194
|
+
rb_ary_new3(long n, ...)
|
195
|
+
|
196
|
+
Creates an n-element array from the arguments.
|
197
|
+
|
198
|
+
rb_ary_new4(long n, VALUE *elts)
|
199
|
+
|
200
|
+
Creates an n-element array from a C array.
|
201
|
+
|
202
|
+
rb_ary_push(VALUE ary, VALUE val)
|
203
|
+
rb_ary_pop(VALUE ary)
|
204
|
+
rb_ary_shift(VALUE ary)
|
205
|
+
rb_ary_unshift(VALUE ary, VALUE val)
|
206
|
+
|
207
|
+
Array operations. The first argument to each functions must be an
|
208
|
+
array. They may dump core if other types given.
|
209
|
+
|
210
|
+
2. Extending Ruby with C
|
211
|
+
|
212
|
+
2.1 Addding new features to Ruby
|
213
|
+
|
214
|
+
You can add new features (classes, methods, etc.) to the Ruby
|
215
|
+
interpreter. Ruby provides APIs for defining the following things:
|
216
|
+
|
217
|
+
* Classes, Modules
|
218
|
+
* Methods, Singleton Methods
|
219
|
+
* Constants
|
220
|
+
|
221
|
+
2.1.1 Class/module definition
|
222
|
+
|
223
|
+
To define a class or module, use the functions below:
|
224
|
+
|
225
|
+
VALUE rb_define_class(const char *name, VALUE super)
|
226
|
+
VALUE rb_define_module(const char *name)
|
227
|
+
|
228
|
+
These functions return the newly created class or module. You may
|
229
|
+
want to save this reference into a variable to use later.
|
230
|
+
|
231
|
+
To define nested classes or modules, use the functions below:
|
232
|
+
|
233
|
+
VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super)
|
234
|
+
VALUE rb_define_module_under(VALUE outer, const char *name)
|
235
|
+
|
236
|
+
2.1.2 Method/singleton method definition
|
237
|
+
|
238
|
+
To define methods or singleton methods, use these functions:
|
239
|
+
|
240
|
+
void rb_define_method(VALUE klass, const char *name,
|
241
|
+
VALUE (*func)(), int argc)
|
242
|
+
|
243
|
+
void rb_define_singleton_method(VALUE object, const char *name,
|
244
|
+
VALUE (*func)(), int argc)
|
245
|
+
|
246
|
+
The `argc' represents the number of the arguments to the C function,
|
247
|
+
which must be less than 17. But I believe you don't need that much. :-)
|
248
|
+
|
249
|
+
If `argc' is negative, it specifies the calling sequence, not number of
|
250
|
+
the arguments.
|
251
|
+
|
252
|
+
If argc is -1, the function will be called as:
|
253
|
+
|
254
|
+
VALUE func(int argc, VALUE *argv, VALUE obj)
|
255
|
+
|
256
|
+
where argc is the actual number of arguments, argv is the C array of
|
257
|
+
the arguments, and obj is the receiver.
|
258
|
+
|
259
|
+
If argc is -2, the arguments are passed in a Ruby array. The function
|
260
|
+
will be called like:
|
261
|
+
|
262
|
+
VALUE func(VALUE obj, VALUE args)
|
263
|
+
|
264
|
+
where obj is the receiver, and args is the Ruby array containing
|
265
|
+
actual arguments.
|
266
|
+
|
267
|
+
There are two more functions to define methods. One is to define
|
268
|
+
private methods:
|
269
|
+
|
270
|
+
void rb_define_private_method(VALUE klass, const char *name,
|
271
|
+
VALUE (*func)(), int argc)
|
272
|
+
|
273
|
+
The other is to define module functions, which are private AND singleton
|
274
|
+
methods of the module. For example, sqrt is the module function
|
275
|
+
defined in Math module. It can be call in the form like:
|
276
|
+
|
277
|
+
Math.sqrt(4)
|
278
|
+
|
279
|
+
or
|
280
|
+
|
281
|
+
include Math
|
282
|
+
sqrt(4)
|
283
|
+
|
284
|
+
To define module functions, use:
|
285
|
+
|
286
|
+
void rb_define_module_function(VALUE module, const char *name,
|
287
|
+
VALUE (*func)(), int argc)
|
288
|
+
|
289
|
+
Oh, in addition, function-like methods, which are private methods defined
|
290
|
+
in the Kernel module, can be defined using:
|
291
|
+
|
292
|
+
void rb_define_global_function(const char *name, VALUE (*func)(), int argc)
|
293
|
+
|
294
|
+
To define alias to the method,
|
295
|
+
|
296
|
+
void rb_define_alias(VALUE module, const char* new, const char* old);
|
297
|
+
|
298
|
+
2.1.3 Constant definition
|
299
|
+
|
300
|
+
We have 2 functions to define constants:
|
301
|
+
|
302
|
+
void rb_define_const(VALUE klass, const char *name, VALUE val)
|
303
|
+
void rb_define_global_const(const char *name, VALUE val)
|
304
|
+
|
305
|
+
The former is to define a constant under specified class/module. The
|
306
|
+
latter is to define a global constant.
|
307
|
+
|
308
|
+
2.2 Use Ruby features from C
|
309
|
+
|
310
|
+
There are several ways to invoke Ruby's features from C code.
|
311
|
+
|
312
|
+
2.2.1 Evaluate Ruby Programs in a String
|
313
|
+
|
314
|
+
The easiest way to use Ruby's functionality from a C program is to
|
315
|
+
evaluate the string as Ruby program. This function will do the job.
|
316
|
+
|
317
|
+
VALUE rb_eval_string(const char *str)
|
318
|
+
|
319
|
+
Evaluation is done under the current context, thus current local variables
|
320
|
+
of the innermost method (which is defined by Ruby) can be accessed.
|
321
|
+
|
322
|
+
2.2.2 ID or Symbol
|
323
|
+
|
324
|
+
You can invoke methods directly, without parsing the string. First I
|
325
|
+
need to explain about symbols (whose data type is ID). ID is the
|
326
|
+
integer number to represent Ruby's identifiers such as variable names.
|
327
|
+
It can be accessed from Ruby in the form:
|
328
|
+
|
329
|
+
:Identifier
|
330
|
+
|
331
|
+
You can get the symbol value from a string within C code by using
|
332
|
+
|
333
|
+
rb_intern(const char *name)
|
334
|
+
|
335
|
+
2.2.3 Invoke Ruby method from C
|
336
|
+
|
337
|
+
To invoke methods directly, you can use the function below
|
338
|
+
|
339
|
+
VALUE rb_funcall(VALUE recv, ID mid, int argc, ...)
|
340
|
+
|
341
|
+
This function invokes a method on the recv, with the method name
|
342
|
+
specified by the symbol mid.
|
343
|
+
|
344
|
+
2.2.4 Accessing the variables and constants
|
345
|
+
|
346
|
+
You can access class variables and instance variables using access
|
347
|
+
functions. Also, global variables can be shared between both environments.
|
348
|
+
There's no way to access Ruby's local variables.
|
349
|
+
|
350
|
+
The functions to access/modify instance variables are below:
|
351
|
+
|
352
|
+
VALUE rb_ivar_get(VALUE obj, ID id)
|
353
|
+
VALUE rb_ivar_set(VALUE obj, ID id, VALUE val)
|
354
|
+
|
355
|
+
id must be the symbol, which can be retrieved by rb_intern().
|
356
|
+
|
357
|
+
To access the constants of the class/module:
|
358
|
+
|
359
|
+
VALUE rb_const_get(VALUE obj, ID id)
|
360
|
+
|
361
|
+
See 2.1.3 for defining new constant.
|
362
|
+
|
363
|
+
3. Information sharing between Ruby and C
|
364
|
+
|
365
|
+
3.1 Ruby constants that C can be accessed from C
|
366
|
+
|
367
|
+
The following Ruby constants can be referred from C.
|
368
|
+
|
369
|
+
Qtrue
|
370
|
+
Qfalse
|
371
|
+
|
372
|
+
Boolean values. Qfalse is false in C also (i.e. 0).
|
373
|
+
|
374
|
+
Qnil
|
375
|
+
|
376
|
+
Ruby nil in C scope.
|
377
|
+
|
378
|
+
3.2 Global variables shared between C and Ruby
|
379
|
+
|
380
|
+
Information can be shared between the two environments using shared global
|
381
|
+
variables. To define them, you can use functions listed below:
|
382
|
+
|
383
|
+
void rb_define_variable(const char *name, VALUE *var)
|
384
|
+
|
385
|
+
This function defines the variable which is shared by both environments.
|
386
|
+
The value of the global variable pointed to by `var' can be accessed
|
387
|
+
through Ruby's global variable named `name'.
|
388
|
+
|
389
|
+
You can define read-only (from Ruby, of course) variables using the
|
390
|
+
function below.
|
391
|
+
|
392
|
+
void rb_define_readonly_variable(const char *name, VALUE *var)
|
393
|
+
|
394
|
+
You can defined hooked variables. The accessor functions (getter and
|
395
|
+
setter) are called on access to the hooked variables.
|
396
|
+
|
397
|
+
void rb_define_hooked_variable(constchar *name, VALUE *var,
|
398
|
+
VALUE (*getter)(), void (*setter)())
|
399
|
+
|
400
|
+
If you need to supply either setter or getter, just supply 0 for the
|
401
|
+
hook you don't need. If both hooks are 0, rb_define_hooked_variable()
|
402
|
+
works just like rb_define_variable().
|
403
|
+
|
404
|
+
void rb_define_virtual_variable(const char *name,
|
405
|
+
VALUE (*getter)(), void (*setter)())
|
406
|
+
|
407
|
+
This function defines a Ruby global variable without a corresponding C
|
408
|
+
variable. The value of the variable will be set/get only by hooks.
|
409
|
+
|
410
|
+
The prototypes of the getter and setter functions are as follows:
|
411
|
+
|
412
|
+
(*getter)(ID id, void *data, struct global_entry* entry);
|
413
|
+
(*setter)(VALUE val, ID id, void *data, struct global_entry* entry);
|
414
|
+
|
415
|
+
3.3 Encapsulate C data into Ruby object
|
416
|
+
|
417
|
+
To wrap and objectify a C pointer as a Ruby object (so called
|
418
|
+
DATA), use Data_Wrap_Struct().
|
419
|
+
|
420
|
+
Data_Wrap_Struct(klass, mark, free, ptr)
|
421
|
+
|
422
|
+
Data_Wrap_Struct() returns a created DATA object. The klass argument
|
423
|
+
is the class for the DATA object. The mark argument is the function
|
424
|
+
to mark Ruby objects pointed by this data. The free argument is the
|
425
|
+
function to free the pointer allocation. If this is -1, the pointer
|
426
|
+
will be just freed. The functions mark and free will be called from
|
427
|
+
garbage collector.
|
428
|
+
|
429
|
+
You can allocate and wrap the structure in one step.
|
430
|
+
|
431
|
+
Data_Make_Struct(klass, type, mark, free, sval)
|
432
|
+
|
433
|
+
This macro returns an allocated Data object, wrapping the pointer to
|
434
|
+
the structure, which is also allocated. This macro works like:
|
435
|
+
|
436
|
+
(sval = ALLOC(type), Data_Wrap_Struct(klass, mark, free, sval))
|
437
|
+
|
438
|
+
Arguments klass, mark, and free work like their counterparts in
|
439
|
+
Data_Wrap_Struct(). A pointer to the allocated structure will be
|
440
|
+
assigned to sval, which should be a pointer of the type specified.
|
441
|
+
|
442
|
+
To retrieve the C pointer from the Data object, use the macro
|
443
|
+
Data_Get_Struct().
|
444
|
+
|
445
|
+
Data_Get_Struct(obj, type, sval)
|
446
|
+
|
447
|
+
A pointer to the structure will be assigned to the variable sval.
|
448
|
+
|
449
|
+
See the example below for details.
|
450
|
+
|
451
|
+
4. Example - Creating dbm extension
|
452
|
+
|
453
|
+
OK, here's the example of making an extension library. This is the
|
454
|
+
extension to access DBMs. The full source is included in the ext/
|
455
|
+
directory in the Ruby's source tree.
|
456
|
+
|
457
|
+
(1) make the directory
|
458
|
+
|
459
|
+
% mkdir ext/dbm
|
460
|
+
|
461
|
+
Make a directory for the extension library under ext directory.
|
462
|
+
|
463
|
+
(2) create MANIFEST file
|
464
|
+
|
465
|
+
% cd ext/dbm
|
466
|
+
% touch MANIFEST
|
467
|
+
|
468
|
+
There should be MANIFEST file in the directory for the extension
|
469
|
+
library. Make an empty file for now.
|
470
|
+
|
471
|
+
(3) design the library
|
472
|
+
|
473
|
+
You need to design the library features, before making it.
|
474
|
+
|
475
|
+
(4) write C code.
|
476
|
+
|
477
|
+
You need to write C code for your extension library. If your library
|
478
|
+
has only one source file, choosing ``LIBRARY.c'' as a file name is
|
479
|
+
preferred. On the other hand, in case your library has multiple source
|
480
|
+
files, avoid choosing ``LIBRARY.c'' for a file name. It may conflict
|
481
|
+
with an intermediate file ``LIBRARY.o'' on some platforms.
|
482
|
+
|
483
|
+
Ruby will execute the initializing function named ``Init_LIBRARY'' in
|
484
|
+
the library. For example, ``Init_dbm()'' will be executed when loading
|
485
|
+
the library.
|
486
|
+
|
487
|
+
Here's the example of an initializing function.
|
488
|
+
|
489
|
+
--
|
490
|
+
Init_dbm()
|
491
|
+
{
|
492
|
+
/* define DBM class */
|
493
|
+
cDBM = rb_define_class("DBM", rb_cObject);
|
494
|
+
/* DBM includes Enumerate module */
|
495
|
+
rb_include_module(cDBM, rb_mEnumerable);
|
496
|
+
|
497
|
+
/* DBM has class method open(): arguments are received as C array */
|
498
|
+
rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1);
|
499
|
+
|
500
|
+
/* DBM instance method close(): no args */
|
501
|
+
rb_define_method(cDBM, "close", fdbm_close, 0);
|
502
|
+
/* DBM instance method []: 1 argument */
|
503
|
+
rb_define_method(cDBM, "[]", fdbm_fetch, 1);
|
504
|
+
:
|
505
|
+
|
506
|
+
/* ID for a instance variable to store DBM data */
|
507
|
+
id_dbm = rb_intern("dbm");
|
508
|
+
}
|
509
|
+
--
|
510
|
+
|
511
|
+
The dbm extension wraps the dbm struct in the C environment using
|
512
|
+
Data_Make_Struct.
|
513
|
+
|
514
|
+
--
|
515
|
+
struct dbmdata {
|
516
|
+
int di_size;
|
517
|
+
DBM *di_dbm;
|
518
|
+
};
|
519
|
+
|
520
|
+
|
521
|
+
obj = Data_Make_Struct(klass, struct dbmdata, 0, free_dbm, dbmp);
|
522
|
+
--
|
523
|
+
|
524
|
+
This code wraps the dbmdata structure into a Ruby object. We avoid wrapping
|
525
|
+
DBM* directly, because we want to cache size information.
|
526
|
+
|
527
|
+
To retrieve the dbmdata structure from a Ruby object, we define the
|
528
|
+
following macro:
|
529
|
+
|
530
|
+
--
|
531
|
+
#define GetDBM(obj, dbmp) {\
|
532
|
+
Data_Get_Struct(obj, struct dbmdata, dbmp);\
|
533
|
+
if (dbmp->di_dbm == 0) closed_dbm();\
|
534
|
+
}
|
535
|
+
--
|
536
|
+
|
537
|
+
This sort of complicated macro does the retrieving and close checking for
|
538
|
+
the DBM.
|
539
|
+
|
540
|
+
There are three kinds of way to receive method arguments. First,
|
541
|
+
methods with a fixed number of arguments receive arguments like this:
|
542
|
+
|
543
|
+
--
|
544
|
+
static VALUE
|
545
|
+
fdbm_delete(obj, keystr)
|
546
|
+
VALUE obj, keystr;
|
547
|
+
{
|
548
|
+
:
|
549
|
+
}
|
550
|
+
--
|
551
|
+
|
552
|
+
The first argument of the C function is the self, the rest are the
|
553
|
+
arguments to the method.
|
554
|
+
|
555
|
+
Second, methods with an arbitrary number of arguments receive
|
556
|
+
arguments like this:
|
557
|
+
|
558
|
+
--
|
559
|
+
static VALUE
|
560
|
+
fdbm_s_open(argc, argv, klass)
|
561
|
+
int argc;
|
562
|
+
VALUE *argv;
|
563
|
+
VALUE klass;
|
564
|
+
{
|
565
|
+
:
|
566
|
+
if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) {
|
567
|
+
mode = 0666; /* default value */
|
568
|
+
}
|
569
|
+
:
|
570
|
+
}
|
571
|
+
--
|
572
|
+
|
573
|
+
The first argument is the number of method arguments, the second
|
574
|
+
argument is the C array of the method arguments, and the third
|
575
|
+
argument is the receiver of the method.
|
576
|
+
|
577
|
+
You can use the function rb_scan_args() to check and retrieve the
|
578
|
+
arguments. For example, "11" means that the method requires at least one
|
579
|
+
argument, and at most receives two arguments.
|
580
|
+
|
581
|
+
Methods with an arbitrary number of arguments can receive arguments
|
582
|
+
by Ruby's array, like this:
|
583
|
+
|
584
|
+
--
|
585
|
+
static VALUE
|
586
|
+
fdbm_indexes(obj, args)
|
587
|
+
VALUE obj, args;
|
588
|
+
{
|
589
|
+
:
|
590
|
+
}
|
591
|
+
--
|
592
|
+
|
593
|
+
The first argument is the receiver, the second one is the Ruby array
|
594
|
+
which contains the arguments to the method.
|
595
|
+
|
596
|
+
** Notice
|
597
|
+
|
598
|
+
GC should know about global variables which refer to Ruby's objects, but
|
599
|
+
are not exported to the Ruby world. You need to protect them by
|
600
|
+
|
601
|
+
void rb_global_variable(VALUE *var)
|
602
|
+
|
603
|
+
(5) prepare extconf.rb
|
604
|
+
|
605
|
+
If the file named extconf.rb exists, it will be executed to generate
|
606
|
+
Makefile. If not, the compilation scheme will try to generate Makefile
|
607
|
+
anyway.
|
608
|
+
|
609
|
+
extconf.rb is the file for check compilation conditions etc. You
|
610
|
+
need to put
|
611
|
+
|
612
|
+
require 'mkmf'
|
613
|
+
|
614
|
+
at the top of the file. You can use the functions below to check
|
615
|
+
various conditions.
|
616
|
+
|
617
|
+
have_library(lib, func): check whether library containing function exists.
|
618
|
+
have_func(func, header): check whether function exists
|
619
|
+
have_header(header): check whether header file exists
|
620
|
+
create_makefile(target): generate Makefile
|
621
|
+
|
622
|
+
The value of the variables below will affect the Makefile.
|
623
|
+
|
624
|
+
$CFLAGS: included in CFLAGS make variable (such as -I)
|
625
|
+
$LDFLAGS: included in LDFLAGS make variable (such as -L)
|
626
|
+
|
627
|
+
If a compilation condition is not fulfilled, you should not call
|
628
|
+
``create_makefile''. The Makefile will not generated, compilation will
|
629
|
+
not be done.
|
630
|
+
|
631
|
+
(6) prepare depend (optional)
|
632
|
+
|
633
|
+
If the file named depend exists, Makefile will include that file to
|
634
|
+
check dependencies. You can make this file by invoking
|
635
|
+
|
636
|
+
% gcc -MM *.c > depend
|
637
|
+
|
638
|
+
It's no harm. Prepare it.
|
639
|
+
|
640
|
+
(7) put file names into MANIFEST (optional)
|
641
|
+
|
642
|
+
% find * -type f -print > MANIFEST
|
643
|
+
% vi MANIFEST
|
644
|
+
|
645
|
+
Append file names into MANIFEST. The compilation scheme requires
|
646
|
+
MANIFEST only to exist, but it's better to take this step in order
|
647
|
+
to distinguish which files are required.
|
648
|
+
|
649
|
+
(8) generate Makefile
|
650
|
+
|
651
|
+
Try generating the Makefile by:
|
652
|
+
|
653
|
+
ruby extconf.rb
|
654
|
+
|
655
|
+
You don't need this step if you put the extension library under the ext
|
656
|
+
directory of the ruby source tree. In that case, compilation of the
|
657
|
+
interpreter will do this step for you.
|
658
|
+
|
659
|
+
(9) make
|
660
|
+
|
661
|
+
Type
|
662
|
+
|
663
|
+
make
|
664
|
+
|
665
|
+
to compile your extension. You don't need this step either if you have
|
666
|
+
put extension library under the ext directory of the ruby source tree.
|
667
|
+
|
668
|
+
(9) debug
|
669
|
+
|
670
|
+
You may need to rb_debug the extension. Extensions can be linked
|
671
|
+
statically by the adding directory name in the ext/Setup file so that
|
672
|
+
you can inspect the extension with the debugger.
|
673
|
+
|
674
|
+
(10) done, now you have the extension library
|
675
|
+
|
676
|
+
You can do anything you want with your library. The author of Ruby
|
677
|
+
will not claim any restrictions on your code depending on the Ruby API.
|
678
|
+
Feel free to use, modify, distribute or sell your program.
|
679
|
+
|
680
|
+
Appendix A. Ruby source files overview
|
681
|
+
|
682
|
+
ruby language core
|
683
|
+
|
684
|
+
class.c
|
685
|
+
error.c
|
686
|
+
eval.c
|
687
|
+
gc.c
|
688
|
+
object.c
|
689
|
+
parse.y
|
690
|
+
variable.c
|
691
|
+
|
692
|
+
utility functions
|
693
|
+
|
694
|
+
dln.c
|
695
|
+
regex.c
|
696
|
+
st.c
|
697
|
+
util.c
|
698
|
+
|
699
|
+
ruby interpreter implementation
|
700
|
+
|
701
|
+
dmyext.c
|
702
|
+
inits.c
|
703
|
+
main.c
|
704
|
+
ruby.c
|
705
|
+
version.c
|
706
|
+
|
707
|
+
class library
|
708
|
+
|
709
|
+
array.c
|
710
|
+
bignum.c
|
711
|
+
compar.c
|
712
|
+
dir.c
|
713
|
+
enum.c
|
714
|
+
file.c
|
715
|
+
hash.c
|
716
|
+
io.c
|
717
|
+
marshal.c
|
718
|
+
math.c
|
719
|
+
numeric.c
|
720
|
+
pack.c
|
721
|
+
prec.c
|
722
|
+
process.c
|
723
|
+
random.c
|
724
|
+
range.c
|
725
|
+
re.c
|
726
|
+
signal.c
|
727
|
+
sprintf.c
|
728
|
+
string.c
|
729
|
+
struct.c
|
730
|
+
time.c
|
731
|
+
|
732
|
+
Appendix B. Ruby extension API reference
|
733
|
+
|
734
|
+
** Types
|
735
|
+
|
736
|
+
VALUE
|
737
|
+
|
738
|
+
The type for the Ruby object. Actual structures are defined in ruby.h,
|
739
|
+
such as struct RString, etc. To refer the values in structures, use
|
740
|
+
casting macros like RSTRING(obj).
|
741
|
+
|
742
|
+
** Variables and constants
|
743
|
+
|
744
|
+
Qnil
|
745
|
+
|
746
|
+
const: nil object
|
747
|
+
|
748
|
+
Qtrue
|
749
|
+
|
750
|
+
const: true object(default true value)
|
751
|
+
|
752
|
+
Qfalse
|
753
|
+
|
754
|
+
const: false object
|
755
|
+
|
756
|
+
** C pointer wrapping
|
757
|
+
|
758
|
+
Data_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval)
|
759
|
+
|
760
|
+
Wrap a C pointer into a Ruby object. If object has references to other
|
761
|
+
Ruby objects, they should be marked by using the mark function during
|
762
|
+
the GC process. Otherwise, mark should be 0. When this object is no
|
763
|
+
longer referred by anywhere, the pointer will be discarded by free
|
764
|
+
function.
|
765
|
+
|
766
|
+
Data_Make_Struct(klass, type, mark, free, sval)
|
767
|
+
|
768
|
+
This macro allocates memory using malloc(), assigns it to the variable
|
769
|
+
sval, and returns the DATA encapsulating the pointer to memory region.
|
770
|
+
|
771
|
+
Data_Get_Struct(data, type, sval)
|
772
|
+
|
773
|
+
This macro retrieves the pointer value from DATA, and assigns it to
|
774
|
+
the variable sval.
|
775
|
+
|
776
|
+
** Checking data types
|
777
|
+
|
778
|
+
TYPE(value)
|
779
|
+
FIXNUM_P(value)
|
780
|
+
NIL_P(value)
|
781
|
+
void Check_Type(VALUE value, int type)
|
782
|
+
void Check_SafeStr(VALUE value)
|
783
|
+
|
784
|
+
** Data type conversion
|
785
|
+
|
786
|
+
FIX2INT(value)
|
787
|
+
INT2FIX(i)
|
788
|
+
NUM2INT(value)
|
789
|
+
INT2NUM(i)
|
790
|
+
NUM2DBL(value)
|
791
|
+
rb_float_new(f)
|
792
|
+
STR2CSTR(value)
|
793
|
+
rb_str_new2(s)
|
794
|
+
|
795
|
+
** defining class/module
|
796
|
+
|
797
|
+
VALUE rb_define_class(const char *name, VALUE super)
|
798
|
+
|
799
|
+
Defines a new Ruby class as a subclass of super.
|
800
|
+
|
801
|
+
VALUE rb_define_class_under(VALUE module, const char *name, VALUE super)
|
802
|
+
|
803
|
+
Creates a new Ruby class as a subclass of super, under the module's
|
804
|
+
namespace.
|
805
|
+
|
806
|
+
VALUE rb_define_module(const char *name)
|
807
|
+
|
808
|
+
Defines a new Ruby module.
|
809
|
+
|
810
|
+
VALUE rb_define_module_under(VALUE module, const char *name, VALUE super)
|
811
|
+
|
812
|
+
Defines a new Ruby module under the module's namespace.
|
813
|
+
|
814
|
+
void rb_include_module(VALUE klass, VALUE module)
|
815
|
+
|
816
|
+
Includes module into class. If class already includes it, just
|
817
|
+
ignored.
|
818
|
+
|
819
|
+
void rb_extend_object(VALUE object, VALUE module)
|
820
|
+
|
821
|
+
Extend the object with the module's attributes.
|
822
|
+
|
823
|
+
** Defining Global Variables
|
824
|
+
|
825
|
+
void rb_define_variable(const char *name, VALUE *var)
|
826
|
+
|
827
|
+
Defines a global variable which is shared between C and Ruby. If name
|
828
|
+
contains a character which is not allowed to be part of the symbol,
|
829
|
+
it can't be seen from Ruby programs.
|
830
|
+
|
831
|
+
void rb_define_readonly_variable(const char *name, VALUE *var)
|
832
|
+
|
833
|
+
Defines a read-only global variable. Works just like
|
834
|
+
rb_define_variable(), except defined variable is read-only.
|
835
|
+
|
836
|
+
void rb_define_virtual_variable(const char *name,
|
837
|
+
VALUE (*getter)(), VALUE (*setter)())
|
838
|
+
|
839
|
+
Defines a virtual variable, whose behavior is defined by a pair of C
|
840
|
+
functions. The getter function is called when the variable is
|
841
|
+
referred. The setter function is called when the value is set to the
|
842
|
+
variable. The prototype for getter/setter functions are:
|
843
|
+
|
844
|
+
VALUE getter(ID id)
|
845
|
+
void setter(VALUE val, ID id)
|
846
|
+
|
847
|
+
The getter function must return the value for the access.
|
848
|
+
|
849
|
+
void rb_define_hooked_variable(const char *name, VALUE *var,
|
850
|
+
VALUE (*getter)(), VALUE (*setter)())
|
851
|
+
|
852
|
+
Defines hooked variable. It's a virtual variable with a C variable.
|
853
|
+
The getter is called as
|
854
|
+
|
855
|
+
VALUE getter(ID id, VALUE *var)
|
856
|
+
|
857
|
+
returning a new value. The setter is called as
|
858
|
+
|
859
|
+
void setter(VALUE val, ID id, VALUE *var)
|
860
|
+
|
861
|
+
GC requires C global variables which hold Ruby values to be marked.
|
862
|
+
|
863
|
+
void rb_global_variable(VALUE *var)
|
864
|
+
|
865
|
+
Tells GC to protect these variables.
|
866
|
+
|
867
|
+
** Constant Definition
|
868
|
+
|
869
|
+
void rb_define_const(VALUE klass, const char *name, VALUE val)
|
870
|
+
|
871
|
+
Defines a new constant under the class/module.
|
872
|
+
|
873
|
+
void rb_define_global_const(const char *name, VALUE val)
|
874
|
+
|
875
|
+
Defines a global constant. This is just the same as
|
876
|
+
|
877
|
+
rb_define_const(cKernal, name, val)
|
878
|
+
|
879
|
+
** Method Definition
|
880
|
+
|
881
|
+
rb_define_method(VALUE klass, const char *name, VALUE (*func)(), int argc)
|
882
|
+
|
883
|
+
Defines a method for the class. func is the function pointer. argc
|
884
|
+
is the number of arguments. if argc is -1, the function will receive
|
885
|
+
3 arguments: argc, argv, and self. if argc is -2, the function will
|
886
|
+
receive 2 arguments, self and args, where args is a Ruby array of
|
887
|
+
the method arguments.
|
888
|
+
|
889
|
+
rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(), int argc)
|
890
|
+
|
891
|
+
Defines a private method for the class. Arguments are same as
|
892
|
+
rb_define_method().
|
893
|
+
|
894
|
+
rb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(), int argc)
|
895
|
+
|
896
|
+
Defines a singleton method. Arguments are same as rb_define_method().
|
897
|
+
|
898
|
+
rb_scan_args(int argc, VALUE *argv, const char *fmt, ...)
|
899
|
+
|
900
|
+
Retrieve argument from argc, argv. The fmt is the format string for
|
901
|
+
the arguments, such as "12" for 1 non-optional argument, 2 optional
|
902
|
+
arguments. If `*' appears at the end of fmt, it means the rest of
|
903
|
+
the arguments are assigned to the corresponding variable, packed in
|
904
|
+
an array.
|
905
|
+
|
906
|
+
** Invoking Ruby method
|
907
|
+
|
908
|
+
VALUE rb_funcall(VALUE recv, ID mid, int narg, ...)
|
909
|
+
|
910
|
+
Invokes a method. To retrieve mid from a method name, use rb_intern().
|
911
|
+
|
912
|
+
VALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv)
|
913
|
+
|
914
|
+
Invokes a method, passing arguments by an array of values.
|
915
|
+
|
916
|
+
VALUE rb_eval_string(const char *str)
|
917
|
+
|
918
|
+
Compiles and executes the string as a Ruby program.
|
919
|
+
|
920
|
+
ID rb_intern(const char *name)
|
921
|
+
|
922
|
+
Returns ID corresponding to the name.
|
923
|
+
|
924
|
+
char *rb_id2name(ID id)
|
925
|
+
|
926
|
+
Returns the name corresponding ID.
|
927
|
+
|
928
|
+
char *rb_class2name(VALUE klass)
|
929
|
+
|
930
|
+
Returns the name of the class.
|
931
|
+
|
932
|
+
int rb_respond_to(VALUE object, ID id)
|
933
|
+
|
934
|
+
Returns true if the object responds to the message specified by id.
|
935
|
+
|
936
|
+
** Instance Variables
|
937
|
+
|
938
|
+
VALUE rb_iv_get(VALUE obj, const char *name)
|
939
|
+
|
940
|
+
Retrieve the value of the instance variable. If the name is not
|
941
|
+
prefixed by `@', that variable shall be inaccessible from Ruby.
|
942
|
+
|
943
|
+
VALUE rb_iv_set(VALUE obj, const char *name, VALUE val)
|
944
|
+
|
945
|
+
Sets the value of the instance variable.
|
946
|
+
|
947
|
+
** Control Structure
|
948
|
+
|
949
|
+
VALUE rb_iterate(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2)
|
950
|
+
|
951
|
+
Calls the function func1, supplying func2 as the block. func1 will be
|
952
|
+
called with the argument arg1. func2 receives the value from yield as
|
953
|
+
the first argument, arg2 as the second argument.
|
954
|
+
|
955
|
+
VALUE rb_yield(VALUE val)
|
956
|
+
|
957
|
+
Evaluates the block with value val.
|
958
|
+
|
959
|
+
VALUE rb_rescue(VALUE (*func1)(), void *arg1, VALUE (*func2)(), void *arg2)
|
960
|
+
|
961
|
+
Calls the function func1, with arg1 as the argument. If an exception
|
962
|
+
occurs during func1, it calls func2 with arg2 as the argument. The
|
963
|
+
return value of rb_rescue() is the return value from func1 if no
|
964
|
+
exception occurs, from func2 otherwise.
|
965
|
+
|
966
|
+
VALUE rb_ensure(VALUE (*func1)(), void *arg1, void (*func2)(), void *arg2)
|
967
|
+
|
968
|
+
Calls the function func1 with arg1 as the argument, then calls func2
|
969
|
+
with arg2 if execution terminated. The return value from
|
970
|
+
rb_ensure() is that of func1.
|
971
|
+
|
972
|
+
** Exceptions and Errors
|
973
|
+
|
974
|
+
void rb_warn(const char *fmt, ...)
|
975
|
+
|
976
|
+
Prints a warning message according to a printf-like format.
|
977
|
+
|
978
|
+
void rb_warning(const char *fmt, ...)
|
979
|
+
|
980
|
+
Prints a warning message according to a printf-like format, if
|
981
|
+
$VERBOSE is true.
|
982
|
+
|
983
|
+
void rb_raise(rb_eRuntimeError, const char *fmt, ...)
|
984
|
+
|
985
|
+
Raises RuntimeError. The fmt is a format string just like printf().
|
986
|
+
|
987
|
+
void rb_raise(VALUE exception, const char *fmt, ...)
|
988
|
+
|
989
|
+
Raises a class exception. The fmt is a format string just like printf().
|
990
|
+
|
991
|
+
void rb_fatal(const char *fmt, ...)
|
992
|
+
|
993
|
+
Raises a fatal error, terminates the interpreter. No exception handling
|
994
|
+
will be done for fatal errors, but ensure blocks will be executed.
|
995
|
+
|
996
|
+
void rb_bug(const char *fmt, ...)
|
997
|
+
|
998
|
+
Terminates the interpreter immediately. This function should be
|
999
|
+
called under the situation caused by the bug in the interpreter. No
|
1000
|
+
exception handling nor ensure execution will be done.
|
1001
|
+
|
1002
|
+
** Initialize and Starts the Interpreter
|
1003
|
+
|
1004
|
+
The embedding API functions are below (not needed for extension libraries):
|
1005
|
+
|
1006
|
+
void ruby_init()
|
1007
|
+
|
1008
|
+
Initializes the interpreter.
|
1009
|
+
|
1010
|
+
void ruby_options(int argc, char **argv)
|
1011
|
+
|
1012
|
+
Process command line arguments for the interpreter.
|
1013
|
+
|
1014
|
+
void ruby_run()
|
1015
|
+
|
1016
|
+
Starts execution of the interpreter.
|
1017
|
+
|
1018
|
+
void ruby_script(char *name)
|
1019
|
+
|
1020
|
+
Specifies the name of the script ($0).
|
1021
|
+
|
1022
|
+
Appendix C. Functions Available in extconf.rb
|
1023
|
+
|
1024
|
+
These functions are available in extconf.rb:
|
1025
|
+
|
1026
|
+
have_library(lib, func)
|
1027
|
+
|
1028
|
+
Checks whether the library exists, containing the specified function.
|
1029
|
+
Returns true if the library exists.
|
1030
|
+
|
1031
|
+
find_library(lib, func, path...)
|
1032
|
+
|
1033
|
+
Checks whether a library which contains the specified function exists in
|
1034
|
+
path. Returns true if the library exists.
|
1035
|
+
|
1036
|
+
have_func(func, header)
|
1037
|
+
|
1038
|
+
Checks whether func exists with header. Returns true if the function
|
1039
|
+
exists. To check functions in an additional library, you need to
|
1040
|
+
check that library first using have_library().
|
1041
|
+
|
1042
|
+
have_header(header)
|
1043
|
+
|
1044
|
+
Checks whether header exists. Returns true if the header file exists.
|
1045
|
+
|
1046
|
+
create_makefile(target)
|
1047
|
+
|
1048
|
+
Generates the Makefile for the extension library. If you don't invoke
|
1049
|
+
this method, the compilation will not be done.
|
1050
|
+
|
1051
|
+
with_config(withval[, default=nil])
|
1052
|
+
|
1053
|
+
Parses the command line options and returns the value specified by
|
1054
|
+
--with-<withval>.
|
1055
|
+
|
1056
|
+
dir_config(target[, default_dir])
|
1057
|
+
dir_config(target[, default_include, default_lib])
|
1058
|
+
|
1059
|
+
Parses the command line options and adds the directories specified by
|
1060
|
+
--with-<target>-dir, --with-<target>-include, and/or --with-<target>-lib
|
1061
|
+
to $CFLAGS and/or $LDFLAGS. --with-<target>-dir=/path is equivalent to
|
1062
|
+
--with-<target>-include=/path/include --with-<target>-lib=/path/lib.
|
1063
|
+
Returns an array of the added directories ([include_dir, lib_dir]).
|
1064
|
+
|
1065
|
+
/*
|
1066
|
+
* Local variables:
|
1067
|
+
* fill-column: 70
|
1068
|
+
* end:
|
1069
|
+
*/
|