(892c46283a5ea4179500d951c9d4866c0051f27b)

Public APIs related to rb_f_require(). More...

#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"

Include dependency graph for load.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	HAVE_RB_EXT_RESOLVE_SYMBOL 1
	This macro is to provide backwards compatibility. More...

Functions
void	rb_load (VALUE path, int wrap)
	Loads and executes the Ruby program in the given file. More...

void	rb_load_protect (VALUE path, int wrap, int *state)
	Identical to rb_load(), except it avoids potential global escapes. More...

int	rb_provided (const char *feature)
	Queries if the given feature has already been loaded into the execution context. More...

int	rb_feature_provided (const char feature, const char *loading)
	Identical to rb_provided(), except it additionally returns the "canonical" name of the loaded feature. More...

void	rb_provide (const char *feature)
	Declares that the given feature is already provided by someone else. More...

VALUE	rb_f_require (VALUE self, VALUE feature)
	Identical to rb_require_string(), except it ignores the first argument for no reason. More...

VALUE	rb_require_string (VALUE feature)
	Finds and loads the given feature, if absent. More...

void *	rb_ext_resolve_symbol (const char feature, const char symbol)
	Resolves and returns a symbol of a function in the native extension specified by the feature and symbol names. More...

extension configuration
#define	RB_EXT_RACTOR_SAFE(f) rb_ext_ractor_safe(f)
	Just another name of rb_ext_ractor_safe. More...

#define	HAVE_RB_EXT_RACTOR_SAFE 1
	This macro is to provide backwards compatibility. More...

void	rb_ext_ractor_safe (bool flag)
	Asserts that the extension library that calls this function is aware of Ractor. More...

Detailed Description

Public APIs related to rb_f_require().

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 load.h.

Macro Definition Documentation

◆ HAVE_RB_EXT_RACTOR_SAFE

#define HAVE_RB_EXT_RACTOR_SAFE 1

This macro is to provide backwards compatibility.

It must be safe to do something like:

#ifdef HAVE_RB_EXT_RACTOR_SAFE
rb_ext_ractor_safe(true);
#endif

Definition at line 249 of file load.h.

◆ HAVE_RB_EXT_RESOLVE_SYMBOL

#define HAVE_RB_EXT_RESOLVE_SYMBOL 1

This macro is to provide backwards compatibility.

It provides a way to define function prototypes and resolving function symbols in a safe way.

// prototypes
#ifdef HAVE_RB_EXT_RESOLVE_SYMBOL
VALUE *(*other_extension_func)(VALUE,VALUE);
#else
VALUE other_extension_func(VALUE);
#endif
 
// in Init_xxx()
#ifdef HAVE_RB_EXT_RESOLVE_SYMBOL
other_extension_func = \
    (VALUE(*)(VALUE,VALUE))rb_ext_resolve_symbol(fname, sym_name);
if (other_extension_func == NULL) {
  // raise your own error
}
#endif

Definition at line 214 of file load.h.

◆ RB_EXT_RACTOR_SAFE

#define RB_EXT_RACTOR_SAFE ( f ) rb_ext_ractor_safe(f)

Just another name of rb_ext_ractor_safe.

Definition at line 237 of file load.h.

Function Documentation

◆ rb_ext_ractor_safe()

void rb_ext_ractor_safe ( bool flag )

Asserts that the extension library that calls this function is aware of Ractor.

Multiple Ractors run without protecting each other. This doesn't interface well with C programs, unless designed with an in-depth understanding of how Ractors work. Extension libraries are shut out from Ractors by default. This API is to bypass that restriction. Once after it was called, successive calls to rb_define_method() etc. become definitions of methods that are aware of Ractors. The amendment would be in effect until the end of rb_require_string() etc.

Parameters

[in] flag Either the library is aware of Ractors or not.

Postcondition: Methods would be callable form Ractors, if flag is true.

Definition at line 1228 of file load.c.

◆ rb_ext_resolve_symbol()

void* rb_ext_resolve_symbol	(	const char *	feature,
		const char *	symbol
	)

Resolves and returns a symbol of a function in the native extension specified by the feature and symbol names.

Extensions will use this function to access the symbols provided by other native extensions.

Parameters

[in]	feature	Name of a feature, e.g. `"json"`.
[in]	symbol	Name of a symbol defined by the feature.

Returns: The resolved symbol of a function, defined and externed by the specified feature. It may be NULL if the feature is not loaded, the feature is not extension, or the symbol is not found.

Definition at line 1584 of file load.c.

◆ rb_f_require()

VALUE rb_f_require	(	VALUE	self,
		VALUE	feature
	)

Identical to rb_require_string(), except it ignores the first argument for no reason.

There seems to be no reason for 3rd party extension libraries to use it.

Parameters

[in]	self	Ignored. Can be anything.
[in]	feature	Name of a feature, e.g. `"json"`.

Exceptions

rb_eLoadError	No such feature.
rb_eRuntimeError	`$"` is frozen; unable to push.

Return values

RUBY_Qtrue	The feature is loaded for the first time.
RUBY_Qfalse	The feature has already been loaded.

Postcondition: $" is updated.

Definition at line 1027 of file load.c.

◆ rb_feature_provided()

int rb_feature_provided	(	const char *	feature,
		const char **	loading
	)

Identical to rb_provided(), except it additionally returns the "canonical" name of the loaded feature.

This can be handy when for instance you want to know the actually loaded library is either foo.rb or foo.so.

Parameters

[in]	feature	Name of a library you want to know about.
[out]	loading	Return buffer.

Return values

1	Yes there is.
0	Not yet.

Definition at line 687 of file load.c.

Referenced by rb_provided().

◆ rb_load()

void rb_load	(	VALUE	path,
		int	wrap
	)

Loads and executes the Ruby program in the given file.

If the path is an absolute path (e.g. starts with ‘’/'`), the file will be loaded directly using the absolute path. If the path is an explicit relative path (e.g. starts with ‘’./'or'../'`), the file will be loaded using the relative path from the current directory. Otherwise, the file will be searched for in the library directories listed in the $LOAD_PATH. If the file is found in a directory, this function will attempt to load the file relative to that directory. If the file is not found in any of the directories in the $LOAD_PATH, the file will be loaded using the relative path from the current directory.

If the file doesn't exist when there is an attempt to load it, a LoadError will be raised.

If the wrap parameter is true, the loaded script will be executed under an anonymous module, protecting the calling program's global namespace. In no circumstance will any local variables in the loaded file be propagated to the loading environment.

Parameters

[in]	path	Pathname of a file to load.
[in]	wrap	Either to load under an anonymous module.

Exceptions

rb_eTypeError	`path` is not a string.
rb_eArgError	`path` is broken as a pathname.
rb_eEncCompatError	`path` is incompatible with pathnames.
rb_eLoadError	`path` not found.
rb_eException	Any exceptions while loading the contents.

Definition at line 856 of file load.c.

Referenced by rb_load_protect().

◆ rb_load_protect()

void rb_load_protect	(	VALUE	path,
		int	wrap,
		int *	state
	)

Identical to rb_load(), except it avoids potential global escapes.

Such global escapes include exceptions, throw, break, for example.

It first evaluates the given file as rb_load() does. If no global escape occurred during the evaluation, it *state is set to zero on return. Otherwise, it sets *state to nonzero. If state is NULL, it is not set in both cases.

Parameters

[in]	path	Pathname of a file to load.
[in]	wrap	Either to load under an anonymous module.
[out]	state	State of execution.

Postcondition: *state is set to zero if succeeded. Nonzero otherwise.

Warning: You have to clear the error info with rb_set_errinfo(Qnil) if you decide to ignore the caught exception.

See also: rb_load; rb_protect

Definition at line 864 of file load.c.

◆ rb_provide()

void rb_provide ( const char * feature )

Declares that the given feature is already provided by someone else.

This API can be handy when you have an extension called foo.so which, when required, also provides functionality of bar.so.

Parameters

[in] feature Name of a library which had already been provided.

Postcondition: No further require would search feature.

Definition at line 715 of file load.c.

◆ rb_provided()

int rb_provided ( const char * feature )

Queries if the given feature has already been loaded into the execution context.

The "feature" head are things like "json" or "socket".

Parameters

[in] feature Name of a library you want to know about.

Return values

1	Yes there is.
0	Not yet.

Definition at line 654 of file load.c.

◆ rb_require_string()

VALUE rb_require_string ( VALUE feature )

Finds and loads the given feature, if absent.

If the feature is an absolute path (e.g. starts with ‘’/'`), the feature will be loaded directly using the absolute path. If the feature is an explicit relative path (e.g. starts with ‘’./'or'../'`), the feature will be loaded using the relative path from the current directory. Otherwise, the feature will be searched for in the library directories listed in the $LOAD_PATH.

If the feature has the extension ".rb", it is loaded as a source file; if the extension is ".so", ".o", or ".dll", or the default shared library extension on the current platform, Ruby loads the shared library as a Ruby extension. Otherwise, Ruby tries adding ".rb", ".so", and so on to the name until found. If the file named cannot be found, a LoadError will be raised.

For extension libraries the given feature may use any shared library extension. For example, on Linux you can require "socket.dll" to actually load socket.so.

The absolute path of the loaded file is added to $LOADED_FEATURES. A file will not be loaded again if its path already appears in there.

Any constants or globals within the loaded source file will be available in the calling program's global namespace. However, local variables will not be propagated to the loading environment.

Parameters

[in] feature Name of a feature, e.g. "json".

Exceptions

rb_eLoadError	No such feature.
rb_eRuntimeError	`$"` is frozen; unable to push.

Return values

RUBY_Qtrue	The feature is loaded for the first time.
RUBY_Qfalse	The feature has already been loaded.

Postcondition: $" is updated.

Definition at line 1385 of file load.c.

Referenced by rb_f_require().

(892c46283a5ea4179500d951c9d4866c0051f27b)

Macros

Functions

extension configuration

Detailed Description

Macro Definition Documentation

◆ HAVE_RB_EXT_RACTOR_SAFE

◆ HAVE_RB_EXT_RESOLVE_SYMBOL

◆ RB_EXT_RACTOR_SAFE

Function Documentation

◆ rb_ext_ractor_safe()

◆ rb_ext_resolve_symbol()

◆ rb_f_require()

◆ rb_feature_provided()

◆ rb_load()

◆ rb_load_protect()

◆ rb_provide()

◆ rb_provided()

◆ rb_require_string()