summaryrefslogtreecommitdiff
path: root/include/ruby/internal/interpreter.h
diff options
context:
space:
mode:
Diffstat (limited to 'include/ruby/internal/interpreter.h')
-rw-r--r--include/ruby/internal/interpreter.h235
1 files changed, 223 insertions, 12 deletions
diff --git a/include/ruby/internal/interpreter.h b/include/ruby/internal/interpreter.h
index 29dee60aab..a10e7ad2d8 100644
--- a/include/ruby/internal/interpreter.h
+++ b/include/ruby/internal/interpreter.h
@@ -17,10 +17,11 @@
* 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.
+ * extension libraries. They could be written in C++98.
* @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,275 @@ 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(void *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(volatile 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(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()