D7net
Home
Console
Upload
information
Create File
Create Folder
About
Tools
:
/
opt
/
alt
/
ruby34
/
share
/
ri
/
system
/
Filename :
page-extension_rdoc.ri
back
Copy
U:RDoc::TopLevel[ i I"extension.rdoc:ETcRDoc::Parser::Simpleo:RDoc::Markup::Document: @parts[�S:RDoc::Markup::Heading: leveli: textI"*Creating extension libraries for Ruby;To: RDoc::Markup::BlankLine o: RDoc::Markup::Paragraph;[I"EThis document explains how to make extension libraries for Ruby.;T@ S; ; i; I"Basic Knowledge;T@ o; ;[I"JIn C, variables have types and data do not have types. In contrast, ;TI"HRuby variables do not have a static type, and data themselves have ;TI"Dtypes, so data will need to be converted between the languages.;T@ o; ;[I"HObjects in Ruby are represented by the C type `VALUE'. Each VALUE ;TI" data has its data type.;T@ o; ;[I"2To retrieve C data from a VALUE, you need to:;T@ o:RDoc::Markup::List: @type: NUMBER: @items[o:RDoc::Markup::ListItem: @label0;[o; ;[I"#Identify the VALUE's data type;To;;0;[o; ;[I""Convert the VALUE into C data;T@ o; ;[I"BConverting to the wrong data type may cause serious problems.;T@ S; ; i; I"Ruby data types;T@ o; ;[I"7The Ruby interpreter has the following data types:;T@ o;;: NOTE;[o;;[I"T_NIL ;T;[o; ;[I"nil;To;;[I"T_OBJECT ;T;[o; ;[I"ordinary object;To;;[I"T_CLASS ;T;[o; ;[I" class;To;;[I"T_MODULE ;T;[o; ;[I" module;To;;[I"T_FLOAT ;T;[o; ;[I"floating point number;To;;[I"T_STRING ;T;[o; ;[I" string;To;;[I"T_REGEXP ;T;[o; ;[I"regular expression;To;;[I"T_ARRAY ;T;[o; ;[I" array;To;;[I"T_HASH ;T;[o; ;[I"associative array;To;;[I"T_STRUCT ;T;[o; ;[I"(Ruby) structure;To;;[I"T_BIGNUM ;T;[o; ;[I" multi precision integer;To;;[I"T_FIXNUM ;T;[o; ;[I"#Fixnum(31bit or 63bit integer);To;;[I"T_COMPLEX ;T;[o; ;[I"complex number;To;;[I"T_RATIONAL ;T;[o; ;[I"rational number;To;;[I"T_FILE ;T;[o; ;[I"IO;To;;[I"T_TRUE ;T;[o; ;[I" true;To;;[I"T_FALSE ;T;[o; ;[I" false;To;;[I"T_DATA ;T;[o; ;[I" data;To;;[I"T_SYMBOL ;T;[o; ;[I" symbol;T@ o; ;[I"@In addition, there are several other types used internally:;T@ o;;;;[ o;;[I"T_ICLASS ;T;[o; ;[I"included module;To;;[I"T_MATCH ;T;[o; ;[I"MatchData object;To;;[I"T_UNDEF ;T;[o; ;[I"undefined;To;;[I"T_NODE ;T;[o; ;[I"syntax tree node;To;;[I"T_ZOMBIE ;T;[o; ;[I"!object awaiting finalization;T@ o; ;[I"7Most of the types are represented by C structures.;T@ S; ; i; I"!Check type of the VALUE data;T@ o; ;[I"JThe macro TYPE() defined in ruby.h shows the data type of the VALUE. ;TI"KTYPE() returns the constant number T_XXXX described above. To handle ;TI"9data types, your code will look something like this:;T@ o:RDoc::Markup::Verbatim;[I"switch (TYPE(obj)) { ;TI" case T_FIXNUM: ;TI" /* process Fixnum */ ;TI" break; ;TI" case T_STRING: ;TI" /* process String */ ;TI" break; ;TI" case T_ARRAY: ;TI" /* process Array */ ;TI" break; ;TI" default: ;TI" /* raise exception */ ;TI"5 rb_raise(rb_eTypeError, "not valid value"); ;TI" break; ;TI"} ;T: @format0o; ;[I"*There is the data type check function;T@ o;;[I",void Check_Type(VALUE value, int type) ;T;0o; ;[I"Cwhich raises an exception if the VALUE does not have the type ;TI"specified.;T@ o; ;[I"<There are also faster check macros for fixnums and nil.;T@ o;;[I"FIXNUM_P(obj) ;TI"NIL_P(obj) ;T;0S; ; i; I" Convert VALUE into C data;T@ o; ;[ I"CThe data for type T_NIL, T_FALSE, T_TRUE are nil, false, true ;TI";respectively. They are singletons for the data type. ;TI":The equivalent C constants are: Qnil, Qfalse, Qtrue. ;TI"ERTEST() will return true if a VALUE is neither Qfalse nor Qnil. ;TI"4If you need to differentiate Qfalse from Qnil, ;TI"&specifically test against Qfalse.;T@ o; ;[I"AThe T_FIXNUM data is a 31bit or 63bit length fixed integer. ;TI"BThis size depends on the size of long: if long is 32bit then ;TI"AT_FIXNUM is 31bit, if long is 64bit then T_FIXNUM is 63bit. ;TI";T_FIXNUM can be converted to a C integer by using the ;TI"GFIX2INT() macro or FIX2LONG(). Though you have to check that the ;TI"Kdata is really FIXNUM before using them, they are faster. FIX2LONG() ;TI"Enever raises exceptions, but FIX2INT() raises RangeError if the ;TI"7result is bigger or smaller than the size of int. ;TI"EThere are also NUM2INT() and NUM2LONG() which converts any Ruby ;TI"Bnumbers into C integers. These macros include a type check, ;TI"Iso an exception will be raised if the conversion failed. NUM2DBL() ;TI"Dcan be used to retrieve the double float value in the same way.;T@ o; ;[ I" You can use the macros ;TI"EStringValue() and StringValuePtr() to get a char* from a VALUE. ;TI"NStringValue(var) replaces var's value with the result of "var.to_str()". ;TI"IStringValuePtr(var) does the same replacement and returns the char* ;TI"Krepresentation of var. These macros will skip the replacement if var ;TI"His a String. Notice that the macros take only the lvalue as their ;TI"3argument, to change the value of var in place.;T@ o; ;[ I"FYou can also use the macro named StringValueCStr(). This is just ;TI"Jlike StringValuePtr(), but always adds a NUL character at the end of ;TI"Kthe result. If the result contains a NUL character, this macro causes ;TI""the ArgumentError exception. ;TI"JStringValuePtr() doesn't guarantee the existence of a NUL at the end ;TI"3of the result, and the result may contain NUL.;T@ o; ;[I"JOther data types have corresponding C structures, e.g. struct RArray ;TI"Hfor T_ARRAY etc. The VALUE of the type which has the corresponding ;TI"Gstructure can be cast to retrieve the pointer to the struct. The ;TI"Ecasting macro will be of the form RXXXX for each data type; for ;TI"Iinstance, RARRAY(obj). See "ruby.h". However, we do not recommend ;TI"Nto access RXXXX data directly because these data structures are complex. ;TI"IUse corresponding rb_xxx() functions to access the internal struct. ;TI"MFor example, to access an entry of array, use rb_ary_entry(ary, offset) ;TI"(and rb_ary_store(ary, offset, obj).;T@ o; ;[I"HThere are some accessing macros for structure members, for example ;TI"H`RSTRING_LEN(str)' to get the size of the Ruby String object. The ;TI"<allocated region can be accessed by `RSTRING_PTR(str)'.;T@ o; ;[I"KNotice: Do not change the value of the structure directly, unless you ;TI"Fare responsible for the result. This ends up being the cause of ;TI"interesting bugs.;T@ S; ; i; I" Convert C data into VALUE;T@ o; ;[I"&To convert C data to Ruby values:;T@ o;;;;[o;;[I" FIXNUM ;T;[o; ;[I"Cleft shift 1 bit, and turn on its least significant bit (LSB).;T@ o;;[I"Other pointer values ;T;[o; ;[I"cast to VALUE.;T@ o; ;[I"OYou can determine whether a VALUE is a pointer or not by checking its LSB.;T@ o; ;[I"ONotice: Ruby does not allow arbitrary pointer values to be a VALUE. They ;TI"Mshould be pointers to the structures which Ruby knows about. The known ;TI"(structures are defined in <ruby.h>.;T@ o; ;[I";To convert C numbers to Ruby values, use these macros:;T@ o;;;;[o;;[I"INT2FIX() ;T;[o; ;[I" for integers within 31bits.;To;;[I"INT2NUM() ;T;[o; ;[I""for arbitrary sized integers.;T@ o; ;[I"LINT2NUM() converts an integer into a Bignum if it is out of the FIXNUM ;TI" range, but is a bit slower.;T@ S; ; i; I" Manipulating Ruby object;T@ o; ;[ I"IAs I already mentioned, it is not recommended to modify an object's ;TI"Linternal structure. To manipulate objects, use the functions supplied ;TI"Iby the Ruby interpreter. Some (not all) of the useful functions are ;TI"listed below:;T@ S; ; i ; I"String functions;T@ o;;;;[o;;[I"+rb_str_new(const char *ptr, long len) ;T;[o; ;[I" Creates a new Ruby string.;T@ o;;[I""rb_str_new2(const char *ptr) ;TI"&rb_str_new_cstr(const char *ptr) ;T;[o; ;[I"GCreates a new Ruby string from a C string. This is equivalent to ;TI""rb_str_new(ptr, strlen(ptr)).;T@ o;;[I")rb_str_new_literal(const char *ptr) ;T;[o; ;[I"7Creates a new Ruby string from a C string literal.;T@ o;;[I")rb_sprintf(const char *format, ...) ;TI"1rb_vsprintf(const char *format, va_list ap) ;T;[ o; ;[I"5Creates a new Ruby string with printf(3) format.;T@ o; ;[ I"JNote: In the format string, "%"PRIsVALUE can be used for Object#to_s ;TI"I(or Object#inspect if '+' flag is set) output (and related argument ;TI"Fmust be a VALUE). Since it conflicts with "%i", for integers in ;TI" format strings, use "%d".;T@ o;;[I"+rb_str_append(VALUE str1, VALUE str2) ;T;[o; ;[I"2Appends Ruby string str2 to Ruby string str1.;T@ o;;[I"6rb_str_cat(VALUE str, const char *ptr, long len) ;T;[o; ;[I";Appends len bytes of data from ptr to the Ruby string.;T@ o;;[I"-rb_str_cat2(VALUE str, const char* ptr) ;TI"1rb_str_cat_cstr(VALUE str, const char* ptr) ;T;[o; ;[I"@Appends C string ptr to Ruby string str. This function is ;TI"5equivalent to rb_str_cat(str, ptr, strlen(ptr)).;T@ o;;[I"5rb_str_catf(VALUE str, const char* format, ...) ;TI"=rb_str_vcatf(VALUE str, const char* format, va_list ap) ;T;[o; ;[ I"EAppends C string format and successive arguments to Ruby string ;TI"Astr according to a printf-like format. These functions are ;TI"Cequivalent to rb_str_append(str, rb_sprintf(format, ...)) and ;TI"?rb_str_append(str, rb_vsprintf(format, ap)), respectively.;T@ o;;[I"Arb_enc_str_new(const char *ptr, long len, rb_encoding *enc) ;TI"<rb_enc_str_new_cstr(const char *ptr, rb_encoding *enc) ;T;[o; ;[I";Creates a new Ruby string with the specified encoding.;T@ o;;[I"?rb_enc_str_new_literal(const char *ptr, rb_encoding *enc) ;T;[o; ;[I"JCreates a new Ruby string from a C string literal with the specified ;TI"encoding.;T@ o;;[I"3rb_usascii_str_new(const char *ptr, long len) ;TI".rb_usascii_str_new_cstr(const char *ptr) ;T;[o; ;[I"6Creates a new Ruby string with encoding US-ASCII.;T@ o;;[I"1rb_usascii_str_new_literal(const char *ptr) ;T;[o; ;[I"ECreates a new Ruby string from a C string literal with encoding ;TI"US-ASCII.;T@ o;;[I"0rb_utf8_str_new(const char *ptr, long len) ;TI"+rb_utf8_str_new_cstr(const char *ptr) ;T;[o; ;[I"3Creates a new Ruby string with encoding UTF-8.;T@ o;;[I".rb_utf8_str_new_literal(const char *ptr) ;T;[o; ;[I"ECreates a new Ruby string from a C string literal with encoding ;TI" UTF-8.;T@ o;;[I"(rb_str_resize(VALUE str, long len) ;T;[o; ;[ I"IResizes a Ruby string to len bytes. If str is not modifiable, this ;TI"Efunction raises an exception. The length of str must be set in ;TI"Eadvance. If len is less than the old length the content beyond ;TI"Hlen bytes is discarded, else if len is greater than the old length ;TI"Gthe content beyond the old length bytes will not be preserved but ;TI"Hwill be garbage. Note that RSTRING_PTR(str) may change by calling ;TI"this function.;T@ o;;[I")rb_str_set_len(VALUE str, long len) ;T;[o; ;[ I"GSets the length of a Ruby string. If str is not modifiable, this ;TI"Hfunction raises an exception. This function preserves the content ;TI"Hup to len bytes, regardless RSTRING_LEN(str). len must not exceed ;TI"the capacity of str.;T@ o;;[I" rb_str_modify(VALUE str) ;T;[o; ;[ I"GPrepares a Ruby string to modify. If str is not modifiable, this ;TI"Ffunction raises an exception, or if the buffer of str is shared, ;TI"Ethis function allocates new buffer to make it unshared. Always ;TI"Eyou MUST call this function before modifying the contents using ;TI"'RSTRING_PTR and/or rb_str_set_len.;T@ S; ; i ; I"Array functions;T@ o;;;;[ o;;[I"rb_ary_new() ;T;[o; ;[I"'Creates an array with no elements.;T@ o;;[I"rb_ary_new2(long len) ;TI" rb_ary_new_capa(long len) ;T;[o; ;[I"CCreates an array with no elements, allocating internal buffer ;TI"for len elements.;T@ o;;[I" rb_ary_new3(long n, ...) ;TI"'rb_ary_new_from_args(long n, ...) ;T;[o; ;[I"3Creates an n-element array from the arguments.;T@ o;;[I"&rb_ary_new4(long n, VALUE *elts) ;TI"1rb_ary_new_from_values(long n, VALUE *elts) ;T;[o; ;[I"/Creates an n-element array from a C array.;T@ o;;[I" rb_ary_to_ary(VALUE obj) ;T;[o; ;[I"(Converts the object into an array. ;TI"!Equivalent to Object#to_ary.;T@ o; ;[I"PThere are many functions to operate an array. They may dump core if other ;TI"types are given.;T@ o;;;;[ o;;[I"9rb_ary_aref(int argc, const VALUE *argv, VALUE ary) ;T;[o; ;[I" Equivalent to Array#[].;T@ o;;[I"*rb_ary_entry(VALUE ary, long offset) ;T;[o; ;[I"\ary[offset];T@ o;;[I"5rb_ary_store(VALUE ary, long offset, VALUE obj) ;T;[o; ;[I"\ary[offset] = obj;T@ o;;[I"2rb_ary_subseq(VALUE ary, long beg, long len) ;T;[o; ;[I"ary[beg, len];T@ o;;[ I"'rb_ary_push(VALUE ary, VALUE val) ;TI"rb_ary_pop(VALUE ary) ;TI" rb_ary_shift(VALUE ary) ;TI"*rb_ary_unshift(VALUE ary, VALUE val) ;T;[o; ;[I".ary.push, ary.pop, ary.shift, ary.unshift;T@ o;;[I"7rb_ary_cat(VALUE ary, const VALUE *ptr, long len) ;T;[o; ;[I";Appends len elements of objects from ptr to the array.;T@ S; ; i; I"Extending Ruby with C;T@ S; ; i; I" Adding new features to Ruby;T@ o; ;[I"CYou can add new features (classes, methods, etc.) to the Ruby ;TI"Hinterpreter. Ruby provides APIs for defining the following things:;T@ o;;: BULLET;[o;;0;[o; ;[I"Classes, Modules;To;;0;[o; ;[I" Methods, singleton methods;To;;0;[o; ;[I"Constants;T@ S; ; i ; I" Class and Module Definition;T@ o; ;[I":To define a class or module, use the functions below:;T@ o;;[I":VALUE rb_define_class(const char *name, VALUE super) ;TI".VALUE rb_define_module(const char *name) ;T;0o; ;[I"HThese functions return the newly created class or module. You may ;TI">want to save this reference into a variable to use later.;T@ o; ;[I"BTo define nested classes or modules, use the functions below:;T@ o;;[I"MVALUE rb_define_class_under(VALUE outer, const char *name, VALUE super) ;TI"AVALUE rb_define_module_under(VALUE outer, const char *name) ;T;0S; ; i ; I"+Method and singleton method definition;T@ o; ;[I"ATo define methods or singleton methods, use these functions:;T@ o;;[ I":void rb_define_method(VALUE klass, const char *name, ;TI"= VALUE (*func)(ANYARGS), int argc) ;TI" ;TI"Evoid rb_define_singleton_method(VALUE object, const char *name, ;TI"G VALUE (*func)(ANYARGS), int argc) ;T;0o; ;[I"JThe `argc' represents the number of the arguments to the C function, ;TI"Dwhich must be less than 17. But I doubt you'll need that many.;T@ o; ;[I"MIf `argc' is negative, it specifies the calling sequence, not number of ;TI"the arguments.;T@ o; ;[I"3If argc is -1, the function will be called as:;T@ o;;[I"2VALUE func(int argc, VALUE *argv, VALUE obj) ;T;0o; ;[I"Jwhere argc is the actual number of arguments, argv is the C array of ;TI",the arguments, and obj is the receiver.;T@ o; ;[I"KIf argc is -2, the arguments are passed in a Ruby array. The function ;TI"will be called like:;T@ o;;[I"'VALUE func(VALUE obj, VALUE args) ;T;0o; ;[I"Fwhere obj is the receiver, and args is the Ruby array containing ;TI"actual arguments.;T@ o; ;[I"FThere are some more functions to define methods. One takes an ID ;TI"Fas the name of method to be defined. See also ID or Symbol below.;T@ o;;[I"4void rb_define_method_id(VALUE klass, ID name, ;TI"@ VALUE (*func)(ANYARGS), int argc) ;T;0o; ;[I"AThere are two functions to define private/protected methods:;T@ o;;[ I"Bvoid rb_define_private_method(VALUE klass, const char *name, ;TI"E VALUE (*func)(ANYARGS), int argc) ;TI"Dvoid rb_define_protected_method(VALUE klass, const char *name, ;TI"G VALUE (*func)(ANYARGS), int argc) ;T;0o; ;[ I"CAt last, rb_define_module_function defines a module function, ;TI"<which are private AND singleton methods of the module. ;TI"HFor example, sqrt is a module function defined in the Math module. ;TI"+It can be called in the following way:;T@ o;;[I"Math.sqrt(4) ;T;0o; ;[I"or;T@ o;;[I"include Math ;TI" sqrt(4) ;T;0o; ;[I"%To define module functions, use:;T@ o;;[I"Dvoid rb_define_module_function(VALUE module, const char *name, ;TI"F VALUE (*func)(ANYARGS), int argc) ;T;0o; ;[I"KIn addition, function-like methods, which are private methods defined ;TI"0in the Kernel module, can be defined using:;T@ o;;[I"Xvoid rb_define_global_function(const char *name, VALUE (*func)(ANYARGS), int argc) ;T;0o; ;[I"'To define an alias for the method,;T@ o;;[I"Kvoid rb_define_alias(VALUE module, const char* new, const char* old); ;T;0o; ;[I"0To define a reader/writer for an attribute,;T@ o;;[I"Mvoid rb_define_attr(VALUE klass, const char *name, int read, int write) ;T;0o; ;[I"8To define and undefine the `allocate' class method,;T@ o;;[I"Ivoid rb_define_alloc_func(VALUE klass, VALUE (*func)(VALUE klass)); ;TI",void rb_undef_alloc_func(VALUE klass); ;T;0o; ;[I"Cfunc has to take the klass as the argument and return a newly ;TI"Hallocated instance. This instance should be as empty as possible, ;TI":without any expensive (including external) resources.;T@ o; ;[I"MIf you are overriding an existing method of any ancestor of your class, ;TI"you may rely on:;T@ o;;[I"6VALUE rb_call_super(int argc, const VALUE *argv) ;T;0o; ;[I"HTo specify whether keyword arguments are passed when calling super:;T@ o;;[I"GVALUE rb_call_super_kw(int argc, const VALUE *argv, int kw_splat) ;T;0o; ;[I"P+kw_splat+ can have these possible values (used by all methods that accept ;TI"+kw_splat+ argument):;T@ o;;;;[o;;[I"RB_NO_KEYWORDS ;T;[o; ;[I"Do not pass keywords;To;;[I"RB_PASS_KEYWORDS ;T;[o; ;[I"?Pass keywords, final argument should be a hash of keywords;To;;[I" RB_PASS_CALLED_KEYWORDS ;T;[o; ;[I"5Pass keywords if current method was called with ;TI"-keywords, useful for argument delegation;T@ o; ;[I"FTo achieve the receiver of the current scope (if no other way is ;TI" available), you can use:;T@ o;;[I"%VALUE rb_current_receiver(void) ;T;0S; ; i ; I"Constant definition;T@ o; ;[I"-We have 2 functions to define constants:;T@ o;;[I"Dvoid rb_define_const(VALUE klass, const char *name, VALUE val) ;TI">void rb_define_global_const(const char *name, VALUE val) ;T;0o; ;[I"KThe former is to define a constant under specified class/module. The ;TI"+latter is to define a global constant.;T@ S; ; i; I" Use Ruby features from C;T@ o; ;[I"BThere are several ways to invoke Ruby's features from C code.;T@ S; ; i ; I"'Evaluate Ruby programs in a string;T@ o; ;[I"HThe easiest way to use Ruby's functionality from a C program is to ;TI"Ievaluate the string as Ruby program. This function will do the job:;T@ o;;[I"+VALUE rb_eval_string(const char *str) ;T;0o; ;[I"PEvaluation is done under the current context, thus current local variables ;TI"Hof the innermost method (which is defined by Ruby) can be accessed.;T@ o; ;[I"GNote that the evaluation can raise an exception. There is a safer ;TI"function:;T@ o;;[I"?VALUE rb_eval_string_protect(const char *str, int *state) ;T;0o; ;[I"PIt returns nil when an error occurred. Moreover, *state is zero if str was ;TI"2successfully evaluated, or nonzero otherwise.;T@ S; ; i ; I"ID or Symbol;T@ o; ;[ I"KYou can invoke methods directly, without parsing the string. First I ;TI"Fneed to explain about ID. ID is the integer number to represent ;TI"DRuby's identifiers such as variable names. The Ruby data type ;TI"Icorresponding to ID is Symbol. It can be accessed from Ruby in the ;TI" form:;T@ o;;[I":Identifier ;T;0o; ;[I"or;T@ o;;[I":"any kind of string" ;T;0o; ;[I"BYou can get the ID value from a string within C code by using;T@ o;;[I"!rb_intern(const char *name) ;TI" rb_intern_str(VALUE name) ;T;0o; ;[I"IYou can retrieve ID from Ruby object (Symbol or String) given as an ;TI"argument by using;T@ o;;[I" rb_to_id(VALUE symbol) ;TI"'rb_check_id(volatile VALUE *name) ;TI"Drb_check_id_cstr(const char *name, long len, rb_encoding *enc) ;T;0o; ;[ I"KThese functions try to convert the argument to a String if it was not ;TI"Fa Symbol nor a String. The second function stores the converted ;TI"Kresult into *name, and returns 0 if the string is not a known symbol. ;TI"FAfter this function returned a non-zero value, *name is always a ;TI"FSymbol or a String, otherwise it is a String if the result is 0. ;TI"FThe third function takes NUL-terminated C string, not Ruby VALUE.;T@ o; ;[I"JYou can retrieve Symbol from Ruby object (Symbol or String) given as ;TI"an argument by using;T@ o;;[I" rb_to_symbol(VALUE name) ;TI",rb_check_symbol(volatile VALUE *namep) ;TI"Grb_check_symbol_cstr(const char *ptr, long len, rb_encoding *enc) ;T;0o; ;[I"FThese functions are similar to above functions except that these ;TI"&return a Symbol instead of an ID.;T@ o; ;[I"1You can convert C ID to Ruby Symbol by using;T@ o;;[I"VALUE ID2SYM(ID id) ;T;0o; ;[I"1and to convert Ruby Symbol object to ID, use;T@ o;;[I" ID SYM2ID(VALUE symbol) ;T;0S; ; i ; I" Invoke Ruby method from C;T@ o; ;[I"?To invoke methods directly, you can use the function below;T@ o;;[I"9VALUE rb_funcall(VALUE recv, ID mid, int argc, ...) ;T;0o; ;[I"FThis function invokes a method on the recv, with the method name ;TI"!specified by the symbol mid.;T@ S; ; i ; I"*Accessing the variables and constants;T@ o; ;[I"HYou can access class variables and instance variables using access ;TI"Cfunctions. Also, global variables can be shared between both ;TI"Denvironments. There's no way to access Ruby's local variables.;T@ o; ;[I"AThe functions to access/modify instance variables are below:;T@ o;;[I")VALUE rb_ivar_get(VALUE obj, ID id) ;TI"4VALUE rb_ivar_set(VALUE obj, ID id, VALUE val) ;T;0o; ;[I"Bid must be the symbol, which can be retrieved by rb_intern().;T@ o; ;[I"1To access the constants of the class/module:;T@ o;;[I"*VALUE rb_const_get(VALUE obj, ID id) ;T;0o; ;[I"(See also Constant Definition above.;T@ S; ; i; I"+Information sharing between Ruby and C;T@ S; ; i; I"/Ruby constants that can be accessed from C;T@ o; ;[I" As stated in section 1.3, ;TI"9the following Ruby constants can be referred from C.;T@ o;;;;[o;;[I" Qtrue ;TI" Qfalse ;T;[o; ;[I"9Boolean values. Qfalse is false in C also (i.e. 0).;T@ o;;[I" Qnil ;T;[o; ;[I"Ruby nil in C scope.;T@ S; ; i; I"/Global variables shared between C and Ruby;T@ o; ;[I"PInformation can be shared between the two environments using shared global ;TI"Dvariables. To define them, you can use functions listed below:;T@ o;;[I";void rb_define_variable(const char *name, VALUE *var) ;T;0o; ;[I"NThis function defines the variable which is shared by both environments. ;TI"JThe value of the global variable pointed to by `var' can be accessed ;TI"1through Ruby's global variable named `name'.;T@ o; ;[I"IYou can define read-only (from Ruby, of course) variables using the ;TI"function below.;T@ o;;[I"Dvoid rb_define_readonly_variable(const char *name, VALUE *var) ;T;0o; ;[I"JYou can define hooked variables. The accessor functions (getter and ;TI":setter) are called on access to the hooked variables.;T@ o;;[I"Bvoid rb_define_hooked_variable(const char *name, VALUE *var, ;TI"I VALUE (*getter)(), void (*setter)()) ;T;0o; ;[I"JIf you need to supply either setter or getter, just supply 0 for the ;TI"Lhook you don't need. If both hooks are 0, rb_define_hooked_variable() ;TI"*works just like rb_define_variable().;T@ o; ;[I"FThe prototypes of the getter and setter functions are as follows:;T@ o;;[I")VALUE (*getter)(ID id, VALUE *var); ;TI"3void (*setter)(VALUE val, ID id, VALUE *var); ;T;0o; ;[I"JAlso you can define a Ruby global variable without a corresponding C ;TI"Hvariable. The value of the variable will be set/get only by hooks.;T@ o;;[I"7void rb_define_virtual_variable(const char *name, ;TI"J VALUE (*getter)(), void (*setter)()) ;T;0o; ;[I"FThe prototypes of the getter and setter functions are as follows:;T@ o;;[I" VALUE (*getter)(ID id); ;TI"'void (*setter)(VALUE val, ID id); ;T;0S; ; i; I"*Encapsulate C data into a Ruby object;T@ o; ;[ I"GSometimes you need to expose your struct in the C world as a Ruby ;TI" object. ;TI"EIn a situation like this, making use of the TypedData_XXX macro ;TI"Kfamily, the pointer to the struct and the Ruby object can be mutually ;TI"converted.;T@ S; ; i ; I" C struct to Ruby object;T@ o; ;[I"HYou can convert sval, a pointer to your struct, into a Ruby object ;TI"with the next macro.;T@ o;;[I"3TypedData_Wrap_Struct(klass, data_type, sval) ;T;0o; ;[I"FTypedData_Wrap_Struct() returns a created Ruby object as a VALUE.;T@ o; ;[I"GThe klass argument is the class for the object. The klass should ;TI"Fderive from rb_cObject, and the allocator must be set by calling ;TI"1rb_define_alloc_func or rb_undef_alloc_func.;T@ o; ;[I"Fdata_type is a pointer to a const rb_data_type_t which describes ;TI"'how Ruby should manage the struct.;T@ o; ;[I"Erb_data_type_t is defined like this. Let's take a look at each ;TI"member of the struct.;T@ o;;[I"8typedef struct rb_data_type_struct rb_data_type_t; ;TI" ;TI""struct rb_data_type_struct { ;TI"' const char *wrap_struct_name; ;TI" struct { ;TI"# void (*dmark)(void*); ;TI"# void (*dfree)(void*); ;TI", size_t (*dsize)(const void *); ;TI"& void (*dcompact)(void*); ;TI" void *reserved[1]; ;TI" } function; ;TI"' const rb_data_type_t *parent; ;TI" void *data; ;TI" VALUE flags; ;TI"}; ;T;0o; ;[ I"Gwrap_struct_name is an identifier of this instance of the struct. ;TI"BIt is basically used for collecting and emitting statistics. ;TI"GSo the identifier must be unique in the process, but doesn't need ;TI"+to be valid as a C or Ruby identifier.;T@ o; ;[I"HThese dmark / dfree functions are invoked during GC execution. No ;TI"Gobject allocations are allowed during it, so do not allocate ruby ;TI"objects inside them.;T@ o; ;[I"Idmark is a function to mark Ruby objects referred from your struct. ;TI"EIt must mark all references from your struct with rb_gc_mark or ;TI"5its family if your struct keeps such references.;T@ o; ;[I"9dfree is a function to free the pointer allocation. ;TI"BIf this is RUBY_DEFAULT_FREE, the pointer will be just freed.;T@ o; ;[ I"Adsize calculates memory consumption in bytes by the struct. ;TI"0Its parameter is a pointer to your struct. ;TI"IYou can pass 0 as dsize if it is hard to implement such a function. ;TI",But it is still recommended to avoid 0.;T@ o; ;[I"<dcompact is invoked when memory compaction took place. ;TI"DReferred Ruby objects that were marked by rb_gc_mark_movable() ;TI".can here be updated per rb_gc_location().;T@ o; ;[I"&You have to fill reserved with 0.;T@ o; ;[I"Hparent can point to another C type definition that the Ruby object ;TI"Eis inherited from. Then TypedData_Get_Struct() does also accept ;TI"derived objects.;T@ o; ;[I"?You can fill "data" with an arbitrary value for your use. ;TI"'Ruby does nothing with the member.;T@ o; ;[I"9flags is a bitwise-OR of the following flag values. ;TI"ISince they require deep understanding of garbage collector in Ruby, ;TI"5you can just set 0 to flags if you are not sure.;T@ o;;;;[o;;[I"!RUBY_TYPED_FREE_IMMEDIATELY ;T;[ o; ;[ I"FThis flag makes the garbage collector immediately invoke dfree() ;TI"1during GC when it need to free your struct. ;TI"AYou can specify this flag if the dfree never unlocks Ruby's ;TI"internal lock (GVL).;T@ o; ;[I"@If this flag is not set, Ruby defers invocation of dfree() ;TI"8and invokes dfree() at the same time as finalizers.;T@ o;;[I" RUBY_TYPED_WB_PROTECTED ;T;[ o; ;[I"IIt shows that implementation of the object supports write barriers. ;TI"GIf this flag is set, Ruby is better able to do garbage collection ;TI"of the object.;T@ o; ;[I"DWhen it is set, however, you are responsible for putting write ;TI"Bbarriers in all implementations of methods of that object as ;TI";appropriate. Otherwise Ruby might crash while running.;T@ o; ;[I"=More about write barriers can be found in {Generational ;TI"0GC}[rdoc-ref:@Appendix+D.+Generational+GC].;T@ o;;[I"!RUBY_TYPED_FROZEN_SHAREABLE ;T;[ o; ;[I"KThis flag indicates that the object is shareable object if the object ;TI"Kis frozen. See {Ractor support}[rdoc-ref:@Appendix+F.+Ractor+support] ;TI"more details.;T@ o; ;[I"DIf this flag is not set, the object can not become a shareable ;TI".object by Ractor.make_shareable() method.;T@ o; ;[I"INote that this macro can raise an exception. If sval to be wrapped ;TI"Kholds a resource needs to be released (e.g., allocated memory, handle ;TI"Ifrom an external library, and etc), you will have to use rb_protect.;T@ o; ;[I"BYou can allocate and wrap the structure in one step, in more ;TI"preferable manner.;T@ o;;[I"9TypedData_Make_Struct(klass, type, data_type, sval) ;T;0o; ;[I"LThis macro returns an allocated T_DATA object, wrapping the pointer to ;TI"Dthe structure, which is also allocated. This macro works like:;T@ o;;[I"J(sval = ZALLOC(type), TypedData_Wrap_Struct(klass, data_type, sval)) ;T;0o; ;[I"JHowever, you should use this macro instead of "allocation then wrap" ;TI"Klike the above code if it is simply allocated, because the latter can ;TI"Graise a NoMemoryError and sval will be memory leaked in that case.;T@ o; ;[I"CArguments klass and data_type work like their counterparts in ;TI"ITypedData_Wrap_Struct(). A pointer to the allocated structure will ;TI"Jbe assigned to sval, which should be a pointer of the type specified.;T@ S; ; i ; I"7Declaratively marking/compacting struct references;T@ o; ;[ I"RIn the case where your struct refers to Ruby objects that are simple values, ;TI"Pnot wrapped in conditional logic or complex data structures an alternative ;TI"Qapproach to marking and reference updating is provided, by declaring offset ;TI"-references to the VALUES in your struct.;T@ o; ;[I"NDoing this allows the Ruby GC to support marking these references and GC ;TI"Pcompaction without the need to define the +dmark+ and +dcompact+ callbacks.;T@ o; ;[I"PYou must define a static list of VALUE pointers to the offsets within your ;TI"Tstruct where the references are located, and set the "data" member to point to ;TI"Kthis reference list. The reference list must end with +RUBY_END_REFS+.;T@ o; ;[I"DSome Macros have been provided to make edge referencing easier:;T@ o;;;;[ o;;0;[o; ;[I"�<code>RUBY_TYPED_DECL_MARKING</code> =A flag that can be set on the +ruby_data_type_t+ to indicate that references are being declared as edges.;T@ o;;0;[o; ;[I"a<code>RUBY_REFERENCES(ref_list_name)</code> - Define _ref_list_name_ as a list of references;T@ o;;0;[o; ;[I"E<code>RUBY_REF_END</code> - The end mark of the references list.;T@ o;;0;[o; ;[I"�<code>RUBY_REF_EDGE(struct, member)</code> - Declare _member_ as a VALUE edge from _struct_. Use this after +RUBY_REFERENCES_START+;T@ o;;0;[o; ;[I"P+RUBY_REFS_LIST_PTR+ - Coerce the reference list into a format that can be ;TI"0accepted by the existing +dmark+ interface.;T@ o; ;[I"7The example below is from Dir (defined in +dir.c+);T@ o;;[ I"U// The struct being wrapped. Notice this contains 3 members of which the second ;TI"5// is a VALUE reference to another ruby object. ;TI"struct dir_data { ;TI" DIR *dir; ;TI" const VALUE path; ;TI" rb_encoding *enc; ;TI"} ;TI" ;TI"P// Define a reference list `dir_refs` containing a single entry to `path`. ;TI",// Needs terminating with RUBY_REF_END ;TI"#RUBY_REFERENCES(dir_refs) = { ;TI"( RUBY_REF_EDGE(dir_data, path), ;TI" RUBY_REF_END ;TI"}; ;TI" ;TI"O// Override the "dmark" field with the defined reference list now that we ;TI"Q// no longer need a marking callback and add RUBY_TYPED_DECL_MARKING to the ;TI"// flags field ;TI"3static const rb_data_type_t dir_data_type = { ;TI" "dir", ;TI"A {RUBY_REFS_LIST_PTR(dir_refs), dir_free, dir_memsize,}, ;TI"b 0, NULL, RUBY_TYPED_WB_PROTECTED | RUBY_TYPED_FREE_IMMEDIATELY | RUBY_TYPED_DECL_MARKING ;TI"}; ;T;0o; ;[I"TDeclaring simple references declaratively in this manner allows the GC to both ;TI"Umark, and move the underlying object, and automatically update the reference to ;TI"it during compaction.;T@ S; ; i ; I" Ruby object to C struct;T@ o; ;[I"ETo retrieve the C pointer from the T_DATA object, use the macro ;TI" TypedData_Get_Struct().;T@ o;;[I"7TypedData_Get_Struct(obj, type, &data_type, sval) ;T;0o; ;[I"FA pointer to the structure will be assigned to the variable sval.;T@ o; ;[I"'See the example below for details.;T@ S; ; i; I")Example - Creating the dbm Extension;T@ o; ;[I"IOK, here's the example of making an extension library. This is the ;TI"Hextension to access DBMs. The full source is included in the ext/ ;TI")directory in the Ruby's source tree.;T@ S; ; i; I"Make the directory;T@ o;;[I"% mkdir ext/dbm ;T;0o; ;[I"DMake a directory for the extension library under ext directory.;T@ S; ; i; I"Design the Library;T@ o; ;[I"?You need to design the library features, before making it.;T@ S; ; i; I"Write the C Code;T@ o; ;[ I"KYou need to write C code for your extension library. If your library ;TI"Hhas only one source file, choosing ``LIBRARY.c'' as a file name is ;TI"Mpreferred. On the other hand, in case your library has multiple source ;TI"Kfiles, avoid choosing ``LIBRARY.c'' for a file name. It may conflict ;TI"@with an intermediate file ``LIBRARY.o'' on some platforms. ;TI"GNote that some functions in mkmf library described below generate ;TI"Ia file ``conftest.c'' for checking with compilation. You shouldn't ;TI"6choose ``conftest.c'' as a name of a source file.;T@ o; ;[I"KRuby will execute the initializing function named ``Init_LIBRARY'' in ;TI"Mthe library. For example, ``Init_dbm()'' will be executed when loading ;TI"the library.;T@ o; ;[I"4Here's the example of an initializing function.;T@ o;;[ I"#include <ruby.h> ;TI" void ;TI"Init_dbm(void) ;TI"{ ;TI" /* define DBM class */ ;TI": VALUE cDBM = rb_define_class("DBM", rb_cObject); ;TI"" /* Redefine DBM.allocate ;TI"1 rb_define_alloc_func(cDBM, fdbm_alloc); ;TI". /* DBM includes Enumerable module */ ;TI"2 rb_include_module(cDBM, rb_mEnumerable); ;TI" ;TI"N /* DBM has class method open(): arguments are received as C array */ ;TI"D rb_define_singleton_method(cDBM, "open", fdbm_s_open, -1); ;TI" ;TI"4 /* DBM instance method close(): no args */ ;TI"9 rb_define_method(cDBM, "close", fdbm_close, 0); ;TI"2 /* DBM instance method []: 1 argument */ ;TI"5 rb_define_method(cDBM, "[]", fdbm_aref, 1); ;TI" ;TI" /* ... */ ;TI" ;TI"< /* ID for a instance variable to store DBM data */ ;TI"$ id_dbm = rb_intern("dbm"); ;TI"} ;T;0o; ;[I"GThe dbm extension wraps the dbm struct in the C environment using ;TI"TypedData_Make_Struct.;T@ o;;[I"struct dbmdata { ;TI" int di_size; ;TI" DBM *di_dbm; ;TI"}; ;TI" ;TI".static const rb_data_type_t dbm_type = { ;TI" "dbm", ;TI"& {0, free_dbm, memsize_dbm,}, ;TI" 0, 0, ;TI"& RUBY_TYPED_FREE_IMMEDIATELY, ;TI"}; ;TI" ;TI"static VALUE ;TI" fdbm_alloc(VALUE klass) ;TI"{ ;TI" struct dbmdata *dbmp; ;TI"S /* Allocate T_DATA object and C struct and fill struct with zero bytes */ ;TI"O return TypedData_Make_Struct(klass, struct dbmdata, &dbm_type, dbmp); ;TI"} ;T;0o; ;[ I"IThis code wraps the dbmdata structure into a Ruby object. We avoid ;TI"Hwrapping DBM* directly, because we want to cache size information. ;TI"HSince Object.allocate allocates an ordinary T_OBJECT type (instead ;TI"Hof T_DATA), it's important to either use rb_define_alloc_func() to ;TI"8overwrite it or rb_undef_alloc_func() to delete it.;T@ o; ;[I"ITo retrieve the dbmdata structure from a Ruby object, we define the ;TI"following macro:;T@ o;;[ I"%#define GetDBM(obj, dbmp) do {\ ;TI"J TypedData_Get_Struct((obj), struct dbmdata, &dbm_type, (dbmp));\ ;TI") if ((dbmp) == 0) closed_dbm();\ ;TI"1 if ((dbmp)->di_dbm == 0) closed_dbm();\ ;TI"} while (0) ;T;0o; ;[I"KThis sort of complicated macro does the retrieving and close checking ;TI"for the DBM.;T@ o; ;[I"GThere are three kinds of way to receive method arguments. First, ;TI"Jmethods with a fixed number of arguments receive arguments like this:;T@ o;;[I"static VALUE ;TI"(fdbm_aref(VALUE obj, VALUE keystr) ;TI"{ ;TI" struct dbmdata *dbmp; ;TI" GetDBM(obj, dbmp); ;TI"* /* Use dbmp to access the key */ ;TI"; dbm_fetch(dbmp->di_dbm, StringValueCStr(keystr)); ;TI" /* ... */ ;TI"} ;T;0o; ;[I"HThe first argument of the C function is the self, the rest are the ;TI" arguments to the method.;T@ o; ;[I"CSecond, methods with an arbitrary number of arguments receive ;TI"arguments like this:;T@ o;;[I"static VALUE ;TI"5fdbm_s_open(int argc, VALUE *argv, VALUE klass) ;TI"{ ;TI" /* ... */ ;TI"C if (rb_scan_args(argc, argv, "11", &file, &vmode) == 1) { ;TI"7 mode = 0666; /* default value */ ;TI" } ;TI" /* ... */ ;TI"} ;T;0o; ;[I"FThe first argument is the number of method arguments, the second ;TI"Dargument is the C array of the method arguments, and the third ;TI",argument is the receiver of the method.;T@ o; ;[ I"GYou can use the function rb_scan_args() to check and retrieve the ;TI"Farguments. The third argument is a string that specifies how to ;TI"Ecapture method arguments and assign them to the following VALUE ;TI"references.;T@ o; ;[I"KYou can just check the argument number with rb_check_arity(), this is ;TI"Ahandy in the case you want to treat the arguments as a list.;T@ o; ;[I"LThe following is an example of a method that takes arguments by Ruby's ;TI" array:;T@ o;;[ I"static VALUE ;TI"1thread_initialize(VALUE thread, VALUE args) ;TI"{ ;TI" /* ... */ ;TI"} ;T;0o; ;[I"JThe first argument is the receiver, the second one is the Ruby array ;TI"0which contains the arguments to the method.;T@ o; ;[I"Y<b>Notice</b>: GC should know about global variables which refer to Ruby's objects, ;TI"Ibut are not exported to the Ruby world. You need to protect them by;T@ o;;[I")void rb_global_variable(VALUE *var) ;T;0o; ;[I"!or the objects themselves by;T@ o;;[I"3void rb_gc_register_mark_object(VALUE object) ;T;0S; ; i; I"Prepare extconf.rb;T@ o; ;[I"JIf the file named extconf.rb exists, it will be executed to generate ;TI"Makefile.;T@ o; ;[I"Jextconf.rb is the file for checking compilation conditions etc. You ;TI"need to put;T@ o;;[I"require 'mkmf' ;T;0o; ;[I"Gat the top of the file. You can use the functions below to check ;TI"various conditions.;T@ o;;[I"Uappend_cppflags(array-of-flags[, opt]): append each flag to $CPPFLAGS if usable ;TI"Qappend_cflags(array-of-flags[, opt]): append each flag to $CFLAGS if usable ;TI"Sappend_ldflags(array-of-flags[, opt]): append each flag to $LDFLAGS if usable ;TI"Ihave_macro(macro[, headers[, opt]]): check whether macro is defined ;TI"chave_library(lib[, func[, headers[, opt]]]): check whether library containing function exists ;TI"@find_library(lib[, func, *paths]): find library from paths ;TI"Ehave_func(func[, headers[, opt]): check whether function exists ;TI"Dhave_var(var[, headers[, opt]]): check whether variable exists ;TI"Phave_header(header[, preheaders[, opt]]): check whether header file exists ;TI"9find_header(header, *paths): find header from paths ;TI"Fhave_framework(fw): check whether framework exists (for MacOS X) ;TI"Yhave_struct_member(type, member[, headers[, opt]]): check whether struct has member ;TI"Bhave_type(type[, headers[, opt]]): check whether type exists ;TI"Jfind_type(type, opt, *headers): check whether type exists in headers ;TI"Lhave_const(const[, headers[, opt]]): check whether constant is defined ;TI"?check_sizeof(type[, headers[, opts]]): check size of type ;TI"Icheck_signedness(type[, headers[, opts]]): check signedness of type ;TI"Mconvertible_int(type[, headers[, opts]]): find convertible integer type ;TI"=find_executable(bin[, path]): find executable file path ;TI"7create_header(header): generate configured header ;TI"Acreate_makefile(target[, target_prefix]): generate Makefile ;T;0o; ;[I"@See MakeMakefile for full documentation of these functions.;T@ o; ;[I"?The value of the variables below will affect the Makefile.;T@ o;;[ I"<$CFLAGS: included in CFLAGS make variable (such as -O) ;TI"D$CPPFLAGS: included in CPPFLAGS make variable (such as -I, -D) ;TI">$LDFLAGS: included in LDFLAGS make variable (such as -L) ;TI"&$objs: list of object file names ;T;0o; ;[I"DCompiler/linker flags are not portable usually, you should use ;TI"K+append_cppflags+, +append_cpflags+ and +append_ldflags+ respectively ;TI"7instead of appending the above variables directly.;T@ o; ;[I"MNormally, the object files list is automatically generated by searching ;TI"Ksource files, but you must define them explicitly if any sources will ;TI"!be generated while building.;T@ o; ;[I"FIf a compilation condition is not fulfilled, you should not call ;TI"P``create_makefile''. The Makefile will not be generated, compilation will ;TI"not be done.;T@ S; ; i; I" Prepare depend (Optional);T@ o; ;[I"IIf the file named depend exists, Makefile will include that file to ;TI"<check dependencies. You can make this file by invoking;T@ o;;[I" % gcc -MM *.c > depend ;T;0o; ;[I" It's harmless. Prepare it.;T@ S; ; i; I"Generate Makefile;T@ o; ;[I"$Try generating the Makefile by:;T@ o;;[I"ruby extconf.rb ;T;0o; ;[I"DIf the library should be installed under vendor_ruby directory ;TI"Dinstead of site_ruby directory, use --vendor option as follows.;T@ o;;[I" ruby extconf.rb --vendor ;T;0o; ;[I"MYou don't need this step if you put the extension library under the ext ;TI"Jdirectory of the ruby source tree. In that case, compilation of the ;TI"+interpreter will do this step for you.;T@ S; ; i; I" Run make;T@ o; ;[I" Type;T@ o;;[I" make ;T;0o; ;[I"Mto compile your extension. You don't need this step either if you have ;TI"Oput the extension library under the ext directory of the ruby source tree.;T@ S; ; i; I" Debug;T@ o; ;[I"GYou may need to rb_debug the extension. Extensions can be linked ;TI"Kstatically by adding the directory name in the ext/Setup file so that ;TI"5you can inspect the extension with the debugger.;T@ S; ; i; I"-Done! Now you have the extension library;T@ o; ;[I"IYou can do anything you want with your library. The author of Ruby ;TI"Mwill not claim any restrictions on your code depending on the Ruby API. ;TI"?Feel free to use, modify, distribute or sell your program.;T@ S; ; i; I"6Appendix A. Ruby header and source files overview;T@ S; ; i; I"Ruby header files;T@ o; ;[ I"IEverything under <tt>$repo_root/include/ruby</tt> is installed with ;TI" <tt>make install</tt>. ;TI"MIt should be included per <tt>#include <ruby.h></tt> from C extensions. ;TI"LAll symbols are public API with the exception of symbols prefixed with ;TI"K+rbimpl_+ or +RBIMPL_+. They are implementation details and shouldn't ;TI" be used by C extensions.;T@ o; ;[I"JOnly <tt>$repo_root/include/ruby/*.h</tt> whose corresponding macros ;TI"Fare defined in the <tt>$repo_root/include/ruby.h</tt> header are ;TI"7allowed to be <tt>#include</tt>-d by C extensions.;T@ o; ;[I"LHeader files under <tt>$repo_root/internal/</tt> or directly under the ;TI":root <tt>$repo_root/*.h</tt> are not make-installed. ;TI"7They are internal headers with only internal APIs.;T@ S; ; i; I"Ruby language core;T@ o;;;;[ o;;[I"class.c ;T;[o; ;[I"classes and modules;To;;[I"error.c ;T;[o; ;[I".exception classes and exception mechanism;To;;[I"gc.c ;T;[o; ;[I"memory management;To;;[I"load.c ;T;[o; ;[I"library loading;To;;[I"object.c ;T;[o; ;[I" objects;To;;[I"variable.c ;T;[o; ;[I" variables and constants;T@ S; ; i; I"Ruby syntax parser;T@ o;;;;[ o;;[I"parse.y ;T;[o; ;[I"grammar definition;To;;[I"parse.c ;T;[o; ;[I")automatically generated from parse.y;To;;[I"defs/keywords ;T;[o; ;[I"reserved keywords;To;;[I"lex.c ;T;[o; ;[I"*automatically generated from keywords;T@ S; ; i; I"!Ruby evaluator (a.k.a. YARV);T@ o;;[ I"compile.c ;TI" eval.c ;TI"eval_error.c ;TI"eval_jump.c ;TI"eval_safe.c ;TI"9insns.def : definition of VM instructions ;TI"6iseq.c : implementation of VM::ISeq ;TI"Cthread.c : thread management and context switching ;TI"1thread_win32.c : thread implementation ;TI"!thread_pthread.c : ditto ;TI" vm.c ;TI"vm_dump.c ;TI"vm_eval.c ;TI"vm_exec.c ;TI"vm_insnhelper.c ;TI"vm_method.c ;TI" ;TI"8defs/opt_insns_unif.def : instruction unification ;TI"=defs/opt_operand.def : definitions for optimization ;TI" ;TI"8 -> insn*.inc : automatically generated ;TI"8 -> opt*.inc : automatically generated ;TI"8 -> vm.inc : automatically generated ;T;0S; ; i; I"(Regular expression engine (Onigumo);T@ o;;[ I"regcomp.c ;TI"regenc.c ;TI"regerror.c ;TI"regexec.c ;TI"regparse.c ;TI"regsyntax.c ;T;0S; ; i; I"Utility functions;T@ o;;;;[ o;;[I"debug.c ;T;[o; ;[I"!debug symbols for C debugger;To;;[I"dln.c ;T;[o; ;[I"dynamic loading;To;;[I"st.c ;T;[o; ;[I" general purpose hash table;To;;[I"strftime.c ;T;[o; ;[I"formatting times;To;;[I"util.c ;T;[o; ;[I"misc utilities;T@ S; ; i; I"$Ruby interpreter implementation;T@ o;;[I"dmyext.c ;TI"dmydln.c ;TI"dmyencoding.c ;TI" id.c ;TI" inits.c ;TI" main.c ;TI" ruby.c ;TI"version.c ;TI" ;TI"gem_prelude.rb ;TI"prelude.rb ;T;0S; ; i; I"Class library;T@ o;;;;[!o;;[I"array.c ;T;[o; ;[I" Array;To;;[I"bignum.c ;T;[o; ;[I" Bignum;To;;[I"compar.c ;T;[o; ;[I"Comparable;To;;[I"complex.c ;T;[o; ;[I" Complex;To;;[I"cont.c ;T;[o; ;[I"Fiber, Continuation;To;;[I"dir.c ;T;[o; ;[I"Dir;To;;[I"enum.c ;T;[o; ;[I"Enumerable;To;;[I"enumerator.c ;T;[o; ;[I"Enumerator;To;;[I"file.c ;T;[o; ;[I" File;To;;[I"hash.c ;T;[o; ;[I" Hash;To;;[I"io.c ;T;[o; ;[I"IO;To;;[I"marshal.c ;T;[o; ;[I" Marshal;To;;[I"math.c ;T;[o; ;[I" Math;To;;[I"numeric.c ;T;[o; ;[I"$Numeric, Integer, Fixnum, Float;To;;[I"pack.c ;T;[o; ;[I" Array#pack, String#unpack;To;;[I"proc.c ;T;[o; ;[I"Binding, Proc;To;;[I"process.c ;T;[o; ;[I" Process;To;;[I"random.c ;T;[o; ;[I"random number;To;;[I"range.c ;T;[o; ;[I" Range;To;;[I"rational.c ;T;[o; ;[I" Rational;To;;[I"re.c ;T;[o; ;[I"Regexp, MatchData;To;;[I"signal.c ;T;[o; ;[I" Signal;To;;[I"sprintf.c ;T;[o; ;[I"String#sprintf;To;;[I"string.c ;T;[o; ;[I" String;To;;[I"struct.c ;T;[o; ;[I" Struct;To;;[I"time.c ;T;[o; ;[I" Time;T@ o;;[I"defs/known_errors.def ;T;[o; ;[I" Errno::* exception classes;To;;[I"-> known_errors.inc ;T;[o; ;[I" automatically generated;T@ S; ; i; I"Multilingualization;T@ o;;;;[ o;;[I"encoding.c ;T;[o; ;[I" Encoding;To;;[I"transcode.c ;T;[o; ;[I"Encoding::Converter;To;;[I"enc/*.c ;T;[o; ;[I"encoding classes;To;;[I"enc/trans/* ;T;[o; ;[I" codepoint mapping tables;T@ S; ; i; I"&goruby interpreter implementation;T@ o;;[I"goruby.c ;TI"6golf_prelude.rb : goruby specific libraries. ;TI"3 -> golf_prelude.c : automatically generated ;T;0S; ; i; I"-Appendix B. Ruby extension API reference;T@ S; ; i; I" Types;T@ o;;;;[o;;[I" VALUE ;T;[o; ;[I"MThe type for the Ruby object. Actual structures are defined in ruby.h, ;TI"Jsuch as struct RString, etc. To refer the values in structures, use ;TI"&casting macros like RSTRING(obj).;T@ S; ; i; I" Variables and constants;T@ o;;;;[o;;[I" Qnil ;T;[o; ;[I"nil object;T@ o;;[I" Qtrue ;T;[o; ;[I"%true object (default true value);T@ o;;[I" Qfalse ;T;[o; ;[I"false object;T@ S; ; i; I"C pointer wrapping;T@ o;;;;[o;;[I"OData_Wrap_Struct(VALUE klass, void (*mark)(), void (*free)(), void *sval) ;T;[o; ;[ I"MWrap a C pointer into a Ruby object. If object has references to other ;TI"KRuby objects, they should be marked by using the mark function during ;TI"Kthe GC process. Otherwise, mark should be 0. When this object is no ;TI"Hlonger referred by anywhere, the pointer will be discarded by free ;TI"function.;T@ o;;[I"5Data_Make_Struct(klass, type, mark, free, sval) ;T;[o; ;[I"LThis macro allocates memory using malloc(), assigns it to the variable ;TI"Ksval, and returns the DATA encapsulating the pointer to memory region.;T@ o;;[I"'Data_Get_Struct(data, type, sval) ;T;[o; ;[I"IThis macro retrieves the pointer value from DATA, and assigns it to ;TI"the variable sval.;T@ S; ; i; I"Checking VALUE types;T@ o;;;;[ o;;[I" RB_TYPE_P(value, type) ;T;[o; ;[I"9Is +value+ an internal type (T_NIL, T_FIXNUM, etc.)?;T@ o;;[I"TYPE(value) ;T;[o; ;[I"*Internal type (T_NIL, T_FIXNUM, etc.);T@ o;;[I"FIXNUM_P(value) ;T;[o; ;[I"Is +value+ a Fixnum?;T@ o;;[I"NIL_P(value) ;T;[o; ;[I"Is +value+ nil?;T@ o;;[I" RB_INTEGER_TYPE_P(value) ;T;[o; ;[I"Is +value+ an Integer?;T@ o;;[I" RB_FLOAT_TYPE_P(value) ;T;[o; ;[I"Is +value+ a Float?;T@ o;;[I",void Check_Type(VALUE value, int type) ;T;[o; ;[I"JEnsures +value+ is of the given internal +type+ or raises a TypeError;T@ S; ; i; I"VALUE type conversion;T@ o;;;;[o;;[I" FIX2INT(value), INT2FIX(i) ;T;[o; ;[I"Fixnum <-> integer;T@ o;;[I""FIX2LONG(value), LONG2FIX(l) ;T;[o; ;[I"Fixnum <-> long;T@ o;;[I" NUM2INT(value), INT2NUM(i) ;T;[o; ;[I"Numeric <-> integer;T@ o;;[I"#NUM2UINT(value), UINT2NUM(ui) ;T;[o; ;[I"!Numeric <-> unsigned integer;T@ o;;[I""NUM2LONG(value), LONG2NUM(l) ;T;[o; ;[I"Numeric <-> long;T@ o;;[I"%NUM2ULONG(value), ULONG2NUM(ul) ;T;[o; ;[I" Numeric <-> unsigned long;T@ o;;[I" NUM2LL(value), LL2NUM(ll) ;T;[o; ;[I"Numeric <-> long long;T@ o;;[I""NUM2ULL(value), ULL2NUM(ull) ;T;[o; ;[I"#Numeric <-> unsigned long long;T@ o;;[I"$NUM2OFFT(value), OFFT2NUM(off) ;T;[o; ;[I"Numeric <-> off_t;T@ o;;[I"'NUM2SIZET(value), SIZET2NUM(size) ;T;[o; ;[I"Numeric <-> size_t;T@ o;;[I"*NUM2SSIZET(value), SSIZET2NUM(ssize) ;T;[o; ;[I"Numeric <-> ssize_t;T@ o;;[I"|rb_integer_pack(value, words, numwords, wordsize, nails, flags), rb_integer_unpack(words, numwords, wordsize, nails, flags) ;T;[o; ;[I".Numeric <-> Arbitrary size integer buffer;T@ o;;[I"NUM2DBL(value) ;T;[o; ;[I"Numeric -> double;T@ o;;[I"rb_float_new(f) ;T;[o; ;[I"double -> Float;T@ o;;[I"RSTRING_LEN(str) ;T;[o; ;[I"-String -> length of String data in bytes;T@ o;;[I"RSTRING_PTR(str) ;T;[o; ;[I"&String -> pointer to String data ;TI";Note that the result pointer may not be NUL-terminated;T@ o;;[I"StringValue(value) ;T;[o; ;[I"#Object with \#to_str -> String;T@ o;;[I"StringValuePtr(value) ;T;[o; ;[I"3Object with \#to_str -> pointer to String data;T@ o;;[I" StringValueCStr(value) ;T;[o; ;[I"FObject with \#to_str -> pointer to String data without NUL bytes ;TI"<It is guaranteed that the result data is NUL-terminated;T@ o;;[I"rb_str_new2(s) ;T;[o; ;[I"char * -> String;T@ S; ; i; I"!Defining classes and modules;T@ o;;;;[ o;;[I":VALUE rb_define_class(const char *name, VALUE super) ;T;[o; ;[I"5Defines a new Ruby class as a subclass of super.;T@ o;;[I"NVALUE rb_define_class_under(VALUE module, const char *name, VALUE super) ;T;[o; ;[I"ICreates a new Ruby class as a subclass of super, under the module's ;TI"namespace.;T@ o;;[I".VALUE rb_define_module(const char *name) ;T;[o; ;[I" Defines a new Ruby module.;T@ o;;[I"BVALUE rb_define_module_under(VALUE module, const char *name) ;T;[o; ;[I"<Defines a new Ruby module under the module's namespace.;T@ o;;[I"7void rb_include_module(VALUE klass, VALUE module) ;T;[o; ;[I"MIncludes module into class. If class already includes it, just ignored.;T@ o;;[I"7void rb_extend_object(VALUE object, VALUE module) ;T;[o; ;[I"4Extend the object with the module's attributes.;T@ S; ; i; I" Defining global variables;T@ o;;;;[ o;;[I";void rb_define_variable(const char *name, VALUE *var) ;T;[o; ;[I"LDefines a global variable which is shared between C and Ruby. If name ;TI"Icontains a character which is not allowed to be part of the symbol, ;TI")it can't be seen from Ruby programs.;T@ o;;[I"Dvoid rb_define_readonly_variable(const char *name, VALUE *var) ;T;[o; ;[I";Defines a read-only global variable. Works just like ;TI"Drb_define_variable(), except the defined variable is read-only.;T@ o;;[I"\void rb_define_virtual_variable(const char *name, VALUE (*getter)(), void (*setter)()) ;T;[ o; ;[ I"JDefines a virtual variable, whose behavior is defined by a pair of C ;TI"Dfunctions. The getter function is called when the variable is ;TI"Nreferenced. The setter function is called when the variable is set to a ;TI";value. The prototype for getter/setter functions are:;T@ o;;[I"VALUE getter(ID id) ;TI"#void setter(VALUE val, ID id) ;T;0o; ;[I">The getter function must return the value for the access.;T@ o;;[I"gvoid rb_define_hooked_variable(const char *name, VALUE *var, VALUE (*getter)(), void (*setter)()) ;T;[ o; ;[I"JDefines hooked variable. It's a virtual variable with a C variable. ;TI" The getter is called as;T@ o;;[I"%VALUE getter(ID id, VALUE *var) ;T;0o; ;[I"4returning a new value. The setter is called as;T@ o;;[I"/void setter(VALUE val, ID id, VALUE *var) ;T;0o;;[I")void rb_global_variable(VALUE *var) ;T;[o; ;[I"PTells GC to protect C global variable, which holds Ruby value to be marked.;T@ o;;[I"3void rb_gc_register_mark_object(VALUE object) ;T;[o; ;[I"LTells GC to protect the +object+, which may not be referenced anywhere.;T@ S; ; i; I"Constant definition;T@ o;;;;[o;;[I"Dvoid rb_define_const(VALUE klass, const char *name, VALUE val) ;T;[o; ;[I"3Defines a new constant under the class/module.;T@ o;;[I">void rb_define_global_const(const char *name, VALUE val) ;T;[o; ;[I"9Defines a global constant. This is just the same as;T@ o;;[I",rb_define_const(rb_cObject, name, val) ;T;0S; ; i; I"Method definition;T@ o;;;;[ o;;[I"Wrb_define_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ;T;[o; ;[ I"JDefines a method for the class. func is the function pointer. argc ;TI"Kis the number of arguments. if argc is -1, the function will receive ;TI"J3 arguments: argc, argv, and self. if argc is -2, the function will ;TI"Greceive 2 arguments, self and args, where args is a Ruby array of ;TI"the method arguments.;T@ o;;[I"_rb_define_private_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ;T;[o; ;[I"DDefines a private method for the class. Arguments are same as ;TI"rb_define_method().;T@ o;;[I"arb_define_singleton_method(VALUE klass, const char *name, VALUE (*func)(ANYARGS), int argc) ;T;[o; ;[I"KDefines a singleton method. Arguments are same as rb_define_method().;T@ o;;[I"0rb_check_arity(int argc, int min, int max) ;T;[o; ;[I"JCheck the number of arguments, argc is in the range of min..max. If ;TI"Imax is UNLIMITED_ARGUMENTS, upper bound is not checked. If argc is ;TI"4out of bounds, an ArgumentError will be raised.;T@ o;;[I"?rb_scan_args(int argc, VALUE *argv, const char *fmt, ...) ;T;[ o; ;[I"DRetrieve argument from argc and argv to given VALUE references ;TI"Jaccording to the format string. The format can be described in ABNF ;TI"as follows:;T@ o;;[!I"Jscan-arg-spec := param-arg-spec [keyword-arg-spec] [block-arg-spec] ;TI" ;TI"Fparam-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec / ;TI"- pre-opt-post-arg-spec ;TI"Lpre-arg-spec := num-of-leading-mandatory-args [num-of-optional-args] ;TI"4post-arg-spec := sym-for-variable-length-args ;TI"8 [num-of-trailing-mandatory-args] ;TI"Qpre-opt-post-arg-spec := num-of-leading-mandatory-args num-of-optional-args ;TI"= num-of-trailing-mandatory-args ;TI"-keyword-arg-spec := sym-for-keyword-arg ;TI")block-arg-spec := sym-for-block-arg ;TI" ;TI"Enum-of-leading-mandatory-args := DIGIT ; The number of leading ;TI"C ; mandatory arguments ;TI"Fnum-of-optional-args := DIGIT ; The number of optional ;TI"9 ; arguments ;TI"Gsym-for-variable-length-args := "*" ; Indicates that variable ;TI"D ; length arguments are ;TI"H ; captured as a ruby array ;TI"Fnum-of-trailing-mandatory-args := DIGIT ; The number of trailing ;TI"C ; mandatory arguments ;TI"Fsym-for-keyword-arg := ":" ; Indicates that keyword ;TI"L ; argument captured as a hash. ;TI"L ; If keyword arguments are not ;TI"F ; provided, returns nil. ;TI"Jsym-for-block-arg := "&" ; Indicates that an iterator ;TI"K ; block should be captured if ;TI"5 ; given ;T;0o; ;[ I"CFor example, "12" means that the method requires at least one ;TI"Kargument, and at most receives three (1+2) arguments. So, the format ;TI"Kstring must be followed by three variable references, which are to be ;TI"Kassigned to captured arguments. For omitted arguments, variables are ;TI"Kset to Qnil. NULL can be put in place of a variable reference, which ;TI"Imeans the corresponding captured argument(s) should be just dropped.;T@ o; ;[I"IThe number of given arguments, excluding an option hash or iterator ;TI"block, is returned.;T@ o;;[I"Prb_scan_args_kw(int kw_splat, int argc, VALUE *argv, const char *fmt, ...) ;T;[o; ;[ I"RThe same as +rb_scan_args+, except the +kw_splat+ argument specifies whether ;TI"Mkeyword arguments are provided (instead of being determined by the call ;TI"Mfrom Ruby to the C function). +kw_splat+ should be one of the following ;TI" values:;T@ o;;;;[o;;[I"'RB_SCAN_ARGS_PASS_CALLED_KEYWORDS ;T;[o; ;[I"%Same behavior as +rb_scan_args+.;To;;[I"RB_SCAN_ARGS_KEYWORDS ;T;[o; ;[I"4The final argument should be a hash treated as ;TI"keywords.;To;;[I"%RB_SCAN_ARGS_LAST_HASH_KEYWORDS ;T;[o; ;[I".Treat a final argument as keywords if it ;TI".is a hash, and not as keywords otherwise.;T@ o;;[I"gint rb_get_kwargs(VALUE keyword_hash, const ID *table, int required, int optional, VALUE *values) ;T;[ o; ;[I"LRetrieves argument VALUEs bound to keywords, which directed by +table+ ;TI"Iinto +values+, deleting retrieved entries from +keyword_hash+ along ;TI"Fthe way. First +required+ number of IDs referred by +table+ are ;TI"?mandatory, and succeeding +optional+ (- +optional+ - 1 if ;TI"?+optional+ is negative) number of IDs are optional. If a ;TI"Gmandatory key is not contained in +keyword_hash+, raises "missing ;TI"Ekeyword" +ArgumentError+. If an optional key is not present in ;TI"O+keyword_hash+, the corresponding element in +values+ is set to +Qundef+. ;TI"NIf +optional+ is negative, rest of +keyword_hash+ are ignored, otherwise ;TI".raises "unknown keyword" +ArgumentError+.;T@ o; ;[ I"JBe warned, handling keyword arguments in the C API is less efficient ;TI"Gthan handling them in Ruby. Consider using a Ruby wrapper method ;TI"&around a non-keyword C function. ;TI"1ref: https://bugs.ruby-lang.org/issues/11339;T@ o;;[I"5VALUE rb_extract_keywords(VALUE *original_hash) ;T;[o; ;[ I"FExtracts pairs whose key is a symbol into a new hash from a hash ;TI"Hobject referred by +original_hash+. If the original hash contains ;TI"Lnon-symbol keys, then they are copied to another hash and the new hash ;TI"9is stored through +original_hash+, else 0 is stored.;T@ S; ; i; I"Invoking Ruby method;T@ o;;;;[o;;[I"9VALUE rb_funcall(VALUE recv, ID mid, int narg, ...) ;T;[o; ;[I"MInvokes a method. To retrieve mid from a method name, use rb_intern(). ;TI"1Able to call even private/protected methods.;T@ o;;[I"BVALUE rb_funcall2(VALUE recv, ID mid, int argc, VALUE *argv) ;TI"BVALUE rb_funcallv(VALUE recv, ID mid, int argc, VALUE *argv) ;T;[o; ;[I"@Invokes a method, passing arguments as an array of values. ;TI"1Able to call even private/protected methods.;T@ o;;[I"SVALUE rb_funcallv_kw(VALUE recv, ID mid, int argc, VALUE *argv, int kw_splat) ;T;[o; ;[I"HSame as rb_funcallv, using +kw_splat+ to determine whether keyword ;TI"arguments are passed.;T@ o;;[I"IVALUE rb_funcallv_public(VALUE recv, ID mid, int argc, VALUE *argv) ;T;[o; ;[I"@Invokes a method, passing arguments as an array of values. ;TI"&Able to call only public methods.;T@ o;;[I"ZVALUE rb_funcallv_public_kw(VALUE recv, ID mid, int argc, VALUE *argv, int kw_splat) ;T;[o; ;[I"OSame as rb_funcallv_public, using +kw_splat+ to determine whether keyword ;TI"arguments are passed.;T@ o;;[I"UVALUE rb_funcall_passing_block(VALUE recv, ID mid, int argc, const VALUE* argv) ;T;[o; ;[I"PSame as rb_funcallv_public, except is passes the currently active block as ;TI"'the block when calling the method.;T@ o;;[I"fVALUE rb_funcall_passing_block_kw(VALUE recv, ID mid, int argc, const VALUE* argv, int kw_splat) ;T;[o; ;[I"MSame as rb_funcall_passing_block, using +kw_splat+ to determine whether ;TI""keyword arguments are passed.;T@ o;;[I"hVALUE rb_funcall_with_block(VALUE recv, ID mid, int argc, const VALUE *argv, VALUE passed_procval) ;T;[o; ;[I"PSame as rb_funcallv_public, except +passed_procval+ specifies the block to ;TI"pass to the method.;T@ o;;[I"yVALUE rb_funcall_with_block_kw(VALUE recv, ID mid, int argc, const VALUE *argv, VALUE passed_procval, int kw_splat) ;T;[o; ;[I"JSame as rb_funcall_with_block, using +kw_splat+ to determine whether ;TI""keyword arguments are passed.;T@ o;;[I"+VALUE rb_eval_string(const char *str) ;T;[o; ;[I"8Compiles and executes the string as a Ruby program.;T@ o;;[I"$ID rb_intern(const char *name) ;T;[o; ;[I"*Returns ID corresponding to the name.;T@ o;;[I" char *rb_id2name(ID id) ;T;[o; ;[I"'Returns the name corresponding ID.;T@ o;;[I"&char *rb_class2name(VALUE klass) ;T;[o; ;[I"#Returns the name of the class.;T@ o;;[I")int rb_respond_to(VALUE obj, ID id) ;T;[o; ;[I"HReturns true if the object responds to the message specified by id.;T@ S; ; i; I"Instance variables;T@ o;;;;[o;;[I"2VALUE rb_iv_get(VALUE obj, const char *name) ;T;[o; ;[I"FRetrieve the value of the instance variable. If the name is not ;TI"Dprefixed by `@', that variable shall be inaccessible from Ruby.;T@ o;;[I"=VALUE rb_iv_set(VALUE obj, const char *name, VALUE val) ;T;[o; ;[I"-Sets the value of the instance variable.;T@ S; ; i; I"Control structure;T@ o;;;;[o;;[I"kVALUE rb_block_call(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2) ;T;[o; ;[ I"GCalls a method on the recv, with the method name specified by the ;TI"Dsymbol mid, with argc arguments in argv, supplying func as the ;TI"Hblock. When func is called as the block, it will receive the value ;TI"Ifrom yield as the first argument, and data2 as the second argument. ;TI"AWhen yielded with multiple values (in C, rb_yield_values(), ;TI"Lrb_yield_values2() and rb_yield_splat()), data2 is packed as an Array, ;TI"Lwhereas yielded values can be gotten via argc/argv of the third/fourth ;TI"arguments.;T@ o;;[I"|VALUE rb_block_call_kw(VALUE recv, ID mid, int argc, VALUE * argv, VALUE (*func) (ANYARGS), VALUE data2, int kw_splat) ;T;[o; ;[I"JSame as rb_funcall_with_block, using +kw_splat+ to determine whether ;TI""keyword arguments are passed.;T@ o;;[I"^\[OBSOLETE] VALUE rb_iterate(VALUE (*func1)(), VALUE arg1, VALUE (*func2)(), VALUE arg2) ;T;[ o; ;[I"LCalls the function func1, supplying func2 as the block. func1 will be ;TI"Lcalled with the argument arg1. func2 receives the value from yield as ;TI"5the first argument, arg2 as the second argument.;T@ o; ;[I"OWhen rb_iterate is used in 1.9, func1 has to call some Ruby-level method. ;TI"DThis function is obsolete since 1.9; use rb_block_call instead.;T@ o;;[I" VALUE rb_yield(VALUE val) ;T;[o; ;[I"2Yields val as a single argument to the block.;T@ o;;[I"'VALUE rb_yield_values(int n, ...) ;T;[o; ;[I"PYields +n+ number of arguments to the block, using one C argument per Ruby ;TI"argument.;T@ o;;[I"0VALUE rb_yield_values2(int n, VALUE *argv) ;T;[o; ;[I"QYields +n+ number of arguments to the block, with all Ruby arguments in the ;TI"C argv array.;T@ o;;[I"@VALUE rb_yield_values_kw(int n, VALUE *argv, int kw_splat) ;T;[o; ;[I"ESame as rb_yield_values2, using +kw_splat+ to determine whether ;TI""keyword arguments are passed.;T@ o;;[I"&VALUE rb_yield_splat(VALUE args) ;T;[o; ;[I"JSame as rb_yield_values2, except arguments are specified by the Ruby ;TI"array +args+.;T@ o;;[I"7VALUE rb_yield_splat_kw(VALUE args, int kw_splat) ;T;[o; ;[I"CSame as rb_yield_splat, using +kw_splat+ to determine whether ;TI""keyword arguments are passed.;T@ o;;[I"_VALUE rb_rescue(VALUE (*func1)(ANYARGS), VALUE arg1, VALUE (*func2)(ANYARGS), VALUE arg2) ;T;[o; ;[ I"KCalls the function func1, with arg1 as the argument. If an exception ;TI"Ioccurs during func1, it calls func2 with arg2 as the first argument ;TI"Hand the exception object as the second argument. The return value ;TI"Kof rb_rescue() is the return value from func1 if no exception occurs, ;TI"from func2 otherwise.;T@ o;;[I"_VALUE rb_ensure(VALUE (*func1)(ANYARGS), VALUE arg1, VALUE (*func2)(ANYARGS), VALUE arg2) ;T;[o; ;[I"JCalls the function func1 with arg1 as the argument, then calls func2 ;TI"?with arg2 if execution terminated. The return value from ;TI"=rb_ensure() is that of func1 when no exception occurred.;T@ o;;[I"DVALUE rb_protect(VALUE (*func) (VALUE), VALUE arg, int *state) ;T;[o; ;[ I"HCalls the function func with arg as the argument. If no exception ;TI"Moccurred during func, it returns the result of func and *state is zero. ;TI"IOtherwise, it returns Qnil and sets *state to nonzero. If state is ;TI"(NULL, it is not set in both cases. ;TI"EYou have to clear the error info with rb_set_errinfo(Qnil) when ;TI"#ignoring the caught exception.;T@ o;;[I"!void rb_jump_tag(int state) ;T;[o; ;[I"RContinues the exception caught by rb_protect() and rb_eval_string_protect(). ;TI"Kstate must be the returned value from those functions. This function ;TI" never return to the caller.;T@ o;;[I"void rb_iter_break() ;T;[o; ;[I"LExits from the current innermost block. This function never return to ;TI"the caller.;T@ o;;[I"+void rb_iter_break_value(VALUE value) ;T;[o; ;[I"LExits from the current innermost block with the value. The block will ;TI"Ireturn the given argument value. This function never return to the ;TI" caller.;T@ S; ; i; I"Exceptions and errors;T@ o;;;;[ o;;[I"(void rb_warn(const char *fmt, ...) ;T;[o; ;[I"@Prints a warning message according to a printf-like format.;T@ o;;[I"+void rb_warning(const char *fmt, ...) ;T;[o; ;[I"DPrints a warning message according to a printf-like format, if ;TI"$VERBOSE is true.;T@ o;;[I";void rb_raise(rb_eRuntimeError, const char *fmt, ...) ;T;[o; ;[I"IRaises RuntimeError. The fmt is a format string just like printf().;T@ o;;[I":void rb_raise(VALUE exception, const char *fmt, ...) ;T;[o; ;[I"NRaises a class exception. The fmt is a format string just like printf().;T@ o;;[I")void rb_fatal(const char *fmt, ...) ;T;[o; ;[I"NRaises a fatal error, terminates the interpreter. No exception handling ;TI"Gwill be done for fatal errors, but ensure blocks will be executed.;T@ o;;[I"'void rb_bug(const char *fmt, ...) ;T;[o; ;[I"FTerminates the interpreter immediately. This function should be ;TI"Jcalled under the situation caused by the bug in the interpreter. No ;TI":exception handling nor ensure execution will be done.;T@ o; ;[ I"JNote: In the format string, "%"PRIsVALUE can be used for Object#to_s ;TI"I(or Object#inspect if '+' flag is set) output (and related argument ;TI"Fmust be a VALUE). Since it conflicts with "%i", for integers in ;TI" format strings, use "%d".;T@ S; ; i; I"Threading;T@ o; ;[ I"HAs of Ruby 1.9, Ruby supports native 1:1 threading with one kernel ;TI"Pthread per Ruby Thread object. Currently, there is a GVL (Global VM Lock) ;TI"Nwhich prevents simultaneous execution of Ruby code which may be released ;TI"Rby the rb_thread_call_without_gvl and rb_thread_call_without_gvl2 functions. ;TI"JThese functions are tricky-to-use and documented in thread.c; do not ;TI"2use them before reading comments in thread.c.;T@ o;;;;[o;;[I"#void rb_thread_schedule(void) ;T;[o; ;[I"CGive the scheduler a hint to pass execution to another thread.;T@ S; ; i; I"2Input/Output (IO) on a single file descriptor;T@ o;;;;[o;;[I"%int rb_io_wait_readable(int fd) ;T;[o; ;[I"KWait indefinitely for the given FD to become readable, allowing other ;TI"Ethreads to be scheduled. Returns a true value if a read may be ;TI"9performed, false if there is an unrecoverable error.;T@ o;;[I"%int rb_io_wait_writable(int fd) ;T;[o; ;[I"3Like rb_io_wait_readable, but for writability.;T@ o;;[I"Lint rb_wait_for_single_fd(int fd, int events, struct timeval *timeout) ;T;[ o; ;[I"EAllows waiting on a single FD for one or multiple events with a ;TI"specified timeout.;T@ o; ;[I"C+events+ is a mask of any combination of the following values:;T@ o;;;;[o;;0;[o; ;[I"7RB_WAITFD_IN - wait for readability of normal data;To;;0;[o; ;[I")RB_WAITFD_OUT - wait for writability;To;;0;[o; ;[I"8RB_WAITFD_PRI - wait for readability of urgent data;T@ o; ;[I"/Use a NULL +timeout+ to wait indefinitely.;T@ S; ; i; I"I/O multiplexing;T@ o; ;[ I"HRuby supports I/O multiplexing based on the select(2) system call. ;TI"%The Linux select_tut(2) manpage ;TI"><http://man7.org/linux/man-pages/man2/select_tut.2.html> ;TI"Lprovides a good overview on how to use select(2), and the Ruby API has ;TI"Kanalogous functions and data structures to the well-known select API. ;TI"GUnderstanding of select(2) is required to understand this section.;T@ o;;;;[ o;;[I" typedef struct rb_fdset_t ;T;[o; ;[I"IThe data structure which wraps the fd_set bitmap used by select(2). ;TI"AThis allows Ruby to use FD sets larger than that allowed by ;TI".historic limitations on modern platforms.;T@ o;;[I"#void rb_fd_init(rb_fdset_t *) ;T;[o; ;[I"MInitializes the rb_fdset_t, it must be initialized before other rb_fd_* ;TI"Goperations. Analogous to calling malloc(3) to allocate an fd_set.;T@ o;;[I"#void rb_fd_term(rb_fdset_t *) ;T;[o; ;[I"JDestroys the rb_fdset_t, releasing any memory and resources it used. ;TI"BIt must be reinitialized using rb_fd_init before future use. ;TI"BAnalogous to calling free(3) to release memory for an fd_set.;T@ o;;[I"#void rb_fd_zero(rb_fdset_t *) ;T;[o; ;[I"AClears all FDs from the rb_fdset_t, analogous to FD_ZERO(3).;T@ o;;[I"*void rb_fd_set(int fd, rb_fdset_t *) ;T;[o; ;[I"?Adds a given FD in the rb_fdset_t, analogous to FD_SET(3).;T@ o;;[I"*void rb_fd_clr(int fd, rb_fdset_t *) ;T;[o; ;[I"DRemoves a given FD from the rb_fdset_t, analogous to FD_CLR(3).;T@ o;;[I"1int rb_fd_isset(int fd, const rb_fdset_t *) ;T;[o; ;[I"HReturns true if a given FD is set in the rb_fdset_t, false if not. ;TI" Analogous to FD_ISSET(3).;T@ o;;[I"}int rb_thread_fd_select(int nfds, rb_fdset_t *readfds, rb_fdset_t *writefds, rb_fdset_t *exceptfds, struct timeval *timeout) ;T;[ o; ;[I"CAnalogous to the select(2) system call, but allows other Ruby ;TI"+threads to be scheduled while waiting.;T@ o; ;[I"BWhen only waiting on a single FD, favor rb_io_wait_readable, ;TI"Crb_io_wait_writable, or rb_wait_for_single_fd functions since ;TI"Jthey can be optimized for specific platforms (currently, only Linux).;T@ S; ; i; I")Initialize and start the interpreter;T@ o; ;[I"PThe embedding API functions are below (not needed for extension libraries):;T@ o;;;;[ o;;[I"void ruby_init() ;T;[o; ;[I"!Initializes the interpreter.;T@ o;;[I"/void *ruby_options(int argc, char **argv) ;T;[o; ;[ I"9Process command line arguments for the interpreter. ;TI".And compiles the Ruby source to execute. ;TI"9It returns an opaque pointer to the compiled source ;TI""or an internal special value.;T@ o;;[I" int ruby_run_node(void *n) ;T;[o; ;[I"<Runs the given compiled source and exits this process. ;TI">It returns EXIT_SUCCESS if successfully runs the source. ;TI"'Otherwise, it returns other value.;T@ o;;[I""void ruby_script(char *name) ;T;[o; ;[I"+Specifies the name of the script ($0).;T@ S; ; i; I"%Hooks for the interpreter events;T@ o;;;;[o;;[I"[void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data) ;T;[ o; ;[I"@Adds a hook function for the specified interpreter events. ;TI"%events should be OR'ed value of:;T@ o;;[I"RUBY_EVENT_LINE ;TI"RUBY_EVENT_CLASS ;TI"RUBY_EVENT_END ;TI"RUBY_EVENT_CALL ;TI"RUBY_EVENT_RETURN ;TI"RUBY_EVENT_C_CALL ;TI"RUBY_EVENT_C_RETURN ;TI"RUBY_EVENT_RAISE ;TI"RUBY_EVENT_ALL ;T;0o; ;[I"5The definition of rb_event_hook_func_t is below:;T@ o;;[I"Htypedef void (*rb_event_hook_func_t)(rb_event_t event, VALUE data, ;TI"J VALUE self, ID id, VALUE klass) ;T;0o; ;[I"LThe third argument `data' to rb_add_event_hook() is passed to the hook ;TI"Kfunction as the second argument, which was the pointer to the current ;TI"?NODE in 1.8. See RB_EVENT_HOOKS_HAVE_CALLBACK_DATA below.;T@ o;;[I"9int rb_remove_event_hook(rb_event_hook_func_t func) ;T;[o; ;[I")Removes the specified hook function.;T@ S; ; i; I"Memory usage;T@ o;;;;[o;;[I"2void rb_gc_adjust_memory_usage(ssize_t diff) ;T;[o; ;[ I"LAdjusts the amount of registered external memory. You can tell GC how ;TI"Kmuch memory is used by an external library by this function. Calling ;TI"Kthis function with positive diff means the memory usage is increased; ;TI"Gnew memory block is allocated or a block is reallocated as larger ;TI"Lsize. Calling this function with negative diff means the memory usage ;TI"His decreased; a memory block is freed or a block is reallocated as ;TI"5smaller size. This function may trigger the GC.;T@ S; ; i; I" Macros for compatibility;T@ o; ;[I"GSome macros to check API compatibilities are available by default.;T@ o;;;;[ o;;[I"NORETURN_STYLE_NEW ;T;[o; ;[I"EMeans that NORETURN macro is functional style instead of prefix.;T@ o;;[I" HAVE_RB_DEFINE_ALLOC_FUNC ;T;[o; ;[I"LMeans that function rb_define_alloc_func() is provided, that means the ;TI"Fallocation framework is used. This is the same as the result of ;TI"1have_func("rb_define_alloc_func", "ruby.h").;T@ o;;[I"HAVE_RB_REG_NEW_STR ;T;[o; ;[I"KMeans that function rb_reg_new_str() is provided, that creates Regexp ;TI"Cobject from String object. This is the same as the result of ;TI"+have_func("rb_reg_new_str", "ruby.h").;T@ o;;[I"HAVE_RB_IO_T ;T;[o; ;[I")Means that type rb_io_t is provided.;T@ o;;[I" USE_SYMBOL_AS_METHOD_NAME ;T;[o; ;[I"@Means that Symbols will be returned as method names, e.g., ;TI"3Module#methods, \#singleton_methods and so on.;T@ o;;[I"HAVE_RUBY_*_H ;T;[ o; ;[I"IDefined in ruby.h and means corresponding header is available. For ;TI"Kinstance, when HAVE_RUBY_ST_H is defined you should use ruby/st.h not ;TI"mere st.h.;T@ o; ;[I"IHeader files corresponding to these macros may be <tt>#include</tt> ;TI"'directly from extension libraries.;T@ o;;[I"'RB_EVENT_HOOKS_HAVE_CALLBACK_DATA ;T;[o; ;[I"KMeans that rb_add_event_hook() takes the third argument `data', to be ;TI"-passed to the given event hook function.;T@ S; ; i; I"GDefining backward compatible macros for keyword argument functions;T@ o; ;[ I"LMost ruby C extensions are designed to support multiple Ruby versions. ;TI"CIn order to correctly support Ruby 2.7+ in regards to keyword ;TI"Eargument separation, C extensions need to use <code>*_kw</code> ;TI"Gfunctions. However, these functions do not exist in Ruby 2.6 and ;TI"Kbelow, so in those cases macros should be defined to allow you to use ;TI"Gthe same code on multiple Ruby versions. Here are example macros ;TI"Kyou can use in extensions that support Ruby 2.6 (or below) when using ;TI"<the <code>*_kw</code> functions introduced in Ruby 2.7.;T@ o;;[$I" #ifndef RB_PASS_KEYWORDS ;TI"+/* Only define macros on Ruby <2.7 */ ;TI"D#define rb_funcallv_kw(o, m, c, v, kw) rb_funcallv(o, m, c, v) ;TI"R#define rb_funcallv_public_kw(o, m, c, v, kw) rb_funcallv_public(o, m, c, v) ;TI"^#define rb_funcall_passing_block_kw(o, m, c, v, kw) rb_funcall_passing_block(o, m, c, v) ;TI"^#define rb_funcall_with_block_kw(o, m, c, v, b, kw) rb_funcall_with_block(o, m, c, v, b) ;TI"R#define rb_scan_args_kw(kw, c, v, s, ...) rb_scan_args(c, v, s, __VA_ARGS__) ;TI"<#define rb_call_super_kw(c, v, kw) rb_call_super(c, v) ;TI"A#define rb_yield_values_kw(c, v, kw) rb_yield_values2(c, v) ;TI"8#define rb_yield_splat_kw(a, kw) rb_yield_splat(a) ;TI"T#define rb_block_call_kw(o, m, c, v, f, p, kw) rb_block_call(o, m, c, v, f, p) ;TI"F#define rb_fiber_resume_kw(o, c, v, kw) rb_fiber_resume(o, c, v) ;TI">#define rb_fiber_yield_kw(c, v, kw) rb_fiber_yield(c, v) ;TI"h#define rb_enumeratorize_with_size_kw(o, m, c, v, f, kw) rb_enumeratorize_with_size(o, m, c, v, f) ;TI"G#define SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat) \ ;TI"K rb_enumeratorize_with_size((obj), ID2SYM(rb_frame_this_func()), \ ;TI"? (argc), (argv), (size_fn)) ;TI"S#define RETURN_SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat) do { \ ;TI"S if (!rb_block_given_p()) \ ;TI"S return SIZED_ENUMERATOR(obj, argc, argv, size_fn); \ ;TI" } while (0) ;TI"i#define RETURN_ENUMERATOR_KW(obj, argc, argv, kw_splat) RETURN_SIZED_ENUMERATOR(obj, argc, argv, 0) ;TI"N#define rb_check_funcall_kw(o, m, c, v, kw) rb_check_funcall(o, m, c, v) ;TI"H#define rb_obj_call_init_kw(o, c, v, kw) rb_obj_call_init(o, c, v) ;TI"R#define rb_class_new_instance_kw(c, v, k, kw) rb_class_new_instance(c, v, k) ;TI":#define rb_proc_call_kw(p, a, kw) rb_proc_call(p, a) ;TI"\#define rb_proc_call_with_block_kw(p, c, v, b, kw) rb_proc_call_with_block(p, c, v, b) ;TI"D#define rb_method_call_kw(c, v, m, kw) rb_method_call(c, v, m) ;TI"`#define rb_method_call_with_block_kw(c, v, m, b, kw) rb_method_call_with_block(c, v, m, b) ;TI"<#define rb_eval_cmd_kwd(c, a, kw) rb_eval_cmd(c, a, 0) ;TI" #endif ;T;0S; ; i; I":Appendix C. Functions available for use in extconf.rb;T@ o; ;[I"9See documentation for {mkmf}[rdoc-ref:MakeMakefile].;T@ S; ; i; I" Appendix D. Generational GC;T@ o; ;[I"KRuby 2.1 introduced a generational garbage collector (called RGenGC). ;TI")RGenGC (mostly) keeps compatibility.;T@ o; ;[ I"NGenerally, the use of the technique called write barriers is required in ;TI"-extension libraries for generational GC ;TI"P(https://en.wikipedia.org/wiki/Garbage_collection_%28computer_science%29). ;TI"ERGenGC works fine without write barriers in extension libraries.;T@ o; ;[I"DIf your library adheres to the following tips, performance can ;TI"Ube further improved. Especially, the "Don't touch pointers directly" section is ;TI"important.;T@ S; ; i; I"Incompatibility;T@ o; ;[I"KYou can't write RBASIC(obj)->klass field directly because it is const ;TI"value now.;T@ o; ;[I"LBasically you should not write this field because MRI expects it to be ;TI"Lan immutable field, but if you want to do it in your extension you can ;TI"!use the following functions:;T@ o;;;;[o;;[I""VALUE rb_obj_hide(VALUE obj) ;T;[o; ;[I"GClear RBasic::klass field. The object will be an internal object. ;TI"5ObjectSpace::each_object can't find this object.;T@ o;;[I"1VALUE rb_obj_reveal(VALUE obj, VALUE klass) ;T;[o; ;[I"&Reset RBasic::klass to be klass. ;TI"<We expect the `klass' is hidden class by rb_obj_hide().;T@ S; ; i; I"Write barriers;T@ o; ;[I"GRGenGC doesn't require write barriers to support generational GC. ;TI"HHowever, caring about write barrier can improve the performance of ;TI"-RGenGC. Please check the following tips.;T@ S; ; i ; I""Don't touch pointers directly;T@ o; ;[I"JIn MRI (include/ruby/ruby.h), some macros to acquire pointers to the ;TI"Binternal data structures are supported such as RARRAY_PTR(), ;TI" RSTRUCT_PTR() and so on.;T@ o; ;[I"NDO NOT USE THESE MACROS and instead use the corresponding C-APIs such as ;TI"-rb_ary_aref(), rb_ary_store() and so on.;T@ S; ; i ; I".Consider whether to insert write barriers;T@ o; ;[I"JYou don't need to care about write barriers if you only use built-in ;TI" types.;T@ o; ;[I"JIf you support T_DATA objects, you may consider using write barriers.;T@ o; ;[ I"FInserting write barriers into T_DATA objects only works with the ;TI"Lfollowing type objects: (a) long-lived objects, (b) when a huge number ;TI"Hof objects are generated and \(c) container-type objects that have ;TI"Lreferences to other objects. If your extension provides such a type of ;TI"7T_DATA objects, consider inserting write barriers.;T@ o; ;[I"C(a): short-lived objects don't become old generation objects. ;TI"C(b): only a few oldgen objects don't have performance impact. ;TI"?\(c): only a few references don't have performance impact.;T@ o; ;[ I"FInserting write barriers is a very difficult hack, it is easy to ;TI"Mintroduce critical bugs. And inserting write barriers has several areas ;TI"Jof overhead. Basically we don't recommend you insert write barriers. ;TI")Please carefully consider the risks.;T@ S; ; i ; I" Combine with built-in types;T@ o; ;[I"KPlease consider utilizing built-in types. Most built-in types support ;TI"Jwrite barrier, so you can use them to avoid manually inserting write ;TI"barriers.;T@ o; ;[ I"KFor example, if your T_DATA has references to other objects, then you ;TI"Ncan move these references to Array. A T_DATA object only has a reference ;TI"Ito an array object. Or you can also use a Struct object to gather a ;TI"GT_DATA object (without any references) and an that Array contains ;TI"references.;T@ o; ;[I"JWith use of such techniques, you don't need to insert write barriers ;TI" anymore.;T@ S; ; i ; I"Insert write barriers;T@ o; ;[ I"K\[AGAIN] Inserting write barriers is a very difficult hack, and it is ;TI"Geasy to introduce critical bugs. And inserting write barriers has ;TI"Nseveral areas of overhead. Basically we don't recommend you insert write ;TI"3barriers. Please carefully consider the risks.;T@ o; ;[I"NBefore inserting write barriers, you need to know about RGenGC algorithm ;TI"M(gc.c will help you). Macros and functions to insert write barriers are ;TI"Iavailable in include/ruby/ruby.h. An example is available in iseq.c.;T@ o; ;[I"IFor a complete guide for RGenGC and write barriers, please refer to ;TI"C<https://bugs.ruby-lang.org/projects/ruby-master/wiki/RGenGC>.;T@ S; ; i; I"9Appendix E. RB_GC_GUARD to protect from premature GC;T@ o; ;[ I"GC Ruby currently uses conservative garbage collection, thus VALUE ;TI"Kvariables must remain visible on the stack or registers to ensure any ;TI"Nassociated data remains usable. Optimizing C compilers are not designed ;TI"Mwith conservative garbage collection in mind, so they may optimize away ;TI"Nthe original VALUE even if the code depends on data associated with that ;TI" VALUE.;T@ o; ;[I"HThe following example illustrates the use of RB_GC_GUARD to ensure ;TI"Fthe contents of sptr remain valid while the second invocation of ;TI" rb_str_new_cstr is running.;T@ o;;[ I"VALUE s, w; ;TI"const char *sptr; ;TI" ;TI"Ls = rb_str_new_cstr("hello world!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!"); ;TI" sptr = RSTRING_PTR(s); ;TI"Aw = rb_str_new_cstr(sptr + 6); /* Possible GC invocation */ ;TI" ;TI"ERB_GC_GUARD(s); /* ensure s (and thus sptr) do not get GC-ed */ ;T;0o; ;[ I"NIn the above example, RB_GC_GUARD must be placed _after_ the last use of ;TI"Nsptr. Placing RB_GC_GUARD before dereferencing sptr would be of no use. ;TI"KRB_GC_GUARD is only effective on the VALUE data type, not converted C ;TI"data types.;T@ o; ;[ I"GRB_GC_GUARD would not be necessary at all in the above example if ;TI"Hnon-inlined function calls are made on the `s' VALUE after sptr is ;TI"Gdereferenced. Thus, in the above example, calling any un-inlined ;TI" function on `s' such as:;T@ o;;[I"rb_str_modify(s); ;T;0o; ;[I"AWill ensure `s' stays on the stack or register to prevent a ;TI"/GC invocation from prematurely freeing it.;T@ o; ;[I"GUsing the RB_GC_GUARD macro is preferable to using the "volatile" ;TI"=keyword in C. RB_GC_GUARD has the following advantages:;T@ o;;;;[o;;0;[o; ;[I")the intent of the macro use is clear;T@ o;;0;[o; ;[I"GRB_GC_GUARD only affects its call site, "volatile" generates some ;TI"Fextra code every time the variable is used, hurting optimization.;T@ o;;0;[o; ;[I"B"volatile" implementations may be buggy/inconsistent in some ;TI"Icompilers and architectures. RB_GC_GUARD is customizable for broken ;TI"Bsystems/compilers without negatively affecting other systems.;T@ S; ; i; I" Appendix F. Ractor support;T@ o; ;[ I"PRactor(s) are the parallel execution mechanism introduced in Ruby 3.0. All ;TI"Vractors can run in parallel on a different OS thread (using an underlying system ;TI"Tprovided thread), so the C extension should be thread-safe. A C extension that ;TI"9can run in multiple ractors is called "Ractor-safe".;T@ o; ;[I"DRactor safety around C extensions has the following properties:;To;;;;[o;;0;[o; ;[I"BBy default, all C extensions are recognized as Ractor-unsafe.;To;;0;[o; ;[I"RRactor-unsafe C-methods may only be called from the main Ractor. If invoked ;TI"@by a non-main Ractor, then a Ractor::UnsafeError is raised.;To;;0;[o; ;[I"NIf an extension desires to be marked as Ractor-safe the extension should ;TI"Pcall rb_ext_ractor_safe(true) at the Init_ function for the extension, and ;TI"7all defined methods will be marked as Ractor-safe.;T@ o; ;[I"PTo make a "Ractor-safe" C extension, we need to check the following points:;T@ o;;;;[ o;;0;[o; ;[I"5Do not share unshareable objects between ractors;T@ o; ;[I"NFor example, C's global variable can lead sharing an unshareable objects ;TI"between ractors.;T@ o;;[I"VALUE g_var; ;TI"9VALUE set(VALUE self, VALUE v){ return g_var = v; } ;TI",VALUE get(VALUE self){ return g_var; } ;T;0o; ;[I"Lset() and get() pair can share an unshareable objects using g_var, and ;TI"it is Ractor-unsafe.;T@ o; ;[I"LNot only using global variables directly, some indirect data structure ;TI"Hsuch as global st_table can share the objects, so please take care.;T@ o; ;[I"JNote that class and module objects are shareable objects, so you can ;TI"Kkeep the code "cFoo = rb_define_class(...)" with C's global variables.;T@ o;;0;[o; ;[I"-Check the thread-safety of the extension;T@ o; ;[I"LAn extension should be thread-safe. For example, the following code is ;TI"not thread-safe:;T@ o;;[ I" bool g_called = false; ;TI" VALUE call(VALUE self) { ;TI"A if (g_called) rb_raise("recursive call is not allowed."); ;TI" g_called = true; ;TI"# VALUE ret = do_something(); ;TI" g_called = false; ;TI" return ret; ;TI"} ;T;0o; ;[I"Fbecause g_called global variable should be synchronized by other ;TI"Lractor's threads. To avoid such data-race, some synchronization should ;TI"Kbe used. Check include/ruby/thread_native.h and include/ruby/atomic.h.;T@ o; ;[ I"RWith Ractors, all objects given as method parameters and the receiver (self) ;TI"Kare guaranteed to be from the current Ractor or to be shareable. As a ;TI"Tconsequence, it is easier to make code ractor-safe than to make code generally ;TI"Sthread-safe. For example, we don't need to lock an array object to access the ;TI"element of it.;T@ o;;0;[ o; ;[I"0Check the thread-safety of any used library;T@ o; ;[I"SIf the extension relies on an external library, such as a function foo() from ;TI"Ga library libfoo, the function libfoo foo() should be thread safe.;T@ o;;0;[ o; ;[I" Make an object shareable;T@ o; ;[I";This is not required to make an extension Ractor-safe.;T@ o; ;[I"IIf an extension provides special objects defined by rb_data_type_t, ;TI"8consider these objects can become shareable or not.;T@ o; ;[I"JRUBY_TYPED_FROZEN_SHAREABLE flag indicates that these objects can be ;TI"Nshareable objects if the object is frozen. This means that if the object ;TI"<is frozen, the mutation of wrapped data is not allowed.;T@ o;;0;[o; ;[I" Others;T@ o; ;[I"UThere are possibly other points or requirements which must be considered in the ;TI"Tmaking of a Ractor-safe extension. This document will be extended as they are ;TI"discovered.;T: @file@:0@omit_headings_from_table_of_contents_below0