(37a72b0150ec36b4ea27175039afc28c62207b0c)

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

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 3714 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]	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 3728 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:

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 707 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]	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 732 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);
}

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 726 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]	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 738 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]	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 3776 of file variable.c.

◆ 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 913 of file variable.c.

◆ 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 899 of file variable.c.

◆ 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 4201 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 4212 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().

(37a72b0150ec36b4ea27175039afc28c62207b0c)

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ rb_gvar_getter_t

◆ rb_gvar_marker_t

◆ rb_gvar_setter_t

Function Documentation

◆ rb_define_const()

◆ rb_define_global_const()

◆ rb_define_hooked_variable()

◆ rb_define_readonly_variable()

◆ rb_define_variable()

◆ rb_define_virtual_variable()

◆ rb_deprecate_constant()

◆ rb_gv_get()

◆ rb_gv_set()

◆ rb_iv_get()

◆ rb_iv_set()

Variable Documentation

◆ rb_gvar_readonly_setter

◆ rb_gvar_undef_getter

◆ rb_gvar_undef_marker

◆ rb_gvar_undef_setter

◆ rb_gvar_val_getter

◆ rb_gvar_val_marker

◆ rb_gvar_val_setter

◆ rb_gvar_var_getter

◆ rb_gvar_var_marker

◆ rb_gvar_var_setter