Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Macros | Functions
load.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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:

Go to the source code of 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
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
#endif
void rb_ext_ractor_safe(bool flag)
Asserts that the extension library that calls this function is aware of Ractor.
Definition: load.c:1220

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
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 symb...
Definition: load.c:1568
uintptr_t VALUE
Type that represents a Ruby object.
Definition: value.h:40

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]flagEither the library is aware of Ractors or not.
Postcondition
Methods would be callable form Ractors, if flag is true.

Definition at line 1220 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]featureName of a feature, e.g. "json".
[in]symbolName 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 1568 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]selfIgnored. Can be anything.
[in]featureName of a feature, e.g. "json".
Exceptions
rb_eLoadErrorNo such feature.
rb_eRuntimeError$" is frozen; unable to push.
Return values
RUBY_QtrueThe feature is loaded for the first time.
RUBY_QfalseThe feature has already been loaded.
Postcondition
$" is updated.

Definition at line 1019 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]featureName of a library you want to know about.
[out]loadingReturn buffer.
Return values
1Yes there is.
0Not yet.

Definition at line 686 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]pathPathname of a file to load.
[in]wrapEither to load under an anonymous module.
Exceptions
rb_eTypeErrorpath is not a string.
rb_eArgErrorpath is broken as a pathname.
rb_eEncCompatErrorpath is incompatible with pathnames.
rb_eLoadErrorpath not found.
rb_eExceptionAny exceptions while loading the contents.

Definition at line 848 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]pathPathname of a file to load.
[in]wrapEither to load under an anonymous module.
[out]stateState 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 856 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]featureName of a library which had already been provided.
Postcondition
No further require would search feature.

Definition at line 714 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]featureName of a library you want to know about.
Return values
1Yes there is.
0Not yet.

Definition at line 653 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]featureName of a feature, e.g. "json".
Exceptions
rb_eLoadErrorNo such feature.
rb_eRuntimeError$" is frozen; unable to push.
Return values
RUBY_QtrueThe feature is loaded for the first time.
RUBY_QfalseThe feature has already been loaded.
Postcondition
$" is updated.

Definition at line 1377 of file load.c.

Referenced by rb_f_require().