Ruby  3.4.0dev (2024-12-06 revision 892c46283a5ea4179500d951c9d4866c0051f27b)
Typedefs | Functions | Variables
variable.h File Reference

(892c46283a5ea4179500d951c9d4866c0051f27b)

Declares rb_define_variable(). More...

#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/noreturn.h"
Include dependency graph for variable.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef VALUE rb_gvar_getter_t(ID id, VALUE *data)
 Type that represents a global variable getter function. More...
 
typedef void rb_gvar_setter_t(VALUE val, ID id, VALUE *data)
 Type that represents a global variable setter function. More...
 
typedef void rb_gvar_marker_t(VALUE *var)
 Type that represents a global variable marker function. More...
 

Functions

void rb_define_variable (const char *name, VALUE *var)
 "Shares" a global variable between Ruby and C. More...
 
void rb_define_virtual_variable (const char *name, rb_gvar_getter_t *getter, rb_gvar_setter_t *setter)
 Defines a global variable that is purely function-backended. More...
 
void rb_define_hooked_variable (const char *name, VALUE *var, rb_gvar_getter_t *getter, rb_gvar_setter_t *setter)
 Identical to rb_define_virtual_variable(), but can also specify a storage. More...
 
void rb_define_readonly_variable (const char *name, const VALUE *var)
 Identical to rb_define_variable(), except it does not allow Ruby programs to assign values to such global variable. More...
 
void rb_define_const (VALUE klass, const char *name, VALUE val)
 Defines a Ruby level constant under a namespace. More...
 
void rb_define_global_const (const char *name, VALUE val)
 Identical to rb_define_const(), except it defines that of "global", i.e. More...
 
void rb_deprecate_constant (VALUE mod, const char *name)
 Asserts that the given constant is deprecated. More...
 
VALUE rb_gv_set (const char *name, VALUE val)
 Assigns to a global variable. More...
 
VALUE rb_gv_get (const char *name)
 Obtains a global variable. More...
 
VALUE rb_iv_get (VALUE obj, const char *name)
 Obtains an instance variable. More...
 
VALUE rb_iv_set (VALUE obj, const char *name, VALUE val)
 Assigns to an instance variable. More...
 

Variables

rb_gvar_getter_t rb_gvar_undef_getter
 
rb_gvar_setter_t rb_gvar_undef_setter
 
rb_gvar_marker_t rb_gvar_undef_marker
 
rb_gvar_getter_t rb_gvar_val_getter
 This is the getter function that backs global variables defined from a ruby script. More...
 
rb_gvar_setter_t rb_gvar_val_setter
 This is the setter function that backs global variables defined from a ruby script. More...
 
rb_gvar_marker_t rb_gvar_val_marker
 This is the setter function that backs global variables defined from a ruby script. More...
 
rb_gvar_getter_t rb_gvar_var_getter
 
rb_gvar_setter_t rb_gvar_var_setter
 
rb_gvar_marker_t rb_gvar_var_marker
 
rb_gvar_setter_t rb_gvar_readonly_setter
 This function just raises rb_eNameError. More...
 

Detailed Description

Declares rb_define_variable().

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
Warning
Symbols prefixed with either RBIMPL or rbimpl are implementation details. Don't take them as canon. They could rapidly appear then vanish. The name (path) of this header file is also an implementation detail. Do not expect it to persist at the place it is now. Developers are free to move it anywhere anytime at will.
Note
To ruby-core: remember that this header can be possibly recursively included from extension libraries written in C++. Do not expect for instance __VA_ARGS__ is always available. We assume C99 for ruby itself but we don't assume languages of extension libraries. They could be written in C++98.

Definition in file variable.h.

Typedef Documentation

◆ rb_gvar_getter_t

typedef VALUE rb_gvar_getter_t(ID id, VALUE *data)

Type that represents a global variable getter function.

Parameters
[in]idThe variable name.
[in,out]dataWhere the value is stored.
Returns
The value that shall be visible from Ruby.

Definition at line 37 of file variable.h.

◆ rb_gvar_marker_t

typedef void rb_gvar_marker_t(VALUE *var)

Type that represents a global variable marker function.

Parameters
[in]varWhere the value is to be stored.

Definition at line 53 of file variable.h.

◆ rb_gvar_setter_t

typedef void rb_gvar_setter_t(VALUE val, ID id, VALUE *data)

Type that represents a global variable setter function.

Parameters
[in]valThe value to set.
[in]idThe variable name.
[in,out]dataWhere the value is to be stored.

Definition at line 46 of file variable.h.

Function Documentation

◆ rb_define_const()

void rb_define_const ( VALUE  klass,
const char *  name,
VALUE  val 
)

Defines a Ruby level constant under a namespace.

Parameters
[out]klassNamespace for the constant to reside.
[in]nameName of the constant.
[in]valValue of the constant.
Exceptions
rb_eTypeErrorklass is not a kind of rb_cModule.
rb_eFrozenErrorklass is frozen.
Postcondition
Ruby level constant klass::name is defined to be val.
Note
This API does not stop you from defining a constant that is unable to reach from ruby (like for instance passing non-capital letter to name).
This API does not stop you from overwriting a constant that already exist.

Definition at line 3726 of file variable.c.

Referenced by rb_define_global_const().

◆ rb_define_global_const()

void rb_define_global_const ( const char *  name,
VALUE  val 
)

Identical to rb_define_const(), except it defines that of "global", i.e.

toplevel constant.

Parameters
[in]nameName of the constant.
[in]valValue of the constant.
Exceptions
rb_eFrozenErrorrb_cObject is frozen.
Postcondition
Ruby level constant ::name is defined to be val.
Note
This API does not stop you from defining a constant that is unable to reach from ruby (like for instance passing non-capital letter to name).
This API does not stop you from overwriting a constant that already exist.

Definition at line 3740 of file variable.c.

Referenced by ruby_prog_init().

◆ rb_define_hooked_variable()

void rb_define_hooked_variable ( const char *  name,
VALUE var,
rb_gvar_getter_t getter,
rb_gvar_setter_t setter 
)

Identical to rb_define_virtual_variable(), but can also specify a storage.

A programmer can use the storage for e.g. memoisation, storing intermediate computation result, etc.

Also you can pass 0 to this function, unlike other variants:

Parameters
[in]nameVariable name, in C's string.
[in]varVariable storage.
[in]getterA getter function.
[in]setterA setter function.
Postcondition
Ruby level global variable named name is defined if absent.

Definition at line 719 of file variable.c.

Referenced by rb_define_readonly_variable(), rb_define_variable(), rb_define_virtual_variable(), and ruby_prog_init().

◆ rb_define_readonly_variable()

void rb_define_readonly_variable ( const char *  name,
const VALUE var 
)

Identical to rb_define_variable(), except it does not allow Ruby programs to assign values to such global variable.

C codes can still set values at will. This could be handy for you when implementing an errno-like experience, where a method updates a read-only global variable as a side- effect.

Parameters
[in]nameVariable (Ruby side).
[in]varVariable (C side).
Postcondition
Ruby level global variable named name is defined if absent, and its storage is set to var.

Definition at line 744 of file variable.c.

◆ rb_define_variable()

void rb_define_variable ( const char *  name,
VALUE var 
)

"Shares" a global variable between Ruby and C.

Normally a Ruby-level global variable is stored somewhere deep inside of the interpreter's execution context, but this way you can explicitly specify its storage.

static VALUE foo;
extern "C" void
init_Foo(void)
{
foo = rb_eval_string("...");
rb_define_variable("$foo", &foo);
}
VALUE rb_eval_string(const char *str)
Evaluates the given string.
Definition: vm_eval.c:1975
void rb_define_variable(const char *name, VALUE *var)
"Shares" a global variable between Ruby and C.
Definition: variable.c:738
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40

In the above example a Ruby global variable named $foo is stored in a C global variable named foo.

Parameters
[in]nameVariable (Ruby side).
[in]varVariable (C side).
Postcondition
Ruby level global variable named name is defined if absent, and its storage is set to var.

Definition at line 738 of file variable.c.

◆ rb_define_virtual_variable()

void rb_define_virtual_variable ( const char *  name,
rb_gvar_getter_t getter,
rb_gvar_setter_t setter 
)

Defines a global variable that is purely function-backended.

By using this API a programmer can define a global variable that dynamically changes from time to time.

Parameters
[in]nameVariable name, in C's string.
[in]getterA getter function.
[in]setterA setter function.
Postcondition
Ruby level global variable named name is defined if absent.

Definition at line 750 of file variable.c.

Referenced by ruby_prog_init().

◆ rb_deprecate_constant()

void rb_deprecate_constant ( VALUE  mod,
const char *  name 
)

Asserts that the given constant is deprecated.

Attempt to refer such constant will produce a warning.

Parameters
[in]modNamespace of the target constant.
[in]nameName of the constant.
Exceptions
rb_eNameErrorNo such constant.
rb_eFrozenErrormod is frozen.
Postcondition
name under mod is deprecated.

Definition at line 3788 of file variable.c.

◆ rb_gv_get()

VALUE rb_gv_get ( const char *  name)

Obtains a global variable.

Parameters
[in]nameGlobal variable to query.
Return values
RUBY_QnilThe global variable does not exist.
otherwiseThe value assigned to the global variable.

Definition at line 925 of file variable.c.

◆ rb_gv_set()

VALUE rb_gv_set ( const char *  name,
VALUE  val 
)

Assigns to a global variable.

Parameters
[in]nameTarget global variable.
[in]valValue to assign.
Returns
Passed value.
Postcondition
Ruby level global variable named name is defined if absent, whose value is set to val.

Definition at line 911 of file variable.c.

◆ rb_iv_get()

VALUE rb_iv_get ( VALUE  obj,
const char *  name 
)

Obtains an instance variable.

Parameters
[in]objTarget object.
[in]nameTarget instance variable to query.
Exceptions
rb_eEncodingErrorname is corrupt (contains Hanzi etc.).
Return values
RUBY_nilNo such instance variable.
otherwiseThe value assigned to the instance variable.

Definition at line 4213 of file variable.c.

◆ rb_iv_set()

VALUE rb_iv_set ( VALUE  obj,
const char *  name,
VALUE  val 
)

Assigns to an instance variable.

Parameters
[out]objTarget object.
[in]nameTarget instance variable.
[in]valValue to assign.
Exceptions
rb_eFrozenErrorCan't modify obj.
rb_eArgErrorobj has too many instance variables.
Returns
Passed value.
Postcondition
An instance variable named name is defined if absent on obj, whose value is set to val.

Definition at line 4224 of file variable.c.

Variable Documentation

◆ rb_gvar_readonly_setter

rb_gvar_setter_t rb_gvar_readonly_setter

This function just raises rb_eNameError.

Handy when you want to prohibit a global variable from being squashed by someone.

Definition at line 135 of file variable.h.

Referenced by rb_define_readonly_variable(), rb_define_virtual_variable(), and ruby_prog_init().

◆ rb_gvar_undef_getter

rb_gvar_getter_t rb_gvar_undef_getter
Deprecated:

This function has no actual usage (than in ruby itself). Please ignore. It was a bad idea to expose this function to 3rd parties, but we can no longer delete it.

Definition at line 62 of file variable.h.

◆ rb_gvar_undef_marker

rb_gvar_marker_t rb_gvar_undef_marker
Deprecated:

This function has no actual usage (than in ruby itself). Please ignore. It was a bad idea to expose this function to 3rd parties, but we can no longer delete it.

Definition at line 80 of file variable.h.

◆ rb_gvar_undef_setter

rb_gvar_setter_t rb_gvar_undef_setter
Deprecated:

This function has no actual usage (than in ruby itself). Please ignore. It was a bad idea to expose this function to 3rd parties, but we can no longer delete it.

Definition at line 71 of file variable.h.

◆ rb_gvar_val_getter

rb_gvar_getter_t rb_gvar_val_getter

This is the getter function that backs global variables defined from a ruby script.

Extension libraries can use this if its global variable needs no custom logic.

Definition at line 87 of file variable.h.

Referenced by rb_define_virtual_variable().

◆ rb_gvar_val_marker

rb_gvar_marker_t rb_gvar_val_marker

This is the setter function that backs global variables defined from a ruby script.

Extension libraries can use this if its global variable needs no custom logic.

Definition at line 101 of file variable.h.

◆ rb_gvar_val_setter

rb_gvar_setter_t rb_gvar_val_setter

This is the setter function that backs global variables defined from a ruby script.

Extension libraries can use this if its global variable needs no custom logic.

Definition at line 94 of file variable.h.

◆ rb_gvar_var_getter

rb_gvar_getter_t rb_gvar_var_getter
Deprecated:

This function has no actual usage (than in ruby itself). Please ignore. It was a bad idea to expose this function to 3rd parties, but we can no longer delete it.

Definition at line 110 of file variable.h.

Referenced by rb_define_hooked_variable().

◆ rb_gvar_var_marker

rb_gvar_marker_t rb_gvar_var_marker
Deprecated:

This function has no actual usage (than in ruby itself). Please ignore. It was a bad idea to expose this function to 3rd parties, but we can no longer delete it.

Definition at line 128 of file variable.h.

Referenced by rb_define_hooked_variable().

◆ rb_gvar_var_setter

rb_gvar_setter_t rb_gvar_var_setter
Deprecated:

This function has no actual usage (than in ruby itself). Please ignore. It was a bad idea to expose this function to 3rd parties, but we can no longer delete it.

Definition at line 119 of file variable.h.

Referenced by rb_define_hooked_variable().