Current File : //opt/alt/ruby33/include/ruby/internal/intern/load.h
#ifndef RBIMPL_INTERN_LOAD_H /*-*-C++-*-vi:se ft=cpp:*/
#define RBIMPL_INTERN_LOAD_H
/**
* @file
* @author Ruby developers <ruby-core@ruby-lang.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.
* @brief Public APIs related to ::rb_f_require().
*/
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/value.h"
RBIMPL_SYMBOL_EXPORT_BEGIN()
/* load.c */
/**
* 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.
*
* @param[in] path Pathname of a file to load.
* @param[in] wrap Either to load under an anonymous module.
* @exception rb_eTypeError `path` is not a string.
* @exception rb_eArgError `path` is broken as a pathname.
* @exception rb_eEncCompatError `path` is incompatible with pathnames.
* @exception rb_eLoadError `path` not found.
* @exception rb_eException Any exceptions while loading the contents.
*
* @internal
*
* It seems this function is under the rule of bootsnap's regime?
*/
void rb_load(VALUE path, int wrap);
/**
* 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.
*
* @param[in] path Pathname of a file to load.
* @param[in] wrap Either to load under an anonymous module.
* @param[out] state State of execution.
* @post `*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 rb_load
* @see rb_protect
*
* @internal
*
* Though not a part of our public API, `state` is in fact an
* enum ruby_tag_type. You can see the potential "nonzero" values by looking
* at vm_core.h.
*/
void rb_load_protect(VALUE path, int wrap, int *state);
RBIMPL_ATTR_NONNULL(())
/**
* Queries if the given feature has already been loaded into the execution
* context. The "feature" head are things like `"json"` or `"socket"`.
*
* @param[in] feature Name of a library you want to know about.
* @retval 1 Yes there is.
* @retval 0 Not yet.
*/
int rb_provided(const char *feature);
RBIMPL_ATTR_NONNULL((1))
/**
* 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`.
*
* @param[in] feature Name of a library you want to know about.
* @param[out] loading Return buffer.
* @retval 1 Yes there is.
* @retval 0 Not yet.
*/
int rb_feature_provided(const char *feature, const char **loading);
RBIMPL_ATTR_NONNULL(())
/**
* 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`.
*
* @param[in] feature Name of a library which had already been provided.
* @post No further `require` would search `feature`.
*/
void rb_provide(const char *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.
*
* @param[in] self Ignored. Can be anything.
* @param[in] feature Name of a feature, e.g. `"json"`.
* @exception rb_eLoadError No such feature.
* @exception 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 `$"` is updated.
*/
VALUE rb_f_require(VALUE self, 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.
*
* @param[in] feature Name of a feature, e.g. `"json"`.
* @exception rb_eLoadError No such feature.
* @exception 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 `$"` is updated.
*/
VALUE rb_require_string(VALUE feature);
/**
* 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.
*
* @param[in] feature Name of a feature, e.g. `"json"`.
* @param[in] symbol Name of a symbol defined by the feature.
* @return 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.
*/
void *rb_ext_resolve_symbol(const char *feature, const char *symbol);
/**
* This macro is to provide backwards compatibility. It provides a way to
* define function prototypes and resolving function symbols in a safe way.
*
* ```CXX
* // 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
* ```
*/
#define HAVE_RB_EXT_RESOLVE_SYMBOL 1
/**
* @name extension configuration
* @{
*/
/**
* 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.
*
* @param[in] flag Either the library is aware of Ractors or not.
* @post Methods would be callable form Ractors, if `flag` is true.
*/
void rb_ext_ractor_safe(bool flag);
/** @alias{rb_ext_ractor_safe} */
#define RB_EXT_RACTOR_SAFE(f) rb_ext_ractor_safe(f)
/**
* This macro is to provide backwards compatibility. It must be safe to do
* something like:
*
* ```CXX
* #ifdef HAVE_RB_EXT_RACTOR_SAFE
* rb_ext_ractor_safe(true);
* #endif
* ```
*/
#define HAVE_RB_EXT_RACTOR_SAFE 1
/** @} */
RBIMPL_SYMBOL_EXPORT_END()
#endif /* RBIMPL_INTERN_LOAD_H */