Ruby: include/ruby/internal/intern/load.h File Reference

Ruby 3.3.6p108 (2024-11-05 revision 75015d4c1f6965b5e85e96fb309f1f2129f933c0)

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

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

## Functions
void | rb_load (VALUE path, int wrap)
| Loads and executes the Ruby program in the given file.
void | rb_load_protect (VALUE path, int wrap, int *state)
| Identical to rb_load(), except it avoids potential global escapes.
int | rb_provided (const char *feature)
| Queries if the given feature has already been loaded into the execution context.
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.
void | rb_provide (const char *feature)
| Declares that the given feature is already provided by someone else.
VALUE | rb_f_require (VALUE self, VALUE feature)
| Identical to rb_require_string(), except it ignores the first argument for no reason.
VALUE | rb_require_string (VALUE feature)
| Finds and loads the given feature, if absent.
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.

## extension configuration
#define | RB_EXT_RACTOR_SAFE(f)
| Just another name of rb_ext_ractor_safe.
#define | HAVE_RB_EXT_RACTOR_SAFE 1
| This macro is to provide backwards compatibility.
void | rb_ext_ractor_safe (bool flag)
| Asserts that the extension library that calls this function is aware of Ractor.

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

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
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 symb...
Definition load.c:1550
VALUE
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 | ) |

Value:
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 1214 of file load.c.

Referenced by rb_ext_ractor_safe().

## ◆ 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 1550 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. @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 1013 of file load.c.

Referenced by rb_f_require().

## ◆ 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 686 of file load.c.

Referenced by rb_feature_provided(), and 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 841 of file load.c.

Referenced by rb_load(), and 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 849 of file load.c.

Referenced by rb_load_protect().

## ◆ 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 714 of file load.c.

Referenced by rb_provide().

## ◆ 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 653 of file load.c.

Referenced by rb_provided().

## ◆ 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. @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 1371 of file load.c.

Referenced by rb_f_require().