Ruby: include/ruby/internal/variable.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Typedefs | Functions | Variables
variable.h File Reference

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"`

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.
typedef void | rb_gvar_setter_t(VALUE val, ID id, VALUE *data)
| Type that represents a global variable setter function.
typedef void | rb_gvar_marker_t(VALUE *var)
| Type that represents a global variable marker function.

## Functions
void | rb_define_variable (const char *name, VALUE *var)
| "Shares" a global variable between Ruby and C.
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.
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.
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.
void | rb_define_const (VALUE klass, const char *name, VALUE val)
| Defines a Ruby level constant under a namespace.
void | rb_define_global_const (const char *name, VALUE val)
| Identical to rb_define_const(), except it defines that of "global", i.e.
void | rb_deprecate_constant (VALUE mod, const char *name)
| Asserts that the given constant is deprecated.
VALUE | rb_gv_set (const char *name, VALUE val)
| Assigns to a global variable.
VALUE | rb_gv_get (const char *name)
| Obtains a global variable.
VALUE | rb_iv_get (VALUE obj, const char *name)
| Obtains an instance variable.
VALUE | rb_iv_set (VALUE obj, const char *name, VALUE val)
| Assigns to an instance variable.

## 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.
rb_gvar_setter_t | rb_gvar_val_setter
| This is the setter function that backs global variables defined from a ruby script.
rb_gvar_marker_t | rb_gvar_val_marker
| This is the setter function that backs global variables defined from a ruby script.
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.

## Detailed Description

Declares rb_define_variable().

Author
  Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org

Copyright
  This file is a part of the programming language Ruby. Permission is hereby granted, to either redistribute and/or modify this file, provided that the conditions mentioned in the file COPYING are met. Consult the file for details.

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] | id | The variable name.
  [in,out] | data | Where 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] | var | Where 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] | val | The value to set.
  [in] | id | The variable name.
  [in,out] | data | Where 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] | klass | Namespace for the constant to reside.
  [in] | name | Name of the constant.
  [in] | val | Value of the constant.

Exceptions

  rb_eTypeError | `klass` is not a kind of rb_cModule.
  rb_eFrozenError | `klass` 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 3440 of file variable.c.

Referenced by rb_define_const(), and 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] | name | Name of the constant.
  [in] | val | Value of the constant.

Exceptions

  rb_eFrozenError | rb_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 3452 of file variable.c.

Referenced by rb_define_global_const(), and 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:

- When getter is 0 rb_gvar_var_getter is used instead.
- When setter is 0 rb_gvar_var_setter is used instead.
- When data is 0, you must specify a non-zero setter function. Otherwise rb_gvar_var_setter tries to write to `*NULL`, and just causes SEGV.

Parameters

  [in] | name | Variable name, in C's string.
  [in] | var | Variable storage.
  [in] | getter | A getter function.
  [in] | setter | A setter function.

Postcondition
  Ruby level global variable named `name` is defined if absent.

Definition at line 579 of file variable.c.

## ◆ 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] | name | Variable (Ruby side).
  [in] | var | Variable (C side).

Postcondition
  Ruby level global variable named `name` is defined if absent, and its storage is set to `var`.

Definition at line 604 of file variable.c.

Referenced by rb_define_readonly_variable().

## ◆ 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);
}
rb_eval_string
VALUE rb_eval_string(const char *str)
Evaluates the given string.
Definition vm_eval.c:1848
rb_define_variable
void rb_define_variable(const char *name, VALUE *var)
"Shares" a global variable between Ruby and C.
Definition variable.c:598
VALUE
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] | name | Variable (Ruby side).
  [in] | var | Variable (C side).

Postcondition
  Ruby level global variable named `name` is defined if absent, and its storage is set to `var`.

Definition at line 598 of file variable.c.

Referenced by rb_define_variable().

## ◆ 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] | name | Variable name, in C's string.
  [in] | getter | A getter function.
  [in] | setter | A setter function.

Postcondition
  Ruby level global variable named `name` is defined if absent.

Definition at line 610 of file variable.c.

## ◆ 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] | mod | Namespace of the target constant.
  [in] | name | Name of the constant.

Exceptions

  rb_eNameError | No such constant.
  rb_eFrozenError | `mod` is frozen.

Postcondition
  `name` under `mod` is deprecated.

Definition at line 3500 of file variable.c.

Referenced by rb_deprecate_constant().

## ◆ rb_gv_get()

VALUE rb_gv_get | ( | const char * | name | ) |

Obtains a global variable.

Parameters

  [in] | name | Global variable to query.

Return values

  RUBY_Qnil | The global variable does not exist.
  otherwise | The value assigned to the global variable.

Definition at line 785 of file variable.c.

Referenced by rb_gv_get().

## ◆ rb_gv_set()

VALUE rb_gv_set | ( | const char * | name,
|  | VALUE | val )

Assigns to a global variable.

Parameters

  [in] | name | Target global variable.
  [in] | val | Value 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 771 of file variable.c.

Referenced by rb_gv_set().

## ◆ rb_iv_get()

VALUE rb_iv_get | ( | VALUE | obj,
|  | const char * | name )

Obtains an instance variable.

Parameters

  [in] | obj | Target object.
  [in] | name | Target instance variable to query.

Exceptions

  rb_eEncodingError | `name` is corrupt (contains Hanzi etc.).

Return values

  RUBY_nil | No such instance variable.
  otherwise | The value assigned to the instance variable.

Definition at line 3936 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] | obj | Target object.
  [in] | name | Target instance variable.
  [in] | val | Value to assign.

Exceptions

  rb_eFrozenError | Can't modify `obj`.
  rb_eArgError | `obj` 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 3947 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().