Ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e0ba6b95ab71a441357ed5484e33498)
Functions
load.h File Reference

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

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

Go to the source code of this file.

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

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:1074

Definition at line 212 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 200 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 1074 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$"</tt> is frozen; unable to push. @retval RUBY_Qtrue The feature is loaded for the first time. @retval RUBY_Qfalse The feature has already been loaded. @post <tt>$" is updated.

Definition at line 906 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 610 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 727 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 735 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 638 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 577 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$"</tt> is frozen; unable to push. @retval RUBY_Qtrue The feature is loaded for the first time. @retval RUBY_Qfalse The feature has already been loaded. @post <tt>$" is updated.

Definition at line 1224 of file load.c.

Referenced by rb_f_require(), and rb_require().