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 */