mirror of
https://github.com/ruby/ruby.git
synced 2022-11-09 12:17:21 -05:00
include/ruby/internal/interpreter.h: add doxygen
Must not be a bad idea to improve documents. [ci skip] In fact many functions declared in the header file are already documented more or less. They were just copy & pasted, with applying some style updates.
This commit is contained in:
卜部昌平
parent
03fd22a170
commit
f83b14af24
Notes:
git
2021-09-10 20:01:50 +09:00
5 changed files with 226 additions and 85 deletions
55
eval.c
55
eval.c
|
|
@ -61,11 +61,6 @@ extern ID ruby_static_id_cause;
|
|||
(!SPECIAL_CONST_P(obj) && \
|
||||
(BUILTIN_TYPE(obj) == T_CLASS || BUILTIN_TYPE(obj) == T_MODULE))
|
||||
|
||||
/*!
|
||||
* Initializes the VM and builtin libraries.
|
||||
* @retval 0 if succeeded.
|
||||
* @retval non-zero an error occurred.
|
||||
*/
|
||||
int
|
||||
ruby_setup(void)
|
||||
{
|
||||
|
|
@ -99,11 +94,6 @@ ruby_setup(void)
|
|||
return state;
|
||||
}
|
||||
|
||||
/*!
|
||||
* Calls ruby_setup() and check error.
|
||||
*
|
||||
* Prints errors and calls exit(3) if an error occurred.
|
||||
*/
|
||||
void
|
||||
ruby_init(void)
|
||||
{
|
||||
|
|
@ -115,16 +105,6 @@ ruby_init(void)
|
|||
}
|
||||
}
|
||||
|
||||
/*! Processes command line arguments and compiles the Ruby source to execute.
|
||||
*
|
||||
* This function does:
|
||||
* \li Processes the given command line flags and arguments for ruby(1)
|
||||
* \li compiles the source code from the given argument, -e or stdin, and
|
||||
* \li returns the compiled source as an opaque pointer to an internal data structure
|
||||
*
|
||||
* @return an opaque pointer to the compiled source or an internal special value.
|
||||
* @sa ruby_executable_node().
|
||||
*/
|
||||
void *
|
||||
ruby_options(int argc, char **argv)
|
||||
{
|
||||
|
|
@ -184,13 +164,6 @@ rb_ec_finalize(rb_execution_context_t *ec)
|
|||
rb_objspace_call_finalizer(rb_ec_vm_ptr(ec)->objspace);
|
||||
}
|
||||
|
||||
/** Runs the VM finalization processes.
|
||||
*
|
||||
* <code>END{}</code> and procs registered by <code>Kernel.#at_exit</code> are
|
||||
* executed here. See the Ruby language spec for more details.
|
||||
*
|
||||
* @note This function is allowed to raise an exception if an error occurred.
|
||||
*/
|
||||
void
|
||||
ruby_finalize(void)
|
||||
{
|
||||
|
|
@ -199,16 +172,6 @@ ruby_finalize(void)
|
|||
rb_ec_finalize(ec);
|
||||
}
|
||||
|
||||
/** Destructs the VM.
|
||||
*
|
||||
* Runs the VM finalization processes as well as ruby_finalize(), and frees
|
||||
* resources used by the VM.
|
||||
*
|
||||
* @param ex Default value to the return value.
|
||||
* @return If an error occurred returns a non-zero. If otherwise, returns the
|
||||
* given ex.
|
||||
* @note This function does not raise any exception.
|
||||
*/
|
||||
int
|
||||
ruby_cleanup(int ex)
|
||||
{
|
||||
|
|
@ -322,25 +285,12 @@ rb_ec_exec_node(rb_execution_context_t *ec, void *n)
|
|||
return state;
|
||||
}
|
||||
|
||||
/*! Calls ruby_cleanup() and exits the process */
|
||||
void
|
||||
ruby_stop(int ex)
|
||||
{
|
||||
exit(ruby_cleanup(ex));
|
||||
}
|
||||
|
||||
/*! Checks the return value of ruby_options().
|
||||
* @param n return value of ruby_options().
|
||||
* @param status pointer to the exit status of this process.
|
||||
*
|
||||
* ruby_options() sometimes returns a special value to indicate this process
|
||||
* should immediately exit. This function checks if the case. Also stores the
|
||||
* exit status that the caller have to pass to exit(3) into
|
||||
* <code>*status</code>.
|
||||
*
|
||||
* @retval non-zero if the given opaque pointer is actually a compiled source.
|
||||
* @retval 0 if the given value is such a special value.
|
||||
*/
|
||||
int
|
||||
ruby_executable_node(void *n, int *status)
|
||||
{
|
||||
|
|
@ -358,10 +308,6 @@ ruby_executable_node(void *n, int *status)
|
|||
return FALSE;
|
||||
}
|
||||
|
||||
/*! Runs the given compiled source and exits this process.
|
||||
* @retval 0 if successfully run the source
|
||||
* @retval non-zero if an error occurred.
|
||||
*/
|
||||
int
|
||||
ruby_run_node(void *n)
|
||||
{
|
||||
|
|
@ -375,7 +321,6 @@ ruby_run_node(void *n)
|
|||
return rb_ec_cleanup(ec, rb_ec_exec_node(ec, n));
|
||||
}
|
||||
|
||||
/*! Runs the given compiled source */
|
||||
int
|
||||
ruby_exec_node(void *n)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -21,6 +21,7 @@
|
|||
* @brief Interpreter embedding APIs.
|
||||
*/
|
||||
#include "ruby/internal/attr/noreturn.h"
|
||||
#include "ruby/internal/attr/nonnull.h"
|
||||
#include "ruby/internal/dllexport.h"
|
||||
#include "ruby/internal/value.h"
|
||||
|
||||
|
|
@ -28,65 +29,279 @@ RBIMPL_SYMBOL_EXPORT_BEGIN()
|
|||
|
||||
/**
|
||||
* @defgroup embed CRuby Embedding APIs
|
||||
*
|
||||
* CRuby interpreter APIs. These are APIs to embed MRI interpreter into your
|
||||
* program.
|
||||
* These functions are not a part of Ruby extension library API.
|
||||
* Extension libraries of Ruby should not depend on these functions.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/** @defgroup ruby1 ruby(1) implementation
|
||||
/**
|
||||
* @defgroup ruby1 ruby(1) implementation
|
||||
*
|
||||
* A part of the implementation of ruby(1) command.
|
||||
* Other programs that embed Ruby interpreter do not always need to use these
|
||||
* functions.
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
RBIMPL_ATTR_NONNULL(())
|
||||
/**
|
||||
* Initializes the process for libruby.
|
||||
*
|
||||
* This function assumes this process is `ruby(1)` and it has just started.
|
||||
* Usually programs that embed CRuby interpreter may not call this function,
|
||||
* and may do their own initialization.
|
||||
*
|
||||
* @param[in] argc Pointer to process main's `argc`.
|
||||
* @param[in] argv Pointer to process main's `argv`.
|
||||
* @warning `argc` and `argv` cannot be `NULL`.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* AFAIK Ruby does write to argv, especially `argv[0][0]`, via setproctitle(3).
|
||||
* It is intentional that the argument is not const-qualified.
|
||||
*/
|
||||
void ruby_sysinit(int *argc, char ***argv);
|
||||
|
||||
/**
|
||||
* Calls ruby_setup() and check error.
|
||||
*
|
||||
* Prints errors and calls exit(3) if an error occurred.
|
||||
*/
|
||||
void ruby_init(void);
|
||||
|
||||
/**
|
||||
* Processes command line arguments and compiles the Ruby source to execute.
|
||||
*
|
||||
* This function does:
|
||||
* - Processes the given command line flags and arguments for `ruby(1)`
|
||||
* - Compiles the source code from the given argument, `-e` or `stdin`, and
|
||||
* - Returns the compiled source as an opaque pointer to an internal data
|
||||
* structure
|
||||
*
|
||||
* @param[in] argc Process main's `argc`.
|
||||
* @param[in] argv Process main's `argv`.
|
||||
* @return An opaque pointer to the compiled source or an internal special
|
||||
* value. Pass it to ruby_executable_node() to detect which.
|
||||
* @see ruby_executable_node
|
||||
*/
|
||||
void* ruby_options(int argc, char** argv);
|
||||
|
||||
/**
|
||||
* Checks the return value of ruby_options().
|
||||
*
|
||||
* ruby_options() sometimes returns a special value to indicate this process
|
||||
* should immediately exit. This function checks if the case. Also stores the
|
||||
* exit status that the caller have to pass to exit(3) into `*status`.
|
||||
*
|
||||
* @param[in] n A return value of ruby_options().
|
||||
* @param[out] status Pointer to the exit status of this process.
|
||||
* @retval 0 The given value is such a special value.
|
||||
* @retval otherwise The given opaque pointer is actually a compiled
|
||||
* source.
|
||||
*/
|
||||
int ruby_executable_node(void *n, int *status);
|
||||
|
||||
/**
|
||||
* Runs the given compiled source and exits this process.
|
||||
*
|
||||
* @param[in] n Opaque "node" pointer.
|
||||
* @retval EXIT_SUCCESS Successfully run the source.
|
||||
* @retval EXIT_FAILURE An error occurred.
|
||||
*/
|
||||
int ruby_run_node(void *n);
|
||||
|
||||
/* version.c */
|
||||
/** Prints the version information of the CRuby interpreter to stdout. */
|
||||
void ruby_show_version(void);
|
||||
|
||||
#ifndef ruby_show_copyright
|
||||
/** Prints the copyright notice of the CRuby interpreter to stdout. */
|
||||
void ruby_show_copyright(void);
|
||||
#endif
|
||||
|
||||
/*! A convenience macro to call ruby_init_stack(). Must be placed just after
|
||||
* variable declarations */
|
||||
/**
|
||||
* A convenience macro to call ruby_init_stack().
|
||||
* Must be placed just after variable declarations.
|
||||
*/
|
||||
#define RUBY_INIT_STACK \
|
||||
VALUE variable_in_this_stack_frame; \
|
||||
ruby_init_stack(&variable_in_this_stack_frame);
|
||||
/*! @} */
|
||||
/** @} */
|
||||
|
||||
void ruby_init_stack(volatile VALUE*);
|
||||
/**
|
||||
* Set stack bottom of Ruby implementation.
|
||||
*
|
||||
* You must call this function before any heap allocation by Ruby
|
||||
* implementation. Or GC will break living objects.
|
||||
*
|
||||
* @param[in] addr A pointer somewhere on the stack, near its bottom.
|
||||
*/
|
||||
void ruby_init_stack(volatile VALUE *addr);
|
||||
|
||||
/**
|
||||
* Initializes the VM and builtin libraries.
|
||||
*
|
||||
* @retval 0 Initialization succeeded.
|
||||
* @retval otherwise An error occurred.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* Though not a part of our public API, the return value is in fact an enum
|
||||
* ruby_tag_type. You can see the potential "otherwise" values by looking at
|
||||
* vm_core.h.
|
||||
*/
|
||||
int ruby_setup(void);
|
||||
int ruby_cleanup(int);
|
||||
|
||||
/**
|
||||
* Destructs the VM.
|
||||
*
|
||||
* Runs the VM finalization processes as well as ruby_finalize(), and frees
|
||||
* resources used by the VM.
|
||||
*
|
||||
* @param[in] ex Default value to the return value.
|
||||
* @retval EXIT_FAILURE An error occurred.
|
||||
* @retval ex Successful cleanup.
|
||||
* @note This function does not raise any exception.
|
||||
*/
|
||||
int ruby_cleanup(
|
||||
#if !defined(__cplusplus) || __cplusplus <= 201704L
|
||||
volatile /* C++20 killed volatile. cf: http://wg21.link/P1152 */
|
||||
#endif
|
||||
int ex);
|
||||
|
||||
/**
|
||||
* Runs the VM finalization processes.
|
||||
*
|
||||
* `END{}` and procs registered by `Kernel.#at_exit` are executed here. See the
|
||||
* Ruby language spec for more details.
|
||||
*
|
||||
* @note This function is allowed to raise an exception if an error occurred.
|
||||
*/
|
||||
void ruby_finalize(void);
|
||||
|
||||
RBIMPL_ATTR_NORETURN()
|
||||
/** Calls ruby_cleanup() and exits the process. */
|
||||
void ruby_stop(int);
|
||||
|
||||
/**
|
||||
* Checks for stack overflow.
|
||||
*
|
||||
* @retval true NG machine stack is about to overflow.
|
||||
* @retval false OK there still is a room in the stack.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* Does anybody use it? So far @shyouhei have never seen any actual use-case.
|
||||
*/
|
||||
int ruby_stack_check(void);
|
||||
size_t ruby_stack_length(VALUE**);
|
||||
|
||||
/**
|
||||
* Queries what Ruby thinks is the machine stack. Ruby manages a region of
|
||||
* memory. It calls that area the "machine stack". By calling this function,
|
||||
* in spite of its name, you can obtain both one end of the stack and its
|
||||
* length at once. Which means you can know the entire region.
|
||||
*
|
||||
* @param[out] topnotch On return the pointer points to the upmost address of
|
||||
* the macihne stack that Ruby knows.
|
||||
* @return Length of the machine stack that Ruby knows.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* Does anybody use it? @shyouhei is quite skeptical if this is useful outside
|
||||
* of the VM. Maybe it was a wrong idea to expose this API to 3rd parties.
|
||||
*/
|
||||
size_t ruby_stack_length(VALUE **topnotch);
|
||||
|
||||
/**
|
||||
* Identical to ruby_run_node(), except it returns an opaque execution status.
|
||||
* You can pass it to rb_cleanup().
|
||||
*
|
||||
* @param[in] n Opaque "node" pointer.
|
||||
* @retval 0 Successful end-of-execution.
|
||||
* @retval otherwise An error occurred.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* Though not a part of our public API, the return value is in fact an enum
|
||||
* ruby_tag_type. You can see the potential "otherwise" values by looking at
|
||||
* vm_core.h.
|
||||
*/
|
||||
int ruby_exec_node(void *n);
|
||||
|
||||
/**
|
||||
* Sets the current script name to this value.
|
||||
*
|
||||
* This is similar to `$0 = name` in Ruby level but also affects
|
||||
* `Method#location` and others.
|
||||
*
|
||||
* @param[in] name File name to set.
|
||||
*/
|
||||
void ruby_script(const char* name);
|
||||
|
||||
/**
|
||||
* Identical to ruby_script(), except it takes the name as a Ruby String
|
||||
* instance.
|
||||
*
|
||||
* @param[in] name File name to set.
|
||||
*/
|
||||
void ruby_set_script_name(VALUE name);
|
||||
|
||||
/** Defines built-in variables */
|
||||
void ruby_prog_init(void);
|
||||
void ruby_set_argv(int, char**);
|
||||
void *ruby_process_options(int, char**);
|
||||
|
||||
/**
|
||||
* Sets argv that ruby understands. Your program might have its own command
|
||||
* line parameters etc. Handle them as you wish, and pass remaining parts of
|
||||
* argv here.
|
||||
*
|
||||
* @param[in] argc Number of elements of `argv`.
|
||||
* @param[in] argv Command line arguments.
|
||||
*/
|
||||
void ruby_set_argv(int argc, char **argv);
|
||||
|
||||
/**
|
||||
* Identical to ruby_options(), except it raises ruby-level exceptions on
|
||||
* failure.
|
||||
*
|
||||
* @param[in] argc Process main's `argc`.
|
||||
* @param[in] argv Process main's `argv`.
|
||||
* @return An opaque "node" pointer.
|
||||
*/
|
||||
void *ruby_process_options(int argc, char **argv);
|
||||
|
||||
/**
|
||||
* Sets up `$LOAD_PATH`.
|
||||
*
|
||||
* @internal
|
||||
*
|
||||
* @shyouhei guesses this has to be called at very later stage, at least after
|
||||
* the birth of object system. But is not exactly sure when.
|
||||
*/
|
||||
void ruby_init_loadpath(void);
|
||||
void ruby_incpush(const char*);
|
||||
|
||||
/**
|
||||
* Appends the given path to the end of the load path.
|
||||
*
|
||||
* @pre ruby_init_loadpath() must be done beforehand.
|
||||
* @param[in] path The path you want to push to the load path.
|
||||
*/
|
||||
void ruby_incpush(const char *path);
|
||||
|
||||
/**
|
||||
* Clear signal handlers.
|
||||
*
|
||||
* Ruby installs its own signal handler (apart from those which user scripts
|
||||
* set). This is to clear that. Must be called when the ruby part terminates,
|
||||
* before switching to your program's own logic.
|
||||
*/
|
||||
void ruby_sig_finalize(void);
|
||||
|
||||
/*! @} */
|
||||
/** @} */
|
||||
|
||||
RBIMPL_SYMBOL_EXPORT_END()
|
||||
|
||||
|
|
|
|||
13
ruby.c
13
ruby.c
|
|
@ -2436,11 +2436,6 @@ external_str_new_cstr(const char *p)
|
|||
#endif
|
||||
}
|
||||
|
||||
/*! Sets the current script name to this value.
|
||||
*
|
||||
* This is similar to <code>$0 = name</code> in Ruby level but also affects
|
||||
* <code>Method#location</code> and others.
|
||||
*/
|
||||
void
|
||||
ruby_script(const char *name)
|
||||
{
|
||||
|
|
@ -2524,7 +2519,6 @@ debug_setter(VALUE val, ID id, VALUE *dmy)
|
|||
*rb_ruby_debug_ptr() = val;
|
||||
}
|
||||
|
||||
/*! Defines built-in variables */
|
||||
void
|
||||
ruby_prog_init(void)
|
||||
{
|
||||
|
|
@ -2625,13 +2619,6 @@ fill_standard_fds(void)
|
|||
}
|
||||
}
|
||||
|
||||
/*! Initializes the process for libruby.
|
||||
*
|
||||
* This function assumes this process is ruby(1) and it has just started.
|
||||
* Usually programs that embed CRuby interpreter may not call this function,
|
||||
* and may do their own initialization.
|
||||
* argc and argv cannot be NULL.
|
||||
*/
|
||||
void
|
||||
ruby_sysinit(int *argc, char ***argv)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -908,10 +908,6 @@ reserve_stack(volatile char *limit, size_t size)
|
|||
#endif
|
||||
|
||||
#undef ruby_init_stack
|
||||
/* Set stack bottom of Ruby implementation.
|
||||
*
|
||||
* You must call this function before any heap allocation by Ruby implementation.
|
||||
* Or GC will break living objects */
|
||||
void
|
||||
ruby_init_stack(volatile VALUE *addr)
|
||||
{
|
||||
|
|
|
|||
|
|
@ -114,7 +114,6 @@ Init_ruby_description(void)
|
|||
rb_define_global_const("RUBY_DESCRIPTION", /* MKSTR(description) */ description);
|
||||
}
|
||||
|
||||
/*! Prints the version information of the CRuby interpreter to stdout. */
|
||||
void
|
||||
ruby_show_version(void)
|
||||
{
|
||||
|
|
@ -133,7 +132,6 @@ ruby_show_version(void)
|
|||
fflush(stdout);
|
||||
}
|
||||
|
||||
/*! Prints the copyright notice of the CRuby interpreter to stdout. */
|
||||
void
|
||||
ruby_show_copyright(void)
|
||||
{
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue