diff options
Diffstat (limited to 'include/ruby')
143 files changed, 13752 insertions, 3584 deletions
diff --git a/include/ruby/assert.h b/include/ruby/assert.h index c9f2c3fbef..acc5e5bbfc 100644 --- a/include/ruby/assert.h +++ b/include/ruby/assert.h @@ -22,6 +22,7 @@ */ #include "ruby/internal/assume.h" #include "ruby/internal/attr/cold.h" +#include "ruby/internal/attr/format.h" #include "ruby/internal/attr/noreturn.h" #include "ruby/internal/cast.h" #include "ruby/internal/dllexport.h" @@ -103,7 +104,7 @@ # /* keep NDEBUG undefined */ #elif (RBIMPL_NDEBUG == 0) && (RBIMPL_RUBY_DEBUG == 0) -# /* The (*1) situation in avobe diagram. */ +# /* The (*1) situation in above diagram. */ # define RUBY_DEBUG 0 # define RUBY_NDEBUG 1 # define NDEBUG @@ -132,6 +133,11 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() RBIMPL_ATTR_NORETURN() RBIMPL_ATTR_COLD() void rb_assert_failure(const char *file, int line, const char *name, const char *expr); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 5, 6) +void rb_assert_failure_detail(const char *file, int line, const char *name, const char *expr, const char *fmt, ...); RBIMPL_SYMBOL_EXPORT_END() #ifdef RUBY_FUNCTION_NAME_STRING @@ -147,8 +153,28 @@ RBIMPL_SYMBOL_EXPORT_END() * * @param mesg The message to display. */ -#define RUBY_ASSERT_FAIL(mesg) \ +#if defined(HAVE___VA_OPT__) +# if RBIMPL_HAS_WARNING("-Wgnu-zero-variadic-macro-arguments") +/* __VA_OPT__ is to be used for the zero variadic macro arguments + * cases. */ +RBIMPL_WARNING_IGNORED(-Wgnu-zero-variadic-macro-arguments) +# endif +# define RBIMPL_VA_OPT_ARGS(...) __VA_OPT__(,) __VA_ARGS__ + +# define RUBY_ASSERT_FAIL(mesg, ...) \ + rb_assert_failure##__VA_OPT__(_detail)( \ + __FILE__, __LINE__, RBIMPL_ASSERT_FUNC, mesg RBIMPL_VA_OPT_ARGS(__VA_ARGS__)) +#elif !defined(__cplusplus) +# define RBIMPL_VA_OPT_ARGS(...) + +# define RUBY_ASSERT_FAIL(mesg, ...) \ rb_assert_failure(__FILE__, __LINE__, RBIMPL_ASSERT_FUNC, mesg) +#else +# undef RBIMPL_VA_OPT_ARGS + +# define RUBY_ASSERT_FAIL(mesg) \ + rb_assert_failure(__FILE__, __LINE__, RBIMPL_ASSERT_FUNC, mesg) +#endif /** * Asserts that the expression is truthy. If not aborts with the message. @@ -156,15 +182,25 @@ RBIMPL_SYMBOL_EXPORT_END() * @param expr What supposedly evaluates to true. * @param mesg The message to display on failure. */ -#define RUBY_ASSERT_MESG(expr, mesg) \ +#if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT_MESG(expr, ...) \ + (RB_LIKELY(expr) ? RBIMPL_ASSERT_NOTHING : RUBY_ASSERT_FAIL(__VA_ARGS__)) +#else +# define RUBY_ASSERT_MESG(expr, mesg) \ (RB_LIKELY(expr) ? RBIMPL_ASSERT_NOTHING : RUBY_ASSERT_FAIL(mesg)) +#endif /** * A variant of #RUBY_ASSERT that does not interface with #RUBY_DEBUG. * * @copydetails #RUBY_ASSERT */ -#define RUBY_ASSERT_ALWAYS(expr) RUBY_ASSERT_MESG((expr), #expr) +#if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT_ALWAYS(expr, ...) \ + RUBY_ASSERT_MESG(expr, #expr RBIMPL_VA_OPT_ARGS(__VA_ARGS__)) +#else +# define RUBY_ASSERT_ALWAYS(expr) RUBY_ASSERT_MESG((expr), #expr) +#endif /** * Asserts that the given expression is truthy if and only if #RUBY_DEBUG is truthy. @@ -172,9 +208,18 @@ RBIMPL_SYMBOL_EXPORT_END() * @param expr What supposedly evaluates to true. */ #if RUBY_DEBUG -# define RUBY_ASSERT(expr) RUBY_ASSERT_MESG((expr), #expr) +# if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT(expr, ...) \ + RUBY_ASSERT_MESG((expr), #expr RBIMPL_VA_OPT_ARGS(__VA_ARGS__)) +# else +# define RUBY_ASSERT(expr) RUBY_ASSERT_MESG((expr), #expr) +# endif #else -# define RUBY_ASSERT(expr) RBIMPL_ASSERT_NOTHING +# if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT(/* expr, */...) RBIMPL_ASSERT_NOTHING +# else +# define RUBY_ASSERT(expr) RBIMPL_ASSERT_NOTHING +# endif #endif /** @@ -187,9 +232,18 @@ RBIMPL_SYMBOL_EXPORT_END() /* Currently `RUBY_DEBUG == ! defined(NDEBUG)` is always true. There is no * difference any longer between this one and `RUBY_ASSERT`. */ #if defined(NDEBUG) -# define RUBY_ASSERT_NDEBUG(expr) RBIMPL_ASSERT_NOTHING +# if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT_NDEBUG(/* expr, */...) RBIMPL_ASSERT_NOTHING +# else +# define RUBY_ASSERT_NDEBUG(expr) RBIMPL_ASSERT_NOTHING +# endif #else -# define RUBY_ASSERT_NDEBUG(expr) RUBY_ASSERT_MESG((expr), #expr) +# if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT_NDEBUG(expr, ...) \ + RUBY_ASSERT_MESG((expr), #expr RBIMPL_VA_OPT_ARGS(__VA_ARGS__)) +# else +# define RUBY_ASSERT_NDEBUG(expr) RUBY_ASSERT_MESG((expr), #expr) +# endif #endif /** @@ -197,10 +251,20 @@ RBIMPL_SYMBOL_EXPORT_END() * @param mesg The message to display on failure. */ #if RUBY_DEBUG -# define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) RUBY_ASSERT_MESG((expr), (mesg)) +# if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT_MESG_WHEN(cond, /* expr, */...) \ + RUBY_ASSERT_MESG(__VA_ARGS__) +# else +# define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) RUBY_ASSERT_MESG((expr), (mesg)) +# endif #else -# define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) \ +# if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT_MESG_WHEN(cond, expr, ...) \ + ((cond) ? RUBY_ASSERT_MESG((expr), __VA_ARGS__) : RBIMPL_ASSERT_NOTHING) +# else +# define RUBY_ASSERT_MESG_WHEN(cond, expr, mesg) \ ((cond) ? RUBY_ASSERT_MESG((expr), (mesg)) : RBIMPL_ASSERT_NOTHING) +# endif #endif /** @@ -210,7 +274,23 @@ RBIMPL_SYMBOL_EXPORT_END() * @param cond Extra condition that shall hold for assertion to take effect. * @param expr What supposedly evaluates to true. */ -#define RUBY_ASSERT_WHEN(cond, expr) RUBY_ASSERT_MESG_WHEN((cond), (expr), #expr) +#if defined(RBIMPL_VA_OPT_ARGS) +# define RUBY_ASSERT_WHEN(cond, expr, ...) \ + RUBY_ASSERT_MESG_WHEN(cond, expr, #expr RBIMPL_VA_OPT_ARGS(__VA_ARGS__)) +#else +# define RUBY_ASSERT_WHEN(cond, expr) RUBY_ASSERT_MESG_WHEN((cond), (expr), #expr) +#endif + +/** + * A variant of #RUBY_ASSERT that asserts when either #RUBY_DEBUG or built-in + * type of `obj` is `type`. + * + * @param obj Object to check its built-in typue. + * @param type Built-in type constant, T_ARRAY, T_STRING, etc. + */ +#define RUBY_ASSERT_BUILTIN_TYPE(obj, type) \ + RUBY_ASSERT(RB_TYPE_P(obj, type), \ + "Actual type is %s", rb_builtin_type_name(BUILTIN_TYPE(obj))) /** * This is either #RUBY_ASSERT or #RBIMPL_ASSUME, depending on #RUBY_DEBUG. @@ -218,17 +298,19 @@ RBIMPL_SYMBOL_EXPORT_END() * @copydetails #RUBY_ASSERT */ #if RUBY_DEBUG -# define RBIMPL_ASSERT_OR_ASSUME(expr) RUBY_ASSERT_ALWAYS(expr) +# define RBIMPL_ASSERT_OR_ASSUME RUBY_ASSERT_ALWAYS +#elif ! defined(RBIMPL_VA_OPT_ARGS) +# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSUME(expr) #elif RBIMPL_COMPILER_BEFORE(Clang, 7, 0, 0) # /* See commit 67d259c5dccd31fe49d417fec169977712ffdf10 */ -# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSERT_NOTHING +# define RBIMPL_ASSERT_OR_ASSUME(...) RBIMPL_ASSERT_NOTHING #elif defined(RUBY_ASSERT_NOASSUME) # /* See commit d300a734414ef6de7e8eb563b7cc4389c455ed08 */ -# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSERT_NOTHING +# define RBIMPL_ASSERT_OR_ASSUME(...) RBIMPL_ASSERT_NOTHING #elif ! defined(RBIMPL_HAVE___ASSUME) -# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSERT_NOTHING +# define RBIMPL_ASSERT_OR_ASSUME(...) RBIMPL_ASSERT_NOTHING #else -# define RBIMPL_ASSERT_OR_ASSUME(expr) RBIMPL_ASSUME(expr) +# define RBIMPL_ASSERT_OR_ASSUME(expr, ...) RBIMPL_ASSUME(expr) #endif #endif /* RUBY_ASSERT_H */ diff --git a/include/ruby/atomic.h b/include/ruby/atomic.h index 083f1f6aa0..fcc48f532c 100644 --- a/include/ruby/atomic.h +++ b/include/ruby/atomic.h @@ -1,236 +1,1145 @@ -#ifndef RUBY_ATOMIC_H +#ifndef RUBY_ATOMIC_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_ATOMIC_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 Atomic operations + * + * Basically, if we could assume either C11 or C++11, these macros are just + * redundant. Sadly we cannot. We have to do them ourselves. + */ + +#include "ruby/internal/config.h" + +#ifdef STDC_HEADERS +# include <stddef.h> /* size_t */ +#endif + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> /* ssize_t */ +#endif + +#if RBIMPL_COMPILER_IS(MSVC) +# pragma intrinsic(_InterlockedOr) +#elif defined(__sun) && defined(HAVE_ATOMIC_H) +# include <atomic.h> +#endif + +#include "ruby/assert.h" +#include "ruby/backward/2/limits.h" +#include "ruby/internal/attr/artificial.h" +#include "ruby/internal/attr/noalias.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/compiler_since.h" +#include "ruby/internal/cast.h" +#include "ruby/internal/value.h" +#include "ruby/internal/static_assert.h" +#include "ruby/internal/stdbool.h" /* - * - RUBY_ATOMIC_CAS, RUBY_ATOMIC_EXCHANGE, RUBY_ATOMIC_FETCH_*: - * return the old value. - * - RUBY_ATOMIC_ADD, RUBY_ATOMIC_SUB, RUBY_ATOMIC_INC, RUBY_ATOMIC_DEC, RUBY_ATOMIC_OR, RUBY_ATOMIC_SET: - * may be void. + * Asserts that your environment supports more than one atomic types. These + * days systems tend to have such property (C11 was a standard of decades ago, + * right?) but we still support older ones. */ -#if 0 -#elif defined HAVE_GCC_ATOMIC_BUILTINS +#if defined(__DOXYGEN__) || defined(HAVE_GCC_ATOMIC_BUILTINS) || defined(HAVE_GCC_SYNC_BUILTINS) +# define RUBY_ATOMIC_GENERIC_MACRO 1 +#endif + +/** + * Type that is eligible for atomic operations. Depending on your host + * platform you might have more than one such type, but we choose one of them + * anyways. + */ +#if defined(__DOXYGEN__) +using rb_atomic_t = std::atomic<unsigned>; +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) +typedef unsigned int rb_atomic_t; +#elif defined(HAVE_GCC_SYNC_BUILTINS) typedef unsigned int rb_atomic_t; -# define RUBY_ATOMIC_FETCH_ADD(var, val) __atomic_fetch_add(&(var), (val), __ATOMIC_SEQ_CST) -# define RUBY_ATOMIC_FETCH_SUB(var, val) __atomic_fetch_sub(&(var), (val), __ATOMIC_SEQ_CST) -# define RUBY_ATOMIC_OR(var, val) __atomic_fetch_or(&(var), (val), __ATOMIC_SEQ_CST) -# define RUBY_ATOMIC_EXCHANGE(var, val) __atomic_exchange_n(&(var), (val), __ATOMIC_SEQ_CST) -# define RUBY_ATOMIC_CAS(var, oldval, newval) RB_GNUC_EXTENSION_BLOCK( \ - __typeof__(var) oldvaldup = (oldval); /* oldval should not be modified */ \ - __atomic_compare_exchange_n(&(var), &oldvaldup, (newval), 0, __ATOMIC_SEQ_CST, __ATOMIC_SEQ_CST); \ - oldvaldup ) +#elif defined(_WIN32) +# include <winsock2.h> // to prevent macro redefinitions +# include <windows.h> // for `LONG` and `Interlocked` functions +typedef LONG rb_atomic_t; +#elif defined(__sun) && defined(HAVE_ATOMIC_H) +typedef unsigned int rb_atomic_t; +#elif defined(HAVE_STDATOMIC_H) +# include <stdatomic.h> +typedef unsigned int rb_atomic_t; +#else +# error No atomic operation found +#endif -# define RUBY_ATOMIC_GENERIC_MACRO 1 +/* Memory ordering constants */ +#if defined(HAVE_GCC_ATOMIC_BUILTINS) +# define RBIMPL_ATOMIC_RELAXED __ATOMIC_RELAXED +# define RBIMPL_ATOMIC_ACQUIRE __ATOMIC_ACQUIRE +# define RBIMPL_ATOMIC_RELEASE __ATOMIC_RELEASE +# define RBIMPL_ATOMIC_ACQ_REL __ATOMIC_ACQ_REL +# define RBIMPL_ATOMIC_SEQ_CST __ATOMIC_SEQ_CST +#elif defined(HAVE_STDATOMIC_H) +# define RBIMPL_ATOMIC_RELAXED memory_order_relaxed +# define RBIMPL_ATOMIC_ACQUIRE memory_order_acquire +# define RBIMPL_ATOMIC_RELEASE memory_order_release +# define RBIMPL_ATOMIC_ACQ_REL memory_order_acq_rel +# define RBIMPL_ATOMIC_SEQ_CST memory_order_seq_cst +#else +/* Dummy values for unsupported platforms */ +# define RBIMPL_ATOMIC_RELAXED 0 +# define RBIMPL_ATOMIC_ACQUIRE 1 +# define RBIMPL_ATOMIC_RELEASE 2 +# define RBIMPL_ATOMIC_ACQ_REL 3 +# define RBIMPL_ATOMIC_SEQ_CST 4 +#endif -#elif defined HAVE_GCC_SYNC_BUILTINS -/* @shyouhei hack to support atomic operations in case of gcc. Gcc - * has its own pseudo-insns to support them. See info, or - * http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html */ +/** + * Atomically replaces the value pointed by `var` with the result of addition + * of `val` to the old value of `var`. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to add. + * @return What was stored in `var` before the addition. + * @post `var` holds `var + val`. + */ +#define RUBY_ATOMIC_FETCH_ADD(var, val) rbimpl_atomic_fetch_add(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) -typedef unsigned int rb_atomic_t; /* Anything OK */ -# define RUBY_ATOMIC_FETCH_ADD(var, val) __sync_fetch_and_add(&(var), (val)) -# define RUBY_ATOMIC_FETCH_SUB(var, val) __sync_fetch_and_sub(&(var), (val)) -# define RUBY_ATOMIC_OR(var, val) __sync_fetch_and_or(&(var), (val)) -# define RUBY_ATOMIC_EXCHANGE(var, val) __sync_lock_test_and_set(&(var), (val)) -# define RUBY_ATOMIC_CAS(var, oldval, newval) __sync_val_compare_and_swap(&(var), (oldval), (newval)) +/** + * Atomically replaces the value pointed by `var` with the result of + * subtraction of `val` to the old value of `var`. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to subtract. + * @return What was stored in `var` before the subtraction. + * @post `var` holds `var - val`. + */ +#define RUBY_ATOMIC_FETCH_SUB(var, val) rbimpl_atomic_fetch_sub(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) -# define RUBY_ATOMIC_GENERIC_MACRO 1 +/** + * Atomically replaces the value pointed by `var` with the result of + * bitwise OR between `val` and the old value of `var`. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to mix. + * @return void + * @post `var` holds `var | val`. + * @note For portability, this macro can return void. + */ +#define RUBY_ATOMIC_OR(var, val) rbimpl_atomic_or(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Atomically replaces the value pointed by `var` with `val`. This is just an + * assignment, but you can additionally know the previous value. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + */ +#define RUBY_ATOMIC_EXCHANGE(var, val) rbimpl_atomic_exchange(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Atomic compare-and-swap. This stores `val` to `var` if and only if the + * assignment changes the value of `var` from `oldval` to `newval`. You can + * detect whether the assignment happened or not using the return value. + * + * @param var A variable of ::rb_atomic_t. + * @param oldval Expected value of `var` before the assignment. + * @param newval What you want to store at `var`. + * @retval oldval Successful assignment (`var` is now `newval`). + * @retval otherwise Something else is at `var`; not updated. + */ +#define RUBY_ATOMIC_CAS(var, oldval, newval) \ + rbimpl_atomic_cas(&(var), (oldval), (newval), RBIMPL_ATOMIC_SEQ_CST, RBIMPL_ATOMIC_SEQ_CST) + +/** + * Atomic load. This loads `var` with an atomic intrinsic and returns + * its value. + * + * @param var A variable of ::rb_atomic_t + * @return What was stored in `var`j + */ +#define RUBY_ATOMIC_LOAD(var) rbimpl_atomic_load(&(var), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except for the return type. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to set. + * @return void + * @post `var` holds `val`. + */ +#define RUBY_ATOMIC_SET(var, val) rbimpl_atomic_store(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_FETCH_ADD, except for the return type. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to add. + * @return void + * @post `var` holds `var + val`. + */ +#define RUBY_ATOMIC_ADD(var, val) rbimpl_atomic_add(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_FETCH_SUB, except for the return type. + * + * @param var A variable of ::rb_atomic_t. + * @param val Value to subtract. + * @return void + * @post `var` holds `var - val`. + */ +#define RUBY_ATOMIC_SUB(var, val) rbimpl_atomic_sub(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Atomically increments the value pointed by `var`. + * + * @param var A variable of ::rb_atomic_t. + * @return void + * @post `var` holds `var + 1`. + */ +#define RUBY_ATOMIC_INC(var) rbimpl_atomic_inc(&(var), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Atomically decrements the value pointed by `var`. + * + * @param var A variable of ::rb_atomic_t. + * @return void + * @post `var` holds `var - 1`. + */ +#define RUBY_ATOMIC_DEC(var) rbimpl_atomic_dec(&(var), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_FETCH_ADD, except it expects its arguments to be `size_t`. + * There are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `size_t`. + * @param val Value to add. + * @return What was stored in `var` before the addition. + * @post `var` holds `var + val`. + */ +#define RUBY_ATOMIC_SIZE_FETCH_ADD(var, val) rbimpl_atomic_size_fetch_add(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_INC, except it expects its argument is `size_t`. + * There are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `size_t`. + * @return void + * @post `var` holds `var + 1`. + */ +#define RUBY_ATOMIC_SIZE_INC(var) rbimpl_atomic_size_inc(&(var), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_DEC, except it expects its argument is `size_t`. + * There are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `size_t`. + * @return void + * @post `var` holds `var - 1`. + */ +#define RUBY_ATOMIC_SIZE_DEC(var) rbimpl_atomic_size_dec(&(var), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except it expects its arguments are + * `size_t`. There are cases where ::rb_atomic_t is 32bit while `size_t` is + * 64bit. This should be used for size related operations to support such + * platforms. + * + * @param var A variable of `size_t`. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + */ +#define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) \ + rbimpl_atomic_size_exchange(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_CAS, except it expects its arguments are `size_t`. + * There are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `size_t`. + * @param oldval Expected value of `var` before the assignment. + * @param newval What you want to store at `var`. + * @retval oldval Successful assignment (`var` is now `newval`). + * @retval otherwise Something else is at `var`; not updated. + */ +#define RUBY_ATOMIC_SIZE_CAS(var, oldval, newval) \ + rbimpl_atomic_size_cas(&(var), (oldval), (newval), RBIMPL_ATOMIC_SEQ_CST, RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_ADD, except it expects its arguments are `size_t`. + * There are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `size_t`. + * @param val Value to add. + * @return void + * @post `var` holds `var + val`. + */ +#define RUBY_ATOMIC_SIZE_ADD(var, val) rbimpl_atomic_size_add(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_SUB, except it expects its arguments are `size_t`. + * There are cases where ::rb_atomic_t is 32bit while `size_t` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `size_t`. + * @param val Value to subtract. + * @return void + * @post `var` holds `var - val`. + */ +#define RUBY_ATOMIC_SIZE_SUB(var, val) rbimpl_atomic_size_sub(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except it expects its arguments are + * `void*`. There are cases where ::rb_atomic_t is 32bit while `void*` is + * 64bit. This should be used for pointer related operations to support such + * platforms. + * + * @param var A variable of `void *`. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + * + * @internal + * + * :FIXME: this `(void*)` cast is evil! However `void*` is incompatible with + * some pointers, most notably function pointers. + */ +#define RUBY_ATOMIC_PTR_EXCHANGE(var, val) \ + RBIMPL_CAST(rbimpl_atomic_ptr_exchange((void **)&(var), (void *)val, RBIMPL_ATOMIC_SEQ_CST)) + +/** + * Identical to #RUBY_ATOMIC_LOAD, except it expects its arguments are `void*`. + * There are cases where ::rb_atomic_t is 32bit while `void*` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `void*` + * @return The value of `var` (without tearing) + */ +#define RUBY_ATOMIC_PTR_LOAD(var) \ + RBIMPL_CAST(rbimpl_atomic_ptr_load((void **)&var, RBIMPL_ATOMIC_SEQ_CST)) + +/** +* Identical to #RUBY_ATOMIC_SET, except it expects its arguments are +* `void*`. There are cases where ::rb_atomic_t is 32bit while ::VALUE is +* 64bit. This should be used for pointer related operations to support such +* platforms. +* +* @param var A variable of `void*`. +* @param val Value to set. +* @post `var` holds `val`. +*/ +#define RUBY_ATOMIC_PTR_SET(var, val) \ + rbimpl_atomic_ptr_store((volatile void **)&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_CAS, except it expects its arguments are `void*`. + * There are cases where ::rb_atomic_t is 32bit while `void*` is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `void*`. + * @param oldval Expected value of `var` before the assignment. + * @param newval What you want to store at `var`. + * @retval oldval Successful assignment (`var` is now `newval`). + * @retval otherwise Something else is at `var`; not updated. + */ +#define RUBY_ATOMIC_PTR_CAS(var, oldval, newval) \ + RBIMPL_CAST(rbimpl_atomic_ptr_cas((void **)&(var), (void *)(oldval), (void *)(newval), RBIMPL_ATOMIC_SEQ_CST, RBIMPL_ATOMIC_SEQ_CST)) + +/** + * Identical to #RUBY_ATOMIC_SET, except it expects its arguments are + * ::VALUE. There are cases where ::rb_atomic_t is 32bit while ::VALUE is + * 64bit. This should be used for pointer related operations to support such + * platforms. + * + * @param var A variable of ::VALUE. + * @param val Value to set. + * @post `var` holds `val`. + */ +#define RUBY_ATOMIC_VALUE_SET(var, val) \ + rbimpl_atomic_value_store(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_EXCHANGE, except it expects its arguments are + * ::VALUE. There are cases where ::rb_atomic_t is 32bit while ::VALUE is + * 64bit. This should be used for pointer related operations to support such + * platforms. + * + * @param var A variable of ::VALUE. + * @param val Value to set. + * @return What was stored in `var` before the assignment. + * @post `var` holds `val`. + */ +#define RUBY_ATOMIC_VALUE_EXCHANGE(var, val) \ + rbimpl_atomic_value_exchange(&(var), (val), RBIMPL_ATOMIC_SEQ_CST) + +/** + * Identical to #RUBY_ATOMIC_CAS, except it expects its arguments are ::VALUE. + * There are cases where ::rb_atomic_t is 32bit while ::VALUE is 64bit. This + * should be used for size related operations to support such platforms. + * + * @param var A variable of `void*`. + * @param oldval Expected value of `var` before the assignment. + * @param newval What you want to store at `var`. + * @retval oldval Successful assignment (`var` is now `newval`). + * @retval otherwise Something else is at `var`; not updated. + */ +#define RUBY_ATOMIC_VALUE_CAS(var, oldval, newval) \ + rbimpl_atomic_value_cas(&(var), (oldval), (newval), RBIMPL_ATOMIC_SEQ_CST, RBIMPL_ATOMIC_SEQ_CST) + +/** @cond INTERNAL_MACRO */ +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline rb_atomic_t +rbimpl_atomic_fetch_add(volatile rb_atomic_t *ptr, rb_atomic_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + return __atomic_fetch_add(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + return __sync_fetch_and_add(ptr, val); + +#elif defined(_WIN32) + return InterlockedExchangeAdd(ptr, val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + /* + * `atomic_add_int_nv` takes its second argument as `int`! Meanwhile our + * `rb_atomic_t` is unsigned. We cannot pass `val` as-is. We have to + * manually check integer overflow. + */ + RBIMPL_ASSERT_OR_ASSUME(val <= INT_MAX); + return atomic_add_int_nv(ptr, val) - val; -#elif defined _WIN32 -#if RBIMPL_COMPILER_SINCE(MSVC, 13, 0, 0) -#pragma intrinsic(_InterlockedOr) +#elif defined(HAVE_STDATOMIC_H) + return atomic_fetch_add_explicit((_Atomic volatile rb_atomic_t *)ptr, val, memory_order); + +#else +# error Unsupported platform. #endif -typedef LONG rb_atomic_t; +} + +/** @cond INTERNAL_MACRO */ +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline size_t +rbimpl_atomic_size_fetch_add(volatile size_t *ptr, size_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + return __atomic_fetch_add(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + return __sync_fetch_and_add(ptr, val); + +#elif defined(_WIN32) + return InterlockedExchangeAdd64(ptr, val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) && (defined(_LP64) || defined(_I32LPx)) + /* Ditto for `atomic_add_int_nv`. */ + RBIMPL_ASSERT_OR_ASSUME(val <= LONG_MAX); + atomic_add_long(ptr, val); -# define RUBY_ATOMIC_SET(var, val) InterlockedExchange(&(var), (val)) -# define RUBY_ATOMIC_INC(var) InterlockedIncrement(&(var)) -# define RUBY_ATOMIC_DEC(var) InterlockedDecrement(&(var)) -# define RUBY_ATOMIC_FETCH_ADD(var, val) InterlockedExchangeAdd(&(var), (val)) -# define RUBY_ATOMIC_FETCH_SUB(var, val) InterlockedExchangeAdd(&(var), -(LONG)(val)) -#if defined __GNUC__ -# define RUBY_ATOMIC_OR(var, val) __asm__("lock\n\t" "orl\t%1, %0" : "=m"(var) : "Ir"(val)) -#elif RBIMPL_COMPILER_BEFORE(MSVC, 13, 0, 0) -# define RUBY_ATOMIC_OR(var, val) rb_w32_atomic_or(&(var), (val)) +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + RBIMPL_STATIC_ASSERT(size_of_rb_atomic_t, sizeof *ptr == sizeof(rb_atomic_t)); + + volatile rb_atomic_t *const tmp = RBIMPL_CAST((volatile rb_atomic_t *)ptr); + rbimpl_atomic_fetch_add(tmp, val, memory_order); + +#elif defined(HAVE_STDATOMIC_H) + return atomic_fetch_add_explicit((_Atomic volatile size_t *)ptr, val, memory_order); + +#else +# error Unsupported platform. +#endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) static inline void -rb_w32_atomic_or(volatile rb_atomic_t *var, rb_atomic_t val) +rbimpl_atomic_add(volatile rb_atomic_t *ptr, rb_atomic_t val, int memory_order) { -#ifdef _M_IX86 - __asm mov eax, var; - __asm mov ecx, val; - __asm lock or [eax], ecx; + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + /* + * GCC on amd64 is smart enough to detect this `__atomic_add_fetch`'s + * return value is not used, then compiles it into single `LOCK ADD` + * instruction. + */ + __atomic_add_fetch(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + __sync_add_and_fetch(ptr, val); + +#elif defined(_WIN32) + /* + * `InterlockedExchangeAdd` is `LOCK XADD`. It seems there also is + * `_InterlockedAdd` intrinsic in ARM Windows but not for x86? Sticking to + * `InterlockedExchangeAdd` for better portability. + */ + InterlockedExchangeAdd(ptr, val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + /* Ditto for `atomic_add_int_nv`. */ + RBIMPL_ASSERT_OR_ASSUME(val <= INT_MAX); + atomic_add_int(ptr, val); + +#elif defined(HAVE_STDATOMIC_H) + atomic_fetch_add_explicit((_Atomic volatile rb_atomic_t *)ptr, val, memory_order); + #else -#error unsupported architecture +# error Unsupported platform. #endif } + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_size_add(volatile size_t *ptr, size_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_add_fetch(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + __sync_add_and_fetch(ptr, val); + +#elif defined(_WIN64) + /* Ditto for `InterlockeExchangedAdd`. */ + InterlockedExchangeAdd64(ptr, val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) && (defined(_LP64) || defined(_I32LPx)) + /* Ditto for `atomic_add_int_nv`. */ + RBIMPL_ASSERT_OR_ASSUME(val <= LONG_MAX); + atomic_add_long(ptr, val); + +#elif defined(_WIN32) || (defined(__sun) && defined(HAVE_ATOMIC_H)) + RBIMPL_STATIC_ASSERT(size_of_rb_atomic_t, sizeof *ptr == sizeof(rb_atomic_t)); + + volatile rb_atomic_t *const tmp = RBIMPL_CAST((volatile rb_atomic_t *)ptr); + rbimpl_atomic_add(tmp, val, memory_order); + +#elif defined(HAVE_STDATOMIC_H) + atomic_fetch_add_explicit((_Atomic volatile size_t *)ptr, val, memory_order); + #else -# define RUBY_ATOMIC_OR(var, val) _InterlockedOr(&(var), (val)) +# error Unsupported platform. #endif -# define RUBY_ATOMIC_EXCHANGE(var, val) InterlockedExchange(&(var), (val)) -# define RUBY_ATOMIC_CAS(var, oldval, newval) InterlockedCompareExchange(&(var), (newval), (oldval)) -# if RBIMPL_COMPILER_BEFORE(MSVC, 13, 0, 0) -static inline rb_atomic_t -rb_w32_atomic_cas(volatile rb_atomic_t *var, rb_atomic_t oldval, rb_atomic_t newval) -{ - return (rb_atomic_t)InterlockedCompareExchange((PVOID *)var, (PVOID)newval, (PVOID)oldval); -} -# undef RUBY_ATOMIC_CAS -# define RUBY_ATOMIC_CAS(var, oldval, newval) rb_w32_atomic_cas(&(var), (oldval), (newval)) -# endif -# ifdef _M_AMD64 -# define RUBY_ATOMIC_SIZE_ADD(var, val) InterlockedExchangeAdd64((LONG_LONG *)&(var), (val)) -# define RUBY_ATOMIC_SIZE_SUB(var, val) InterlockedExchangeAdd64((LONG_LONG *)&(var), -(LONG)(val)) -# define RUBY_ATOMIC_SIZE_INC(var) InterlockedIncrement64(&(var)) -# define RUBY_ATOMIC_SIZE_DEC(var) InterlockedDecrement64(&(var)) -# define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) InterlockedExchange64(&(var), (val)) -# define RUBY_ATOMIC_SIZE_CAS(var, oldval, newval) InterlockedCompareExchange64(&(var), (newval), (oldval)) -# else -# define RUBY_ATOMIC_SIZE_ADD(var, val) InterlockedExchangeAdd((LONG *)&(var), (val)) -# define RUBY_ATOMIC_SIZE_SUB(var, val) InterlockedExchangeAdd((LONG *)&(var), -(LONG)(val)) -# define RUBY_ATOMIC_SIZE_INC(var) InterlockedIncrement((LONG *)&(var)) -# define RUBY_ATOMIC_SIZE_DEC(var) InterlockedDecrement((LONG *)&(var)) -# define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) InterlockedExchange((LONG *)&(var), (val)) -# endif - -# ifdef InterlockedExchangePointer -# define RUBY_ATOMIC_PTR_EXCHANGE(var, val) InterlockedExchangePointer((PVOID volatile *)&(var), (PVOID)(val)) -# endif /* See below for definitions of other situations */ +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_inc(volatile rb_atomic_t *ptr, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) || defined(HAVE_GCC_SYNC_BUILTINS) + rbimpl_atomic_add(ptr, 1, memory_order); + +#elif defined(_WIN32) + InterlockedIncrement(ptr); #elif defined(__sun) && defined(HAVE_ATOMIC_H) -#include <atomic.h> -typedef unsigned int rb_atomic_t; + atomic_inc_uint(ptr); -# define RUBY_ATOMIC_INC(var) atomic_inc_uint(&(var)) -# define RUBY_ATOMIC_DEC(var) atomic_dec_uint(&(var)) -# define RUBY_ATOMIC_FETCH_ADD(var, val) rb_atomic_fetch_add(&(var), (val)) -# define RUBY_ATOMIC_FETCH_SUB(var, val) rb_atomic_fetch_sub(&(var), (val)) -# define RUBY_ATOMIC_ADD(var, val) atomic_add_uint(&(var), (val)) -# define RUBY_ATOMIC_SUB(var, val) atomic_sub_uint(&(var), (val)) -# define RUBY_ATOMIC_OR(var, val) atomic_or_uint(&(var), (val)) -# define RUBY_ATOMIC_EXCHANGE(var, val) atomic_swap_uint(&(var), (val)) -# define RUBY_ATOMIC_CAS(var, oldval, newval) atomic_cas_uint(&(var), (oldval), (newval)) +#elif defined(HAVE_STDATOMIC_H) + rbimpl_atomic_add(ptr, 1, memory_order); -static inline rb_atomic_t -rb_atomic_fetch_add(volatile rb_atomic_t *var, rb_atomic_t val) +#else +# error Unsupported platform. +#endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_size_inc(volatile size_t *ptr, int memory_order) { - return atomic_add_int_nv(var, val) - val; + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) || defined(HAVE_GCC_SYNC_BUILTINS) + rbimpl_atomic_size_add(ptr, 1, memory_order); + +#elif defined(_WIN64) + InterlockedIncrement64(ptr); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) && (defined(_LP64) || defined(_I32LPx)) + atomic_inc_ulong(ptr); + +#elif defined(_WIN32) || (defined(__sun) && defined(HAVE_ATOMIC_H)) + RBIMPL_STATIC_ASSERT(size_of_size_t, sizeof *ptr == sizeof(rb_atomic_t)); + + rbimpl_atomic_size_add(ptr, 1, memory_order); + +#elif defined(HAVE_STDATOMIC_H) + rbimpl_atomic_size_add(ptr, 1, memory_order); + +#else +# error Unsupported platform. +#endif } +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) static inline rb_atomic_t -rb_atomic_fetch_sub(volatile rb_atomic_t *var, rb_atomic_t val) +rbimpl_atomic_fetch_sub(volatile rb_atomic_t *ptr, rb_atomic_t val, int memory_order) { - return atomic_add_int_nv(var, (rb_atomic_t)(-(int)val)) + val; -} + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + return __atomic_fetch_sub(ptr, val, memory_order); -# if defined(_LP64) || defined(_I32LPx) -# define RUBY_ATOMIC_SIZE_ADD(var, val) atomic_add_long(&(var), (val)) -# define RUBY_ATOMIC_SIZE_SUB(var, val) atomic_add_long(&(var), -(val)) -# define RUBY_ATOMIC_SIZE_INC(var) atomic_inc_ulong(&(var)) -# define RUBY_ATOMIC_SIZE_DEC(var) atomic_dec_ulong(&(var)) -# define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) atomic_swap_ulong(&(var), (val)) -# define RUBY_ATOMIC_SIZE_CAS(var, oldval, val) atomic_cas_ulong(&(var), (oldval), (val)) -# else -# define RUBY_ATOMIC_SIZE_ADD(var, val) atomic_add_int(&(var), (val)) -# define RUBY_ATOMIC_SIZE_SUB(var, val) atomic_add_int(&(var), -(val)) -# define RUBY_ATOMIC_SIZE_INC(var) atomic_inc_uint(&(var)) -# define RUBY_ATOMIC_SIZE_DEC(var) atomic_dec_uint(&(var)) -# define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) atomic_swap_uint(&(var), (val)) -# endif +#elif defined(HAVE_GCC_SYNC_BUILTINS) + return __sync_fetch_and_sub(ptr, val); + +#elif defined(_WIN32) + /* rb_atomic_t is signed here! Safe to do `-val`. */ + return InterlockedExchangeAdd(ptr, -val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + /* Ditto for `rbimpl_atomic_fetch_add`. */ + const signed neg = -1; + RBIMPL_ASSERT_OR_ASSUME(val <= INT_MAX); + return atomic_add_int_nv(ptr, neg * val) + val; + +#elif defined(HAVE_STDATOMIC_H) + return atomic_fetch_sub_explicit((_Atomic volatile rb_atomic_t *)ptr, val, memory_order); #else -# error No atomic operation found +# error Unsupported platform. #endif +} -#ifndef RUBY_ATOMIC_SET -# define RUBY_ATOMIC_SET(var, val) (void)RUBY_ATOMIC_EXCHANGE(var, val) -#endif +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_sub(volatile rb_atomic_t *ptr, rb_atomic_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_sub_fetch(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + __sync_sub_and_fetch(ptr, val); + +#elif defined(_WIN32) + InterlockedExchangeAdd(ptr, -val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + const signed neg = -1; + RBIMPL_ASSERT_OR_ASSUME(val <= INT_MAX); + atomic_add_int(ptr, neg * val); -#ifndef RUBY_ATOMIC_ADD -# define RUBY_ATOMIC_ADD(var, val) (void)RUBY_ATOMIC_FETCH_ADD(var, val) +#elif defined(HAVE_STDATOMIC_H) + atomic_fetch_sub_explicit((_Atomic volatile rb_atomic_t *)ptr, val, memory_order); + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_size_sub(volatile size_t *ptr, size_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_sub_fetch(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + __sync_sub_and_fetch(ptr, val); + +#elif defined(_WIN64) + const ssize_t neg = -1; + InterlockedExchangeAdd64(ptr, neg * val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) && (defined(_LP64) || defined(_I32LPx)) + const signed neg = -1; + RBIMPL_ASSERT_OR_ASSUME(val <= LONG_MAX); + atomic_add_long(ptr, neg * val); -#ifndef RUBY_ATOMIC_SUB -# define RUBY_ATOMIC_SUB(var, val) (void)RUBY_ATOMIC_FETCH_SUB(var, val) +#elif defined(_WIN32) || (defined(__sun) && defined(HAVE_ATOMIC_H)) + RBIMPL_STATIC_ASSERT(size_of_rb_atomic_t, sizeof *ptr == sizeof(rb_atomic_t)); + + volatile rb_atomic_t *const tmp = RBIMPL_CAST((volatile rb_atomic_t *)ptr); + rbimpl_atomic_sub(tmp, val, memory_order); + +#elif defined(HAVE_STDATOMIC_H) + atomic_fetch_sub_explicit((_Atomic volatile size_t *)ptr, val, memory_order); + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_dec(volatile rb_atomic_t *ptr, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) || defined(HAVE_GCC_SYNC_BUILTINS) + rbimpl_atomic_sub(ptr, 1, memory_order); -#ifndef RUBY_ATOMIC_INC -# define RUBY_ATOMIC_INC(var) RUBY_ATOMIC_ADD(var, 1) +#elif defined(_WIN32) + InterlockedDecrement(ptr); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + atomic_dec_uint(ptr); + +#elif defined(HAVE_STDATOMIC_H) + rbimpl_atomic_sub(ptr, 1, memory_order); + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_size_dec(volatile size_t *ptr, int memory_order) +{ + (void)memory_order; +#if 0 -#ifndef RUBY_ATOMIC_DEC -# define RUBY_ATOMIC_DEC(var) RUBY_ATOMIC_SUB(var, 1) +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) || defined(HAVE_GCC_SYNC_BUILTINS) + rbimpl_atomic_size_sub(ptr, 1, memory_order); + +#elif defined(_WIN64) + InterlockedDecrement64(ptr); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) && (defined(_LP64) || defined(_I32LPx)) + atomic_dec_ulong(ptr); + +#elif defined(_WIN32) || (defined(__sun) && defined(HAVE_ATOMIC_H)) + RBIMPL_STATIC_ASSERT(size_of_size_t, sizeof *ptr == sizeof(rb_atomic_t)); + + rbimpl_atomic_size_sub(ptr, 1, memory_order); + +#elif defined(HAVE_STDATOMIC_H) + rbimpl_atomic_size_sub(ptr, 1, memory_order); + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_or(volatile rb_atomic_t *ptr, rb_atomic_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_or_fetch(ptr, val, memory_order); -#ifndef RUBY_ATOMIC_SIZE_INC -# define RUBY_ATOMIC_SIZE_INC(var) RUBY_ATOMIC_INC(var) +#elif defined(HAVE_GCC_SYNC_BUILTINS) + __sync_or_and_fetch(ptr, val); + +#elif RBIMPL_COMPILER_IS(MSVC) + _InterlockedOr(ptr, val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + atomic_or_uint(ptr, val); + +#elif !defined(_WIN32) && defined(HAVE_STDATOMIC_H) + atomic_fetch_or_explicit((_Atomic volatile rb_atomic_t *)ptr, val, memory_order); + +#else +# error Unsupported platform. #endif +} -#ifndef RUBY_ATOMIC_SIZE_DEC -# define RUBY_ATOMIC_SIZE_DEC(var) RUBY_ATOMIC_DEC(var) +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline rb_atomic_t +rbimpl_atomic_exchange(volatile rb_atomic_t *ptr, rb_atomic_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + return __atomic_exchange_n(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + return __sync_lock_test_and_set(ptr, val); + +#elif defined(_WIN32) + return InterlockedExchange(ptr, val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + return atomic_swap_uint(ptr, val); + +#elif defined(HAVE_STDATOMIC_H) + return atomic_exchange_explicit((_Atomic volatile rb_atomic_t *)ptr, val, memory_order); + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline size_t +rbimpl_atomic_size_exchange(volatile size_t *ptr, size_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + return __atomic_exchange_n(ptr, val, memory_order); + +#elif defined(HAVE_GCC_SYNC_BUILTINS) + return __sync_lock_test_and_set(ptr, val); + +#elif defined(_WIN64) + return InterlockedExchange64(ptr, val); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) && (defined(_LP64) || defined(_I32LPx)) + return atomic_swap_ulong(ptr, val); + +#elif defined(_WIN32) || (defined(__sun) && defined(HAVE_ATOMIC_H)) + RBIMPL_STATIC_ASSERT(size_of_size_t, sizeof *ptr == sizeof(rb_atomic_t)); + + volatile rb_atomic_t *const tmp = RBIMPL_CAST((volatile rb_atomic_t *)ptr); + const rb_atomic_t ret = rbimpl_atomic_exchange(tmp, val, memory_order); + return RBIMPL_CAST((size_t)ret); -#ifndef RUBY_ATOMIC_SIZE_EXCHANGE -# define RUBY_ATOMIC_SIZE_EXCHANGE(var, val) RUBY_ATOMIC_EXCHANGE(var, val) +#elif defined(HAVE_STDATOMIC_H) + return atomic_exchange_explicit((_Atomic volatile size_t *)ptr, val, memory_order); + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_size_store(volatile size_t *ptr, size_t val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_store_n(ptr, val, memory_order); + +#else + rbimpl_atomic_size_exchange(ptr, val, memory_order); -#ifndef RUBY_ATOMIC_SIZE_CAS -# define RUBY_ATOMIC_SIZE_CAS(var, oldval, val) RUBY_ATOMIC_CAS(var, oldval, val) #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void * +rbimpl_atomic_ptr_exchange(void *volatile *ptr, const void *val, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(InterlockedExchangePointer) + /* const_cast */ + PVOID *pptr = RBIMPL_CAST((PVOID *)ptr); + PVOID pval = RBIMPL_CAST((PVOID)val); + return InterlockedExchangePointer(pptr, pval); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + return atomic_swap_ptr(ptr, RBIMPL_CAST((void *)val)); + +#else + RBIMPL_STATIC_ASSERT(sizeof_voidp, sizeof *ptr == sizeof(size_t)); + + const size_t sval = RBIMPL_CAST((size_t)val); + volatile size_t *const sptr = RBIMPL_CAST((volatile size_t *)ptr); + const size_t sret = rbimpl_atomic_size_exchange(sptr, sval, memory_order); + return RBIMPL_CAST((void *)sret); -#ifndef RUBY_ATOMIC_SIZE_ADD -# define RUBY_ATOMIC_SIZE_ADD(var, val) RUBY_ATOMIC_ADD(var, val) #endif +} -#ifndef RUBY_ATOMIC_SIZE_SUB -# define RUBY_ATOMIC_SIZE_SUB(var, val) RUBY_ATOMIC_SUB(var, val) +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_ptr_store(volatile void **ptr, void *val, int memory_order) +{ + RBIMPL_STATIC_ASSERT(sizeof_value, sizeof *ptr == sizeof(size_t)); + + const size_t sval = RBIMPL_CAST((size_t)val); + volatile size_t *const sptr = RBIMPL_CAST((volatile size_t *)ptr); + rbimpl_atomic_size_store(sptr, sval, memory_order); +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline VALUE +rbimpl_atomic_value_exchange(volatile VALUE *ptr, VALUE val, int memory_order) +{ + RBIMPL_STATIC_ASSERT(sizeof_value, sizeof *ptr == sizeof(size_t)); + + const size_t sval = RBIMPL_CAST((size_t)val); + volatile size_t *const sptr = RBIMPL_CAST((volatile size_t *)ptr); + const size_t sret = rbimpl_atomic_size_exchange(sptr, sval, memory_order); + return RBIMPL_CAST((VALUE)sret); +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_value_store(volatile VALUE *ptr, VALUE val, int memory_order) +{ + RBIMPL_STATIC_ASSERT(sizeof_value, sizeof *ptr == sizeof(size_t)); + + const size_t sval = RBIMPL_CAST((size_t)val); + volatile size_t *const sptr = RBIMPL_CAST((volatile size_t *)ptr); + rbimpl_atomic_size_store(sptr, sval, memory_order); +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline rb_atomic_t +rbimpl_atomic_load(volatile rb_atomic_t *ptr, int memory_order) +{ + (void)memory_order; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + return __atomic_load_n(ptr, memory_order); +#else + return rbimpl_atomic_fetch_add(ptr, 0, memory_order); #endif +} -#if RUBY_ATOMIC_GENERIC_MACRO -# ifndef RUBY_ATOMIC_PTR_EXCHANGE -# define RUBY_ATOMIC_PTR_EXCHANGE(var, val) RUBY_ATOMIC_EXCHANGE(var, val) -# endif +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void +rbimpl_atomic_store(volatile rb_atomic_t *ptr, rb_atomic_t val, int memory_order) +{ + (void)memory_order; +#if 0 -# ifndef RUBY_ATOMIC_PTR_CAS -# define RUBY_ATOMIC_PTR_CAS(var, oldval, newval) RUBY_ATOMIC_CAS(var, oldval, newval) -# endif +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_store_n(ptr, val, memory_order); -# ifndef RUBY_ATOMIC_VALUE_EXCHANGE -# define RUBY_ATOMIC_VALUE_EXCHANGE(var, val) RUBY_ATOMIC_EXCHANGE(var, val) -# endif +#else + /* Maybe std::atomic<rb_atomic_t>::store can be faster? */ + rbimpl_atomic_exchange(ptr, val, memory_order); -# ifndef RUBY_ATOMIC_VALUE_CAS -# define RUBY_ATOMIC_VALUE_CAS(var, oldval, val) RUBY_ATOMIC_CAS(var, oldval, val) -# endif #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline rb_atomic_t +rbimpl_atomic_cas(volatile rb_atomic_t *ptr, rb_atomic_t oldval, rb_atomic_t newval, int success_memorder, int failure_memorder) +{ + (void)success_memorder; + (void)failure_memorder; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_compare_exchange_n( + ptr, &oldval, newval, 0, success_memorder, failure_memorder); + return oldval; -#ifndef RUBY_ATOMIC_PTR_EXCHANGE -# if SIZEOF_VOIDP == SIZEOF_SIZE_T -# define RUBY_ATOMIC_PTR_EXCHANGE(var, val) (void *)RUBY_ATOMIC_SIZE_EXCHANGE(*(size_t *)&(var), (size_t)(val)) -# else -# error No atomic exchange for void* -# endif +#elif defined(HAVE_GCC_SYNC_BUILTINS) + return __sync_val_compare_and_swap(ptr, oldval, newval); + +#elif RBIMPL_COMPILER_IS(MSVC) + return InterlockedCompareExchange(ptr, newval, oldval); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + return atomic_cas_uint(ptr, oldval, newval); + +#elif defined(HAVE_STDATOMIC_H) + atomic_compare_exchange_strong_explicit( + (_Atomic volatile rb_atomic_t *)ptr, &oldval, newval, success_memorder, failure_memorder); + return oldval; + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline size_t +rbimpl_atomic_size_cas(volatile size_t *ptr, size_t oldval, size_t newval, int success_memorder, int failure_memorder) +{ + (void)success_memorder; + (void)failure_memorder; +#if 0 + +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + __atomic_compare_exchange_n( + ptr, &oldval, newval, 0, success_memorder, failure_memorder); + return oldval; -#ifndef RUBY_ATOMIC_PTR_CAS -# if SIZEOF_VOIDP == SIZEOF_SIZE_T -# define RUBY_ATOMIC_PTR_CAS(var, oldval, val) (void *)RUBY_ATOMIC_SIZE_CAS(*(size_t *)&(var), (size_t)(oldval), (size_t)(val)) -# else -# error No atomic compare-and-set for void* -# endif +#elif defined(HAVE_GCC_SYNC_BUILTINS) + return __sync_val_compare_and_swap(ptr, oldval, newval); + +#elif defined(_WIN64) + return InterlockedCompareExchange64(ptr, newval, oldval); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) && (defined(_LP64) || defined(_I32LPx)) + return atomic_cas_ulong(ptr, oldval, newval); + +#elif defined(_WIN32) || (defined(__sun) && defined(HAVE_ATOMIC_H)) + RBIMPL_STATIC_ASSERT(size_of_size_t, sizeof *ptr == sizeof(rb_atomic_t)); + + volatile rb_atomic_t *tmp = RBIMPL_CAST((volatile rb_atomic_t *)ptr); + return rbimpl_atomic_cas(tmp, oldval, newval, success_memorder, failure_memorder); + +#elif defined(HAVE_STDATOMIC_H) + atomic_compare_exchange_strong_explicit( + (_Atomic volatile size_t *)ptr, &oldval, newval, success_memorder, failure_memorder); + return oldval; + +#else +# error Unsupported platform. #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void * +rbimpl_atomic_ptr_cas(void **ptr, const void *oldval, const void *newval, int success_memorder, int failure_memorder) +{ + (void)success_memorder; + (void)failure_memorder; +#if 0 + +#elif defined(InterlockedExchangePointer) + /* ... Can we say that InterlockedCompareExchangePtr surly exists when + * InterlockedExchangePointer is defined? Seems so but...?*/ + PVOID *pptr = RBIMPL_CAST((PVOID *)ptr); + PVOID pold = RBIMPL_CAST((PVOID)oldval); + PVOID pnew = RBIMPL_CAST((PVOID)newval); + return InterlockedCompareExchangePointer(pptr, pnew, pold); + +#elif defined(__sun) && defined(HAVE_ATOMIC_H) + void *pold = RBIMPL_CAST((void *)oldval); + void *pnew = RBIMPL_CAST((void *)newval); + return atomic_cas_ptr(ptr, pold, pnew); + + +#else + RBIMPL_STATIC_ASSERT(sizeof_voidp, sizeof *ptr == sizeof(size_t)); + + const size_t snew = RBIMPL_CAST((size_t)newval); + const size_t sold = RBIMPL_CAST((size_t)oldval); + volatile size_t *const sptr = RBIMPL_CAST((volatile size_t *)ptr); + const size_t sret = rbimpl_atomic_size_cas(sptr, sold, snew, success_memorder, failure_memorder); + return RBIMPL_CAST((void *)sret); -#ifndef RUBY_ATOMIC_VALUE_EXCHANGE -# if SIZEOF_VALUE == SIZEOF_SIZE_T -# define RUBY_ATOMIC_VALUE_EXCHANGE(var, val) RUBY_ATOMIC_SIZE_EXCHANGE(*(size_t *)&(var), (size_t)(val)) -# else -# error No atomic exchange for VALUE -# endif #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline void * +rbimpl_atomic_ptr_load(void **ptr, int memory_order) +{ + (void)memory_order; +#if 0 -#ifndef RUBY_ATOMIC_VALUE_CAS -# if SIZEOF_VALUE == SIZEOF_SIZE_T -# define RUBY_ATOMIC_VALUE_CAS(var, oldval, val) RUBY_ATOMIC_SIZE_CAS(*(size_t *)&(var), (size_t)(oldval), (size_t)(val)) -# else -# error No atomic compare-and-set for VALUE -# endif +#elif defined(HAVE_GCC_ATOMIC_BUILTINS) + return __atomic_load_n(ptr, memory_order); +#else + void *val = *ptr; + return rbimpl_atomic_ptr_cas(ptr, val, val, memory_order, memory_order); #endif +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline VALUE +rbimpl_atomic_value_load(volatile VALUE *ptr, int memory_order) +{ + return RBIMPL_CAST((VALUE)rbimpl_atomic_ptr_load((void **)ptr, memory_order)); +} +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL((1)) +static inline VALUE +rbimpl_atomic_value_cas(volatile VALUE *ptr, VALUE oldval, VALUE newval, int success_memorder, int failure_memorder) +{ + RBIMPL_STATIC_ASSERT(sizeof_value, sizeof *ptr == sizeof(size_t)); + + const size_t snew = RBIMPL_CAST((size_t)newval); + const size_t sold = RBIMPL_CAST((size_t)oldval); + volatile size_t *const sptr = RBIMPL_CAST((volatile size_t *)ptr); + const size_t sret = rbimpl_atomic_size_cas(sptr, sold, snew, success_memorder, failure_memorder); + return RBIMPL_CAST((VALUE)sret); +} +/** @endcond */ #endif /* RUBY_ATOMIC_H */ diff --git a/include/ruby/backward.h b/include/ruby/backward.h index 445f4cc69c..6726102158 100644 --- a/include/ruby/backward.h +++ b/include/ruby/backward.h @@ -1,7 +1,6 @@ #ifndef RUBY_RUBY_BACKWARD_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_RUBY_BACKWARD_H 1 /** - * @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 @@ -12,61 +11,9 @@ #include "ruby/internal/interpreter.h" #include "ruby/backward/2/attributes.h" -#define RBIMPL_ATTR_DEPRECATED_SINCE(ver) RBIMPL_ATTR_DEPRECATED(("since " #ver)) -#define RBIMPL_ATTR_DEPRECATED_INTERNAL(ver) RBIMPL_ATTR_DEPRECATED(("since "#ver", also internal")) - -/* eval.c */ -RBIMPL_ATTR_DEPRECATED_SINCE(2.2) void rb_disable_super(); -RBIMPL_ATTR_DEPRECATED_SINCE(2.2) void rb_enable_super(); - -/* hash.c */ -RBIMPL_ATTR_DEPRECATED_SINCE(2.2) void rb_hash_iter_lev(); -RBIMPL_ATTR_DEPRECATED_SINCE(2.2) void rb_hash_ifnone(); - -/* string.c */ -RBIMPL_ATTR_DEPRECATED_SINCE(2.2) void rb_str_associate(); -RBIMPL_ATTR_DEPRECATED_SINCE(2.2) void rb_str_associated(); - -/* variable.c */ -RBIMPL_ATTR_DEPRECATED_SINCE(2.5) void rb_autoload(); - -/* eval.c */ -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.6) void rb_frozen_class_p(); -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.7) void rb_exec_end_proc(); - -/* error.c */ -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.3) void rb_compile_error(); -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.3) void rb_compile_error_with_enc(); -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.3) void rb_compile_error_append(); - -/* gc.c */ -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.7) void rb_gc_call_finalizer_at_exit(); - -/* signal.c */ -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.7) void rb_trap_exit(); - -/* struct.c */ -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.4) void rb_struct_ptr(); - -/* thread.c */ -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.7) void rb_clear_trace_func(); - -/* variable.c */ -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.7) void rb_generic_ivar_table(); -RBIMPL_ATTR_DEPRECATED_INTERNAL(2.6) NORETURN(VALUE rb_mod_const_missing(VALUE, VALUE)); - /* from version.c */ #if defined(RUBY_SHOW_COPYRIGHT_TO_DIE) && !!(RUBY_SHOW_COPYRIGHT_TO_DIE+0) -/* for source code backward compatibility */ -RBIMPL_ATTR_DEPRECATED_SINCE(2.4) -static inline int -ruby_show_copyright_to_die(int exitcode) -{ - ruby_show_copyright(); - return exitcode; -} -#define ruby_show_copyright() /* defer EXIT_SUCCESS */ \ - (exit(ruby_show_copyright_to_die(EXIT_SUCCESS))) +# error RUBY_SHOW_COPYRIGHT_TO_DIE is deprecated #endif #endif /* RUBY_RUBY_BACKWARD_H */ diff --git a/include/ruby/backward/2/assume.h b/include/ruby/backward/2/assume.h index 73a247d48e..d148710127 100644 --- a/include/ruby/backward/2/assume.h +++ b/include/ruby/backward/2/assume.h @@ -24,17 +24,30 @@ #include "ruby/internal/assume.h" #include "ruby/internal/has/builtin.h" -#undef ASSUME /* Kill config.h definition */ -#undef UNREACHABLE /* Kill config.h definition */ -#define ASSUME RBIMPL_ASSUME -#define UNREACHABLE RBIMPL_UNREACHABLE() -#define UNREACHABLE_RETURN RBIMPL_UNREACHABLE_RETURN +#define ASSUME RBIMPL_ASSUME /**< @old{RBIMPL_ASSUME} */ +#define UNREACHABLE RBIMPL_UNREACHABLE() /**< @old{RBIMPL_UNREACHABLE} */ +#define UNREACHABLE_RETURN RBIMPL_UNREACHABLE_RETURN /**< @old{RBIMPL_UNREACHABLE_RETURN} */ /* likely */ #if RBIMPL_HAS_BUILTIN(__builtin_expect) +/** + * Asserts that the given Boolean expression likely holds. + * + * @param x An expression that likely holds. + * + * @note Consider this macro carefully. It has been here since when CPUs were + * like babies, but contemporary processors are beasts. They are + * smarter than mare mortals like us today. Their branch predictions + * highly expectedly outperform your use of this macro. + */ # define RB_LIKELY(x) (__builtin_expect(!!(x), 1)) -# define RB_UNLIKELY(x) (__builtin_expect(!!(x), 0)) +/** + * Asserts that the given Boolean expression likely doesn't hold. + * + * @param x An expression that likely doesn't hold. + */ +# define RB_UNLIKELY(x) (__builtin_expect(!!(x), 0)) #else # define RB_LIKELY(x) (x) # define RB_UNLIKELY(x) (x) diff --git a/include/ruby/backward/2/attributes.h b/include/ruby/backward/2/attributes.h index 1d90d6c4de..916d9e9d5b 100644 --- a/include/ruby/backward/2/attributes.h +++ b/include/ruby/backward/2/attributes.h @@ -1,7 +1,6 @@ #ifndef RUBY_BACKWARD2_ATTRIBUTES_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_BACKWARD2_ATTRIBUTES_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 @@ -40,6 +39,7 @@ #include "ruby/internal/attr/noinline.h" #include "ruby/internal/attr/nonnull.h" #include "ruby/internal/attr/noreturn.h" +#include "ruby/internal/attr/packed_struct.h" #include "ruby/internal/attr/pure.h" #include "ruby/internal/attr/restrict.h" #include "ruby/internal/attr/returns_nonnull.h" @@ -81,10 +81,8 @@ #undef NOINLINE #define NOINLINE(x) RBIMPL_ATTR_NOINLINE() x -#ifndef MJIT_HEADER -# undef ALWAYS_INLINE -# define ALWAYS_INLINE(x) RBIMPL_ATTR_FORCEINLINE() x -#endif +#undef ALWAYS_INLINE +#define ALWAYS_INLINE(x) RBIMPL_ATTR_FORCEINLINE() x #undef ERRORFUNC #define ERRORFUNC(mesg, x) RBIMPL_ATTR_ERROR(mesg) x @@ -148,17 +146,14 @@ #define NORETURN(x) RBIMPL_ATTR_NORETURN() x #define NORETURN_STYLE_NEW -#ifndef PACKED_STRUCT -# define PACKED_STRUCT(x) x -#endif +#undef PACKED_STRUCT +#define PACKED_STRUCT(x) \ + RBIMPL_ATTR_PACKED_STRUCT_BEGIN() x RBIMPL_ATTR_PACKED_STRUCT_END() -#ifndef PACKED_STRUCT_UNALIGNED -# if UNALIGNED_WORD_ACCESS -# define PACKED_STRUCT_UNALIGNED(x) PACKED_STRUCT(x) -# else -# define PACKED_STRUCT_UNALIGNED(x) x -# endif -#endif +#undef PACKED_STRUCT_UNALIGNED +#define PACKED_STRUCT_UNALIGNED(x) \ + RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN() x \ + RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END() #undef RB_UNUSED_VAR #define RB_UNUSED_VAR(x) x RBIMPL_ATTR_MAYBE_UNUSED() diff --git a/include/ruby/backward/2/bool.h b/include/ruby/backward/2/bool.h index 94cdffc600..f2fa390c80 100644 --- a/include/ruby/backward/2/bool.h +++ b/include/ruby/backward/2/bool.h @@ -1,7 +1,6 @@ #ifndef RUBY_BACKWARD2_BOOL_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_BACKWARD2_BOOL_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 @@ -18,7 +17,7 @@ * 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 Defines old #TRUE / #FALSE + * @brief Defines old TRUE / FALSE */ #include "ruby/internal/stdbool.h" diff --git a/include/ruby/backward/2/gcc_version_since.h b/include/ruby/backward/2/gcc_version_since.h index d63138b657..00cc40ca56 100644 --- a/include/ruby/backward/2/gcc_version_since.h +++ b/include/ruby/backward/2/gcc_version_since.h @@ -1,7 +1,6 @@ #ifndef RUBY_BACKWARD2_GCC_VERSION_SINCE_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_BACKWARD2_GCC_VERSION_SINCE_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 @@ -18,7 +17,7 @@ * 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 Defines old #GCC_VERSION_SINCE + * @brief Defines old GCC_VERSION_SINCE */ #include "ruby/internal/compiler_since.h" diff --git a/include/ruby/backward/2/inttypes.h b/include/ruby/backward/2/inttypes.h index ca107c90a0..45460878bc 100644 --- a/include/ruby/backward/2/inttypes.h +++ b/include/ruby/backward/2/inttypes.h @@ -1,7 +1,6 @@ #ifndef RUBY_BACKWARD2_INTTYPES_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_BACKWARD2_INTTYPES_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 diff --git a/include/ruby/backward/2/limits.h b/include/ruby/backward/2/limits.h index 2f1a1a64e6..6f7021e5f4 100644 --- a/include/ruby/backward/2/limits.h +++ b/include/ruby/backward/2/limits.h @@ -1,7 +1,6 @@ #ifndef RUBY_BACKWARD2_LIMITS_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_BACKWARD2_LIMITS_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 @@ -21,7 +20,7 @@ * @brief Historical shim for `<limits.h>`. * * The macros in this header file are obsolescent. Does anyone really need our - * own definition of #CHAR_BIT today? + * own definition of `CHAR_BIT` today? */ #include "ruby/internal/config.h" diff --git a/include/ruby/backward/2/long_long.h b/include/ruby/backward/2/long_long.h index 936232bc40..8e6b2743fc 100644 --- a/include/ruby/backward/2/long_long.h +++ b/include/ruby/backward/2/long_long.h @@ -29,7 +29,15 @@ #include "ruby/internal/has/warning.h" #include "ruby/internal/warning_push.h" -#if RBIMPL_HAS_WARNING("-Wc++11-long-long") +#if defined(__DOXYGEN__) +# /** @cond INTERNAL_MACRO */ +# define HAVE_LONG_LONG 1 +# define HAVE_TRUE_LONG_LONG 1 +# /** @endcond */ +# /** @deprecated Just use `long long` directly. */ +# define LONG_LONG long long. + +#elif RBIMPL_HAS_WARNING("-Wc++11-long-long") # define HAVE_TRUE_LONG_LONG 1 # define LONG_LONG \ RBIMPL_WARNING_PUSH() \ diff --git a/include/ruby/backward/2/r_cast.h b/include/ruby/backward/2/r_cast.h index bd9d21ace6..3d0f40fd1e 100644 --- a/include/ruby/backward/2/r_cast.h +++ b/include/ruby/backward/2/r_cast.h @@ -1,7 +1,6 @@ #ifndef RUBY_BACKWARD2_R_CAST_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_BACKWARD2_R_CAST_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 @@ -18,7 +17,7 @@ * 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 Defines old #R_CAST + * @brief Defines old R_CAST * * Nobody is actively using this macro. */ diff --git a/include/ruby/backward/2/rmodule.h b/include/ruby/backward/2/rmodule.h index 3e2c431973..76c0936462 100644 --- a/include/ruby/backward/2/rmodule.h +++ b/include/ruby/backward/2/rmodule.h @@ -1,7 +1,6 @@ #ifndef RUBY_BACKWARD2_RMODULE_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_BACKWARD2_RMODULE_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 @@ -24,7 +23,7 @@ * who is implementing the internals) could have used those macros for a while. * Kept public as-is here to keep some theoretical backwards compatibility. */ -#define RMODULE_IV_TBL(m) RCLASS_IV_TBL(m) +#define RMODULE_IV_TBL(m) RCLASS_FIELDS(m) #define RMODULE_CONST_TBL(m) RCLASS_CONST_TBL(m) #define RMODULE_M_TBL(m) RCLASS_M_TBL(m) #define RMODULE_SUPER(m) RCLASS_SUPER(m) diff --git a/include/ruby/backward/2/stdalign.h b/include/ruby/backward/2/stdalign.h index 639be1566f..8b491bf564 100644 --- a/include/ruby/backward/2/stdalign.h +++ b/include/ruby/backward/2/stdalign.h @@ -24,7 +24,7 @@ #undef RUBY_ALIGNAS #undef RUBY_ALIGNOF -#define RUBY_ALIGNAS RBIMPL_ALIGNAS -#define RUBY_ALIGNOF RBIMPL_ALIGNOF +#define RUBY_ALIGNAS RBIMPL_ALIGNAS /**< @copydoc RBIMPL_ALIGNAS */ +#define RUBY_ALIGNOF RBIMPL_ALIGNOF /**< @copydoc RBIMPL_ALIGNOF */ #endif /* RUBY_BACKWARD2_STDALIGN_H */ diff --git a/include/ruby/backward/2/stdarg.h b/include/ruby/backward/2/stdarg.h index cfe2b899fd..08659fee47 100644 --- a/include/ruby/backward/2/stdarg.h +++ b/include/ruby/backward/2/stdarg.h @@ -25,6 +25,10 @@ */ #undef _ +/** + * @deprecated Nobody practically needs this macro any longer. + * @brief This was a transition path from K&R to ANSI. + */ #ifdef HAVE_PROTOTYPES # define _(args) args #else @@ -32,12 +36,30 @@ #endif #undef __ +/** + * @deprecated Nobody practically needs this macro any longer. + * @brief This was a transition path from K&R to ANSI. + */ #ifdef HAVE_STDARG_PROTOTYPES # define __(args) args #else # define __(args) () #endif +/** + * Functions declared using this macro take arbitrary arguments, including + * void. + * + * ```CXX + * void func(ANYARGS); + * ``` + * + * This was a necessary evil when there was no such thing like function + * overloading. But it is the 21st century today. People generally need not + * use this. Just use a granular typed function. + * + * @see ruby::backward::cxxanyargs + */ #ifdef __cplusplus #define ANYARGS ... #else diff --git a/include/ruby/backward/cxxanyargs.hpp b/include/ruby/backward/cxxanyargs.hpp index 883384a0b3..0ca2745c20 100644 --- a/include/ruby/backward/cxxanyargs.hpp +++ b/include/ruby/backward/cxxanyargs.hpp @@ -6,7 +6,7 @@ /// 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. -/// @note DO NOT MODERNIZE THIS FILE! As the file name implies it is +/// @note DO NOT MODERNISE THIS FILE! As the file name implies it is /// meant to be a backwards compatibility shim. Please stick to /// C++ 98 and never use newer features, like `constexpr`. /// @brief Provides old prototypes for C++ programs. @@ -39,7 +39,7 @@ namespace ruby { /// Backwards compatibility layer. namespace backward { -/// Provides ANYARGS deprecation warnings. In C, ANYARGS means there is no +/// Provides ANYARGS deprecation warnings. In C, ANYARGS means there is no /// function prototype. Literally anything, even including nothing, can be a /// valid ANYARGS. So passing a correctly prototyped function pointer to an /// ANYARGS-ed function parameter is valid, at the same time passing an @@ -68,7 +68,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @param[in] e Setter function. /// @note Both functions can be nullptr. /// @see rb_define_hooked_variable() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline void rb_define_virtual_variable(const char *q, type *w, void_type *e) { @@ -131,7 +131,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @param[in] r Setter function. /// @note Both functions can be nullptr. /// @see rb_define_virtual_variable() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline void rb_define_hooked_variable(const char *q, VALUE *w, type *e, void_type *r) { @@ -190,33 +190,6 @@ rb_define_hooked_variable(const char *q, VALUE *w, std::nullptr_t e, void_type * /// @name Exceptions and tag jumps /// @{ -// RUBY_CXX_DEPRECATED("by rb_block_call since 1.9") -RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Old way to implement iterators. -/// @param[in] q A function that can yield. -/// @param[in] w Passed to `q`. -/// @param[in] e What is to be yielded. -/// @param[in] r Passed to `e`. -/// @return The return value of `q`. -/// @note `e` can be nullptr. -/// @deprecated This function is obsolated since long before 2.x era. Do not -/// use it any longer. rb_block_call() is provided instead. -inline VALUE -rb_iterate(onearg_type *q, VALUE w, type *e, VALUE r) -{ - rb_block_call_func_t t = reinterpret_cast<rb_block_call_func_t>(e); - return backward::rb_iterate_deprecated(q, w, t, r); -} - -#ifdef HAVE_NULLPTR -RUBY_CXX_DEPRECATED("by rb_block_call since 1.9") -inline VALUE -rb_iterate(onearg_type *q, VALUE w, std::nullptr_t e, VALUE r) -{ - return backward::rb_iterate_deprecated(q, w, e, r); -} -#endif - RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @brief Call a method with a block. /// @param[in] q The self. @@ -227,7 +200,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @param[in] y Passed to `t` /// @return Return value of `q#w(*r,&t)` /// @note 't' can be nullptr. -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline VALUE rb_block_call(VALUE q, ID w, int e, const VALUE *r, type *t, VALUE y) { @@ -255,7 +228,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @see rb_ensure() /// @see rb_rescue2() /// @see rb_protect() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline VALUE rb_rescue(type *q, VALUE w, type *e, VALUE r) { @@ -279,7 +252,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @see rb_ensure() /// @see rb_rescue() /// @see rb_protect() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline VALUE rb_rescue2(type *q, VALUE w, type *e, VALUE r, ...) { @@ -305,7 +278,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @see rb_rescue() /// @see rb_rescue2() /// @see rb_protect() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline VALUE rb_ensure(type *q, VALUE w, type *e, VALUE r) { @@ -326,7 +299,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @see rb_protect() /// @see rb_rb_catch_obj() /// @see rb_rescue() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline VALUE rb_catch(const char *q, type *w, VALUE e) { @@ -353,7 +326,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @see rb_protect() /// @see rb_rb_catch_obj() /// @see rb_rescue() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline VALUE rb_catch_obj(VALUE q, type *w, VALUE e) { @@ -366,14 +339,14 @@ rb_catch_obj(VALUE q, type *w, VALUE e) /// @{ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") -/// @brief Creates a @ref rb_cFiber instance. +/// @brief Creates a rb_cFiber instance. /// @param[in] q The fiber body. /// @param[in] w Passed to `q`. /// @return What was allocated. /// @note It makes no sense to pass nullptr to`q`. /// @see rb_proc_new() -/// @see rb_thread_creatr() -/// @deprecated Use glanular typed overload instead. +/// @see rb_thread_create() +/// @deprecated Use granular typed overload instead. inline VALUE rb_fiber_new(type *q, VALUE w) { @@ -388,8 +361,8 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @return What was allocated. /// @note It makes no sense to pass nullptr to`q`. /// @see rb_fiber_new() -/// @see rb_thread_creatr() -/// @deprecated Use glanular typed overload instead. +/// @see rb_thread_create() +/// @deprecated Use granular typed overload instead. inline VALUE rb_proc_new(type *q, VALUE w) { @@ -405,7 +378,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @note It makes no sense to pass nullptr to`q`. /// @see rb_proc_new() /// @see rb_fiber_new() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline VALUE rb_thread_create(type *q, void *w) { @@ -427,7 +400,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @note It makes no sense to pass nullptr to`w`. /// @see st_foreach_check() /// @see rb_hash_foreach() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline int st_foreach(st_table *q, int_type *w, st_data_t e) { @@ -445,7 +418,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @retval 1 Element removed during traversing. /// @note It makes no sense to pass nullptr to`w`. /// @see st_foreach() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline int st_foreach_check(st_table *q, int_type *w, st_data_t e, st_data_t) { @@ -461,7 +434,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @param[in] e Passed to `w`. /// @note It makes no sense to pass nullptr to`w`. /// @see st_foreach_check() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline void st_foreach_safe(st_table *q, int_type *w, st_data_t e) { @@ -477,7 +450,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @param[in] e Passed to `w`. /// @note It makes no sense to pass nullptr to`w`. /// @see st_foreach() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline void rb_hash_foreach(VALUE q, int_type *w, VALUE e) { @@ -493,7 +466,7 @@ RUBY_CXX_DEPRECATED("Use of ANYARGS in this function is deprecated") /// @param[in] e Passed to `w`. /// @note It makes no sense to pass nullptr to`w`. /// @see st_foreach() -/// @deprecated Use glanular typed overload instead. +/// @deprecated Use granular typed overload instead. inline void rb_ivar_foreach(VALUE q, int_type *w, VALUE e) { @@ -537,11 +510,9 @@ struct driver { * this writing the version is 2.8. Let's warn this later, some time * during 3.x. Hopefully codes in old (ANYARGS-ed) format should be * less than now. */ -#if (RUBY_API_VERSION_MAJOR * 100 + RUBY_API_VERSION_MINOR) >= 301 RUBY_CXX_DEPRECATED("use of ANYARGS is deprecated") -#endif /// @copydoc define(VALUE klass, T mid, U func) - /// @deprecated Pass corrctly typed function instead. + /// @deprecated Pass correctly typed function instead. static inline void define(VALUE klass, T mid, type func) { @@ -594,27 +565,42 @@ struct driver { /* We could perhaps merge this struct into the one above using variadic * template parameters if we could assume C++11, but sadly we cannot. */ +/// @copydoc ruby::backward::cxxanyargs::define_method::driver template<typename T, void (*F)(T mid, type func, int arity)> struct driver0 { + + /// @brief Defines a method + /// @tparam N Arity of the function. + /// @tparam U The function in question template<int N, typename U> struct engine { RUBY_CXX_DEPRECATED("use of ANYARGS is deprecated") + /// @copydoc define(T mid, U func) + /// @deprecated Pass correctly typed function instead. static inline void define(T mid, type func) { F(mid, func, N); } + + /// @brief Defines Kernel#mid as func, whose arity is N. + /// @param[in] mid Name of the method to define. + /// @param[in] func Function that implements klass#mid. static inline void define(T mid, U func) { F(mid, reinterpret_cast<type *>(func), N); } + + /// @copydoc define(T mid, U func) + /// @deprecated Pass correctly typed function instead. static inline void define(T mid, notimpl_type func) { F(mid, reinterpret_cast<type *>(func), N); } }; + /// @cond INTERNAL_MACRO template<int N, bool = false> struct specific : public engine<N, type *> {}; template<bool b> struct specific<15, b> : public engine<15, VALUE(*)(VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE, VALUE)> {}; diff --git a/include/ruby/debug.h b/include/ruby/debug.h index 16891e8458..547d5d94c4 100644 --- a/include/ruby/debug.h +++ b/include/ruby/debug.h @@ -10,6 +10,9 @@ * modify this file, provided that the conditions mentioned in the * file COPYING are met. Consult the file for details. */ +#include "ruby/internal/attr/deprecated.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/attr/returns_nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/event.h" #include "ruby/internal/value.h" @@ -19,74 +22,800 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* Note: This file contains experimental APIs. */ /* APIs can be replaced at Ruby 2.0.1 or later */ +/** + * @name Frame-profiling APIs + * + * @{ + */ -/* profile frames APIs */ +RBIMPL_ATTR_NONNULL((3)) +/** + * Queries mysterious "frame"s of the given range. + * + * The returned values are opaque backtrace pointers, which you are allowed to + * issue a very limited set of operations listed below. Don't call arbitrary + * ruby methods. + * + * @param[in] start Start position (0 means the topmost). + * @param[in] limit Number objects of `buff`. + * @param[out] buff Return buffer. + * @param[out] lines Return buffer. + * @return Number of objects filled into `buff`. + * @post `buff` is filled with backtrace pointers. + * @post `lines` is filled with `__LINE__` of each backtraces. + * + * @internal + * + * @shyouhei doesn't like this abuse of ::VALUE. It should have been + * `const struct rb_callable_method_entry_struct *`. + */ int rb_profile_frames(int start, int limit, VALUE *buff, int *lines); + +/** + * Queries mysterious "frame"s of the given range. + * + * A per-thread version of rb_profile_frames(). + * Arguments and return values are the same with rb_profile_frames() with the + * exception of the first argument _thread_, which accepts the Thread to be + * profiled/queried. + * + * @param[in] thread The Ruby Thread to be profiled. + * @param[in] start Start position (0 means the topmost). + * @param[in] limit Number objects of `buff`. + * @param[out] buff Return buffer. + * @param[out] lines Return buffer. + * @return Number of objects filled into `buff`. + * @post `buff` is filled with backtrace pointers. + * @post `lines` is filled with `__LINE__` of each backtraces. + */ +int rb_profile_thread_frames(VALUE thread, int start, int limit, VALUE *buff, int *lines); + +/** + * Queries the path of the passed backtrace. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil The frame is implemented in C etc. + * @retval otherwise Where `frame` is running. + */ VALUE rb_profile_frame_path(VALUE frame); + +/** + * Identical to rb_profile_frame_path(), except it tries to expand the + * returning path. In case the path is `require`-d from something else + * rb_profile_frame_path() can return relative paths. This one tries to avoid + * that. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval "<cfunc>" The frame is in C. + * @retval RUBY_Qnil Can't infer real path (inside of `eval` etc.). + * @retval otherwise Where `frame` is running. + */ VALUE rb_profile_frame_absolute_path(VALUE frame); + +/** + * Queries human-readable "label" string. This is `"<main>"` for the toplevel, + * `"<compiled>"` for evaluated ones, method name for methods, class name for + * classes. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil Can't infer the label (C etc.). + * @retval "<main>" The frame is global toplevel. + * @retval "<compiled>" The frame is dynamic. + * @retval otherwise Label of the frame. + */ VALUE rb_profile_frame_label(VALUE frame); + +/** + * Identical to rb_profile_frame_label(), except it does not "qualify" the + * result. Consider the following backtrace: + * + * ```ruby + * def bar + * caller_locations + * end + * + * def foo + * [1].map { bar }.first + * end + * + * obj = foo.first + * obj.label # => "block in foo" + * obj.base_label # => "foo" + * ``` + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil Can't infer the label (C etc.). + * @retval "<main>" The frame is global toplevel. + * @retval "<compiled>" The frame is dynamic. + * @retval otherwise Base label of the frame. + */ VALUE rb_profile_frame_base_label(VALUE frame); + +/** + * Identical to rb_profile_frame_label(), except it returns a qualified result. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil Can't infer the label (C etc.). + * @retval "<main>" The frame is global toplevel. + * @retval "<compiled>" The frame is dynamic. + * @retval otherwise Qualified label of the frame. + * + * @internal + * + * As of writing there is no way to obtain this return value from a Ruby + * script. This may change in future (it took 8 years and still no progress, + * though). + */ VALUE rb_profile_frame_full_label(VALUE frame); + +/** + * Queries the first line of the method of the passed frame pointer. Can be + * handy when for instance a debugger want to display the frame in question. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil Can't infer the line (C etc.). + * @retval otherwise Line number of the method in question. + */ VALUE rb_profile_frame_first_lineno(VALUE frame); + +/** + * Queries the class path of the method that the passed frame represents. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil Can't infer the class (global toplevel etc.). + * @retval otherwise Class path as in rb_class_path(). + */ VALUE rb_profile_frame_classpath(VALUE frame); + +/** + * Queries if the method of the passed frame is a singleton class. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qtrue It is a singleton method. + * @retval RUBY_Qfalse Otherwise (normal method/non-method). + */ VALUE rb_profile_frame_singleton_method_p(VALUE frame); + +/** + * Queries the name of the method of the passed frame. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil The frame in question is not a method. + * @retval otherwise Name of the method of the frame. + */ VALUE rb_profile_frame_method_name(VALUE frame); + +/** + * Identical to rb_profile_frame_method_name(), except it "qualifies" the + * return value with its defining class. + * + * @param[in] frame What rb_profile_frames() returned. + * @retval RUBY_Qnil The frame in question is not a method. + * @retval otherwise Qualified name of the method of the frame. + */ VALUE rb_profile_frame_qualified_method_name(VALUE frame); -/* debug inspector APIs */ +/** @} */ + +/** + * @name Debug inspector APIs + * + * @{ + */ + +/** Opaque struct representing a debug inspector. */ typedef struct rb_debug_inspector_struct rb_debug_inspector_t; -typedef VALUE (*rb_debug_inspector_func_t)(const rb_debug_inspector_t *, void *); +/** + * Type of the callback function passed to rb_debug_inspector_open(). + * Inspection shall happen only inside of them. The passed pointers gets + * invalidated once after the callback returns. + * + * @param[in] dc A debug context. + * @param[in,out] data What was passed to rb_debug_inspector_open(). + * @return What would be the return value of rb_debug_inspector_open(). + */ +typedef VALUE (*rb_debug_inspector_func_t)(const rb_debug_inspector_t *dc, void *data); + +/** + * Prepares, executes, then cleans up a debug session. + * + * @param[in] func A callback to run inside of a debug session. + * @param[in,out] data Passed as-is to `func`. + * @return What was returned from `func`. + */ VALUE rb_debug_inspector_open(rb_debug_inspector_func_t func, void *data); + +/** + * Queries the backtrace object of the context. This is as if you call + * `caller_locations` at the point of debugger. + * + * @param[in] dc A debug context. + * @return An array of `Thread::Backtrace::Location` which represents the + * current point of execution at `dc`. + + */ +VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc); + +/** + * Queries the current receiver of the passed context's upper frame. + * + * @param[in] dc A debug context. + * @param[in] index Index of the frame from top to bottom. + * @exception rb_eArgError `index` out of range. + * @return The current receiver at `index`-th frame. + */ VALUE rb_debug_inspector_frame_self_get(const rb_debug_inspector_t *dc, long index); + +/** + * Queries the current class of the passed context's upper frame. + * + * @param[in] dc A debug context. + * @param[in] index Index of the frame from top to bottom. + * @exception rb_eArgError `index` out of range. + * @return The current class at `index`-th frame. + */ VALUE rb_debug_inspector_frame_class_get(const rb_debug_inspector_t *dc, long index); + +/** + * Queries the binding of the passed context's upper frame. + * + * @param[in] dc A debug context. + * @param[in] index Index of the frame from top to bottom. + * @exception rb_eArgError `index` out of range. + * @return The binding at `index`-th frame. + */ VALUE rb_debug_inspector_frame_binding_get(const rb_debug_inspector_t *dc, long index); + +/** + * Queries the instruction sequence of the passed context's upper frame. + * + * @param[in] dc A debug context. + * @param[in] index Index of the frame from top to bottom. + * @exception rb_eArgError `index` out of range. + * @retval RUBY_Qnil `index`-th frame is not in Ruby (C etc.). + * @retval otherwise An instance of `RubyVM::InstructionSequence` which + * represents the instruction sequence at `index`-th + * frame. + */ VALUE rb_debug_inspector_frame_iseq_get(const rb_debug_inspector_t *dc, long index); -VALUE rb_debug_inspector_backtrace_locations(const rb_debug_inspector_t *dc); -/* Old style set_trace_func APIs */ +/** + * Queries the depth of the passed context's upper frame. + * + * Note that the depth is not same as the frame index because debug_inspector + * skips some special frames but the depth counts all frames. + * + * @param[in] dc A debug context. + * @param[in] index Index of the frame from top to bottom. + * @exception rb_eArgError `index` out of range. + * @retval The depth at `index`-th frame in Integer. + */ +VALUE rb_debug_inspector_frame_depth(const rb_debug_inspector_t *dc, long index); + +// A macro to recognize `rb_debug_inspector_frame_depth()` is available or not +#define RB_DEBUG_INSPECTOR_FRAME_DEPTH(dc, index) rb_debug_inspector_frame_depth(dc, index) + +/** + * Return current frame depth. + * + * @retval The depth of the current frame in Integer. + */ +VALUE rb_debug_inspector_current_depth(void); + +/** @} */ + +/** + * @name Old style set_trace_func APIs + * + * @{ + */ /* duplicated def of include/ruby/ruby.h */ -void rb_add_event_hook(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data); -int rb_remove_event_hook(rb_event_hook_func_t func); +#include "ruby/internal/event.h" +/** + * Identical to rb_remove_event_hook(), except it additionally takes the data + * argument. This extra argument is the same as that of rb_add_event_hook(), + * and this function removes the hook which matches both arguments at once. + * + * @param[in] func A callback. + * @param[in] data What to be passed to `func`. + * @return Number of deleted event hooks. + * @note As multiple events can share the same `func` it is quite + * possible for the return value to become more than one. + */ int rb_remove_event_hook_with_data(rb_event_hook_func_t func, VALUE data); + +/** + * Identical to rb_add_event_hook(), except its effect is limited to the passed + * thread. Other threads are not affected by this. + * + * @param[in] thval An instance of ::rb_cThread. + * @param[in] func A callback. + * @param[in] events A set of events that `func` should run. + * @param[in] data Passed as-is to `func`. + * @exception rb_eTypeError `thval` is not a thread. + */ void rb_thread_add_event_hook(VALUE thval, rb_event_hook_func_t func, rb_event_flag_t events, VALUE data); + +/** + * Identical to rb_remove_event_hook(), except it additionally takes a thread + * argument. This extra argument is the same as that of + * rb_thread_add_event_hook(), and this function removes the hook which matches + * both arguments at once. + * + * @param[in] thval An instance of ::rb_cThread. + * @param[in] func A callback. + * @exception rb_eTypeError `thval` is not a thread. + * @return Number of deleted event hooks. + * @note As multiple events can share the same `func` it is quite + * possible for the return value to become more than one. + */ int rb_thread_remove_event_hook(VALUE thval, rb_event_hook_func_t func); + +/** + * Identical to rb_thread_remove_event_hook(), except it additionally takes the + * data argument. It can also be seen as a routine identical to + * rb_remove_event_hook_with_data(), except it additionally takes the thread. + * This function deletes hooks that satisfy all three criteria. + * + * @param[in] thval An instance of ::rb_cThread. + * @param[in] func A callback. + * @param[in] data What to be passed to `func`. + * @exception rb_eTypeError `thval` is not a thread. + * @return Number of deleted event hooks. + * @note As multiple events can share the same `func` it is quite + * possible for the return value to become more than one. + */ int rb_thread_remove_event_hook_with_data(VALUE thval, rb_event_hook_func_t func, VALUE data); -/* TracePoint APIs */ +/** @} */ + +/** + * @name TracePoint APIs + * + * @{ + */ +/** + * Creates a tracepoint by registering a callback function for one or more + * tracepoint events. Once the tracepoint is created, you can use + * rb_tracepoint_enable to enable the tracepoint. + * + * @param[in] target_thread_not_supported_yet Meant for picking the + * thread in which the tracepoint is to be created. + * However, current implementation ignore this + * parameter, tracepoint is created for all threads. + * Simply specify Qnil. + * @param[in] events Event(s) to listen to. + * @param[in] func A callback function. + * @param[in,out] data Void pointer that will be passed to the callback + * function. + * + * When the callback function is called, it will be passed 2 parameters: + * 1. `VALUE tpval` - the TracePoint object from which trace args can be + * extracted. + * 1. `void *data` - A void pointer which helps to share scope with the + * callback function. + * + * It is important to note that you cannot register callbacks for normal events + * and internal events simultaneously because they are different purpose. You + * can use any Ruby APIs (calling methods and so on) on normal event hooks. + * However, in internal events, you can not use any Ruby APIs (even object + * creations). This is why we can't specify internal events by TracePoint + * directly. Limitations are MRI version specific. + * + * Example: + * + * ```CXX + * rb_tracepoint_new( + * Qnil, + * RUBY_INTERNAL_EVENT_NEWOBJ | RUBY_INTERNAL_EVENT_FREEOBJ, + * obj_event_i, + * data); + * ``` + * + * In this example, a callback function `obj_event_i` will be registered for + * internal events #RUBY_INTERNAL_EVENT_NEWOBJ and + * #RUBY_INTERNAL_EVENT_FREEOBJ. + */ VALUE rb_tracepoint_new(VALUE target_thread_not_supported_yet, rb_event_flag_t events, void (*func)(VALUE, void *), void *data); + +/** + * Starts (enables) trace(s) defined by the passed object. A TracePoint object + * does not immediately take effect on creation. You have to explicitly call + * this API. + * + * @param[in] tpval An instance of TracePoint. + * @exception rb_eArgError A trace is already running. + * @return Undefined value. Forget this. It should have returned `void`. + * @post Trace(s) defined by `tpval` start. + */ VALUE rb_tracepoint_enable(VALUE tpval); + +/** + * Stops (disables) an already running instance of TracePoint. + * + * @param[in] tpval An instance of TracePoint. + * @return Undefined value. Forget this. It should have returned `void`. + * @post Trace(s) defined by `tpval` stop. + */ VALUE rb_tracepoint_disable(VALUE tpval); + +/** + * Queries if the passed TracePoint is up and running. + * + * @param[in] tpval An instance of TracePoint. + * @retval RUBY_Qtrue It is. + * @retval RUBY_Qfalse It isn't. + */ VALUE rb_tracepoint_enabled_p(VALUE tpval); +/** + * Type that represents a specific trace event. Roughly resembles the + * tracepoint object that is passed to the block of `TracePoint.new`: + * + * ```ruby + * TracePoint.new(*events) do |obj| + * ... # ^^^^^ Resembles this object. + * end + * ``` + */ typedef struct rb_trace_arg_struct rb_trace_arg_t; + +RBIMPL_ATTR_RETURNS_NONNULL() +/** + * Queries the current event of the passed tracepoint. + * + * @param[in] tpval An instance of TracePoint. + * @exception rb_eRuntimeError `tpval` is disabled. + * @return The current event. + * + * @internal + * + * `tpval` is a fake. There is only one instance of ::rb_trace_arg_t at one + * time. This function just returns that global variable. + */ rb_trace_arg_t *rb_tracearg_from_tracepoint(VALUE tpval); +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the event of the passed trace. + * + * @param[in] trace_arg A trace instance. + * @return Its event. + */ rb_event_flag_t rb_tracearg_event_flag(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Identical to rb_tracearg_event_flag(), except it returns the name of the + * event in Ruby's symbol. + * + * @param[in] trace_arg A trace instance. + * @return Its event, in Ruby level Symbol object. + */ VALUE rb_tracearg_event(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the line of the point where the trace is at. + * + * @param[in] trace_arg A trace instance. + * @retval 0 The trace is not at Ruby frame. + * @return otherwise Its line number. + */ VALUE rb_tracearg_lineno(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the file name of the point where the trace is at. + * + * @param[in] trace_arg A trace instance. + * @retval RUBY_Qnil The trace is not at Ruby frame. + * @retval otherwise Its path. + */ VALUE rb_tracearg_path(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * + * Queries the parameters passed on a call or return event. + * + * @param[in] trace_arg A trace instance + * @exception rb_eRuntimeError The tracing event does not support querying parameters. + * @return Array of parameters in the format of `Method#parameters`. + * + */ +VALUE rb_tracearg_parameters(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the method name of the point where the trace is at. + * + * @param[in] trace_arg A trace instance. + * @retval RUBY_Qnil There is no method. + * @retval otherwise Its method name, in Ruby level Symbol. + */ VALUE rb_tracearg_method_id(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Identical to rb_tracearg_method_id(), except it returns callee id like + * rb_frame_callee(). + * + * @param[in] trace_arg A trace instance. + * @retval RUBY_Qnil There is no method. + * @retval otherwise Its method name, in Ruby level Symbol. + */ VALUE rb_tracearg_callee_id(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the class that defines the method that the passed trace is at. This + * can be different from the class of rb_tracearg_self()'s return value because + * of inheritance(s). + * + * @param[in] trace_arg A trace instance. + * @retval RUBY_Qnil There is no method. + * @retval otherwise Its method's class. + */ VALUE rb_tracearg_defined_class(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Creates a binding object of the point where the trace is at. + * + * @param[in] trace_arg A trace instance. + * @retval RUBY_Qnil The point has no binding. + * @retval otherwise Its binding. + * + * @internal + * + * @shyouhei has no idea on which situation shall this function return + * ::RUBY_Qnil. + */ VALUE rb_tracearg_binding(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the receiver of the point trace is at. + * + * @param[in] trace_arg A trace instance. + * @return Its receiver. + */ VALUE rb_tracearg_self(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the return value that the trace represents. + * + * @param[in] trace_arg A trace instance. + * @exception rb_eRuntimeError The tracing event is not return-related. + * @return The return value. + */ VALUE rb_tracearg_return_value(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the raised exception that the trace represents. + * + * @param[in] trace_arg A trace instance. + * @exception rb_eRuntimeError The tracing event is not exception-related. + * @return The raised exception. + */ VALUE rb_tracearg_raised_exception(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the compiled source code of the 'script_compiled' event. + * If loaded from a file, it will return nil. + * + * @param[in] trace_arg A trace instance + * @exception rb_eRuntimeError The tracing event is not 'script_compiled'. + * @retval RUBY_Qnil The script was loaded from a file. + * @retval otherwise The compiled source code. + * + */ +VALUE rb_tracearg_eval_script(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * + * Queries the compiled instruction sequence on a 'script_compiled' event. + * Note that this method is MRI specific. + * + * @param[in] trace_arg A trace instance + * @exception rb_eRuntimeError The tracing event is not 'script_compiled'. + * @return The `RubyVM::InstructionSequence` object representing the instruction sequence. + * + */ +VALUE rb_tracearg_instruction_sequence(rb_trace_arg_t *trace_arg); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Queries the allocated/deallocated object that the trace represents. + * + * @param[in] trace_arg A trace instance. + * @exception rb_eRuntimeError The tracing event is not GC-related. + * @return The allocated/deallocated object. + */ VALUE rb_tracearg_object(rb_trace_arg_t *trace_arg); + +/** @} */ + +/** + * @name Postponed Job API + * + * @{ + */ + /* * Postponed Job API - * rb_postponed_job_register and rb_postponed_job_register_one are - * async-signal-safe and used via SIGPROF by the "stackprof" RubyGem + * + * This API is designed to be called from contexts where it is not safe to run Ruby + * code (e.g. because they do not hold the GVL or because GC is in progress), and + * defer a callback to run in a context where it _is_ safe. The primary intended + * users of this API is for sampling profilers like the "stackprof" gem; these work + * by scheduling the periodic delivery of a SIGPROF signal, and inside the C-level + * signal handler, deferring a job to collect a Ruby backtrace when it is next safe + * to do so. + * + * Ruby maintains a small, fixed-size postponed job table. An extension using this + * API should first call `rb_postponed_job_preregister` to register a callback + * function in this table and obtain a handle of type `rb_postponed_job_handle_t` + * to it. Subsequently, the callback can be triggered by calling + * `rb_postponed_job_trigger` with that handle, or the `data` associated with the + * callback function can be changed by calling `rb_postponed_job_preregister` again. + * + * Because the postponed job table is quite small (it only has 32 entries on most + * common systems), extensions should generally only preregister one or two `func` + * values. + * + * Historically, this API provided two functions `rb_postponed_job_register` and + * `rb_postponed_job_register_one`, which claimed to be fully async-signal-safe and + * would call back the provided `func` and `data` at an appropriate time. However, + * these functions were subject to race conditions which could cause crashes when + * racing with Ruby's internal use of them. These two functions are still present, + * but are marked as deprecated and have slightly changed semantics: + * + * * rb_postponed_job_register now works like rb_postponed_job_register_one i.e. + * `func` will only be executed at most one time each time Ruby checks for + * interrupts, no matter how many times it is registered + * * They are also called with the last `data` to be registered, not the first + * (which is how rb_postponed_job_register_one previously worked) + */ + + +/** + * Type of postponed jobs. + * + * @param[in,out] arg What was passed to `rb_postponed_job_preregister` */ typedef void (*rb_postponed_job_func_t)(void *arg); + +/** + * The type of a handle returned from `rb_postponed_job_preregister` and + * passed to `rb_postponed_job_trigger` + */ +typedef unsigned int rb_postponed_job_handle_t; +#define POSTPONED_JOB_HANDLE_INVALID ((rb_postponed_job_handle_t)UINT_MAX) + +/** + * Pre-registers a func in Ruby's postponed job preregistration table, + * returning an opaque handle which can be used to trigger the job later. Generally, + * this function will be called during the initialization routine of an extension. + * + * The returned handle can be used later to call `rb_postponed_job_trigger`. This will + * cause Ruby to call back into the registered `func` with `data` at a later time, in + * a context where the GVL is held and it is safe to perform Ruby allocations. + * + * If the given `func` was already pre-registered, this function will overwrite the + * stored data with the newly passed data, and return the same handle instance as + * was previously returned. + * + * If this function is called concurrently with the same `func`, then the stored data + * could be the value from either call (but will definitely be one of them). + * + * If this function is called to update the data concurrently with a call to + * `rb_postponed_job_trigger` on the same handle, it's undefined whether `func` will + * be called with the old data or the new data. + * + * Although the current implementation of this function is in fact async-signal-safe and + * has defined semantics when called concurrently on the same `func`, a future Ruby + * version might require that this method be called under the GVL; thus, programs which + * aim to be forward-compatible should call this method whilst holding the GVL. + * + * @param[in] flags Unused and ignored + * @param[in] func The function to be pre-registered + * @param[in] data The data to be pre-registered + * @retval POSTPONED_JOB_HANDLE_INVALID The job table is full; this registration + * did not succeed and no further registration will do so for + * the lifetime of the program. + * @retval otherwise A handle which can be passed to `rb_postponed_job_trigger` + */ +rb_postponed_job_handle_t rb_postponed_job_preregister(unsigned int flags, rb_postponed_job_func_t func, void *data); + +/** + * Triggers a pre-registered job registered with rb_postponed_job_preregister, + * scheduling it for execution the next time the Ruby VM checks for interrupts. + * The context in which the job is called in holds the GVL and is safe to perform + * Ruby allocations within (i.e. it is not during GC). + * + * This method is async-signal-safe and can be called from any thread, at any + * time, including in signal handlers. + * + * If this method is called multiple times, Ruby will coalesce this into only + * one call to the job the next time it checks for interrupts. + * + * @params[in] h A handle returned from rb_postponed_job_preregister + */ +void rb_postponed_job_trigger(rb_postponed_job_handle_t h); + +/** + * Schedules the given `func` to be called with `data` when Ruby next checks for + * interrupts. If this function is called multiple times in between Ruby checking + * for interrupts, then `func` will be called only once with the `data` value from + * the first call to this function. + * + * Like `rb_postponed_job_trigger`, the context in which the job is called + * holds the GVL and can allocate Ruby objects. + * + * This method essentially has the same semantics as: + * + * ``` + * rb_postponed_job_trigger(rb_postponed_job_preregister(func, data)); + * ``` + * + * @note Previous versions of Ruby promised that the (`func`, `data`) pairs would + * be executed as many times as they were registered with this function; in + * reality this was always subject to race conditions and this function no + * longer provides this guarantee. Instead, multiple calls to this function + * can be coalesced into a single execution of the passed `func`, with the + * most recent `data` registered at that time passed in. + * + * @deprecated This interface implies that arbitrarily many `func`'s can be enqueued + * over the lifetime of the program, whilst in reality the registration + * slots for postponed jobs are a finite resource. This is made clearer + * by the `rb_postponed_job_preregister` and `rb_postponed_job_trigger` + * functions, and a future version of Ruby might delete this function. + * + * @param[in] flags Unused and ignored. + * @param[in] func Job body. + * @param[in,out] data Passed as-is to `func`. + * @retval 0 Postponed job registration table is full. Failed. + * @retval 1 Registration succeeded. + * @post The passed job will run on the next interrupt check. + */ + RBIMPL_ATTR_DEPRECATED(("use rb_postponed_job_preregister and rb_postponed_job_trigger")) int rb_postponed_job_register(unsigned int flags, rb_postponed_job_func_t func, void *data); + +/** + * Identical to `rb_postponed_job_register` + * + * @deprecated This is deprecated for the same reason as `rb_postponed_job_register` + * + * @param[in] flags Unused and ignored. + * @param[in] func Job body. + * @param[in,out] data Passed as-is to `func`. + * @retval 0 Postponed job registration table is full. Failed. + * @retval 1 Registration succeeded. + * @post The passed job will run on the next interrupt check. + */ + RBIMPL_ATTR_DEPRECATED(("use rb_postponed_job_preregister and rb_postponed_job_trigger")) int rb_postponed_job_register_one(unsigned int flags, rb_postponed_job_func_t func, void *data); +/** @} */ + +/** + * @cond INTERNAL_MACRO + * + * Anything after this are intentionally left undocumented, to honour the + * comment below. + */ + /* undocumented advanced tracing APIs */ typedef enum { @@ -98,6 +827,8 @@ typedef enum { void rb_add_event_hook2(rb_event_hook_func_t func, rb_event_flag_t events, VALUE data, rb_event_hook_flag_t hook_flag); void rb_thread_add_event_hook2(VALUE thval, rb_event_hook_func_t func, rb_event_flag_t events, VALUE data, rb_event_hook_flag_t hook_flag); +/** @endcond */ + RBIMPL_SYMBOL_EXPORT_END() #endif /* RUBY_DEBUG_H */ diff --git a/include/ruby/defines.h b/include/ruby/defines.h index d632a69fc1..48184f8a18 100644 --- a/include/ruby/defines.h +++ b/include/ruby/defines.h @@ -72,23 +72,30 @@ #include "ruby/backward/2/assume.h" #include "ruby/backward/2/attributes.h" #include "ruby/backward/2/bool.h" -#include "ruby/backward/2/gcc_version_since.h" #include "ruby/backward/2/long_long.h" #include "ruby/backward/2/stdalign.h" #include "ruby/backward/2/stdarg.h" #include "ruby/internal/dosish.h" #include "ruby/missing.h" +/** + * Asserts that the compilation unit includes Ruby's CAPI. This has been here + * since the very beginning (at least since version 0.49). + */ #define RUBY #ifdef __GNUC__ +# /** This is expanded to nothing for non-GCC compilers. */ # define RB_GNUC_EXTENSION __extension__ +# /** This is expanded to the passed token for non-GCC compilers. */ # define RB_GNUC_EXTENSION_BLOCK(x) __extension__ ({ x; }) #else # define RB_GNUC_EXTENSION # define RB_GNUC_EXTENSION_BLOCK(x) (x) #endif +/** @cond INTERNAL_MACRO */ + /* :FIXME: Can someone tell us why is this macro defined here? @shyouhei * thinks this is a truly internal macro but cannot move around because he * doesn't understand the reason of this arrangement. */ @@ -105,5 +112,5 @@ RBIMPL_SYMBOL_EXPORT_END() #else # define FLUSH_REGISTER_WINDOWS ((void)0) #endif - +/** @endcond */ #endif /* RUBY_DEFINES_H */ diff --git a/include/ruby/encoding.h b/include/ruby/encoding.h index 4e46d0d996..1256393701 100644 --- a/include/ruby/encoding.h +++ b/include/ruby/encoding.h @@ -9,403 +9,23 @@ * 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. + * @brief Encoding relates APIs. + * + * These APIs are mainly for implementing encodings themselves. Encodings are + * built on top of Ruby's core CAPIs. Though not prohibited, there can be + * relatively less rooms for things in this header file be useful when writing + * an extension library. */ -#include "ruby/internal/config.h" -#include <stdarg.h> #include "ruby/ruby.h" -#include "ruby/oniguruma.h" -#include "ruby/internal/dllexport.h" -RBIMPL_SYMBOL_EXPORT_BEGIN() - -enum ruby_encoding_consts { - RUBY_ENCODING_INLINE_MAX = 127, - RUBY_ENCODING_SHIFT = (RUBY_FL_USHIFT+10), - RUBY_ENCODING_MASK = (RUBY_ENCODING_INLINE_MAX<<RUBY_ENCODING_SHIFT - /* RUBY_FL_USER10..RUBY_FL_USER16 */), - RUBY_ENCODING_MAXNAMELEN = 42 -}; - -#define ENCODING_INLINE_MAX RUBY_ENCODING_INLINE_MAX -#define ENCODING_SHIFT RUBY_ENCODING_SHIFT -#define ENCODING_MASK RUBY_ENCODING_MASK - -#define RB_ENCODING_SET_INLINED(obj,i) do {\ - RBASIC(obj)->flags &= ~RUBY_ENCODING_MASK;\ - RBASIC(obj)->flags |= (VALUE)(i) << RUBY_ENCODING_SHIFT;\ -} while (0) -#define RB_ENCODING_SET(obj,i) rb_enc_set_index((obj), (i)) - -#define RB_ENCODING_GET_INLINED(obj) \ - (int)((RBASIC(obj)->flags & RUBY_ENCODING_MASK)>>RUBY_ENCODING_SHIFT) -#define RB_ENCODING_GET(obj) \ - (RB_ENCODING_GET_INLINED(obj) != RUBY_ENCODING_INLINE_MAX ? \ - RB_ENCODING_GET_INLINED(obj) : \ - rb_enc_get_index(obj)) - -#define RB_ENCODING_IS_ASCII8BIT(obj) (RB_ENCODING_GET_INLINED(obj) == 0) - -#define ENCODING_SET_INLINED(obj,i) RB_ENCODING_SET_INLINED(obj,i) -#define ENCODING_SET(obj,i) RB_ENCODING_SET(obj,i) -#define ENCODING_GET_INLINED(obj) RB_ENCODING_GET_INLINED(obj) -#define ENCODING_GET(obj) RB_ENCODING_GET(obj) -#define ENCODING_IS_ASCII8BIT(obj) RB_ENCODING_IS_ASCII8BIT(obj) -#define ENCODING_MAXNAMELEN RUBY_ENCODING_MAXNAMELEN - -enum ruby_coderange_type { - RUBY_ENC_CODERANGE_UNKNOWN = 0, - RUBY_ENC_CODERANGE_7BIT = ((int)RUBY_FL_USER8), - RUBY_ENC_CODERANGE_VALID = ((int)RUBY_FL_USER9), - RUBY_ENC_CODERANGE_BROKEN = ((int)(RUBY_FL_USER8|RUBY_FL_USER9)), - RUBY_ENC_CODERANGE_MASK = (RUBY_ENC_CODERANGE_7BIT| - RUBY_ENC_CODERANGE_VALID| - RUBY_ENC_CODERANGE_BROKEN) -}; - -static inline int -rb_enc_coderange_clean_p(int cr) -{ - return (cr ^ (cr >> 1)) & RUBY_ENC_CODERANGE_7BIT; -} -#define RB_ENC_CODERANGE_CLEAN_P(cr) rb_enc_coderange_clean_p(cr) -#define RB_ENC_CODERANGE(obj) ((int)RBASIC(obj)->flags & RUBY_ENC_CODERANGE_MASK) -#define RB_ENC_CODERANGE_ASCIIONLY(obj) (RB_ENC_CODERANGE(obj) == RUBY_ENC_CODERANGE_7BIT) -#define RB_ENC_CODERANGE_SET(obj,cr) (\ - RBASIC(obj)->flags = \ - (RBASIC(obj)->flags & ~RUBY_ENC_CODERANGE_MASK) | (cr)) -#define RB_ENC_CODERANGE_CLEAR(obj) RB_ENC_CODERANGE_SET((obj),0) - -/* assumed ASCII compatibility */ -#define RB_ENC_CODERANGE_AND(a, b) \ - ((a) == RUBY_ENC_CODERANGE_7BIT ? (b) : \ - (a) != RUBY_ENC_CODERANGE_VALID ? RUBY_ENC_CODERANGE_UNKNOWN : \ - (b) == RUBY_ENC_CODERANGE_7BIT ? RUBY_ENC_CODERANGE_VALID : (b)) - -#define RB_ENCODING_CODERANGE_SET(obj, encindex, cr) \ - do { \ - VALUE rb_encoding_coderange_obj = (obj); \ - RB_ENCODING_SET(rb_encoding_coderange_obj, (encindex)); \ - RB_ENC_CODERANGE_SET(rb_encoding_coderange_obj, (cr)); \ - } while (0) - -#define ENC_CODERANGE_MASK RUBY_ENC_CODERANGE_MASK -#define ENC_CODERANGE_UNKNOWN RUBY_ENC_CODERANGE_UNKNOWN -#define ENC_CODERANGE_7BIT RUBY_ENC_CODERANGE_7BIT -#define ENC_CODERANGE_VALID RUBY_ENC_CODERANGE_VALID -#define ENC_CODERANGE_BROKEN RUBY_ENC_CODERANGE_BROKEN -#define ENC_CODERANGE_CLEAN_P(cr) RB_ENC_CODERANGE_CLEAN_P(cr) -#define ENC_CODERANGE(obj) RB_ENC_CODERANGE(obj) -#define ENC_CODERANGE_ASCIIONLY(obj) RB_ENC_CODERANGE_ASCIIONLY(obj) -#define ENC_CODERANGE_SET(obj,cr) RB_ENC_CODERANGE_SET(obj,cr) -#define ENC_CODERANGE_CLEAR(obj) RB_ENC_CODERANGE_CLEAR(obj) -#define ENC_CODERANGE_AND(a, b) RB_ENC_CODERANGE_AND(a, b) -#define ENCODING_CODERANGE_SET(obj, encindex, cr) RB_ENCODING_CODERANGE_SET(obj, encindex, cr) - -typedef const OnigEncodingType rb_encoding; - -int rb_char_to_option_kcode(int c, int *option, int *kcode); - -int rb_enc_replicate(const char *, rb_encoding *); -int rb_define_dummy_encoding(const char *); -PUREFUNC(int rb_enc_dummy_p(rb_encoding *enc)); -PUREFUNC(int rb_enc_to_index(rb_encoding *enc)); -int rb_enc_get_index(VALUE obj); -void rb_enc_set_index(VALUE obj, int encindex); -int rb_enc_capable(VALUE obj); -int rb_enc_find_index(const char *name); -int rb_enc_alias(const char *alias, const char *orig); -int rb_to_encoding_index(VALUE); -rb_encoding *rb_to_encoding(VALUE); -rb_encoding *rb_find_encoding(VALUE); -rb_encoding *rb_enc_get(VALUE); -rb_encoding *rb_enc_compatible(VALUE,VALUE); -rb_encoding *rb_enc_check(VALUE,VALUE); -VALUE rb_enc_associate_index(VALUE, int); -VALUE rb_enc_associate(VALUE, rb_encoding*); -void rb_enc_copy(VALUE dst, VALUE src); - -VALUE rb_enc_str_new(const char*, long, rb_encoding*); -VALUE rb_enc_str_new_cstr(const char*, rb_encoding*); -VALUE rb_enc_str_new_static(const char*, long, rb_encoding*); -VALUE rb_enc_interned_str(const char *, long, rb_encoding *); -VALUE rb_enc_interned_str_cstr(const char *, rb_encoding *); -VALUE rb_enc_reg_new(const char*, long, rb_encoding*, int); -PRINTF_ARGS(VALUE rb_enc_sprintf(rb_encoding *, const char*, ...), 2, 3); -VALUE rb_enc_vsprintf(rb_encoding *, const char*, va_list); -long rb_enc_strlen(const char*, const char*, rb_encoding*); -char* rb_enc_nth(const char*, const char*, long, rb_encoding*); -VALUE rb_obj_encoding(VALUE); -VALUE rb_enc_str_buf_cat(VALUE str, const char *ptr, long len, rb_encoding *enc); -VALUE rb_enc_uint_chr(unsigned int code, rb_encoding *enc); - -VALUE rb_external_str_new_with_enc(const char *ptr, long len, rb_encoding *); -VALUE rb_str_export_to_enc(VALUE, rb_encoding *); -VALUE rb_str_conv_enc(VALUE str, rb_encoding *from, rb_encoding *to); -VALUE rb_str_conv_enc_opts(VALUE str, rb_encoding *from, rb_encoding *to, int ecflags, VALUE ecopts); - -#ifdef HAVE_BUILTIN___BUILTIN_CONSTANT_P -#define rb_enc_str_new(str, len, enc) RB_GNUC_EXTENSION_BLOCK( \ - (__builtin_constant_p(str) && __builtin_constant_p(len)) ? \ - rb_enc_str_new_static((str), (len), (enc)) : \ - rb_enc_str_new((str), (len), (enc)) \ -) -#define rb_enc_str_new_cstr(str, enc) RB_GNUC_EXTENSION_BLOCK( \ - (__builtin_constant_p(str)) ? \ - rb_enc_str_new_static((str), (long)strlen(str), (enc)) : \ - rb_enc_str_new_cstr((str), (enc)) \ -) -#endif - -PRINTF_ARGS(NORETURN(void rb_enc_raise(rb_encoding *, VALUE, const char*, ...)), 3, 4); - -/* index -> rb_encoding */ -rb_encoding *rb_enc_from_index(int idx); - -/* name -> rb_encoding */ -rb_encoding *rb_enc_find(const char *name); - -/* rb_encoding * -> name */ -#define rb_enc_name(enc) (enc)->name - -/* rb_encoding * -> minlen/maxlen */ -#define rb_enc_mbminlen(enc) (enc)->min_enc_len -#define rb_enc_mbmaxlen(enc) (enc)->max_enc_len - -/* -> mbclen (no error notification: 0 < ret <= e-p, no exception) */ -int rb_enc_mbclen(const char *p, const char *e, rb_encoding *enc); - -/* -> mbclen (only for valid encoding) */ -int rb_enc_fast_mbclen(const char *p, const char *e, rb_encoding *enc); - -/* -> chlen, invalid or needmore */ -int rb_enc_precise_mbclen(const char *p, const char *e, rb_encoding *enc); -#define MBCLEN_CHARFOUND_P(ret) ONIGENC_MBCLEN_CHARFOUND_P(ret) -#define MBCLEN_CHARFOUND_LEN(ret) ONIGENC_MBCLEN_CHARFOUND_LEN(ret) -#define MBCLEN_INVALID_P(ret) ONIGENC_MBCLEN_INVALID_P(ret) -#define MBCLEN_NEEDMORE_P(ret) ONIGENC_MBCLEN_NEEDMORE_P(ret) -#define MBCLEN_NEEDMORE_LEN(ret) ONIGENC_MBCLEN_NEEDMORE_LEN(ret) - -/* -> 0x00..0x7f, -1 */ -int rb_enc_ascget(const char *p, const char *e, int *len, rb_encoding *enc); - - -/* -> code (and len) or raise exception */ -unsigned int rb_enc_codepoint_len(const char *p, const char *e, int *len, rb_encoding *enc); - -/* prototype for obsolete function */ -unsigned int rb_enc_codepoint(const char *p, const char *e, rb_encoding *enc); -/* overriding macro */ -#define rb_enc_codepoint(p,e,enc) rb_enc_codepoint_len((p),(e),0,(enc)) -#define rb_enc_mbc_to_codepoint(p, e, enc) ONIGENC_MBC_TO_CODE((enc),(UChar*)(p),(UChar*)(e)) - -/* -> codelen>0 or raise exception */ -int rb_enc_codelen(int code, rb_encoding *enc); -/* -> 0 for invalid codepoint */ -int rb_enc_code_to_mbclen(int code, rb_encoding *enc); -#define rb_enc_code_to_mbclen(c, enc) ONIGENC_CODE_TO_MBCLEN((enc), (c)); - -/* code,ptr,encoding -> write buf */ -#define rb_enc_mbcput(c,buf,enc) ONIGENC_CODE_TO_MBC((enc),(c),(UChar*)(buf)) - -/* start, ptr, end, encoding -> prev_char */ -#define rb_enc_prev_char(s,p,e,enc) ((char *)onigenc_get_prev_char_head((enc),(UChar*)(s),(UChar*)(p),(UChar*)(e))) -/* start, ptr, end, encoding -> next_char */ -#define rb_enc_left_char_head(s,p,e,enc) ((char *)onigenc_get_left_adjust_char_head((enc),(UChar*)(s),(UChar*)(p),(UChar*)(e))) -#define rb_enc_right_char_head(s,p,e,enc) ((char *)onigenc_get_right_adjust_char_head((enc),(UChar*)(s),(UChar*)(p),(UChar*)(e))) -#define rb_enc_step_back(s,p,e,n,enc) ((char *)onigenc_step_back((enc),(UChar*)(s),(UChar*)(p),(UChar*)(e),(int)(n))) - -/* ptr, ptr, encoding -> newline_or_not */ -#define rb_enc_is_newline(p,end,enc) ONIGENC_IS_MBC_NEWLINE((enc),(UChar*)(p),(UChar*)(end)) - -#define rb_enc_isctype(c,t,enc) ONIGENC_IS_CODE_CTYPE((enc),(c),(t)) -#define rb_enc_isascii(c,enc) ONIGENC_IS_CODE_ASCII(c) -#define rb_enc_isalpha(c,enc) ONIGENC_IS_CODE_ALPHA((enc),(c)) -#define rb_enc_islower(c,enc) ONIGENC_IS_CODE_LOWER((enc),(c)) -#define rb_enc_isupper(c,enc) ONIGENC_IS_CODE_UPPER((enc),(c)) -#define rb_enc_ispunct(c,enc) ONIGENC_IS_CODE_PUNCT((enc),(c)) -#define rb_enc_isalnum(c,enc) ONIGENC_IS_CODE_ALNUM((enc),(c)) -#define rb_enc_isprint(c,enc) ONIGENC_IS_CODE_PRINT((enc),(c)) -#define rb_enc_isspace(c,enc) ONIGENC_IS_CODE_SPACE((enc),(c)) -#define rb_enc_isdigit(c,enc) ONIGENC_IS_CODE_DIGIT((enc),(c)) - -static inline int -rb_enc_asciicompat_inline(rb_encoding *enc) -{ - return rb_enc_mbminlen(enc)==1 && !rb_enc_dummy_p(enc); -} -#define rb_enc_asciicompat(enc) rb_enc_asciicompat_inline(enc) - -CONSTFUNC(int rb_enc_toupper(int c, rb_encoding *enc)); -CONSTFUNC(int rb_enc_tolower(int c, rb_encoding *enc)); -ID rb_intern3(const char*, long, rb_encoding*); -int rb_enc_symname_p(const char*, rb_encoding*); -int rb_enc_symname2_p(const char*, long, rb_encoding*); -int rb_enc_str_coderange(VALUE); -long rb_str_coderange_scan_restartable(const char*, const char*, rb_encoding*, int*); -int rb_enc_str_asciionly_p(VALUE); -#define rb_enc_str_asciicompat_p(str) rb_enc_asciicompat(rb_enc_get(str)) -VALUE rb_enc_from_encoding(rb_encoding *enc); -PUREFUNC(int rb_enc_unicode_p(rb_encoding *enc)); -rb_encoding *rb_ascii8bit_encoding(void); -rb_encoding *rb_utf8_encoding(void); -rb_encoding *rb_usascii_encoding(void); -rb_encoding *rb_locale_encoding(void); -rb_encoding *rb_filesystem_encoding(void); -rb_encoding *rb_default_external_encoding(void); -rb_encoding *rb_default_internal_encoding(void); -#ifndef rb_ascii8bit_encindex -CONSTFUNC(int rb_ascii8bit_encindex(void)); -#endif -#ifndef rb_utf8_encindex -CONSTFUNC(int rb_utf8_encindex(void)); -#endif -#ifndef rb_usascii_encindex -CONSTFUNC(int rb_usascii_encindex(void)); -#endif -int rb_locale_encindex(void); -int rb_filesystem_encindex(void); -VALUE rb_enc_default_external(void); -VALUE rb_enc_default_internal(void); -void rb_enc_set_default_external(VALUE encoding); -void rb_enc_set_default_internal(VALUE encoding); -VALUE rb_locale_charmap(VALUE klass); -long rb_memsearch(const void*,long,const void*,long,rb_encoding*); -char *rb_enc_path_next(const char *,const char *,rb_encoding*); -char *rb_enc_path_skip_prefix(const char *,const char *,rb_encoding*); -char *rb_enc_path_last_separator(const char *,const char *,rb_encoding*); -char *rb_enc_path_end(const char *,const char *,rb_encoding*); -const char *ruby_enc_find_basename(const char *name, long *baselen, long *alllen, rb_encoding *enc); -const char *ruby_enc_find_extname(const char *name, long *len, rb_encoding *enc); -ID rb_check_id_cstr(const char *ptr, long len, rb_encoding *enc); -VALUE rb_check_symbol_cstr(const char *ptr, long len, rb_encoding *enc); - -RUBY_EXTERN VALUE rb_cEncoding; - -/* econv stuff */ - -typedef enum { - econv_invalid_byte_sequence, - econv_undefined_conversion, - econv_destination_buffer_full, - econv_source_buffer_empty, - econv_finished, - econv_after_output, - econv_incomplete_input -} rb_econv_result_t; - -typedef struct rb_econv_t rb_econv_t; - -VALUE rb_str_encode(VALUE str, VALUE to, int ecflags, VALUE ecopts); -int rb_econv_has_convpath_p(const char* from_encoding, const char* to_encoding); - -int rb_econv_prepare_options(VALUE opthash, VALUE *ecopts, int ecflags); -int rb_econv_prepare_opts(VALUE opthash, VALUE *ecopts); - -rb_econv_t *rb_econv_open(const char *source_encoding, const char *destination_encoding, int ecflags); -rb_econv_t *rb_econv_open_opts(const char *source_encoding, const char *destination_encoding, int ecflags, VALUE ecopts); - -rb_econv_result_t rb_econv_convert(rb_econv_t *ec, - const unsigned char **source_buffer_ptr, const unsigned char *source_buffer_end, - unsigned char **destination_buffer_ptr, unsigned char *destination_buffer_end, - int flags); -void rb_econv_close(rb_econv_t *ec); - -/* result: 0:success -1:failure */ -int rb_econv_set_replacement(rb_econv_t *ec, const unsigned char *str, size_t len, const char *encname); - -/* result: 0:success -1:failure */ -int rb_econv_decorate_at_first(rb_econv_t *ec, const char *decorator_name); -int rb_econv_decorate_at_last(rb_econv_t *ec, const char *decorator_name); - -VALUE rb_econv_open_exc(const char *senc, const char *denc, int ecflags); - -/* result: 0:success -1:failure */ -int rb_econv_insert_output(rb_econv_t *ec, - const unsigned char *str, size_t len, const char *str_encoding); - -/* encoding that rb_econv_insert_output doesn't need conversion */ -const char *rb_econv_encoding_to_insert_output(rb_econv_t *ec); - -/* raise an error if the last rb_econv_convert is error */ -void rb_econv_check_error(rb_econv_t *ec); - -/* returns an exception object or nil */ -VALUE rb_econv_make_exception(rb_econv_t *ec); - -int rb_econv_putbackable(rb_econv_t *ec); -void rb_econv_putback(rb_econv_t *ec, unsigned char *p, int n); - -/* returns the corresponding ASCII compatible encoding for encname, - * or NULL if encname is not ASCII incompatible encoding. */ -const char *rb_econv_asciicompat_encoding(const char *encname); - -VALUE rb_econv_str_convert(rb_econv_t *ec, VALUE src, int flags); -VALUE rb_econv_substr_convert(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, int flags); -VALUE rb_econv_str_append(rb_econv_t *ec, VALUE src, VALUE dst, int flags); -VALUE rb_econv_substr_append(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, VALUE dst, int flags); -VALUE rb_econv_append(rb_econv_t *ec, const char *bytesrc, long bytesize, VALUE dst, int flags); - -void rb_econv_binmode(rb_econv_t *ec); - -enum ruby_econv_flag_type { -/* flags for rb_econv_open */ - RUBY_ECONV_ERROR_HANDLER_MASK = 0x000000ff, - - RUBY_ECONV_INVALID_MASK = 0x0000000f, - RUBY_ECONV_INVALID_REPLACE = 0x00000002, - - RUBY_ECONV_UNDEF_MASK = 0x000000f0, - RUBY_ECONV_UNDEF_REPLACE = 0x00000020, - RUBY_ECONV_UNDEF_HEX_CHARREF = 0x00000030, - - RUBY_ECONV_DECORATOR_MASK = 0x0000ff00, - RUBY_ECONV_NEWLINE_DECORATOR_MASK = 0x00003f00, - RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK = 0x00000f00, - RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK = 0x00003000, - - RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR = 0x00000100, - RUBY_ECONV_CRLF_NEWLINE_DECORATOR = 0x00001000, - RUBY_ECONV_CR_NEWLINE_DECORATOR = 0x00002000, - RUBY_ECONV_XML_TEXT_DECORATOR = 0x00004000, - RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR = 0x00008000, - - RUBY_ECONV_STATEFUL_DECORATOR_MASK = 0x00f00000, - RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR = 0x00100000, - - RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR = -#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32) - RUBY_ECONV_CRLF_NEWLINE_DECORATOR, -#else - 0, -#endif -#define ECONV_ERROR_HANDLER_MASK RUBY_ECONV_ERROR_HANDLER_MASK -#define ECONV_INVALID_MASK RUBY_ECONV_INVALID_MASK -#define ECONV_INVALID_REPLACE RUBY_ECONV_INVALID_REPLACE -#define ECONV_UNDEF_MASK RUBY_ECONV_UNDEF_MASK -#define ECONV_UNDEF_REPLACE RUBY_ECONV_UNDEF_REPLACE -#define ECONV_UNDEF_HEX_CHARREF RUBY_ECONV_UNDEF_HEX_CHARREF -#define ECONV_DECORATOR_MASK RUBY_ECONV_DECORATOR_MASK -#define ECONV_NEWLINE_DECORATOR_MASK RUBY_ECONV_NEWLINE_DECORATOR_MASK -#define ECONV_NEWLINE_DECORATOR_READ_MASK RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK -#define ECONV_NEWLINE_DECORATOR_WRITE_MASK RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK -#define ECONV_UNIVERSAL_NEWLINE_DECORATOR RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR -#define ECONV_CRLF_NEWLINE_DECORATOR RUBY_ECONV_CRLF_NEWLINE_DECORATOR -#define ECONV_CR_NEWLINE_DECORATOR RUBY_ECONV_CR_NEWLINE_DECORATOR -#define ECONV_XML_TEXT_DECORATOR RUBY_ECONV_XML_TEXT_DECORATOR -#define ECONV_XML_ATTR_CONTENT_DECORATOR RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR -#define ECONV_STATEFUL_DECORATOR_MASK RUBY_ECONV_STATEFUL_DECORATOR_MASK -#define ECONV_XML_ATTR_QUOTE_DECORATOR RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR -#define ECONV_DEFAULT_NEWLINE_DECORATOR RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR -/* end of flags for rb_econv_open */ - -/* flags for rb_econv_convert */ - RUBY_ECONV_PARTIAL_INPUT = 0x00010000, - RUBY_ECONV_AFTER_OUTPUT = 0x00020000, -#define ECONV_PARTIAL_INPUT RUBY_ECONV_PARTIAL_INPUT -#define ECONV_AFTER_OUTPUT RUBY_ECONV_AFTER_OUTPUT -/* end of flags for rb_econv_convert */ -RUBY_ECONV_FLAGS_PLACEHOLDER}; - -RBIMPL_SYMBOL_EXPORT_END() +#include "ruby/internal/encoding/coderange.h" +#include "ruby/internal/encoding/ctype.h" +#include "ruby/internal/encoding/encoding.h" +#include "ruby/internal/encoding/pathname.h" +#include "ruby/internal/encoding/re.h" +#include "ruby/internal/encoding/sprintf.h" +#include "ruby/internal/encoding/string.h" +#include "ruby/internal/encoding/symbol.h" +#include "ruby/internal/encoding/transcode.h" #endif /* RUBY_ENCODING_H */ diff --git a/include/ruby/fiber/scheduler.h b/include/ruby/fiber/scheduler.h index 246e690587..4d764f68ae 100644 --- a/include/ruby/fiber/scheduler.h +++ b/include/ruby/fiber/scheduler.h @@ -1,4 +1,4 @@ -#ifndef RUBY_FIBER_SCHEDULER_H /*-*-C-*-vi:se ft=c:*/ +#ifndef RUBY_FIBER_SCHEDULER_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_FIBER_SCHEDULER_H /** * @file @@ -7,45 +7,499 @@ * 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. - * @brief Internal header for Scheduler. + * @brief Scheduler APIs. */ +#include "ruby/internal/config.h" + +#include <errno.h> + +#ifdef STDC_HEADERS +#include <stddef.h> /* size_t */ +#endif + #include "ruby/ruby.h" -#include "ruby/intern.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/arithmetic.h" RBIMPL_SYMBOL_EXPORT_BEGIN() +// Version 3: Adds support for `fiber_interrupt`. +#define RUBY_FIBER_SCHEDULER_VERSION 3 + +struct timeval; +struct rb_thread_struct; + +/** + * Wrap a `ssize_t` and `int errno` into a single `VALUE`. This interface should + * be used to safely capture results from system calls like `read` and `write`. + * + * You should use `rb_fiber_scheduler_io_result_apply` to unpack the result of + * this value and update `int errno`. + * + * You should not directly try to interpret the result value as it is considered + * an opaque representation. However, the general representation is an integer + * in the range of `[-int errno, size_t size]`. Linux generally restricts the + * result of system calls like `read` and `write` to `<= 2^31` which means this + * will typically fit within a single FIXNUM. + * + * @param[in] result The result of the system call. + * @param[in] error The value of `errno`. + * @return A `VALUE` which contains the result and/or errno. + */ +static inline VALUE +rb_fiber_scheduler_io_result(ssize_t result, int error) +{ + if (result == -1) { + return RB_INT2NUM(-error); + } + else { + return RB_SIZE2NUM(result); + } +} + +/** + * Apply an io result to the local thread, returning the value of the original + * system call that created it and updating `int errno`. + * + * You should not directly try to interpret the result value as it is considered + * an opaque representation. + * + * @param[in] result The `VALUE` which contains an errno and/or result size. + * @post Updates `int errno` with the value if negative. + * @return The original result of the system call. + */ +static inline ssize_t +rb_fiber_scheduler_io_result_apply(VALUE result) +{ + if (RB_FIXNUM_P(result) && RB_NUM2INT(result) < 0) { + errno = -RB_NUM2INT(result); + return -1; + } + else { + return RB_NUM2SIZE(result); + } +} + +/** + * Queries the current scheduler of the current thread that is calling this + * function. + * + * @retval RUBY_Qnil No scheduler has been set so far to this thread (which + * is the default). + * @retval otherwise The scheduler that was last set for the current thread + * with rb_fiber_scheduler_set(). + */ VALUE rb_fiber_scheduler_get(void); + +/** + * Destructively assigns the passed scheduler to that of the current thread + * that is calling this function. If the scheduler is set, non-blocking fibers + * (created by `Fiber.new` with `blocking: false`, or by `Fiber.schedule`) call + * that scheduler's hook methods on potentially blocking operations, and the + * current thread will call scheduler's `#close` method on finalisation + * (allowing the scheduler to properly manage all non-finished fibers). + * `scheduler` can be an object of any class corresponding to + * `Fiber::Scheduler` interface. Its implementation is up to the user. + * + * @param[in] scheduler The scheduler to set. + * @exception rb_eArgError `scheduler` does not conform the interface. + * @post Current thread's scheduler is `scheduler`. + */ VALUE rb_fiber_scheduler_set(VALUE scheduler); +/** + * Identical to rb_fiber_scheduler_get(), except it also returns ::RUBY_Qnil in + * case of a blocking fiber. As blocking fibers do not participate schedulers' + * scheduling this function can be handy. + * + * @retval RUBY_Qnil No scheduler is in effect. + * @retval otherwise The scheduler that is in effect, if any. + */ VALUE rb_fiber_scheduler_current(void); + +/** + * Identical to rb_fiber_scheduler_current(), except it queries for that of the + * passed thread value instead of the implicit current one. + * + * @param[in] thread Target thread. + * @exception rb_eTypeError `thread` is not a thread. + * @retval RUBY_Qnil No scheduler is in effect in `thread`. + * @retval otherwise The scheduler that is in effect in `thread`. + */ VALUE rb_fiber_scheduler_current_for_thread(VALUE thread); +/** + * Identical to rb_fiber_scheduler_current_for_thread(), except it expects + * a threadptr instead of a thread value. + * + * @param[in] thread Target thread. + * @exception rb_eTypeError `thread` is not a thread. + * @retval RUBY_Qnil No scheduler is in effect in `thread`. + * @retval otherwise The scheduler that is in effect in `thread`. + */ +VALUE rb_fiber_scheduler_current_for_threadptr(struct rb_thread_struct *thread); + +/** + * Converts the passed timeout to an expression that rb_fiber_scheduler_block() + * etc. expects. + * + * @param[in] timeout A duration (can be `NULL`). + * @retval RUBY_Qnil No timeout (blocks indefinitely). + * @retval otherwise A timeout object. + */ VALUE rb_fiber_scheduler_make_timeout(struct timeval *timeout); +/** + * Closes the passed scheduler object. This expects the scheduler to wait for + * all fibers. Thus the scheduler's main loop tends to start here. + * + * @param[in] scheduler Target scheduler. + * @return What `scheduler.close` returns. + */ VALUE rb_fiber_scheduler_close(VALUE scheduler); +/** + * Non-blocking `sleep`. Depending on scheduler implementation, this for + * instance switches to another fiber etc. + * + * @param[in] scheduler Target scheduler. + * @param[in] duration Passed as-is to `scheduler.kernel_sleep`. + * @return What `scheduler.kernel_sleep` returns. + */ VALUE rb_fiber_scheduler_kernel_sleep(VALUE scheduler, VALUE duration); + +/** + * Identical to rb_fiber_scheduler_kernel_sleep(), except it can pass multiple + * arguments. + * + * @param[in] scheduler Target scheduler. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed as-is to `scheduler.kernel_sleep` + * @return What `scheduler.kernel_sleep` returns. + */ VALUE rb_fiber_scheduler_kernel_sleepv(VALUE scheduler, int argc, VALUE * argv); +/** + * Yield to the scheduler, to be resumed on the next scheduling cycle. + * + * @param[in] scheduler Target scheduler. + * @return What `scheduler.yield` returns. + */ +VALUE rb_fiber_scheduler_yield(VALUE scheduler); + +/* Description TBW */ #if 0 VALUE rb_fiber_scheduler_timeout_after(VALUE scheduler, VALUE timeout, VALUE exception, VALUE message); VALUE rb_fiber_scheduler_timeout_afterv(VALUE scheduler, int argc, VALUE * argv); +int rb_fiber_scheduler_supports_process_wait(VALUE scheduler); #endif -int rb_fiber_scheduler_supports_process_wait(VALUE scheduler); +/** + * Non-blocking `waitpid`. Depending on scheduler implementation, this for + * instance switches to another fiber etc. + * + * @param[in] scheduler Target scheduler. + * @param[in] pid Process ID to wait. + * @param[in] flags Wait flags, e.g. `WUNTRACED`. + * @return What `scheduler.process_wait` returns. + */ VALUE rb_fiber_scheduler_process_wait(VALUE scheduler, rb_pid_t pid, int flags); +/** + * Non-blocking wait for the passed "blocker", which is for instance + * `Thread.join` or `Mutex.lock`. Depending on scheduler implementation, this + * for instance switches to another fiber etc. + * + * @param[in] scheduler Target scheduler. + * @param[in] blocker What blocks the current fiber. + * @param[in] timeout Numeric timeout. + * @return What `scheduler.block` returns. + */ VALUE rb_fiber_scheduler_block(VALUE scheduler, VALUE blocker, VALUE timeout); + +/** + * Wakes up a fiber previously blocked using rb_fiber_scheduler_block(). + * + * This function may be called from a different thread. + * + * @param[in] scheduler Target scheduler. + * @param[in] blocker What was awaited for. + * @param[in] fiber What to unblock. + * @return What `scheduler.unblock` returns. + */ VALUE rb_fiber_scheduler_unblock(VALUE scheduler, VALUE blocker, VALUE fiber); +/** + * Non-blocking version of rb_io_wait(). Depending on scheduler + * implementation, this for instance switches to another fiber etc. + * + * The "events" here is a Ruby level integer, which is an OR-ed value of + * `IO::READABLE`, `IO::WRITABLE`, and `IO::PRIORITY`. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to wait. + * @param[in] events An integer set of interests. + * @param[in] timeout Numeric timeout. + * @return What `scheduler.io_wait` returns. + */ VALUE rb_fiber_scheduler_io_wait(VALUE scheduler, VALUE io, VALUE events, VALUE timeout); + +/** + * Non-blocking wait until the passed IO is ready for reading. This is a + * special case of rb_fiber_scheduler_io_wait(), where the interest is + * `IO::READABLE` and timeout is never. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to wait. + * @return What `scheduler.io_wait` returns. + */ VALUE rb_fiber_scheduler_io_wait_readable(VALUE scheduler, VALUE io); + +/** + * Non-blocking wait until the passed IO is ready for writing. This is a + * special case of rb_fiber_scheduler_io_wait(), where the interest is + * `IO::WRITABLE` and timeout is never. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to wait. + * @return What `scheduler.io_wait` returns. + */ VALUE rb_fiber_scheduler_io_wait_writable(VALUE scheduler, VALUE io); -VALUE rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t offset, size_t length); -VALUE rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t offset, size_t length); +/** + * Non-blocking version of `IO.select`. + * + * It's possible that this will be emulated using a thread, so you should not + * rely on it for high performance. + * + * @param[in] scheduler Target scheduler. + * @param[in] readables An array of readable objects. + * @param[in] writables An array of writable objects. + * @param[in] exceptables An array of objects that might encounter exceptional conditions. + * @param[in] timeout Numeric timeout or nil. + * @return What `scheduler.io_select` returns, normally a 3-tuple of arrays of ready objects. + */ +VALUE rb_fiber_scheduler_io_select(VALUE scheduler, VALUE readables, VALUE writables, VALUE exceptables, VALUE timeout); + +/** + * Non-blocking version of `IO.select`, `argv` variant. + */ +VALUE rb_fiber_scheduler_io_selectv(VALUE scheduler, int argc, VALUE *argv); + +/** + * Non-blocking read from the passed IO. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to read from. + * @param[in] buffer The buffer to read to. + * @param[in] length The minimum number of bytes to read. + * @param[in] offset The offset in the buffer to read from. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_read`. + * @return otherwise What `scheduler.io_read` returns `[-errno, size]`. + */ +VALUE rb_fiber_scheduler_io_read(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset); + +/** + * Non-blocking write to the passed IO. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to write to. + * @param[in] buffer The buffer to write from. + * @param[in] length The minimum number of bytes to write. + * @param[in] offset The offset in the buffer to write from. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_write`. + * @return otherwise What `scheduler.io_write` returns `[-errno, size]`. + */ +VALUE rb_fiber_scheduler_io_write(VALUE scheduler, VALUE io, VALUE buffer, size_t length, size_t offset); + +/** + * Non-blocking read from the passed IO at the specified offset. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to read from. + * @param[in] from The offset to read from. + * @param[in] buffer The buffer to read to. + * @param[in] length The minimum number of bytes to read. + * @param[in] offset The offset in the buffer to read to. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_read`. + * @return otherwise What `scheduler.io_read` returns. + */ +VALUE rb_fiber_scheduler_io_pread(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset); + +/** + * Non-blocking write to the passed IO at the specified offset. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to write to. + * @param[in] from The offset to write to. + * @param[in] buffer The buffer to write from. + * @param[in] length The minimum number of bytes to write. + * @param[in] offset The offset in the buffer to write from. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_write`. + * @return otherwise What `scheduler.io_write` returns. + */ +VALUE rb_fiber_scheduler_io_pwrite(VALUE scheduler, VALUE io, rb_off_t from, VALUE buffer, size_t length, size_t offset); + +/** + * Non-blocking read from the passed IO using a native buffer. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to read from. + * @param[in] base The memory to read to. + * @param[in] size Size of the memory. + * @param[in] length The minimum number of bytes to read. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_read`. + * @return otherwise What `scheduler.io_read` returns. + */ +VALUE rb_fiber_scheduler_io_read_memory(VALUE scheduler, VALUE io, void *base, size_t size, size_t length); + +/** + * Non-blocking write to the passed IO using a native buffer. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to write to. + * @param[in] base The memory to write from. + * @param[in] size Size of the memory. + * @param[in] length The minimum number of bytes to write. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_write`. + * @return otherwise What `scheduler.io_write` returns. + */ +VALUE rb_fiber_scheduler_io_write_memory(VALUE scheduler, VALUE io, const void *base, size_t size, size_t length); + +/** + * Non-blocking pread from the passed IO using a native buffer. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to read from. + * @param[in] from The offset to read from. + * @param[in] base The memory to read to. + * @param[in] size Size of the memory. + * @param[in] length The minimum number of bytes to read. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_read`. + * @return otherwise What `scheduler.io_read` returns. + */ +VALUE rb_fiber_scheduler_io_pread_memory(VALUE scheduler, VALUE io, rb_off_t from, void *base, size_t size, size_t length); + +/** + * Non-blocking pwrite to the passed IO using a native buffer. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to write to. + * @param[in] from The offset to write from. + * @param[in] base The memory to write from. + * @param[in] size Size of the memory. + * @param[in] length The minimum number of bytes to write. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_write`. + * @return otherwise What `scheduler.io_write` returns. + */ +VALUE rb_fiber_scheduler_io_pwrite_memory(VALUE scheduler, VALUE io, rb_off_t from, const void *base, size_t size, size_t length); + +/** + * Non-blocking close the given IO. + * + * @param[in] scheduler Target scheduler. + * @param[in] io An io object to close. + * @retval RUBY_Qundef `scheduler` doesn't have `#io_close`. + * @return otherwise What `scheduler.io_close` returns. + */ +VALUE rb_fiber_scheduler_io_close(VALUE scheduler, VALUE io); + +/** + * Non-blocking DNS lookup. + * + * @param[in] scheduler Target scheduler. + * @param[in] hostname A host name to query. + * @retval RUBY_Qundef `scheduler` doesn't have `#address_resolve`. + * @return otherwise What `scheduler.address_resolve` returns. + */ VALUE rb_fiber_scheduler_address_resolve(VALUE scheduler, VALUE hostname); +// The state of the blocking operation execution. +struct rb_fiber_scheduler_blocking_operation_state { + void *result; + int saved_errno; +}; + +// The opaque handle for the blocking operation. +typedef struct rb_fiber_scheduler_blocking_operation rb_fiber_scheduler_blocking_operation_t; + +/** + * Extract the blocking operation handle from a BlockingOperationRuby object. + * + * This function safely extracts the opaque handle from a BlockingOperation VALUE + * while holding the GVL. The returned pointer can be passed to worker threads + * and used with rb_fiber_scheduler_blocking_operation_execute. + * + * @param[in] self The BlockingOperation VALUE to extract from + * @return The opaque struct pointer on success, NULL on error + * @note Experimental. + */ +rb_fiber_scheduler_blocking_operation_t *rb_fiber_scheduler_blocking_operation_extract(VALUE self); + +/** + * Execute blocking operation from handle (GVL not required). + * + * This function executes a blocking operation using the opaque handle + * obtained from rb_fiber_scheduler_blocking_operation_extract. + * It can be called from native threads without holding the GVL. + * + * @param[in] blocking_operation The opaque handle. + * @return 0 on success, -1 on error. + * @note Experimental. Can be called from any thread without holding the GVL + */ +int rb_fiber_scheduler_blocking_operation_execute(rb_fiber_scheduler_blocking_operation_t *blocking_operation); + +/** + * Cancel a blocking operation. + * + * This function cancels a blocking operation. If the operation is queued, + * it just marks it as cancelled. If it's executing, it marks it as cancelled + * and calls the unblock function to interrupt the operation. + * + * @param blocking_operation The opaque struct pointer + * @return 1 if unblock function was called, 0 if just marked cancelled, -1 on error + * @note Experimental. + */ +int rb_fiber_scheduler_blocking_operation_cancel(rb_fiber_scheduler_blocking_operation_t *blocking_operation); + +/** + * Defer the execution of the passed function to the scheduler. + * + * @param[in] scheduler Target scheduler. + * @param[in] function The function to run. + * @param[in] data The data to pass to the function. + * @param[in] unblock_function The unblock function to use to interrupt the operation. + * @param[in] data2 The data to pass to the unblock function. + * @param[in] flags Flags passed to `rb_nogvl`. + * @param[out] state The result and errno of the operation. + * @retval RUBY_Qundef `scheduler` doesn't have `#blocking_operation_wait`. + * @return otherwise What `scheduler.blocking_operation_wait` returns. + */ +VALUE rb_fiber_scheduler_blocking_operation_wait(VALUE scheduler, void* (*function)(void *), void *data, rb_unblock_function_t *unblock_function, void *data2, int flags, struct rb_fiber_scheduler_blocking_operation_state *state); + +/** + * Interrupt a fiber by raising an exception. You can construct an exception using `rb_make_exception`. + * + * This hook may be invoked by a different thread. + * + * @param[in] scheduler Target scheduler. + * @param[in] fiber The fiber to interrupt. + * @param[in] exception The exception to raise in the fiber. + * @return What `scheduler.fiber_interrupt` returns. + */ +VALUE rb_fiber_scheduler_fiber_interrupt(VALUE scheduler, VALUE fiber, VALUE exception); + +/** + * Create and schedule a non-blocking fiber. + * + * @param[in] scheduler Target scheduler. + * @param[in] argc Number of arguments in argv. + * @param[in] argv Array of arguments to pass to the fiber. + * @param[in] kw_splat Whether to expand last argument as keywords. + * @return The created and scheduled fiber. + */ +VALUE rb_fiber_scheduler_fiber(VALUE scheduler, int argc, VALUE *argv, int kw_splat); + RBIMPL_SYMBOL_EXPORT_END() #endif /* RUBY_FIBER_SCHEDULER_H */ diff --git a/include/ruby/intern.h b/include/ruby/intern.h index 2480e2e703..8718169ce2 100644 --- a/include/ruby/intern.h +++ b/include/ruby/intern.h @@ -36,7 +36,6 @@ #include "ruby/internal/intern/error.h" #include "ruby/internal/intern/eval.h" #include "ruby/internal/intern/file.h" -#include "ruby/internal/intern/gc.h" #include "ruby/internal/intern/hash.h" #include "ruby/internal/intern/io.h" #include "ruby/internal/intern/load.h" @@ -52,6 +51,7 @@ #include "ruby/internal/intern/re.h" #include "ruby/internal/intern/ruby.h" #include "ruby/internal/intern/select.h" +#include "ruby/internal/intern/set.h" #include "ruby/internal/intern/signal.h" #include "ruby/internal/intern/sprintf.h" #include "ruby/internal/intern/string.h" diff --git a/include/ruby/internal/abi.h b/include/ruby/internal/abi.h new file mode 100644 index 0000000000..e6d1fa7e8f --- /dev/null +++ b/include/ruby/internal/abi.h @@ -0,0 +1,58 @@ +#ifndef RUBY_ABI_H +#define RUBY_ABI_H + +#ifdef RUBY_ABI_VERSION /* should match the definition in config.h */ + +/* This number represents Ruby's ABI version. + * + * In development Ruby, it should be bumped every time an ABI incompatible + * change is introduced. This will force other developers to rebuild extension + * gems. + * + * The following cases are considered as ABI incompatible changes: + * - Changing any data structures. + * - Changing macros or inline functions causing a change in behavior. + * - Deprecating or removing function declarations. + * + * The following cases are NOT considered as ABI incompatible changes: + * - Any changes that does not involve the header files in the `include` + * directory. + * - Adding macros, inline functions, or function declarations. + * - Backwards compatible refactors. + * - Editing comments. + * + * In released versions of Ruby, this number is not defined since teeny + * versions of Ruby should guarantee ABI compatibility. + */ +#define RUBY_ABI_VERSION 1 + +/* Windows does not support weak symbols so ruby_abi_version will not exist + * in the shared library. */ +#if defined(HAVE_FUNC_WEAK) && !defined(_WIN32) && !defined(__MINGW32__) && !defined(__CYGWIN__) +# define RUBY_DLN_CHECK_ABI +#endif +#endif /* RUBY_ABI_VERSION */ + +#if defined(RUBY_DLN_CHECK_ABI) && !defined(RUBY_EXPORT) + +# ifdef __cplusplus +extern "C" { +# endif + +RUBY_FUNC_EXPORTED unsigned long long __attribute__((weak)) +ruby_abi_version(void) +{ +# ifdef RUBY_ABI_VERSION + return RUBY_ABI_VERSION; +# else + return 0; +# endif +} + +# ifdef __cplusplus +} +# endif + +#endif + +#endif diff --git a/include/ruby/internal/anyargs.h b/include/ruby/internal/anyargs.h index 9d8d16fdab..e4c6d155cc 100644 --- a/include/ruby/internal/anyargs.h +++ b/include/ruby/internal/anyargs.h @@ -84,12 +84,15 @@ #elif defined(_WIN32) || defined(__CYGWIN__) # /* Skip due to [Bug #16134] */ +# define RBIMPL_CAST_FN_PTR 1 #elif ! RBIMPL_HAS_ATTRIBUTE(transparent_union) # /* :TODO: improve here, please find a way to support. */ +# define RBIMPL_CAST_FN_PTR 1 #elif ! defined(HAVE_VA_ARGS_MACRO) # /* :TODO: improve here, please find a way to support. */ +# define RBIMPL_CAST_FN_PTR 1 #else # /** @cond INTERNAL_MACRO */ @@ -239,15 +242,16 @@ # define RBIMPL_ANYARGS_DISPATCH_rb_define_method_13(n) RBIMPL_ANYARGS_DISPATCH((n) == 13, rb_define_method_13, RBIMPL_ANYARGS_DISPATCH_rb_define_method_12(n)) # define RBIMPL_ANYARGS_DISPATCH_rb_define_method_14(n) RBIMPL_ANYARGS_DISPATCH((n) == 14, rb_define_method_14, RBIMPL_ANYARGS_DISPATCH_rb_define_method_13(n)) # define RBIMPL_ANYARGS_DISPATCH_rb_define_method_15(n) RBIMPL_ANYARGS_DISPATCH((n) == 15, rb_define_method_15, RBIMPL_ANYARGS_DISPATCH_rb_define_method_14(n)) -# define RBIMPL_ANYARGS_DISPATCH_rb_define_singleton_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_singleton_method_m3, RBIMPL_ANYARGS_DISPATCH_rb_define_singleton_method_15(n)) -# define RBIMPL_ANYARGS_DISPATCH_rb_define_protected_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_protected_method_m3, RBIMPL_ANYARGS_DISPATCH_rb_define_protected_method_15(n)) -# define RBIMPL_ANYARGS_DISPATCH_rb_define_private_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_private_method_m3, RBIMPL_ANYARGS_DISPATCH_rb_define_private_method_15(n)) -# define RBIMPL_ANYARGS_DISPATCH_rb_define_module_function(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_module_function_m3, RBIMPL_ANYARGS_DISPATCH_rb_define_module_function_15(n)) -# define RBIMPL_ANYARGS_DISPATCH_rb_define_global_function(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_global_function_m3, RBIMPL_ANYARGS_DISPATCH_rb_define_global_function_15(n)) -# define RBIMPL_ANYARGS_DISPATCH_rb_define_method_id(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_method_id_m3, RBIMPL_ANYARGS_DISPATCH_rb_define_method_id_15(n)) -# define RBIMPL_ANYARGS_DISPATCH_rb_define_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_method_m3, RBIMPL_ANYARGS_DISPATCH_rb_define_method_15(n)) +# define RBIMPL_ANYARGS_DISPATCH_rb_define_singleton_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_singleton_method_notimpl, RBIMPL_ANYARGS_DISPATCH_rb_define_singleton_method_15(n)) +# define RBIMPL_ANYARGS_DISPATCH_rb_define_protected_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_protected_method_notimpl, RBIMPL_ANYARGS_DISPATCH_rb_define_protected_method_15(n)) +# define RBIMPL_ANYARGS_DISPATCH_rb_define_private_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_private_method_notimpl, RBIMPL_ANYARGS_DISPATCH_rb_define_private_method_15(n)) +# define RBIMPL_ANYARGS_DISPATCH_rb_define_module_function(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_module_function_notimpl, RBIMPL_ANYARGS_DISPATCH_rb_define_module_function_15(n)) +# define RBIMPL_ANYARGS_DISPATCH_rb_define_global_function(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_global_function_notimpl, RBIMPL_ANYARGS_DISPATCH_rb_define_global_function_15(n)) +# define RBIMPL_ANYARGS_DISPATCH_rb_define_method_id(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_method_id_notimpl, RBIMPL_ANYARGS_DISPATCH_rb_define_method_id_15(n)) +# define RBIMPL_ANYARGS_DISPATCH_rb_define_method(n, f) RBIMPL_ANYARGS_DISPATCH(RBIMPL_CFUNC_IS_rb_f_notimplement(f), rb_define_method_notimpl, RBIMPL_ANYARGS_DISPATCH_rb_define_method_15(n)) # define RBIMPL_ANYARGS_ATTRSET(sym) RBIMPL_ATTR_MAYBE_UNUSED() RBIMPL_ATTR_NONNULL(()) RBIMPL_ATTR_WEAKREF(sym) # define RBIMPL_ANYARGS_DECL(sym, ...) \ +RBIMPL_ANYARGS_ATTRSET(sym) static void sym ## _notimpl(__VA_ARGS__, VALUE(*)(int, const VALUE *, VALUE, VALUE), int); \ RBIMPL_ANYARGS_ATTRSET(sym) static void sym ## _m3(__VA_ARGS__, VALUE(*)(ANYARGS), int); \ RBIMPL_ANYARGS_ATTRSET(sym) static void sym ## _m2(__VA_ARGS__, VALUE(*)(VALUE, VALUE), int); \ RBIMPL_ANYARGS_ATTRSET(sym) static void sym ## _m1(__VA_ARGS__, VALUE(*)(int, union { VALUE *x; const VALUE *y; } __attribute__((__transparent_union__)), VALUE), int); \ @@ -347,6 +351,25 @@ RBIMPL_ANYARGS_DECL(rb_define_method, VALUE, const char *) #endif /* __cplusplus */ +#if defined(RBIMPL_CAST_FN_PTR) && !defined(__cplusplus) +/* In C23, K&R style prototypes are gone and so `void foo(ANYARGS)` became + * equivalent to `void foo(void)` unlike in earlier versions. This is a problem + * for rb_define_* functions since that makes all valid functions one can pass + * trip -Wincompatible-pointer-types, which we treat as errors. This is mostly + * not a problem for the __builtin_choose_expr path, but outside of that we + * need to add a cast for compatibility. + */ +#define rb_define_method(klass, mid, func, arity) rb_define_method((klass), (mid), (VALUE (*)(ANYARGS))(func), (arity)) +#define rb_define_method_id(klass, mid, func, arity) rb_define_method_id((klass), (mid), (VALUE (*)(ANYARGS))(func), (arity)) +#define rb_define_singleton_method(obj, mid, func, arity) rb_define_singleton_method((obj), (mid), (VALUE (*)(ANYARGS))(func), (arity)) +#define rb_define_protected_method(klass, mid, func, arity) rb_define_protected_method((klass), (mid), (VALUE (*)(ANYARGS))(func), (arity)) +#define rb_define_private_method(klass, mid, func, arity) rb_define_private_method((klass), (mid), (VALUE (*)(ANYARGS))(func), (arity)) +#define rb_define_module_function(mod, mid, func, arity) rb_define_module_function((mod), (mid), (VALUE (*)(ANYARGS))(func), (arity)) +#define rb_define_global_function(mid, func, arity) rb_define_global_function((mid), (VALUE (*)(ANYARGS))(func), (arity)) + +#undef RBIMPL_CAST_FN_PTR +#endif /* defined(RBIMPL_CAST_FN_PTR) && !defined(__cplusplus) */ + /** * This macro is to properly cast a function parameter of *_define_method * family. It has been around since 1.x era so you can maximise backwards diff --git a/include/ruby/internal/arithmetic.h b/include/ruby/internal/arithmetic.h index 3f7840c384..7ebb4a86f1 100644 --- a/include/ruby/internal/arithmetic.h +++ b/include/ruby/internal/arithmetic.h @@ -18,7 +18,8 @@ * 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 Conversion between C's arithmtic types and Ruby's numeric types. + * @brief Conversion between C's arithmetic types and Ruby's numeric + * types. */ #include "ruby/internal/arithmetic/char.h" #include "ruby/internal/arithmetic/double.h" diff --git a/include/ruby/internal/arithmetic/char.h b/include/ruby/internal/arithmetic/char.h index 91f06bbf73..920fdc0c9d 100644 --- a/include/ruby/internal/arithmetic/char.h +++ b/include/ruby/internal/arithmetic/char.h @@ -29,9 +29,9 @@ #include "ruby/internal/core/rstring.h" #include "ruby/internal/value_type.h" -#define RB_NUM2CHR rb_num2char_inline -#define NUM2CHR RB_NUM2CHR -#define CHR2FIX RB_CHR2FIX +#define RB_NUM2CHR rb_num2char_inline /**< @alias{rb_num2char_inline} */ +#define NUM2CHR RB_NUM2CHR /**< @old{RB_NUM2CHR} */ +#define CHR2FIX RB_CHR2FIX /**< @old{RB_CHR2FIX} */ /** @cond INTERNAL_MACRO */ #define RB_CHR2FIX RB_CHR2FIX @@ -40,12 +40,35 @@ RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a C's `unsigned char` into an instance of ::rb_cInteger. + * + * @param[in] c Arbitrary `unsigned char` value. + * @return An instance of ::rb_cInteger. + * + * @internal + * + * Nobody explicitly states this but in Ruby, a char means an unsigned integer + * value of range 0..255. This is a general principle. AFAIK there is no + * single line of code where char is signed. + */ static inline VALUE RB_CHR2FIX(unsigned char c) { return RB_INT2FIX(c); } +/** + * Converts an instance of ::rb_cNumeric into C's `char`. At the same time it + * accepts a String of more than one character, and returns its first byte. In + * the early days there was a Ruby level "character" literal `?c`, which + * roughly worked this way. + * + * @param[in] x Either a string or a numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `unsigned int`. + * @return The passed value converted into C's `char`. + */ static inline char rb_num2char_inline(VALUE x) { diff --git a/include/ruby/internal/arithmetic/double.h b/include/ruby/internal/arithmetic/double.h index 79c98915ba..229de47aef 100644 --- a/include/ruby/internal/arithmetic/double.h +++ b/include/ruby/internal/arithmetic/double.h @@ -24,16 +24,49 @@ #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" -#define NUM2DBL rb_num2dbl -#define RFLOAT_VALUE rb_float_value -#define DBL2NUM rb_float_new +#define NUM2DBL rb_num2dbl /**< @old{rb_num2dbl} */ +#define RFLOAT_VALUE rb_float_value /**< @old{rb_float_value} */ +#define DBL2NUM rb_float_new /**< @old{rb_float_new} */ RBIMPL_SYMBOL_EXPORT_BEGIN() -double rb_num2dbl(VALUE); +/** + * Converts an instance of ::rb_cNumeric into C's `double`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @return The passed value converted into C's `double`. + */ +double rb_num2dbl(VALUE num); + RBIMPL_ATTR_PURE() -double rb_float_value(VALUE); -VALUE rb_float_new(double); -VALUE rb_float_new_in_heap(double); +/** + * Extracts its double value from an instance of ::rb_cFloat. + * + * @param[in] num An instance of ::rb_cFloat. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `double`. + */ +double rb_float_value(VALUE num); + +/** + * Converts a C's `double` into an instance of ::rb_cFloat. + * + * @param[in] d Arbitrary `double` value. + * @return An instance of ::rb_cFloat. + */ +VALUE rb_float_new(double d); + +/** + * Identical to rb_float_new(), except it does not generate Flonums. + * + * @param[in] d Arbitrary `double` value. + * @return An instance of ::rb_cFloat. + * + * @internal + * + * @shyouhei has no idea why it is here. + */ +VALUE rb_float_new_in_heap(double d); RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_ARITHMETIC_DOUBLE_H */ diff --git a/include/ruby/internal/arithmetic/fixnum.h b/include/ruby/internal/arithmetic/fixnum.h index 8a3354a377..c8927ac824 100644 --- a/include/ruby/internal/arithmetic/fixnum.h +++ b/include/ruby/internal/arithmetic/fixnum.h @@ -22,23 +22,39 @@ */ #include "ruby/backward/2/limits.h" -#define FIXABLE RB_FIXABLE -#define FIXNUM_MAX RUBY_FIXNUM_MAX -#define FIXNUM_MIN RUBY_FIXNUM_MIN -#define NEGFIXABLE RB_NEGFIXABLE -#define POSFIXABLE RB_POSFIXABLE +#define FIXABLE RB_FIXABLE /**< @old{RB_FIXABLE} */ +#define FIXNUM_MAX RUBY_FIXNUM_MAX /**< @old{RUBY_FIXNUM_MAX} */ +#define FIXNUM_MIN RUBY_FIXNUM_MIN /**< @old{RUBY_FIXNUM_MIN} */ +#define NEGFIXABLE RB_NEGFIXABLE /**< @old{RB_NEGFIXABLE} */ +#define POSFIXABLE RB_POSFIXABLE /**< @old{RB_POSFIXABLE} */ -/* +/** + * Checks if the passed value is in range of fixnum, assuming it is a positive + * number. Can sometimes be useful for C's unsigned integer types. + * + * @internal + * * FIXABLE can be applied to anything, from double to intmax_t. The problem is * double. On a 64bit system RUBY_FIXNUM_MAX is 4,611,686,018,427,387,903, * which is not representable by a double. The nearest value that a double can * represent is 4,611,686,018,427,387,904, which is not fixable. The - * seemingly-stragne "< FIXNUM_MAX + 1" expression below is due to this. + * seemingly-strange "< FIXNUM_MAX + 1" expression below is due to this. */ #define RB_POSFIXABLE(_) ((_) < RUBY_FIXNUM_MAX + 1) + +/** + * Checks if the passed value is in range of fixnum, assuming it is a negative + * number. This is an implementation of #RB_FIXABLE. Rarely used stand alone. + */ #define RB_NEGFIXABLE(_) ((_) >= RUBY_FIXNUM_MIN) + +/** Checks if the passed value is in range of fixnum */ #define RB_FIXABLE(_) (RB_POSFIXABLE(_) && RB_NEGFIXABLE(_)) + +/** Maximum possible value that a fixnum can represent. */ #define RUBY_FIXNUM_MAX (LONG_MAX / 2) + +/** Minimum possible value that a fixnum can represent. */ #define RUBY_FIXNUM_MIN (LONG_MIN / 2) #endif /* RBIMPL_ARITHMETIC_FIXNUM_H */ diff --git a/include/ruby/internal/arithmetic/gid_t.h b/include/ruby/internal/arithmetic/gid_t.h index 9b74225492..361220bfab 100644 --- a/include/ruby/internal/arithmetic/gid_t.h +++ b/include/ruby/internal/arithmetic/gid_t.h @@ -23,14 +23,17 @@ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/long.h" +/** Converts a C's `gid_t` into an instance of ::rb_cInteger. */ #ifndef GIDT2NUM # define GIDT2NUM RB_LONG2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `gid_t`. */ #ifndef NUM2GIDT # define NUM2GIDT RB_NUM2LONG #endif +/** A rb_sprintf() format prefix to be used for a `gid_t` parameter. */ #ifndef PRI_GIDT_PREFIX # define PRI_GIDT_PREFIX PRI_LONG_PREFIX #endif diff --git a/include/ruby/internal/arithmetic/int.h b/include/ruby/internal/arithmetic/int.h index 7ae89ae54c..7b24d16887 100644 --- a/include/ruby/internal/arithmetic/int.h +++ b/include/ruby/internal/arithmetic/int.h @@ -34,16 +34,16 @@ #include "ruby/internal/warning_push.h" #include "ruby/assert.h" -#define RB_INT2NUM rb_int2num_inline -#define RB_NUM2INT rb_num2int_inline -#define RB_UINT2NUM rb_uint2num_inline +#define RB_INT2NUM rb_int2num_inline /**< @alias{rb_int2num_inline} */ +#define RB_NUM2INT rb_num2int_inline /**< @alias{rb_num2int_inline} */ +#define RB_UINT2NUM rb_uint2num_inline /**< @alias{rb_uint2num_inline} */ -#define FIX2INT RB_FIX2INT -#define FIX2UINT RB_FIX2UINT -#define INT2NUM RB_INT2NUM -#define NUM2INT RB_NUM2INT -#define NUM2UINT RB_NUM2UINT -#define UINT2NUM RB_UINT2NUM +#define FIX2INT RB_FIX2INT /**< @old{RB_FIX2INT} */ +#define FIX2UINT RB_FIX2UINT /**< @old{RB_FIX2UINT} */ +#define INT2NUM RB_INT2NUM /**< @old{RB_INT2NUM} */ +#define NUM2INT RB_NUM2INT /**< @old{RB_NUM2INT} */ +#define NUM2UINT RB_NUM2UINT /**< @old{RB_NUM2UINT} */ +#define UINT2NUM RB_UINT2NUM /**< @old{RB_UINT2NUM} */ /** @cond INTERNAL_MACRO */ #define RB_FIX2INT RB_FIX2INT @@ -52,13 +52,79 @@ /** @endcond */ RBIMPL_SYMBOL_EXPORT_BEGIN() -long rb_num2int(VALUE); -long rb_fix2int(VALUE); -unsigned long rb_num2uint(VALUE); -unsigned long rb_fix2uint(VALUE); + +/** + * Converts an instance of ::rb_cNumeric into C's `long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `int`. + * @return The passed value converted into C's `long`. + * + * @internal + * + * Yes, the API is really strange. It returns `long`, but raises when the + * value is out of `int`. This seems to be due to the fact that Matz favoured + * K&R before, and his machine at that moment was an ILP32 architecture. + */ +long rb_num2int(VALUE num); + +/** + * Identical to rb_num2int(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `int`. + * @return The passed value converted into C's `long`. + * + * @internal + * + * This function seems to be a complete waste of disk space. @shyouhei has no + * idea why this is a different thing from rb_num2short(). + */ +long rb_fix2int(VALUE num); + +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned int`. + * @return The passed value converted into C's `unsigned long`. + * + * @internal + * + * Yes, the API is really strange. It returns `unsigned long`, but raises when + * the value is out of `unsigned int`. This seems to be due to the fact that + * Matz favoured K&R before, and his machine at that moment was an ILP32 + * architecture. + */ +unsigned long rb_num2uint(VALUE num); + +/** + * Identical to rb_num2uint(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned int`. + * @return The passed value converted into C's `unsigned long`. + * + * @internal + * + * This function seems to be a complete waste of disk space. @shyouhei has no + * idea why this is a different thing from rb_num2short(). + */ +unsigned long rb_fix2uint(VALUE num); RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a Fixnum into C's `int`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `int`. + */ static inline int RB_FIX2INT(VALUE x) { @@ -80,6 +146,14 @@ RB_FIX2INT(VALUE x) return RBIMPL_CAST((int)ret); } +/** + * Converts an instance of ::rb_cNumeric into C's `int`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `int`. + * @return The passed value converted into C's `int`. + */ static inline int rb_num2int_inline(VALUE x) { @@ -98,6 +172,14 @@ rb_num2int_inline(VALUE x) return RBIMPL_CAST((int)ret); } +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned int`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `unsigned int`. + * @return The passed value converted into C's `unsigned int`. + */ RBIMPL_ATTR_ARTIFICIAL() static inline unsigned int RB_NUM2UINT(VALUE x) @@ -115,6 +197,13 @@ RB_NUM2UINT(VALUE x) } RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a Fixnum into C's `int`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `int`. + */ static inline unsigned int RB_FIX2UINT(VALUE x) { @@ -140,6 +229,12 @@ RBIMPL_WARNING_IGNORED(-Wtype-limits) /* We can ignore them here. */ RBIMPL_WARNING_IGNORED(-Wtautological-constant-out-of-range-compare) #endif +/** + * Converts a C's `int` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `int` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_int2num_inline(int v) { @@ -149,11 +244,17 @@ rb_int2num_inline(int v) return rb_int2big(v); } +/** + * Converts a C's `unsigned int` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `unsigned int` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_uint2num_inline(unsigned int v) { if (RB_POSFIXABLE(v)) - return RB_LONG2FIX(v); + return RB_LONG2FIX(RBIMPL_CAST((long)v)); else return rb_uint2big(v); } diff --git a/include/ruby/internal/arithmetic/intptr_t.h b/include/ruby/internal/arithmetic/intptr_t.h index 622b05a6b7..70090f88e6 100644 --- a/include/ruby/internal/arithmetic/intptr_t.h +++ b/include/ruby/internal/arithmetic/intptr_t.h @@ -29,13 +29,57 @@ #include "ruby/internal/value.h" #include "ruby/internal/dllexport.h" -#define rb_int_new rb_int2inum -#define rb_uint_new rb_uint2inum +#define rb_int_new rb_int2inum /**< @alias{rb_int2inum} */ +#define rb_uint_new rb_uint2inum /**< @alias{rb_uint2inum} */ + +// These definitions are same as fiddle/conversions.h +#if SIZEOF_VOIDP <= SIZEOF_LONG +# define PTR2NUM(x) (LONG2NUM((long)(x))) +# define NUM2PTR(x) ((void*)(NUM2ULONG(x))) +#elif SIZEOF_VOIDP <= SIZEOF_LONG_LONG +# define PTR2NUM(x) (LL2NUM((LONG_LONG)(x))) +# define NUM2PTR(x) ((void*)(NUM2ULL(x))) +#else +// should have been an error in ruby/internal/value.h +# error Need integer for VALUE +#endif RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * Converts a C's `intptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `intptr_t` value. + * @return An instance of ::rb_cInteger. + * @note This function always allocates Bignums, even if the given number + * is small enough to fit into a Fixnum. + */ VALUE rb_int2big(intptr_t i); + +/** + * Converts a C's `intptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `intptr_t` value. + * @return An instance of ::rb_cInteger. + */ VALUE rb_int2inum(intptr_t i); + +/** + * Converts a C's `intptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `intptr_t` value. + * @return An instance of ::rb_cInteger. + * @note This function always allocates Bignums, even if the given number + * is small enough to fit into a Fixnum. + */ VALUE rb_uint2big(uintptr_t i); + +/** + * Converts a C's `uintptr_t` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `uintptr_t` value. + * @return An instance of ::rb_cInteger. + */ VALUE rb_uint2inum(uintptr_t i); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/arithmetic/long.h b/include/ruby/internal/arithmetic/long.h index 59bc5d9be3..6c00dbceb7 100644 --- a/include/ruby/internal/arithmetic/long.h +++ b/include/ruby/internal/arithmetic/long.h @@ -43,23 +43,23 @@ #include "ruby/internal/value.h" #include "ruby/assert.h" -#define FIX2LONG RB_FIX2LONG -#define FIX2ULONG RB_FIX2ULONG -#define INT2FIX RB_INT2FIX -#define LONG2FIX RB_INT2FIX -#define LONG2NUM RB_LONG2NUM -#define NUM2LONG RB_NUM2LONG -#define NUM2ULONG RB_NUM2ULONG -#define RB_FIX2LONG rb_fix2long -#define RB_FIX2ULONG rb_fix2ulong -#define RB_LONG2FIX RB_INT2FIX -#define RB_LONG2NUM rb_long2num_inline -#define RB_NUM2LONG rb_num2long_inline -#define RB_NUM2ULONG rb_num2ulong_inline -#define RB_ULONG2NUM rb_ulong2num_inline -#define ULONG2NUM RB_ULONG2NUM -#define rb_fix_new RB_INT2FIX -#define rb_long2int rb_long2int_inline +#define FIX2LONG RB_FIX2LONG /**< @old{RB_FIX2LONG} */ +#define FIX2ULONG RB_FIX2ULONG /**< @old{RB_FIX2ULONG} */ +#define INT2FIX RB_INT2FIX /**< @old{RB_INT2FIX} */ +#define LONG2FIX RB_INT2FIX /**< @old{RB_INT2FIX} */ +#define LONG2NUM RB_LONG2NUM /**< @old{RB_LONG2NUM} */ +#define NUM2LONG RB_NUM2LONG /**< @old{RB_NUM2LONG} */ +#define NUM2ULONG RB_NUM2ULONG /**< @old{RB_NUM2ULONG} */ +#define RB_FIX2LONG rb_fix2long /**< @alias{rb_fix2long} */ +#define RB_FIX2ULONG rb_fix2ulong /**< @alias{rb_fix2ulong} */ +#define RB_LONG2FIX RB_INT2FIX /**< @alias{RB_INT2FIX} */ +#define RB_LONG2NUM rb_long2num_inline /**< @alias{rb_long2num_inline} */ +#define RB_NUM2LONG rb_num2long_inline /**< @alias{rb_num2long_inline} */ +#define RB_NUM2ULONG rb_num2ulong_inline /**< @alias{rb_num2ulong_inline} */ +#define RB_ULONG2NUM rb_ulong2num_inline /**< @alias{rb_ulong2num_inline} */ +#define ULONG2NUM RB_ULONG2NUM /**< @old{RB_ULONG2NUM} */ +#define rb_fix_new RB_INT2FIX /**< @alias{RB_INT2FIX} */ +#define rb_long2int rb_long2int_inline /**< @alias{rb_long2int_inline} */ /** @cond INTERNAL_MACRO */ #define RB_INT2FIX RB_INT2FIX @@ -69,15 +69,44 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() RBIMPL_ATTR_NORETURN() RBIMPL_ATTR_COLD() +/** + * This is an utility function to raise an ::rb_eRangeError. + * + * @param[in] num A signed value about to overflow. + * @exception rb_eRangeError `num` is out of range of `int`. + */ void rb_out_of_int(SIGNED_VALUE num); +/** + * Converts an instance of ::rb_cNumeric into C's `long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `long`. + * @return The passed value converted into C's `long`. + */ long rb_num2long(VALUE num); + +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned long`. + * @return The passed value converted into C's `unsigned long`. + */ unsigned long rb_num2ulong(VALUE num); RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) RBIMPL_ATTR_ARTIFICIAL() +/** + * Converts a C's `long` into an instance of ::rb_cInteger. + * + * @param[in] i Arbitrary `long` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE RB_INT2FIX(long i) { @@ -85,16 +114,23 @@ RB_INT2FIX(long i) /* :NOTE: VALUE can be wider than long. As j being unsigned, 2j+1 is fully * defined. Also it can be compiled into a single LEA instruction. */ - const unsigned long j = i; - const unsigned long k = 2 * j + RUBY_FIXNUM_FLAG; - const long l = k; + const unsigned long j = RBIMPL_CAST((unsigned long)i); + const unsigned long k = (j << 1) + RUBY_FIXNUM_FLAG; + const long l = RBIMPL_CAST((long)k); const SIGNED_VALUE m = l; /* Sign extend */ - const VALUE n = m; + const VALUE n = RBIMPL_CAST((VALUE)m); RBIMPL_ASSERT_OR_ASSUME(RB_FIXNUM_P(n)); return n; } +/** + * Checks if `int` can hold the given integer. + * + * @param[in] n Arbitrary `long` value. + * @exception rb_eRangeError `n` is out of range of `int`. + * @return Identical value of type `int` + */ static inline int rb_long2int_inline(long n) { @@ -112,6 +148,16 @@ rb_long2int_inline(long n) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * @private + * + * This is an implementation detail of rb_fix2long(). People don't use it + * directly. + * + * @param[in] x A Fixnum. + * @return Identical value of type `long` + * @pre Must not pass anything other than a Fixnum. + */ static inline long rbimpl_fix2long_by_idiv(VALUE x) { @@ -120,7 +166,7 @@ rbimpl_fix2long_by_idiv(VALUE x) /* :NOTE: VALUE can be wider than long. (x-1)/2 never overflows because * RB_FIXNUM_P(x) holds. Also it has no portability issue like y>>1 * below. */ - const SIGNED_VALUE y = x - RUBY_FIXNUM_FLAG; + const SIGNED_VALUE y = RBIMPL_CAST((SIGNED_VALUE)(x - RUBY_FIXNUM_FLAG)); const SIGNED_VALUE z = y / 2; const long w = RBIMPL_CAST((long)z); @@ -130,6 +176,16 @@ rbimpl_fix2long_by_idiv(VALUE x) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * @private + * + * This is an implementation detail of rb_fix2long(). People don't use it + * directly. + * + * @param[in] x A Fixnum. + * @return Identical value of type `long` + * @pre Must not pass anything other than a Fixnum. + */ static inline long rbimpl_fix2long_by_shift(VALUE x) { @@ -137,7 +193,7 @@ rbimpl_fix2long_by_shift(VALUE x) /* :NOTE: VALUE can be wider than long. If right shift is arithmetic, this * is noticeably faster than above. */ - const SIGNED_VALUE y = x; + const SIGNED_VALUE y = RBIMPL_CAST((SIGNED_VALUE)x); const SIGNED_VALUE z = y >> 1; const long w = RBIMPL_CAST((long)z); @@ -147,6 +203,15 @@ rbimpl_fix2long_by_shift(VALUE x) RBIMPL_ATTR_CONST() RBIMPL_ATTR_CONSTEXPR(CXX11) +/** + * @private + * + * This is an implementation detail of rb_fix2long(). People don't use it + * directly. + * + * @retval true This C compiler's right shift operator is arithmetic. + * @retval false This C compiler's right shift operator is logical. + */ static inline bool rbimpl_right_shift_is_arithmetic_p(void) { @@ -155,6 +220,13 @@ rbimpl_right_shift_is_arithmetic_p(void) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * Converts a Fixnum into C's `long`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `long`. + */ static inline long rb_fix2long(VALUE x) { @@ -168,13 +240,29 @@ rb_fix2long(VALUE x) RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) +/** + * Converts a Fixnum into C's `unsigned long`. + * + * @param[in] x Some Fixnum. + * @pre Must not pass anything other than a Fixnum. + * @return The passed value converted into C's `unsigned long`. + * @note Negative fixnums will be converted into large unsigned longs. + */ static inline unsigned long rb_fix2ulong(VALUE x) { RBIMPL_ASSERT_OR_ASSUME(RB_FIXNUM_P(x)); - return rb_fix2long(x); + return RBIMPL_CAST((unsigned long)rb_fix2long(x)); } +/** + * Converts an instance of ::rb_cNumeric into C's `long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `long`. + * @return The passed value converted into C's `long`. + */ static inline long rb_num2long_inline(VALUE x) { @@ -184,20 +272,38 @@ rb_num2long_inline(VALUE x) return rb_num2long(x); } +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `unsigned long`. + * @return The passed value converted into C's `unsigned long`. + * + * @internal + * + * This (negative fixnum would become a large unsigned long while negative + * bignum is an exception) has been THE behaviour of NUM2ULONG since the + * beginning. It is strange, but we can no longer change how it works at this + * moment. We have to get by with it. + * + * @see https://bugs.ruby-lang.org/issues/9089 + */ static inline unsigned long rb_num2ulong_inline(VALUE x) { - /* This (negative fixnum would become a large unsigned long while negative - * bignum is an exception) has been THE behaviour of NUM2ULONG since the - * beginning. It is strange, but we can no longer change how it works at - * this moment. We have to get by with it. See also: - * https://bugs.ruby-lang.org/issues/9089 */ if (RB_FIXNUM_P(x)) return RB_FIX2ULONG(x); else return rb_num2ulong(x); } +/** + * Converts a C's `long` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `long` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_long2num_inline(long v) { @@ -207,11 +313,17 @@ rb_long2num_inline(long v) return rb_int2big(v); } +/** + * Converts a C's `unsigned long` into an instance of ::rb_cInteger. + * + * @param[in] v Arbitrary `unsigned long` value. + * @return An instance of ::rb_cInteger. + */ static inline VALUE rb_ulong2num_inline(unsigned long v) { if (RB_POSFIXABLE(v)) - return RB_LONG2FIX(v); + return RB_LONG2FIX(RBIMPL_CAST((long)v)); else return rb_uint2big(v); } diff --git a/include/ruby/internal/arithmetic/long_long.h b/include/ruby/internal/arithmetic/long_long.h index ffe9e89573..aab455c830 100644 --- a/include/ruby/internal/arithmetic/long_long.h +++ b/include/ruby/internal/arithmetic/long_long.h @@ -25,22 +25,59 @@ #include "ruby/internal/special_consts.h" #include "ruby/backward/2/long_long.h" -#define RB_LL2NUM rb_ll2num_inline -#define RB_ULL2NUM rb_ull2num_inline -#define LL2NUM RB_LL2NUM -#define ULL2NUM RB_ULL2NUM -#define RB_NUM2LL rb_num2ll_inline -#define RB_NUM2ULL rb_num2ull_inline -#define NUM2LL RB_NUM2LL -#define NUM2ULL RB_NUM2ULL +#define RB_LL2NUM rb_ll2num_inline /**< @alias{rb_ll2num_inline} */ +#define RB_ULL2NUM rb_ull2num_inline /**< @alias{rb_ull2num_inline} */ +#define LL2NUM RB_LL2NUM /**< @old{RB_LL2NUM} */ +#define ULL2NUM RB_ULL2NUM /**< @old{RB_ULL2NUM} */ +#define RB_NUM2LL rb_num2ll_inline /**< @alias{rb_num2ll_inline} */ +#define RB_NUM2ULL rb_num2ull_inline /**< @alias{rb_num2ull_inline} */ +#define NUM2LL RB_NUM2LL /**< @old{RB_NUM2LL} */ +#define NUM2ULL RB_NUM2ULL /**< @old{RB_NUM2ULL} */ RBIMPL_SYMBOL_EXPORT_BEGIN() -VALUE rb_ll2inum(LONG_LONG); -VALUE rb_ull2inum(unsigned LONG_LONG); -LONG_LONG rb_num2ll(VALUE); -unsigned LONG_LONG rb_num2ull(VALUE); +/** + * Converts a C's `long long` into an instance of ::rb_cInteger. + * + * @param[in] num Arbitrary `long long` value. + * @return An instance of ::rb_cInteger. + */ +VALUE rb_ll2inum(LONG_LONG num); + +/** + * Converts a C's `unsigned long long` into an instance of ::rb_cInteger. + * + * @param[in] num Arbitrary `unsigned long long` value. + * @return An instance of ::rb_cInteger. + */ +VALUE rb_ull2inum(unsigned LONG_LONG num); + +/** + * Converts an instance of ::rb_cNumeric into C's `long long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `long long`. + * @return The passed value converted into C's `long long`. + */ +LONG_LONG rb_num2ll(VALUE num); + +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long long`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned long long`. + * @return The passed value converted into C's `unsigned long long`. + */ +unsigned LONG_LONG rb_num2ull(VALUE num); RBIMPL_SYMBOL_EXPORT_END() +/** + * Converts a C's `long long` into an instance of ::rb_cInteger. + * + * @param[in] n Arbitrary `long long` value. + * @return An instance of ::rb_cInteger + */ static inline VALUE rb_ll2num_inline(LONG_LONG n) { @@ -48,6 +85,12 @@ rb_ll2num_inline(LONG_LONG n) return rb_ll2inum(n); } +/** + * Converts a C's `unsigned long long` into an instance of ::rb_cInteger. + * + * @param[in] n Arbitrary `unsigned long long` value. + * @return An instance of ::rb_cInteger + */ static inline VALUE rb_ull2num_inline(unsigned LONG_LONG n) { @@ -55,6 +98,14 @@ rb_ull2num_inline(unsigned LONG_LONG n) return rb_ull2inum(n); } +/** + * Converts an instance of ::rb_cNumeric into C's `long long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `long long`. + * @return The passed value converted into C's `long long`. + */ static inline LONG_LONG rb_num2ll_inline(VALUE x) { @@ -64,11 +115,19 @@ rb_num2ll_inline(VALUE x) return rb_num2ll(x); } +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned long long`. + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `unsigned long long`. + * @return The passed value converted into C's `unsigned long long`. + */ static inline unsigned LONG_LONG rb_num2ull_inline(VALUE x) { if (RB_FIXNUM_P(x)) - return RB_FIX2LONG(x); + return RBIMPL_CAST((unsigned LONG_LONG)RB_FIX2LONG(x)); else return rb_num2ull(x); } diff --git a/include/ruby/internal/arithmetic/mode_t.h b/include/ruby/internal/arithmetic/mode_t.h index 57844fedf5..5b7ad35fbc 100644 --- a/include/ruby/internal/arithmetic/mode_t.h +++ b/include/ruby/internal/arithmetic/mode_t.h @@ -23,14 +23,17 @@ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/int.h" +/** Converts a C's `mode_t` into an instance of ::rb_cInteger. */ #ifndef NUM2MODET # define NUM2MODET RB_NUM2INT #endif +/** Converts an instance of ::rb_cNumeric into C's `mode_t`. */ #ifndef MODET2NUM # define MODET2NUM RB_INT2NUM #endif +/** A rb_sprintf() format prefix to be used for a `mode_t` parameter. */ #ifndef PRI_MODET_PREFIX # define PRI_MODET_PREFIX PRI_INT_PREFIX #endif diff --git a/include/ruby/internal/arithmetic/off_t.h b/include/ruby/internal/arithmetic/off_t.h index 0226eb4f25..0ec9362cc9 100644 --- a/include/ruby/internal/arithmetic/off_t.h +++ b/include/ruby/internal/arithmetic/off_t.h @@ -26,6 +26,7 @@ #include "ruby/internal/arithmetic/long_long.h" #include "ruby/backward/2/long_long.h" +/** Converts a C's `off_t` into an instance of ::rb_cInteger. */ #ifdef OFFT2NUM # /* take that. */ #elif SIZEOF_OFF_T == SIZEOF_LONG_LONG @@ -36,6 +37,7 @@ # define OFFT2NUM RB_INT2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `off_t`. */ #ifdef NUM2OFFT # /* take that. */ #elif SIZEOF_OFF_T == SIZEOF_LONG_LONG @@ -46,6 +48,7 @@ # define NUM2OFFT RB_NUM2INT #endif +/** A rb_sprintf() format prefix to be used for an `off_t` parameter. */ #ifdef PRI_OFFT_PREFIX # /* take that. */ #elif SIZEOF_OFF_T == SIZEOF_LONG_LONG diff --git a/include/ruby/internal/arithmetic/pid_t.h b/include/ruby/internal/arithmetic/pid_t.h index 205c181fc8..df9704e8f5 100644 --- a/include/ruby/internal/arithmetic/pid_t.h +++ b/include/ruby/internal/arithmetic/pid_t.h @@ -23,14 +23,17 @@ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/long.h" +/** Converts a C's `pid_t` into an instance of ::rb_cInteger. */ #ifndef PIDT2NUM # define PIDT2NUM RB_LONG2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `pid_t`. */ #ifndef NUM2PIDT # define NUM2PIDT RB_NUM2LONG #endif +/** A rb_sprintf() format prefix to be used for a `pid_t` parameter. */ #ifndef PRI_PIDT_PREFIX # define PRI_PIDT_PREFIX PRI_LONG_PREFIX #endif diff --git a/include/ruby/internal/arithmetic/short.h b/include/ruby/internal/arithmetic/short.h index ac722c4836..7a324d945b 100644 --- a/include/ruby/internal/arithmetic/short.h +++ b/include/ruby/internal/arithmetic/short.h @@ -27,21 +27,80 @@ #include "ruby/internal/dllexport.h" #include "ruby/internal/special_consts.h" -#define RB_NUM2SHORT rb_num2short_inline -#define RB_NUM2USHORT rb_num2ushort -#define NUM2SHORT RB_NUM2SHORT -#define NUM2USHORT RB_NUM2USHORT -#define USHORT2NUM RB_INT2FIX -#define RB_FIX2SHORT rb_fix2short -#define FIX2SHORT RB_FIX2SHORT +#define RB_NUM2SHORT rb_num2short_inline /**< @alias{rb_num2short_inline} */ +#define RB_NUM2USHORT rb_num2ushort /**< @alias{rb_num2ushort} */ +#define NUM2SHORT RB_NUM2SHORT /**< @old{RB_NUM2SHORT} */ +#define NUM2USHORT RB_NUM2USHORT /**< @old{RB_NUM2USHORT} */ +#define USHORT2NUM RB_INT2FIX /**< @old{RB_INT2FIX} */ +#define RB_FIX2SHORT rb_fix2short /**< @alias{rb_fix2ushort} */ +#define FIX2SHORT RB_FIX2SHORT /**< @old{RB_FIX2SHORT} */ RBIMPL_SYMBOL_EXPORT_BEGIN() -short rb_num2short(VALUE); -unsigned short rb_num2ushort(VALUE); -short rb_fix2short(VALUE); -unsigned short rb_fix2ushort(VALUE); + +/** + * Converts an instance of ::rb_cNumeric into C's `short`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `short`. + * @return The passed value converted into C's `short`. + */ +short rb_num2short(VALUE num); + +/** + * Converts an instance of ::rb_cNumeric into C's `unsigned short`. + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned short`. + * @return The passed value converted into C's `unsigned short`. + */ +unsigned short rb_num2ushort(VALUE num); + +/** + * Identical to rb_num2short(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `short`. + * @return The passed value converted into C's `short`. + * + * @internal + * + * This function seems to be a complete waste of disk space. @shyouhei has no + * idea why this is a different thing from rb_num2short(). + */ +short rb_fix2short(VALUE num); + +/** + * Identical to rb_num2ushort(). + * + * @param[in] num Something numeric. + * @exception rb_eTypeError `num` is not a numeric. + * @exception rb_eRangeError `num` is out of range of `unsigned short`. + * @return The passed value converted into C's `unsigned short`. + * + * @internal + * + * This function seems to be a complete waste of disk space. @shyouhei has no + * idea why this is a different thing from rb_num2ushort(). + */ +unsigned short rb_fix2ushort(VALUE num); RBIMPL_SYMBOL_EXPORT_END() +/** + * Identical to rb_num2short(). + * + * @param[in] x Something numeric. + * @exception rb_eTypeError `x` is not a numeric. + * @exception rb_eRangeError `x` is out of range of `short`. + * @return The passed value converted into C's `short`. + * + * @internal + * + * This function seems to be a complete waste of time. @shyouhei has no idea + * why this is a different thing from rb_num2short(). + */ static inline short rb_num2short_inline(VALUE x) { @@ -51,4 +110,4 @@ rb_num2short_inline(VALUE x) return rb_num2short(x); } -#endif /* RBIMPL_ARITHMETIC_SOHRT_H */ +#endif /* RBIMPL_ARITHMETIC_SHORT_H */ diff --git a/include/ruby/internal/arithmetic/size_t.h b/include/ruby/internal/arithmetic/size_t.h index 4b46dfbf8c..1082160b8e 100644 --- a/include/ruby/internal/arithmetic/size_t.h +++ b/include/ruby/internal/arithmetic/size_t.h @@ -26,7 +26,12 @@ #include "ruby/internal/arithmetic/long_long.h" #include "ruby/backward/2/long_long.h" -#if SIZEOF_SIZE_T == SIZEOF_LONG_LONG +#if defined(__DOXYGEN__) +# /** Converts a C's `size_t` into an instance of ::rb_cInteger. */ +# define RB_SIZE2NUM RB_ULONG2NUM +# /** Converts a C's `ssize_t` into an instance of ::rb_cInteger. */ +# define RB_SSIZE2NUM RB_LONG2NUM +#elif SIZEOF_SIZE_T == SIZEOF_LONG_LONG # define RB_SIZE2NUM RB_ULL2NUM # define RB_SSIZE2NUM RB_LL2NUM #elif SIZEOF_SIZE_T == SIZEOF_LONG @@ -37,7 +42,12 @@ # define RB_SSIZE2NUM RB_INT2NUM #endif -#if SIZEOF_SIZE_T == SIZEOF_LONG_LONG +#if defined(__DOXYGEN__) +# /** Converts an instance of ::rb_cInteger into C's `size_t`. */ +# define RB_NUM2SIZE RB_NUM2ULONG +# /** Converts an instance of ::rb_cInteger into C's `ssize_t`. */ +# define RB_NUM2SSIZE RB_NUM2LONG +#elif SIZEOF_SIZE_T == SIZEOF_LONG_LONG # define RB_NUM2SIZE RB_NUM2ULL # define RB_NUM2SSIZE RB_NUM2LL #elif SIZEOF_SIZE_T == SIZEOF_LONG @@ -48,9 +58,9 @@ # define RB_NUM2SSIZE RB_NUM2INT #endif -#define NUM2SIZET RB_NUM2SIZE -#define SIZET2NUM RB_SIZE2NUM -#define NUM2SSIZET RB_NUM2SSIZE -#define SSIZET2NUM RB_SSIZE2NUM +#define NUM2SIZET RB_NUM2SIZE /**< @old{RB_NUM2SIZE} */ +#define SIZET2NUM RB_SIZE2NUM /**< @old{RB_SIZE2NUM} */ +#define NUM2SSIZET RB_NUM2SSIZE /**< @old{RB_NUM2SSIZE} */ +#define SSIZET2NUM RB_SSIZE2NUM /**< @old{RB_SSIZE2NUM} */ #endif /* RBIMPL_ARITHMETIC_SIZE_T_H */ diff --git a/include/ruby/internal/arithmetic/st_data_t.h b/include/ruby/internal/arithmetic/st_data_t.h index 867c382744..91776b3fce 100644 --- a/include/ruby/internal/arithmetic/st_data_t.h +++ b/include/ruby/internal/arithmetic/st_data_t.h @@ -30,7 +30,7 @@ #include "ruby/assert.h" #include "ruby/st.h" -#define ST2FIX RB_ST2FIX +#define ST2FIX RB_ST2FIX /**< @old{RB_ST2FIX} */ /** @cond INTERNAL_MACRO */ #define RB_ST2FIX RB_ST2FIX /** @endcond */ @@ -38,11 +38,27 @@ RBIMPL_ATTR_CONST_UNLESS_DEBUG() RBIMPL_ATTR_CONSTEXPR_UNLESS_DEBUG(CXX14) RBIMPL_ATTR_ARTIFICIAL() -/* See also [ruby-core:84395] [Bug #14218] [ruby-core:82687] [Bug #13877] */ +/** + * Converts a C's `st_data_t` into an instance of ::rb_cInteger. + * + * @param[in] i The data in question. + * @return A converted result + * @warning THIS CONVERSION LOSES DATA! Be warned. + * @see https://bugs.ruby-lang.org/issues/13877 + * @see https://bugs.ruby-lang.org/issues/14218 + * + * @internal + * + * This is needed because of hash functions. Hash functions return + * `st_data_t`, which could theoretically be bigger than Fixnums. However + * allocating Bignums for them every time we calculate hash values is just too + * heavy. To avoid penalty we need to ignore some upper bit(s) and stick to + * Fixnums. This function is used for that purpose. + */ static inline VALUE RB_ST2FIX(st_data_t i) { - SIGNED_VALUE x = i; + SIGNED_VALUE x = RBIMPL_CAST((SIGNED_VALUE)i); if (x >= 0) { x &= RUBY_FIXNUM_MAX; @@ -53,7 +69,7 @@ RB_ST2FIX(st_data_t i) RBIMPL_ASSERT_OR_ASSUME(RB_FIXABLE(x)); unsigned long y = RBIMPL_CAST((unsigned long)x); - return RB_LONG2FIX(y); + return RB_LONG2FIX(RBIMPL_CAST((long)y)); } -#endif /* RBIMPL_ARITHMERIC_ST_DATA_T_H */ +#endif /* RBIMPL_ARITHMETIC_ST_DATA_T_H */ diff --git a/include/ruby/internal/arithmetic/uid_t.h b/include/ruby/internal/arithmetic/uid_t.h index e0048a3dc9..12cde2a9c8 100644 --- a/include/ruby/internal/arithmetic/uid_t.h +++ b/include/ruby/internal/arithmetic/uid_t.h @@ -23,14 +23,17 @@ #include "ruby/internal/config.h" #include "ruby/internal/arithmetic/long.h" +/** Converts a C's `uid_t` into an instance of ::rb_cInteger. */ #ifndef UIDT2NUM # define UIDT2NUM RB_LONG2NUM #endif +/** Converts an instance of ::rb_cNumeric into C's `uid_t`. */ #ifndef NUM2UIDT # define NUM2UIDT RB_NUM2LONG #endif +/** A rb_sprintf() format prefix to be used for a `uid_t` parameter. */ #ifndef PRI_UIDT_PREFIX # define PRI_UIDT_PREFIX PRI_LONG_PREFIX #endif diff --git a/include/ruby/internal/assume.h b/include/ruby/internal/assume.h index 65d34d4ac8..4c183e8af9 100644 --- a/include/ruby/internal/assume.h +++ b/include/ruby/internal/assume.h @@ -32,10 +32,7 @@ #include "ruby/internal/warning_push.h" /** @cond INTERNAL_MACRO */ -#if RBIMPL_COMPILER_SINCE(MSVC, 13, 10, 0) -# define RBIMPL_HAVE___ASSUME - -#elif RBIMPL_COMPILER_SINCE(Intel, 13, 0, 0) +#if defined(HAVE___ASSUME) # define RBIMPL_HAVE___ASSUME #endif /** @endcond */ diff --git a/include/ruby/internal/attr/deprecated.h b/include/ruby/internal/attr/deprecated.h index e1bbdbd15a..a374ace868 100644 --- a/include/ruby/internal/attr/deprecated.h +++ b/include/ruby/internal/attr/deprecated.h @@ -48,7 +48,7 @@ #elif RBIMPL_HAS_ATTRIBUTE(deprecated) /* but not with message. */ # define RBIMPL_ATTR_DEPRECATED(msg) __attribute__((__deprecated__)) -#elif RBIMPL_COMPILER_SINCE(MSVC, 14, 0, 0) +#elif RBIMPL_COMPILER_IS(MSVC) # define RBIMPL_ATTR_DEPRECATED(msg) __declspec(deprecated msg) #elif RBIMPL_HAS_DECLSPEC_ATTRIBUTE(deprecated) @@ -72,4 +72,11 @@ # define RBIMPL_ATTR_DEPRECATED_EXT(msg) RBIMPL_ATTR_DEPRECATED(msg) #endif +#define RBIMPL_ATTR_DEPRECATED_SINCE(ver) \ + RBIMPL_ATTR_DEPRECATED(("since " #ver)) +#define RBIMPL_ATTR_DEPRECATED_INTERNAL(ver) \ + RBIMPL_ATTR_DEPRECATED(("since "#ver", also internal")) +#define RBIMPL_ATTR_DEPRECATED_INTERNAL_ONLY() \ + RBIMPL_ATTR_DEPRECATED(("only for internal use")) + #endif /* RBIMPL_ATTR_DEPRECATED_H */ diff --git a/include/ruby/internal/attr/forceinline.h b/include/ruby/internal/attr/forceinline.h index b7daafede7..5b9ae794af 100644 --- a/include/ruby/internal/attr/forceinline.h +++ b/include/ruby/internal/attr/forceinline.h @@ -29,7 +29,7 @@ * `__forceinline` are mutually exclusive. We have to mimic that behaviour for * non-MSVC compilers. */ -#if RBIMPL_COMPILER_SINCE(MSVC, 12, 0, 0) +#if RBIMPL_COMPILER_IS(MSVC) # define RBIMPL_ATTR_FORCEINLINE() __forceinline #elif RBIMPL_HAS_ATTRIBUTE(always_inline) # define RBIMPL_ATTR_FORCEINLINE() __attribute__((__always_inline__)) inline diff --git a/include/ruby/internal/attr/noalias.h b/include/ruby/internal/attr/noalias.h index 8e508b2bd3..0790ef60e5 100644 --- a/include/ruby/internal/attr/noalias.h +++ b/include/ruby/internal/attr/noalias.h @@ -46,10 +46,21 @@ * that has to be passed to the function as a pointer. ::VALUE -taking * functions thus cannot be attributed as such. */ +#include "ruby/internal/compiler_since.h" #include "ruby/internal/has/declspec_attribute.h" /** Wraps (or simulates) `__declspec((noalias))` */ -#if RBIMPL_HAS_DECLSPEC_ATTRIBUTE(noalias) +#if RBIMPL_COMPILER_BEFORE(Clang, 12, 0, 0) +# /* +# * `::llvm::Attribute::ArgMemOnly` was buggy before. Maybe because nobody +# * actually seriously used it. It seems they somehow mitigated the situation +# * in LLVM 12. Still not found the exact changeset which fiexed the +# * attribute, though. +# * +# * :FIXME: others (armclang, xlclang, ...) can also be affected? +# */ +# define RBIMPL_ATTR_NOALIAS() /* void */ +#elif RBIMPL_HAS_DECLSPEC_ATTRIBUTE(noalias) # define RBIMPL_ATTR_NOALIAS() __declspec(noalias) #else # define RBIMPL_ATTR_NOALIAS() /* void */ diff --git a/include/ruby/internal/attr/nodiscard.h b/include/ruby/internal/attr/nodiscard.h index 087192a7a8..c3ae118942 100644 --- a/include/ruby/internal/attr/nodiscard.h +++ b/include/ruby/internal/attr/nodiscard.h @@ -26,7 +26,7 @@ /** * Wraps (or simulates) `[[nodiscard]]`. In C++ (at least since C++20) a - * nodiscard attribute can have a message why the result shall not be ignoed. + * nodiscard attribute can have a message why the result shall not be ignored. * However GCC attribute and SAL annotation cannot take them. */ #if RBIMPL_HAS_CPP_ATTRIBUTE(nodiscard) diff --git a/include/ruby/internal/attr/noexcept.h b/include/ruby/internal/attr/noexcept.h index ea3001df2a..dd4c667407 100644 --- a/include/ruby/internal/attr/noexcept.h +++ b/include/ruby/internal/attr/noexcept.h @@ -54,7 +54,7 @@ * get smarter and smarter. Today they can infer if it actually throws * or not without any annotations by humans (correct me if I'm wrong). * - * - When an inline function attributed `noexcepr` actually _does_ throw an + * - When an inline function attributed `noexcept` actually _does_ throw an * exception: they have to call `std::terminate` then (C++ standard * mandates so). This means exception handling routines are actually * enforced, not omitted. This doesn't impact runtime performance (The @@ -78,7 +78,7 @@ #elif defined(__INTEL_CXX11_MODE__) # define RBIMPL_ATTR_NOEXCEPT(_) noexcept(noexcept(_)) -#elif RBIMPL_COMPILER_SINCE(MSVC, 19, 0, 0) +#elif RBIMPL_COMPILER_IS(MSVC) # define RBIMPL_ATTR_NOEXCEPT(_) noexcept(noexcept(_)) #elif __cplusplus >= 201103L diff --git a/include/ruby/internal/attr/nonnull.h b/include/ruby/internal/attr/nonnull.h index 874f4236c0..778d5be208 100644 --- a/include/ruby/internal/attr/nonnull.h +++ b/include/ruby/internal/attr/nonnull.h @@ -25,8 +25,10 @@ /** Wraps (or simulates) `__attribute__((nonnull))` */ #if RBIMPL_HAS_ATTRIBUTE(nonnull) # define RBIMPL_ATTR_NONNULL(list) __attribute__((__nonnull__ list)) +# define RBIMPL_NONNULL_ARG(arg) RBIMPL_ASSERT_NOTHING #else # define RBIMPL_ATTR_NONNULL(list) /* void */ +# define RBIMPL_NONNULL_ARG(arg) RUBY_ASSERT(arg) #endif #endif /* RBIMPL_ATTR_NONNULL_H */ diff --git a/include/ruby/internal/attr/nonstring.h b/include/ruby/internal/attr/nonstring.h new file mode 100644 index 0000000000..5ad6ef2a86 --- /dev/null +++ b/include/ruby/internal/attr/nonstring.h @@ -0,0 +1,40 @@ +#ifndef RBIMPL_ATTR_NONSTRING_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RBIMPL_ATTR_NONSTRING_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 Defines #RBIMPL_ATTR_NONSTRING. + */ +#include "ruby/internal/has/attribute.h" + +/** Wraps (or simulates) `__attribute__((nonstring))` */ +#if RBIMPL_HAS_ATTRIBUTE(nonstring) +# define RBIMPL_ATTR_NONSTRING() __attribute__((nonstring)) +# if RBIMPL_COMPILER_SINCE(GCC, 15, 0, 0) +# define RBIMPL_ATTR_NONSTRING_ARRAY() RBIMPL_ATTR_NONSTRING() +# elif RBIMPL_COMPILER_SINCE(Clang, 21, 0, 0) +# define RBIMPL_ATTR_NONSTRING_ARRAY() RBIMPL_ATTR_NONSTRING() +# else +# define RBIMPL_ATTR_NONSTRING_ARRAY() /* void */ +# endif +#else +# define RBIMPL_ATTR_NONSTRING() /* void */ +# define RBIMPL_ATTR_NONSTRING_ARRAY() /* void */ +#endif + +#endif /* RBIMPL_ATTR_NONSTRING_H */ diff --git a/include/ruby/internal/attr/packed_struct.h b/include/ruby/internal/attr/packed_struct.h new file mode 100644 index 0000000000..0678b9acc8 --- /dev/null +++ b/include/ruby/internal/attr/packed_struct.h @@ -0,0 +1,43 @@ +#ifndef RBIMPL_ATTR_PACKED_STRUCT_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RBIMPL_ATTR_PACKED_STRUCT_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 Defines #RBIMPL_ATTR_PACKED_STRUCT_BEGIN, + * #RBIMPL_ATTR_PACKED_STRUCT_END, + * #RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN, and + * #RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END. + */ +#include "ruby/internal/config.h" + +#ifndef RBIMPL_ATTR_PACKED_STRUCT_BEGIN +# define RBIMPL_ATTR_PACKED_STRUCT_BEGIN() /* void */ +#endif +#ifndef RBIMPL_ATTR_PACKED_STRUCT_END +# define RBIMPL_ATTR_PACKED_STRUCT_END() /* void */ +#endif + +#if UNALIGNED_WORD_ACCESS +# define RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN() RBIMPL_ATTR_PACKED_STRUCT_BEGIN() +# define RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END() RBIMPL_ATTR_PACKED_STRUCT_END() +#else +# define RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN() /* void */ +# define RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END() /* void */ +#endif + +#endif diff --git a/include/ruby/internal/attr/restrict.h b/include/ruby/internal/attr/restrict.h index e39104138c..b12fdc9dbc 100644 --- a/include/ruby/internal/attr/restrict.h +++ b/include/ruby/internal/attr/restrict.h @@ -28,7 +28,7 @@ * `__has_declspec_attribute()` which involves macro substitution. */ /** Wraps (or simulates) `__declspec(restrict)` */ -#if RBIMPL_COMPILER_SINCE(MSVC, 14, 0, 0) +#if RBIMPL_COMPILER_IS(MSVC) # define RBIMPL_ATTR_RESTRICT() __declspec(re ## strict) #elif RBIMPL_HAS_ATTRIBUTE(malloc) diff --git a/include/ruby/internal/compiler_is/msvc.h b/include/ruby/internal/compiler_is/msvc.h index 8a864ea558..824f0ecc21 100644 --- a/include/ruby/internal/compiler_is/msvc.h +++ b/include/ruby/internal/compiler_is/msvc.h @@ -38,19 +38,8 @@ # define RBIMPL_COMPILER_VERSION_MINOR (_MSC_FULL_VER % 10000000 / 100000) # define RBIMPL_COMPILER_VERSION_PATCH (_MSC_FULL_VER % 100000) -#elif defined(_MSC_FULL_VER) -# define RBIMPL_COMPILER_IS_MSVC 1 -# /* _MSC_FULL_VER = XXYYZZZZ */ -# define RBIMPL_COMPILER_VERSION_MAJOR (_MSC_FULL_VER / 1000000) -# define RBIMPL_COMPILER_VERSION_MINOR (_MSC_FULL_VER % 1000000 / 10000) -# define RBIMPL_COMPILER_VERSION_PATCH (_MSC_FULL_VER % 10000) - #else -# define RBIMPL_COMPILER_IS_MSVC 1 -# /* _MSC_VER = XXYY */ -# define RBIMPL_COMPILER_VERSION_MAJOR (_MSC_VER / 100) -# define RBIMPL_COMPILER_VERSION_MINOR (_MSC_VER % 100) -# define RBIMPL_COMPILER_VERSION_PATCH 0 +# error Unsupported MSVC version #endif #endif /* RBIMPL_COMPILER_IS_MSVC_H */ diff --git a/include/ruby/internal/config.h b/include/ruby/internal/config.h index b6134c6165..34862ded6e 100644 --- a/include/ruby/internal/config.h +++ b/include/ruby/internal/config.h @@ -50,7 +50,7 @@ # define HAVE_VA_ARGS_MACRO # elif defined(__INTEL_CXX11_MODE__) # define HAVE_VA_ARGS_MACRO -# elif RBIMPL_COMPILER_SINCE(MSVC, 16, 0, 0) +# elif RBIMPL_COMPILER_IS(MSVC) # define HAVE_VA_ARGS_MACRO # else # /* NG, not known. */ @@ -113,6 +113,8 @@ # define UNALIGNED_WORD_ACCESS 1 #elif defined(__powerpc64__) # define UNALIGNED_WORD_ACCESS 1 +#elif defined(__POWERPC__) // __POWERPC__ is defined for ppc and ppc64 on Darwin +# define UNALIGNED_WORD_ACCESS 1 #elif defined(__aarch64__) # define UNALIGNED_WORD_ACCESS 1 #elif defined(__mc68020__) diff --git a/include/ruby/internal/core/rarray.h b/include/ruby/internal/core/rarray.h index 9f1d0509ea..73cc0f5dd9 100644 --- a/include/ruby/internal/core/rarray.h +++ b/include/ruby/internal/core/rarray.h @@ -29,25 +29,13 @@ #include "ruby/internal/core/rbasic.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/fl_type.h" -#include "ruby/internal/rgengc.h" +#include "ruby/internal/gc.h" #include "ruby/internal/stdbool.h" #include "ruby/internal/value.h" #include "ruby/internal/value_type.h" #include "ruby/assert.h" /** - * @private - * @warning Do not touch this macro. - * @warning It is an implementation detail. - * @warning The value of this macro must match for ruby itself and all - * extension libraries, otherwise serious memory corruption shall - * occur. - */ -#ifndef USE_TRANSIENT_HEAP -# define USE_TRANSIENT_HEAP 1 -#endif - -/** * Convenient casting macro. * * @param obj An object, which is in fact an ::RArray. @@ -59,15 +47,9 @@ #define RARRAY_EMBED_LEN_MASK RARRAY_EMBED_LEN_MASK #define RARRAY_EMBED_LEN_MAX RARRAY_EMBED_LEN_MAX #define RARRAY_EMBED_LEN_SHIFT RARRAY_EMBED_LEN_SHIFT -#if USE_TRANSIENT_HEAP -# define RARRAY_TRANSIENT_FLAG RARRAY_TRANSIENT_FLAG -#else -# define RARRAY_TRANSIENT_FLAG 0 -#endif /** @endcond */ #define RARRAY_LEN rb_array_len /**< @alias{rb_array_len} */ #define RARRAY_CONST_PTR rb_array_const_ptr /**< @alias{rb_array_const_ptr} */ -#define RARRAY_CONST_PTR_TRANSIENT rb_array_const_ptr_transient /**< @alias{rb_array_const_ptr_transient} */ /** @cond INTERNAL_MACRO */ #if defined(__fcc__) || defined(__fcc_version) || \ @@ -80,7 +62,6 @@ #define RARRAY_EMBED_LEN RARRAY_EMBED_LEN #define RARRAY_LENINT RARRAY_LENINT -#define RARRAY_TRANSIENT_P RARRAY_TRANSIENT_P #define RARRAY_ASET RARRAY_ASET #define RARRAY_PTR RARRAY_PTR /** @endcond */ @@ -99,6 +80,8 @@ * here is at least incomplete. */ enum ruby_rarray_flags { + /* RUBY_FL_USER0 is for ELTS_SHARED */ + /** * This flag has something to do with memory footprint. If the array is * "small" enough, ruby tries to be creative to abuse padding bits of @@ -118,8 +101,6 @@ enum ruby_rarray_flags { */ RARRAY_EMBED_FLAG = RUBY_FL_USER1, - /* RUBY_FL_USER2 is for ELTS_SHARED */ - /** * When an array employs embedded strategy (see ::RARRAY_EMBED_FLAG), these * bits are used to store the number of elements actually filled into @@ -130,24 +111,8 @@ enum ruby_rarray_flags { * 3rd parties must not be aware that there even is more than one way to * store array elements. It was a bad idea to expose this to them. */ - RARRAY_EMBED_LEN_MASK = RUBY_FL_USER4 | RUBY_FL_USER3 -#if USE_TRANSIENT_HEAP - , - - /** - * This flag has something to do with an array's "transiency". A transient - * array is an array of young generation (of generational GC), who stores - * its elements inside of dedicated memory pages called a transient heap. - * Not every young generation share that storage scheme, but elder - * generations must no join. - * - * @internal - * - * 3rd parties must not be aware that there even is more than one way to - * store array elements. It was a bad idea to expose this to them. - */ - RARRAY_TRANSIENT_FLAG = RUBY_FL_USER13 -#endif + RARRAY_EMBED_LEN_MASK = RUBY_FL_USER9 | RUBY_FL_USER8 | RUBY_FL_USER7 | RUBY_FL_USER6 | + RUBY_FL_USER5 | RUBY_FL_USER4 | RUBY_FL_USER3 }; /** @@ -156,10 +121,7 @@ enum ruby_rarray_flags { */ enum ruby_rarray_consts { /** Where ::RARRAY_EMBED_LEN_MASK resides. */ - RARRAY_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 3, - - /** Max possible number elements that can be embedded. */ - RARRAY_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE) + RARRAY_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 3 }; /** Ruby's array. */ @@ -218,7 +180,12 @@ struct RArray { * to store its elements. In this case the length is encoded into the * flags. */ - const VALUE ary[RARRAY_EMBED_LEN_MAX]; + /* This is a length 1 array because: + * 1. GCC has a bug that does not optimize C flexible array members + * (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102452) + * 2. Zero length arrays are not supported by all compilers + */ + const VALUE ary[1]; } as; }; @@ -245,16 +212,6 @@ VALUE *rb_ary_ptr_use_start(VALUE ary); */ void rb_ary_ptr_use_end(VALUE a); -#if USE_TRANSIENT_HEAP -/** - * Destructively converts an array of transient backend into ordinal one. - * - * @param[out] a An object of ::RArray. - * @pre `a` must be a transient array. - * @post `a` gets out of transient heap, destructively. - */ -void rb_ary_detransient(VALUE a); -#endif RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_PURE_UNLESS_DEBUG() @@ -327,33 +284,6 @@ RARRAY_LENINT(VALUE ary) } RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -/** - * Queries if the array is a transient array. - * - * @param[in] ary Array in question. - * @retval true Yes it is. - * @retval false No it isn't. - * @pre `ary` must be an instance of ::RArray. - * - * @internal - * - * @shyouhei doesn't understand the benefit of this function called from - * extension libraries. - */ -static inline bool -RARRAY_TRANSIENT_P(VALUE ary) -{ - RBIMPL_ASSERT_TYPE(ary, RUBY_T_ARRAY); - -#if USE_TRANSIENT_HEAP - return RB_FL_ANY_RAW(ary, RARRAY_TRANSIENT_FLAG); -#else - return false; -#endif -} - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() /** * @private * @@ -364,7 +294,7 @@ RBIMPL_ATTR_PURE_UNLESS_DEBUG() * @return Its backend storage. */ static inline const VALUE * -rb_array_const_ptr_transient(VALUE a) +rb_array_const_ptr(VALUE a) { RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY); @@ -376,110 +306,21 @@ rb_array_const_ptr_transient(VALUE a) } } -#if ! USE_TRANSIENT_HEAP -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -#endif -/** - * @private - * - * This is an implementation detail of RARRAY_PTR(). People do not use it - * directly. - * - * @param[in] a An object of ::RArray. - * @return Its backend storage. - * @post `a` is not a transient array. - */ -static inline const VALUE * -rb_array_const_ptr(VALUE a) -{ - RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY); - -#if USE_TRANSIENT_HEAP - if (RARRAY_TRANSIENT_P(a)) { - rb_ary_detransient(a); - } -#endif - return rb_array_const_ptr_transient(a); -} - /** * @private * * This is an implementation detail of #RARRAY_PTR_USE. People do not use it * directly. - * - * @param[in] a An object of ::RArray. - * @param[in] allow_transient Whether `a` can be transient or not. - * @return Its backend storage. - * @post `a` is not a transient array unless `allow_transient`. - */ -static inline VALUE * -rb_array_ptr_use_start(VALUE a, - RBIMPL_ATTR_MAYBE_UNUSED() - int allow_transient) -{ - RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY); - -#if USE_TRANSIENT_HEAP - if (!allow_transient) { - if (RARRAY_TRANSIENT_P(a)) { - rb_ary_detransient(a); - } - } -#endif - - return rb_ary_ptr_use_start(a); -} - -/** - * @private - * - * This is an implementation detail of #RARRAY_PTR_USE. People do not use it - * directly. - * - * @param[in] a An object of ::RArray. - * @param[in] allow_transient Whether `a` can be transient or not. */ -static inline void -rb_array_ptr_use_end(VALUE a, - RBIMPL_ATTR_MAYBE_UNUSED() - int allow_transient) -{ - RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY); - rb_ary_ptr_use_end(a); -} - -/** - * @private - * - * This is an implementation detail of #RARRAY_PTR_USE. People do not use it - * directly. - */ -#define RBIMPL_RARRAY_STMT(flag, ary, var, expr) do { \ +#define RBIMPL_RARRAY_STMT(ary, var, expr) do { \ RBIMPL_ASSERT_TYPE((ary), RUBY_T_ARRAY); \ const VALUE rbimpl_ary = (ary); \ - VALUE *var = rb_array_ptr_use_start(rbimpl_ary, (flag)); \ + VALUE *var = rb_ary_ptr_use_start(rbimpl_ary); \ expr; \ - rb_array_ptr_use_end(rbimpl_ary, (flag)); \ + rb_ary_ptr_use_end(rbimpl_ary); \ } while (0) /** - * @private - * - * This is an implementation detail of #RARRAY_PTR_USE. People do not use it - * directly. - */ -#define RARRAY_PTR_USE_START(a) rb_array_ptr_use_start(a, 0) - -/** - * @private - * - * This is an implementation detail of #RARRAY_PTR_USE. People do not use it - * directly. - */ -#define RARRAY_PTR_USE_END(a) rb_array_ptr_use_end(a, 0) - -/** * Declares a section of code where raw pointers are used. In case you need to * touch the raw C array instead of polite CAPIs, then that operation shall be * wrapped using this macro. @@ -505,37 +346,11 @@ rb_array_ptr_use_end(VALUE a, * them use it... Maybe some transition path can be implemented later. */ #define RARRAY_PTR_USE(ary, ptr_name, expr) \ - RBIMPL_RARRAY_STMT(0, ary, ptr_name, expr) - -/** - * @private - * - * This is an implementation detail of #RARRAY_PTR_USE_TRANSIENT. People do - * not use it directly. - */ -#define RARRAY_PTR_USE_START_TRANSIENT(a) rb_array_ptr_use_start(a, 1) - -/** - * @private - * - * This is an implementation detail of #RARRAY_PTR_USE_TRANSIENT. People do - * not use it directly. - */ -#define RARRAY_PTR_USE_END_TRANSIENT(a) rb_array_ptr_use_end(a, 1) - -/** - * Identical to #RARRAY_PTR_USE, except the pointer can be a transient one. - * - * @param ary An object of ::RArray. - * @param ptr_name A variable name which points the C array in `expr`. - * @param expr The expression that touches `ptr_name`. - */ -#define RARRAY_PTR_USE_TRANSIENT(ary, ptr_name, expr) \ - RBIMPL_RARRAY_STMT(1, ary, ptr_name, expr) + RBIMPL_RARRAY_STMT(ary, ptr_name, expr) /** * Wild use of a C pointer. This function accesses the backend storage - * directly. This is slower than #RARRAY_PTR_USE_TRANSIENT. It exercises + * directly. This is slower than #RARRAY_PTR_USE. It exercises * extra manoeuvres to protect our generational GC. Use of this function is * considered archaic. Use a modern way instead. * @@ -570,7 +385,7 @@ RARRAY_PTR(VALUE ary) static inline void RARRAY_ASET(VALUE ary, long i, VALUE v) { - RARRAY_PTR_USE_TRANSIENT(ary, ptr, + RARRAY_PTR_USE(ary, ptr, RB_OBJ_WRITE(ary, &ptr[i], v)); } @@ -585,6 +400,6 @@ RARRAY_ASET(VALUE ary, long i, VALUE v) * remains as it is due to that. If we could warn such usages we can set a * transition path, but currently no way is found to do so. */ -#define RARRAY_AREF(a, i) RARRAY_CONST_PTR_TRANSIENT(a)[i] +#define RARRAY_AREF(a, i) RARRAY_CONST_PTR(a)[i] #endif /* RBIMPL_RARRAY_H */ diff --git a/include/ruby/internal/core/rbasic.h b/include/ruby/internal/core/rbasic.h index 4617f743a7..63cdff8e09 100644 --- a/include/ruby/internal/core/rbasic.h +++ b/include/ruby/internal/core/rbasic.h @@ -55,23 +55,27 @@ enum ruby_rvalue_flags { RVALUE_EMBED_LEN_MAX = RBIMPL_RVALUE_EMBED_LEN_MAX }; +#if (SIZEOF_VALUE < SIZEOF_UINT64_T) +#define RBASIC_SHAPE_ID_FIELD 1 +#else +#define RBASIC_SHAPE_ID_FIELD 0 +#endif + /** - * Ruby's object's, base components. Every single ruby objects have them in - * common. + * Ruby object's base components. All Ruby objects have them in common. */ struct RUBY_ALIGNAS(SIZEOF_VALUE) RBasic { /** - * Per-object flags. Each ruby objects have their own characteristics - * apart from their classes. For instance whether an object is frozen or - * not is not controlled by its class. This is where such properties are - * stored. + * Per-object flags. Each Ruby object has its own characteristics apart + * from its class. For instance, whether an object is frozen or not is not + * controlled by its class. This is where such properties are stored. * * @see enum ::ruby_fl_type * - * @note This is ::VALUE rather than an enum for alignment purpose. Back + * @note This is ::VALUE rather than an enum for alignment purposes. Back * in the 1990s there were no such thing like `_Alignas` in C. */ VALUE flags; @@ -79,14 +83,18 @@ RBasic { /** * Class of an object. Every object has its class. Also, everything is an * object in Ruby. This means classes are also objects. Classes have - * their own classes, classes of classes have their classes, too ... and - * it recursively continues forever. + * their own classes, classes of classes have their classes too, and it + * recursively continues forever. * - * Also note the `const` qualifier. In ruby an object cannot "change" its + * Also note the `const` qualifier. In Ruby, an object cannot "change" its * class. */ const VALUE klass; +#if RBASIC_SHAPE_ID_FIELD + VALUE shape_id; +#endif + #ifdef __cplusplus public: RBIMPL_ATTR_CONSTEXPR(CXX11) @@ -102,8 +110,14 @@ RBasic { RBasic() : flags(RBIMPL_VALUE_NULL), klass(RBIMPL_VALUE_NULL) +#if RBASIC_SHAPE_ID_FIELD + , shape_id(RBIMPL_VALUE_NULL) +#endif { } +# define RBASIC_INIT RBasic() +#else +# define RBASIC_INIT {RBIMPL_VALUE_NULL} #endif }; diff --git a/include/ruby/internal/core/rclass.h b/include/ruby/internal/core/rclass.h index 13a33a28bd..6f78cc569b 100644 --- a/include/ruby/internal/core/rclass.h +++ b/include/ruby/internal/core/rclass.h @@ -26,9 +26,7 @@ #include "ruby/internal/cast.h" /** @cond INTERNAL_MACRO */ -#define RMODULE_IS_OVERLAID RMODULE_IS_OVERLAID #define RMODULE_IS_REFINEMENT RMODULE_IS_REFINEMENT -#define RMODULE_INCLUDED_INTO_REFINEMENT RMODULE_INCLUDED_INTO_REFINEMENT /** @endcond */ /** @@ -55,57 +53,12 @@ * Why is it here, given RClass itself is not? */ enum ruby_rmodule_flags { - - /** - * This flag has something to do with refinements... I guess? It is set on - * occasions for modules that are refined by refinements, but it seems - * ... nobody cares about such things? Not sure but this flag could - * perhaps be a write-only information. - */ - RMODULE_IS_OVERLAID = RUBY_FL_USER2, - /** * This flag has something to do with refinements. A module created using * rb_mod_refine() has this flag set. This is the bit which controls * difference between normal inclusion versus refinements. */ - RMODULE_IS_REFINEMENT = RUBY_FL_USER3, - - /** - * This flag has something to do with refinements. This is set when a - * (non-refinement) module is included into another module, which is a - * refinement. This amends the way `super` searches for a super method. - * - * ```ruby - * class Foo - * def foo - * "Foo" - * end - * end - * - * module Bar - * def foo - * "[#{super}]" # this - * end - * end - * - * module Baz - * refine Foo do - * include Bar - * def foo - * "<#{super}>" - * end - * end - * end - * - * using Baz - * Foo.new.foo # => "[<Foo>]" - * ``` - * - * The `super` marked with "this" comment shall look for overlaid - * `Foo#foo`, which is not the ordinal method lookup direction. - */ - RMODULE_INCLUDED_INTO_REFINEMENT = RUBY_FL_USER4 + RMODULE_IS_REFINEMENT = RUBY_FL_USER1 }; struct RClass; /* Opaque, declared here for RCLASS() macro. */ diff --git a/include/ruby/internal/core/rdata.h b/include/ruby/internal/core/rdata.h index f6656b6546..cee5e7b5ea 100644 --- a/include/ruby/internal/core/rdata.h +++ b/include/ruby/internal/core/rdata.h @@ -37,12 +37,8 @@ #include "ruby/defines.h" /** @cond INTERNAL_MACRO */ -#ifdef RUBY_UNTYPED_DATA_WARNING -# /* Take that. */ -#elif defined(RUBY_EXPORT) -# define RUBY_UNTYPED_DATA_WARNING 1 -#else -# define RUBY_UNTYPED_DATA_WARNING 0 +#ifndef RUBY_UNTYPED_DATA_WARNING +#define RUBY_UNTYPED_DATA_WARNING 1 #endif #define RBIMPL_DATA_FUNC(f) RBIMPL_CAST((void (*)(void *))(f)) @@ -146,7 +142,10 @@ struct RData { */ RUBY_DATA_FUNC dfree; - /** Pointer to the actual C level struct that you want to wrap. */ + /** Pointer to the actual C level struct that you want to wrap. + * This is after dmark and dfree to allow DATA_PTR to continue to work for + * both RData and non-embedded RTypedData. + */ void *data; }; @@ -181,11 +180,6 @@ VALUE rb_data_object_wrap(VALUE klass, void *datap, RUBY_DATA_FUNC dmark, RUBY_D */ VALUE rb_data_object_zalloc(VALUE klass, size_t size, RUBY_DATA_FUNC dmark, RUBY_DATA_FUNC dfree); -/** - * @private - * Documented in include/ruby/internal/globals.h - */ -RUBY_EXTERN VALUE rb_cObject; RBIMPL_SYMBOL_EXPORT_END() /** @@ -331,15 +325,6 @@ rb_data_object_get_warning(VALUE obj) return rb_data_object_get(obj); } -#if defined(HAVE_BUILTIN___BUILTIN_CHOOSE_EXPR_CONSTANT_P) -# define rb_data_object_wrap_warning(klass, ptr, mark, free) \ - RB_GNUC_EXTENSION( \ - __builtin_choose_expr( \ - __builtin_constant_p(klass) && !(klass), \ - rb_data_object_wrap(klass, ptr, mark, free), \ - (rb_data_object_wrap_warning)(klass, ptr, mark, free))) -#endif - /** * This is an implementation detail of #Data_Make_Struct. People don't use it * directly. @@ -361,38 +346,6 @@ rb_data_object_make(VALUE klass, RUBY_DATA_FUNC mark_func, RUBY_DATA_FUNC free_f return result; } -RBIMPL_ATTR_DEPRECATED(("by: rb_data_object_wrap")) -/** @deprecated This function was renamed to rb_data_object_wrap(). */ -static inline VALUE -rb_data_object_alloc(VALUE klass, void *data, RUBY_DATA_FUNC dmark, RUBY_DATA_FUNC dfree) -{ - return rb_data_object_wrap(klass, data, dmark, dfree); -} - -RBIMPL_ATTR_DEPRECATED(("by: rb_cObject. Will be removed in 3.1.")) -RBIMPL_ATTR_PURE() -/** - * @private - * - * @deprecated There once was a variable called rb_cData, which no longer - * exists today. This function is a function because we want - * warnings for the usages. - */ -static inline VALUE -rb_cData(void) -{ - return rb_cObject; -} - -/** - * @private - * - * @deprecated This macro once was a thing in the old days, but makes no sense - * any longer today. Exists here for backwards compatibility - * only. You can safely forget about it. - */ -#define rb_cData rb_cData() - /** @cond INTERNAL_MACRO */ #define rb_data_object_wrap_0 rb_data_object_wrap #define rb_data_object_wrap_1 rb_data_object_wrap_warning diff --git a/include/ruby/internal/core/rfile.h b/include/ruby/internal/core/rfile.h index f8dddde9e5..a0eb8cb833 100644 --- a/include/ruby/internal/core/rfile.h +++ b/include/ruby/internal/core/rfile.h @@ -25,7 +25,7 @@ /* rb_io_t is in ruby/io.h. The header file has historically not been included * into ruby/ruby.h. We follow that tradition. */ -struct rb_io_t; +struct rb_io; /** * Ruby's File and IO. Ruby's IO are not just file descriptors. They have @@ -38,7 +38,7 @@ struct RFile { struct RBasic basic; /** IO's specific fields. */ - struct rb_io_t *fptr; + struct rb_io *fptr; }; /** diff --git a/include/ruby/internal/core/rhash.h b/include/ruby/internal/core/rhash.h index 61d2c15d87..897c570794 100644 --- a/include/ruby/internal/core/rhash.h +++ b/include/ruby/internal/core/rhash.h @@ -54,19 +54,6 @@ * * @internal * - * Declaration of rb_hash_iter_lev() is at include/ruby/backward.h. - */ -#define RHASH_ITER_LEV(h) rb_hash_iter_lev(h) - -/** - * @private - * - * @deprecated This macro once was a thing in the old days, but makes no sense - * any longer today. Exists here for backwards compatibility - * only. You can safely forget about it. - * - * @internal - * * Declaration of rb_hash_ifnone() is at include/ruby/backward.h. */ #define RHASH_IFNONE(h) rb_hash_ifnone(h) diff --git a/include/ruby/internal/core/rmatch.h b/include/ruby/internal/core/rmatch.h index 2d2fd897f5..a528c2999e 100644 --- a/include/ruby/internal/core/rmatch.h +++ b/include/ruby/internal/core/rmatch.h @@ -68,7 +68,7 @@ struct rmatch_offset { }; /** Represents a match. */ -struct rmatch { +struct rb_matchext_struct { /** * "Registers" of a match. This is a quasi-opaque struct that holds * execution result of a match. Roughly resembles `&~`. @@ -82,6 +82,8 @@ struct rmatch { int char_offset_num_allocated; }; +typedef struct rb_matchext_struct rb_matchext_t; + /** * Regular expression execution context. When a regular expression "matches" * to a string, it generates capture groups etc. This struct holds that info. @@ -102,16 +104,13 @@ struct RMatch { VALUE str; /** - * The result of this match. - */ - struct rmatch *rmatch; - - /** * The expression of this match. */ VALUE regexp; /* RRegexp */ }; +#define RMATCH_EXT(m) ((rb_matchext_t *)((char *)(m) + sizeof(struct RMatch))) + RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /** @@ -139,8 +138,7 @@ static inline struct re_registers * RMATCH_REGS(VALUE match) { RBIMPL_ASSERT_TYPE(match, RUBY_T_MATCH); - RBIMPL_ASSERT_OR_ASSUME(RMATCH(match)->rmatch != NULL); - return &RMATCH(match)->rmatch->regs; + return &RMATCH_EXT(match)->regs; } #endif /* RBIMPL_RMATCH_H */ diff --git a/include/ruby/internal/core/robject.h b/include/ruby/internal/core/robject.h index f2028063a6..99f6470ac1 100644 --- a/include/ruby/internal/core/robject.h +++ b/include/ruby/internal/core/robject.h @@ -37,16 +37,15 @@ /** * Convenient casting macro. * - * @param obj An object, which is in fact an ::RRegexp. - * @return The passed object casted to ::RRegexp. + * @param obj An object, which is in fact an ::RObject. + * @return The passed object casted to ::RObject. */ #define ROBJECT(obj) RBIMPL_CAST((struct RObject *)(obj)) /** @cond INTERNAL_MACRO */ -#define ROBJECT_EMBED_LEN_MAX ROBJECT_EMBED_LEN_MAX -#define ROBJECT_EMBED ROBJECT_EMBED -#define ROBJECT_NUMIV ROBJECT_NUMIV -#define ROBJECT_IVPTR ROBJECT_IVPTR -#define ROBJECT_IV_INDEX_TBL ROBJECT_IV_INDEX_TBL +#define ROBJECT_EMBED_LEN_MAX ROBJECT_EMBED_LEN_MAX +#define ROBJECT_HEAP ROBJECT_HEAP +#define ROBJECT_FIELDS_CAPACITY ROBJECT_FIELDS_CAPACITY +#define ROBJECT_FIELDS ROBJECT_FIELDS /** @endcond */ /** @@ -56,10 +55,12 @@ */ enum ruby_robject_flags { /** - * This flag has something to do with memory footprint. If the object is - * "small" enough, ruby tries to be creative to abuse padding bits of - * struct ::RObject for storing instance variables. This flag denotes that - * situation. + * This flag marks that the object's instance variables are stored in an + * external heap buffer. + * Normally, instance variable references are stored inside the object slot, + * but if it overflow, Ruby may have to allocate a separate buffer and spills + * the instance variables there. + * This flag denotes that situation. * * @warning This bit has to be considered read-only. Setting/clearing * this bit without corresponding fix up must cause immediate @@ -72,16 +73,7 @@ enum ruby_robject_flags { * 3rd parties must not be aware that there even is more than one way to * store instance variables. Might better be hidden. */ - ROBJECT_EMBED = RUBY_FL_USER1 -}; - -/** - * This is an enum because GDB wants it (rather than a macro). People need not - * bother. - */ -enum ruby_robject_consts { - /** Max possible number of instance variables that can be embedded. */ - ROBJECT_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE) + ROBJECT_HEAP = RUBY_FL_USER4 }; struct st_table; @@ -103,60 +95,25 @@ struct RObject { * this pattern. */ struct { - - /** - * Number of instance variables. This is per object; objects might - * differ in this field even if they have the identical classes. - */ - uint32_t numiv; - /** Pointer to a C array that holds instance variables. */ - VALUE *ivptr; - - /** - * This is a table that holds instance variable name to index - * mapping. Used when accessing instance variables using names. - * - * @internal - * - * This is a shortcut for `RCLASS_IV_INDEX_TBL(rb_obj_class(obj))`. - */ - struct st_table *iv_index_tbl; + VALUE *fields; } heap; - /** - * Embedded instance variables. When an object is small enough, it + /* Embedded instance variables. When an object is small enough, it * uses this area to store the instance variables. + * + * This is a length 1 array because: + * 1. GCC has a bug that does not optimize C flexible array members + * (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102452) + * 2. Zero length arrays are not supported by all compilers */ - VALUE ary[ROBJECT_EMBED_LEN_MAX]; + VALUE ary[1]; } as; }; RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /** - * Queries the number of instance variables. - * - * @param[in] obj Object in question. - * @return Its number of instance variables. - * @pre `obj` must be an instance of ::RObject. - */ -static inline uint32_t -ROBJECT_NUMIV(VALUE obj) -{ - RBIMPL_ASSERT_TYPE(obj, RUBY_T_OBJECT); - - if (RB_FL_ANY_RAW(obj, ROBJECT_EMBED)) { - return ROBJECT_EMBED_LEN_MAX; - } - else { - return ROBJECT(obj)->as.heap.numiv; - } -} - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -/** * Queries the instance variables. * * @param[in] obj Object in question. @@ -168,17 +125,17 @@ RBIMPL_ATTR_ARTIFICIAL() * @shyouhei finds no reason for this to be visible from extension libraries. */ static inline VALUE * -ROBJECT_IVPTR(VALUE obj) +ROBJECT_FIELDS(VALUE obj) { RBIMPL_ASSERT_TYPE(obj, RUBY_T_OBJECT); struct RObject *const ptr = ROBJECT(obj); - if (RB_FL_ANY_RAW(obj, ROBJECT_EMBED)) { - return ptr->as.ary; + if (RB_UNLIKELY(RB_FL_ANY_RAW(obj, ROBJECT_HEAP))) { + return ptr->as.heap.fields; } else { - return ptr->as.heap.ivptr; + return ptr->as.ary; } } diff --git a/include/ruby/internal/core/rstring.h b/include/ruby/internal/core/rstring.h index e14753ab55..35175ea94a 100644 --- a/include/ruby/internal/core/rstring.h +++ b/include/ruby/internal/core/rstring.h @@ -42,11 +42,7 @@ /** @cond INTERNAL_MACRO */ #define RSTRING_NOEMBED RSTRING_NOEMBED -#define RSTRING_EMBED_LEN_MASK RSTRING_EMBED_LEN_MASK -#define RSTRING_EMBED_LEN_SHIFT RSTRING_EMBED_LEN_SHIFT -#define RSTRING_EMBED_LEN_MAX RSTRING_EMBED_LEN_MAX #define RSTRING_FSTR RSTRING_FSTR -#define RSTRING_EMBED_LEN RSTRING_EMBED_LEN #define RSTRING_LEN RSTRING_LEN #define RSTRING_LENINT RSTRING_LENINT #define RSTRING_PTR RSTRING_PTR @@ -160,19 +156,6 @@ enum ruby_rstring_flags { */ RSTRING_NOEMBED = RUBY_FL_USER1, - /** - * When a string employs embedded strategy (see ::RSTRING_NOEMBED), these - * bits are used to store the number of bytes actually filled into - * ::RString::ary. - * - * @internal - * - * 3rd parties must not be aware that there even is more than one way to - * store a string. Might better be hidden. - */ - RSTRING_EMBED_LEN_MASK = RUBY_FL_USER2 | RUBY_FL_USER3 | RUBY_FL_USER4 | - RUBY_FL_USER5 | RUBY_FL_USER6, - /* Actually, string encodings are also encoded into the flags, using * remaining bits.*/ @@ -199,18 +182,6 @@ enum ruby_rstring_flags { }; /** - * This is an enum because GDB wants it (rather than a macro). People need not - * bother. - */ -enum ruby_rstring_consts { - /** Where ::RSTRING_EMBED_LEN_MASK resides. */ - RSTRING_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 2, - - /** Max possible number of characters that can be embedded. */ - RSTRING_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(char) - 1 -}; - -/** * Ruby's String. A string in ruby conceptually has these information: * * - Encoding of the string. @@ -227,6 +198,13 @@ struct RString { /** Basic part, including flags and class. */ struct RBasic basic; + /** + * Length of the string, not including terminating NUL character. + * + * @note This is in bytes. + */ + long len; + /** String's specific fields. */ union { @@ -235,14 +213,6 @@ struct RString { * pattern. */ struct { - - /** - * Length of the string, not including terminating NUL character. - * - * @note This is in bytes. - */ - long len; - /** * Pointer to the contents of the string. In the old days each * string had dedicated memory regions. That is no longer true @@ -271,14 +241,15 @@ struct RString { } aux; } heap; - /** - * Embedded contents. When a string is short enough, it uses this area - * to store the contents themselves. This was impractical in the 20th - * century, but these days 64 bit machines can typically hold 48 bytes - * here. Could be sufficiently large. In this case the length is - * encoded into the flags. - */ - char ary[RSTRING_EMBED_LEN_MAX + 1]; + /** Embedded contents. */ + struct { + /* This is a length 1 array because: + * 1. GCC has a bug that does not optimize C flexible array members + * (https://gcc.gnu.org/bugzilla/show_bug.cgi?id=102452) + * 2. Zero length arrays are not supported by all compilers + */ + char ary[1]; + } embed; } as; }; @@ -371,71 +342,17 @@ void rb_check_safe_str(VALUE); * only. You can safely forget about it. */ #define Check_SafeStr(v) rb_check_safe_str(RBIMPL_CAST((VALUE)(v))) -RBIMPL_SYMBOL_EXPORT_END() -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -/** - * Queries the length of the string. - * - * @param[in] str String in question. - * @return Its length, in bytes. - * @pre `str` must be an instance of ::RString, and must has its - * ::RSTRING_NOEMBED flag off. - * - * @internal - * - * This was a macro before. It was inevitable to be public, since macros are - * global constructs. But should it be forever? Now that it is a function, - * @shyouhei thinks it could just be eliminated, hidden into implementation - * details. - */ -static inline long -RSTRING_EMBED_LEN(VALUE str) -{ - RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING); - RBIMPL_ASSERT_OR_ASSUME(! RB_FL_ANY_RAW(str, RSTRING_NOEMBED)); - - VALUE f = RBASIC(str)->flags; - f &= RSTRING_EMBED_LEN_MASK; - f >>= RSTRING_EMBED_LEN_SHIFT; - return RBIMPL_CAST((long)f); -} - -RBIMPL_WARNING_PUSH() -#if RBIMPL_COMPILER_IS(Intel) -RBIMPL_WARNING_IGNORED(413) -#endif - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() /** * @private * - * "Expands" an embedded string into an ordinal one. This is a function that - * returns aggregated type. The returned struct always has its `as.heap.len` - * an `as.heap.ptr` fields set appropriately. + * Prints diagnostic message to stderr when RSTRING_PTR or RSTRING_END + * is NULL. * - * This is an implementation detail that 3rd parties should never bother. + * @param[in] func The function name where encountered NULL pointer. */ -static inline struct RString -rbimpl_rstring_getmem(VALUE str) -{ - RBIMPL_ASSERT_TYPE(str, RUBY_T_STRING); - - if (RB_FL_ANY_RAW(str, RSTRING_NOEMBED)) { - return *RSTRING(str); - } - else { - /* Expecting compilers to optimize this on-stack struct away. */ - struct RString retval; - retval.as.heap.len = RSTRING_EMBED_LEN(str); - retval.as.heap.ptr = RSTRING(str)->as.ary; - return retval; - } -} - -RBIMPL_WARNING_POP() +void rb_debug_rstring_null_ptr(const char *func); +RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() @@ -449,7 +366,7 @@ RBIMPL_ATTR_ARTIFICIAL() static inline long RSTRING_LEN(VALUE str) { - return rbimpl_rstring_getmem(str).as.heap.len; + return RSTRING(str)->len; } RBIMPL_ATTR_ARTIFICIAL() @@ -463,25 +380,18 @@ RBIMPL_ATTR_ARTIFICIAL() static inline char * RSTRING_PTR(VALUE str) { - char *ptr = rbimpl_rstring_getmem(str).as.heap.ptr; + char *ptr = RB_FL_TEST_RAW(str, RSTRING_NOEMBED) ? + RSTRING(str)->as.heap.ptr : + RSTRING(str)->as.embed.ary; - if (RB_UNLIKELY(! ptr)) { + if (RUBY_DEBUG && RB_UNLIKELY(! ptr)) { /* :BEWARE: @shyouhei thinks that currently, there are rooms for this - * function to return NULL. In the 20th century that was a pointless - * concern. However struct RString can hold fake strings nowadays. It - * seems no check against NULL are exercised around handling of them - * (one of such usages is located in marshal.c, which scares - * @shyouhei). Better check here for maximum safety. + * function to return NULL. Better check here for maximum safety. * * Also, this is not rb_warn() because RSTRING_PTR() can be called * during GC (see what obj_info() does). rb_warn() needs to allocate * Ruby objects. That is not possible at this moment. */ - fprintf(stderr, "%s\n", - "RSTRING_PTR is returning NULL!! " - "SIGSEGV is highly expected to follow immediately. " - "If you could reproduce, attach your debugger here, " - "and look at the passed string." - ); + rb_debug_rstring_null_ptr("RSTRING_PTR"); } return ptr; @@ -498,19 +408,17 @@ RBIMPL_ATTR_ARTIFICIAL() static inline char * RSTRING_END(VALUE str) { - struct RString buf = rbimpl_rstring_getmem(str); + char *ptr = RB_FL_TEST_RAW(str, RSTRING_NOEMBED) ? + RSTRING(str)->as.heap.ptr : + RSTRING(str)->as.embed.ary; + long len = RSTRING_LEN(str); - if (RB_UNLIKELY(! buf.as.heap.ptr)) { + if (RUBY_DEBUG && RB_UNLIKELY(!ptr)) { /* Ditto. */ - fprintf(stderr, "%s\n", - "RSTRING_END is returning NULL!! " - "SIGSEGV is highly expected to follow immediately. " - "If you could reproduce, attach your debugger here, " - "and look at the passed string." - ); + rb_debug_rstring_null_ptr("RSTRING_END"); } - return &buf.as.heap.ptr[buf.as.heap.len]; + return &ptr[len]; } RBIMPL_ATTR_ARTIFICIAL() @@ -539,16 +447,7 @@ RSTRING_LENINT(VALUE str) * @param ptrvar Variable where its contents is stored. * @param lenvar Variable where its length is stored. */ -#ifdef HAVE_STMT_AND_DECL_IN_EXPR -# define RSTRING_GETMEM(str, ptrvar, lenvar) \ - __extension__ ({ \ - struct RString rbimpl_str = rbimpl_rstring_getmem(str); \ - (ptrvar) = rbimpl_str.as.heap.ptr; \ - (lenvar) = rbimpl_str.as.heap.len; \ - }) -#else # define RSTRING_GETMEM(str, ptrvar, lenvar) \ ((ptrvar) = RSTRING_PTR(str), \ (lenvar) = RSTRING_LEN(str)) -#endif /* HAVE_STMT_AND_DECL_IN_EXPR */ #endif /* RBIMPL_RSTRING_H */ diff --git a/include/ruby/internal/core/rstruct.h b/include/ruby/internal/core/rstruct.h index 69be487b59..0028a1bdcd 100644 --- a/include/ruby/internal/core/rstruct.h +++ b/include/ruby/internal/core/rstruct.h @@ -31,18 +31,6 @@ # include "ruby/backward.h" #endif -/** - * @private - * - * @deprecated This macro once was a thing in the old days, but makes no sense - * any longer today. Exists here for backwards compatibility - * only. You can safely forget about it. - * - * @internal - * - * Declaration of rb_struct_ptr() is at include/ruby/backward.h. - */ -#define RSTRUCT_PTR(st) rb_struct_ptr(st) /** @cond INTERNAL_MACRO */ #define RSTRUCT_LEN RSTRUCT_LEN #define RSTRUCT_SET RSTRUCT_SET diff --git a/include/ruby/internal/core/rtypeddata.h b/include/ruby/internal/core/rtypeddata.h index bbf208867d..ec0794e387 100644 --- a/include/ruby/internal/core/rtypeddata.h +++ b/include/ruby/internal/core/rtypeddata.h @@ -37,6 +37,7 @@ #include "ruby/internal/dllexport.h" #include "ruby/internal/error.h" #include "ruby/internal/fl_type.h" +#include "ruby/internal/static_assert.h" #include "ruby/internal/stdbool.h" #include "ruby/internal/value_type.h" @@ -108,11 +109,17 @@ /** @cond INTERNAL_MACRO */ #define RTYPEDDATA_P RTYPEDDATA_P #define RTYPEDDATA_TYPE RTYPEDDATA_TYPE +#define TYPED_DATA_EMBEDDED ((VALUE)1) +#define TYPED_DATA_PTR_MASK (~(TYPED_DATA_EMBEDDED)) +/** @endcond */ + +/** + * Macros to see if each corresponding flag is defined. + */ #define RUBY_TYPED_FREE_IMMEDIATELY RUBY_TYPED_FREE_IMMEDIATELY #define RUBY_TYPED_FROZEN_SHAREABLE RUBY_TYPED_FROZEN_SHAREABLE #define RUBY_TYPED_WB_PROTECTED RUBY_TYPED_WB_PROTECTED #define RUBY_TYPED_PROMOTED1 RUBY_TYPED_PROMOTED1 -/** @endcond */ /** * @private @@ -137,6 +144,8 @@ rbimpl_typeddata_flags { */ RUBY_TYPED_FREE_IMMEDIATELY = 1, + RUBY_TYPED_EMBEDDABLE = 2, + /** * This flag has something to do with Ractor. Multiple Ractors run without * protecting each other. Sharing an object among Ractors is basically @@ -151,6 +160,12 @@ rbimpl_typeddata_flags { */ RUBY_TYPED_FROZEN_SHAREABLE = RUBY_FL_SHAREABLE, + // experimental flag + // Similar to RUBY_TYPED_FROZEN_SHAREABLE, but doesn't make shareable + // reachable objects from this T_DATA object on the Ractor.make_shareable. + // If it refers to unshareable objects, simply raise an error. + // RUBY_TYPED_FROZEN_SHAREABLE_NO_REC = RUBY_FL_FINALIZE, + /** * This flag has something to do with our garbage collector. These days * ruby objects are "generational". There are those who are young and @@ -173,10 +188,16 @@ rbimpl_typeddata_flags { RUBY_TYPED_WB_PROTECTED = RUBY_FL_WB_PROTECTED, /* THIS FLAG DEPENDS ON Ruby version */ /** - * This flag is mysterious. It seems nobody is currently using it. The - * intention of this flag is also unclear. We need further investigations. + * This flag is used to distinguish RTypedData from deprecated RData objects. */ - RUBY_TYPED_PROMOTED1 = RUBY_FL_PROMOTED1 /* THIS FLAG DEPENDS ON Ruby version */ + RUBY_TYPED_FL_IS_TYPED_DATA = RUBY_FL_USERPRIV0, + + /** + * This flag determines whether marking and compaction should be carried out + * using the dmark/dcompact callback functions or whether we should mark + * declaratively using a list of references defined inside the data struct we're wrapping + */ + RUBY_TYPED_DECL_MARKING = RUBY_FL_USER2 }; /** @@ -241,10 +262,15 @@ struct rb_data_type_struct { RUBY_DATA_FUNC dcompact; /** - * This field is reserved for future extension. For now, it must be - * filled with zeros. + * @internal */ - void *reserved[1]; /* For future extension. + void (*handle_weak_references)(void *); + + /** + * This field is reserved for future extension. For now, it must be + * filled with zeros. + */ + void *reserved[7]; /* For future extension. This array *must* be filled with ZERO. */ } function; @@ -342,26 +368,28 @@ struct RTypedData { /** The part that all ruby objects have in common. */ struct RBasic basic; - /** - * This field stores various information about how Ruby should handle a - * data. This roughly resembles a Ruby level class (apart from method - * definition etc.) - */ - const rb_data_type_t *type; + /** Direct reference to the slots that holds instance variables, if any **/ + VALUE fields_obj; /** - * This has to be always 1. + * This is a `const rb_data_type_t *const` value, with the low bits set: * - * @internal + * 1: Set if object is embedded. * - * Why, then, this is not a const ::VALUE? + * This field stores various information about how Ruby should handle a + * data. This roughly resembles a Ruby level class (apart from method + * definition etc.) */ - VALUE typed_flag; + const VALUE type; /** Pointer to the actual C level struct that you want to wrap. */ void *data; }; +#if !defined(__cplusplus) || __cplusplus >= 201103L +RBIMPL_STATIC_ASSERT(data_in_rtypeddata, offsetof(struct RData, data) == offsetof(struct RTypedData, data)); +#endif + RBIMPL_SYMBOL_EXPORT_BEGIN() RBIMPL_ATTR_NONNULL((3)) /** @@ -376,6 +404,7 @@ RBIMPL_ATTR_NONNULL((3)) */ VALUE rb_data_typed_object_wrap(VALUE klass, void *datap, const rb_data_type_t *type); +RBIMPL_ATTR_NONNULL((3)) /** * Identical to rb_data_typed_object_wrap(), except it allocates a new data * region internally instead of taking an existing one. The allocation is done @@ -391,6 +420,7 @@ VALUE rb_data_typed_object_wrap(VALUE klass, void *datap, const rb_data_type_t * */ VALUE rb_data_typed_object_zalloc(VALUE klass, size_t size, const rb_data_type_t *type); +RBIMPL_ATTR_NONNULL(()) /** * Checks for the domestic relationship between the two. * @@ -405,6 +435,7 @@ VALUE rb_data_typed_object_zalloc(VALUE klass, size_t size, const rb_data_type_t */ int rb_typeddata_inherited_p(const rb_data_type_t *child, const rb_data_type_t *parent); +RBIMPL_ATTR_NONNULL((2)) /** * Checks if the given object is of given kind. * @@ -415,6 +446,7 @@ int rb_typeddata_inherited_p(const rb_data_type_t *child, const rb_data_type_t * */ int rb_typeddata_is_kind_of(VALUE obj, const rb_data_type_t *data_type); +RBIMPL_ATTR_NONNULL((2)) /** * Identical to rb_typeddata_is_kind_of(), except it raises exceptions instead * of returning false. @@ -426,8 +458,49 @@ int rb_typeddata_is_kind_of(VALUE obj, const rb_data_type_t *data_type); * @post Upon successful return `obj`'s type is guaranteed `data_type`. */ void *rb_check_typeddata(VALUE obj, const rb_data_type_t *data_type); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((2)) +/** + * @private + * + * Fails with the given object's type incompatibility to the type. + * + * This is an implementation detail of Check_Type. People don't use it + * directly. + * + * @param[in] obj The object in question. + * @param[in] expected Name of expected data type of `obj`. + */ +void rb_unexpected_object_type(VALUE obj, const char *expected); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL(()) +/** + * @private + * + * Fails with the given object's type incompatibility to the type. + * + * This is an implementation detail of #TypedData_Make_Struct. People don't + * use it directly. + * + * @param[in] actual Actual data type. + * @param[in] expected Expected data type. + */ +void rb_unexpected_typeddata(const rb_data_type_t *actual, const rb_data_type_t *expected); RBIMPL_SYMBOL_EXPORT_END() +#if RUBY_DEBUG +# define RBIMPL_TYPEDDATA_PRECONDITION(obj, unreachable) \ + while (RB_UNLIKELY(!RB_TYPE_P(obj, RUBY_T_DATA))) { \ + rb_unexpected_object_type(obj, "Data"); \ + unreachable; \ + } +#else +# define RBIMPL_TYPEDDATA_PRECONDITION(obj, unreachable) \ + RBIMPL_ASSERT_NOTHING +#endif + /** * Converts sval, a pointer to your struct, into a Ruby object. * @@ -456,14 +529,13 @@ RBIMPL_SYMBOL_EXPORT_END() */ #define TypedData_Make_Struct0(result, klass, type, size, data_type, sval) \ VALUE result = rb_data_typed_object_zalloc(klass, size, data_type); \ - (sval) = RBIMPL_CAST((type *)RTYPEDDATA_DATA(result)); \ + (sval) = RBIMPL_CAST((type *)rbimpl_typeddata_get_data(result)); \ RBIMPL_CAST(/*suppress unused variable warnings*/(void)(sval)) /** * Identical to #TypedData_Wrap_Struct, except it allocates a new data region * internally instead of taking an existing one. The allocation is done using - * ruby_calloc(). Hence it makes no sense for `data_type->function.dfree` to - * be anything other than ::RUBY_TYPED_DEFAULT_FREE. + * ruby_calloc(). * * @param klass Ruby level class of the object. * @param type Type name of the C struct. @@ -494,18 +566,37 @@ RBIMPL_SYMBOL_EXPORT_END() sizeof(type)) #endif -/** - * Obtains a C struct from inside of a wrapper Ruby object. - * - * @param obj An instance of ::RTypedData. - * @param type Type name of the C struct. - * @param data_type The data type describing `type`. - * @param sval Variable name of obtained C struct. - * @exception rb_eTypeError `obj` is not a kind of `data_type`. - * @return Unwrapped C struct that `obj` holds. - */ -#define TypedData_Get_Struct(obj,type,data_type,sval) \ - ((sval) = RBIMPL_CAST((type *)rb_check_typeddata((obj), (data_type)))) +static inline bool +rbimpl_typeddata_embedded_p(VALUE obj) +{ + return (RTYPEDDATA(obj)->type) & TYPED_DATA_EMBEDDED; +} + +RBIMPL_ATTR_DEPRECATED_INTERNAL_ONLY() +static inline bool +RTYPEDDATA_EMBEDDED_P(VALUE obj) +{ + RBIMPL_TYPEDDATA_PRECONDITION(obj, RBIMPL_UNREACHABLE_RETURN(false)); + + return rbimpl_typeddata_embedded_p(obj); +} + +static inline void * +rbimpl_typeddata_get_data(VALUE obj) +{ + /* We reuse the data pointer in embedded TypedData. */ + return rbimpl_typeddata_embedded_p(obj) ? + RBIMPL_CAST((void *)&RTYPEDDATA_DATA(obj)) : + RTYPEDDATA_DATA(obj); +} + +static inline void * +RTYPEDDATA_GET_DATA(VALUE obj) +{ + RBIMPL_TYPEDDATA_PRECONDITION(obj, RBIMPL_UNREACHABLE_RETURN(NULL)); + + return rbimpl_typeddata_get_data(obj); +} RBIMPL_ATTR_PURE() RBIMPL_ATTR_ARTIFICIAL() @@ -523,7 +614,28 @@ RBIMPL_ATTR_ARTIFICIAL() static inline bool rbimpl_rtypeddata_p(VALUE obj) { - return RTYPEDDATA(obj)->typed_flag == 1; + return FL_TEST_RAW(obj, RUBY_TYPED_FL_IS_TYPED_DATA); +} + +RBIMPL_ATTR_PURE() +RBIMPL_ATTR_ARTIFICIAL() +/** + * @private + * + * Identical to rbimpl_rtypeddata_p(), except it is allowed to call on non-data + * objects. + * + * This is an implementation detail of inline functions defined in this file. + * People don't use it directly. + * + * @param[in] obj Object in question + * @retval true `obj` is an instance of ::RTypedData. + * @retval false `obj` is not an instance of ::RTypedData + */ +static inline bool +rbimpl_obj_typeddata_p(VALUE obj) +{ + return RB_TYPE_P(obj, RUBY_T_DATA) && rbimpl_rtypeddata_p(obj); } RBIMPL_ATTR_PURE_UNLESS_DEBUG() @@ -539,19 +651,14 @@ RBIMPL_ATTR_ARTIFICIAL() static inline bool RTYPEDDATA_P(VALUE obj) { -#if RUBY_DEBUG - if (RB_UNLIKELY(! RB_TYPE_P(obj, RUBY_T_DATA))) { - Check_Type(obj, RUBY_T_DATA); - RBIMPL_UNREACHABLE_RETURN(false); - } -#endif + RBIMPL_TYPEDDATA_PRECONDITION(obj, RBIMPL_UNREACHABLE_RETURN(false)); return rbimpl_rtypeddata_p(obj); } RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() -/* :TODO: can this function be __attribute__((returns_nonnull)) or not? */ +RBIMPL_ATTR_RETURNS_NONNULL() /** * Queries for the type of given object. * @@ -559,19 +666,77 @@ RBIMPL_ATTR_ARTIFICIAL() * @return Data type struct that corresponds to `obj`. * @pre `obj` must be an instance of ::RTypedData. */ -static inline const struct rb_data_type_struct * +static inline const rb_data_type_t * RTYPEDDATA_TYPE(VALUE obj) { -#if RUBY_DEBUG - if (RB_UNLIKELY(! RTYPEDDATA_P(obj))) { - rb_unexpected_type(obj, RUBY_T_DATA); - RBIMPL_UNREACHABLE_RETURN(NULL); + RBIMPL_TYPEDDATA_PRECONDITION(obj, RBIMPL_UNREACHABLE_RETURN(NULL)); + + VALUE type = RTYPEDDATA(obj)->type & TYPED_DATA_PTR_MASK; + const rb_data_type_t *ptr = RBIMPL_CAST((const rb_data_type_t *)type); + RBIMPL_ASSERT_OR_ASSUME(ptr); + return ptr; +} + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NONNULL(()) +static inline bool +rbimpl_typeddata_inherited_p_inline(const rb_data_type_t *child, const rb_data_type_t *parent) +{ + do { + if (RB_LIKELY(child == parent)) return true; + } while ((child = child->parent) != NULL); + return false; +} +#define rb_typeddata_inherited_p rbimpl_typeddata_inherited_p_inline + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NONNULL((2)) +static inline bool +rbimpl_typeddata_is_kind_of_inline(VALUE obj, const rb_data_type_t *data_type) +{ + if (RB_UNLIKELY(!rbimpl_obj_typeddata_p(obj))) return false; + return rb_typeddata_inherited_p(RTYPEDDATA_TYPE(obj), data_type); +} +#define rb_typeddata_is_kind_of rbimpl_typeddata_is_kind_of_inline + +RBIMPL_ATTR_ARTIFICIAL() +RBIMPL_ATTR_NONNULL((2)) +/** + * @private + * + * This is an implementation detail of TypedData_Get_Struct(). Don't use it + * directly. + */ +static inline void * +rbimpl_check_typeddata(VALUE obj, const rb_data_type_t *expected_type) +{ + if (RB_UNLIKELY(!rbimpl_obj_typeddata_p(obj))) { + rb_unexpected_object_type(obj, expected_type->wrap_struct_name); + } + + const rb_data_type_t *actual_type = RTYPEDDATA_TYPE(obj); + if (RB_UNLIKELY(!rb_typeddata_inherited_p(actual_type, expected_type))){ + rb_unexpected_typeddata(actual_type, expected_type); } -#endif - return RTYPEDDATA(obj)->type; + return RTYPEDDATA_GET_DATA(obj); } + +/** + * Obtains a C struct from inside of a wrapper Ruby object. + * + * @param obj An instance of ::RTypedData. + * @param type Type name of the C struct. + * @param data_type The data type describing `type`. + * @param sval Variable name of obtained C struct. + * @exception rb_eTypeError `obj` is not a kind of `data_type`. + * @return Unwrapped C struct that `obj` holds. + */ +#define TypedData_Get_Struct(obj,type,data_type,sval) \ + ((sval) = RBIMPL_CAST((type *)rbimpl_check_typeddata((obj), (data_type)))) + +RBIMPL_ATTR_NONNULL((2)) /** * While we don't stop you from using this function, it seems to be an * implementation detail of #TypedData_Make_Struct, which is preferred over @@ -593,12 +758,4 @@ rb_data_typed_object_make(VALUE klass, const rb_data_type_t *type, void **datap, return result; } -RBIMPL_ATTR_DEPRECATED(("by: rb_data_typed_object_wrap")) -/** @deprecated This function was renamed to rb_data_typed_object_wrap(). */ -static inline VALUE -rb_data_typed_object_alloc(VALUE klass, void *datap, const rb_data_type_t *type) -{ - return rb_data_typed_object_wrap(klass, datap, type); -} - #endif /* RBIMPL_RTYPEDDATA_H */ diff --git a/include/ruby/internal/ctype.h b/include/ruby/internal/ctype.h index 0f7ca6c516..8b24026311 100644 --- a/include/ruby/internal/ctype.h +++ b/include/ruby/internal/ctype.h @@ -498,8 +498,8 @@ RBIMPL_ATTR_ARTIFICIAL() * Our own locale-insensitive version of `tolower(3)`. * * @param[in] c Byte in question to convert. - * @retval c The byte is not listed in in IEEE 1003.1 section - * 7.3.1.1 "upper". + * @retval c The byte is not listed in IEEE 1003.1 section 7.3.1.1 + * "upper". * @retval otherwise Byte converted using the map defined in IEEE 1003.1 * section 7.3.1 "tolower". * @note Not only does this function works under the POSIX Locale, but diff --git a/include/ruby/internal/dllexport.h b/include/ruby/internal/dllexport.h index 08a262209d..71026e7100 100644 --- a/include/ruby/internal/dllexport.h +++ b/include/ruby/internal/dllexport.h @@ -37,9 +37,7 @@ * ``` */ #undef RUBY_EXTERN -#if defined(MJIT_HEADER) && defined(_WIN32) -# define RUBY_EXTERN extern __declspec(dllimport) -#elif defined(RUBY_EXPORT) +#if defined(RUBY_EXPORT) # define RUBY_EXTERN extern #elif defined(_WIN32) # define RUBY_EXTERN extern __declspec(dllimport) @@ -59,36 +57,6 @@ # define RUBY_FUNC_EXPORTED /* void */ #endif -/** - * @cond INTERNAL_MACRO - * - * These MJIT related macros are placed here because translate_mjit_header can - * need them. Extension libraries should not touch. - */ - -/* These macros are used for functions which are exported only for MJIT - and NOT ensured to be exported in future versions. */ - -#if ! defined(MJIT_HEADER) -# define MJIT_FUNC_EXPORTED RUBY_FUNC_EXPORTED -#elif ! RBIMPL_COMPILER_IS(MSVC) -# define MJIT_FUNC_EXPORTED RUBY_FUNC_EXPORTED -#else -# define MJIT_FUNC_EXPORTED static -#endif - -#define MJIT_SYMBOL_EXPORT_BEGIN RUBY_SYMBOL_EXPORT_BEGIN -#define MJIT_SYMBOL_EXPORT_END RUBY_SYMBOL_EXPORT_END - -/* On mswin, MJIT header transformation can't be used since cl.exe can't output - preprocessed output preserving macros. So this `MJIT_STATIC` is needed - to force non-static function to static on MJIT header to avoid symbol conflict. */ -#ifdef MJIT_HEADER -# define MJIT_STATIC static -#else -# define MJIT_STATIC -#endif - /** @endcond */ /** Shortcut macro equivalent to `RUBY_SYMBOL_EXPORT_BEGIN extern "C" {`. diff --git a/include/ruby/internal/encoding/coderange.h b/include/ruby/internal/encoding/coderange.h new file mode 100644 index 0000000000..c89f871518 --- /dev/null +++ b/include/ruby/internal/encoding/coderange.h @@ -0,0 +1,202 @@ +#ifndef RUBY_INTERNAL_ENCODING_CODERANGE_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_CODERANGE_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 Routines for code ranges. + */ + +#include "ruby/internal/attr/const.h" +#include "ruby/internal/attr/pure.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/fl_type.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** What rb_enc_str_coderange() returns. */ +enum ruby_coderange_type { + + /** The object's coderange is unclear yet. */ + RUBY_ENC_CODERANGE_UNKNOWN = 0, + + /** The object holds 0 to 127 inclusive and nothing else. */ + RUBY_ENC_CODERANGE_7BIT = ((int)RUBY_FL_USER8), + + /** The object's encoding and contents are consistent each other */ + RUBY_ENC_CODERANGE_VALID = ((int)RUBY_FL_USER9), + + /** The object holds invalid/malformed/broken character(s). */ + RUBY_ENC_CODERANGE_BROKEN = ((int)(RUBY_FL_USER8|RUBY_FL_USER9)), + + /** Where the coderange resides. */ + RUBY_ENC_CODERANGE_MASK = (RUBY_ENC_CODERANGE_7BIT| + RUBY_ENC_CODERANGE_VALID| + RUBY_ENC_CODERANGE_BROKEN) +}; + +RBIMPL_ATTR_CONST() +/** + * @private + * + * This is an implementation detail of #RB_ENC_CODERANGE_CLEAN_P. People don't + * use it directly. + * + * @param[in] cr An enum ::ruby_coderange_type. + * @retval 1 It is. + * @retval 0 It isn't. + */ +static inline int +rb_enc_coderange_clean_p(int cr) +{ + return (cr ^ (cr >> 1)) & RUBY_ENC_CODERANGE_7BIT; +} + +RBIMPL_ATTR_CONST() +/** + * Queries if a code range is "clean". "Clean" in this context means it is + * known and valid. + * + * @param[in] cr An enum ::ruby_coderange_type. + * @retval 1 It is. + * @retval 0 It isn't. + */ +static inline bool +RB_ENC_CODERANGE_CLEAN_P(enum ruby_coderange_type cr) +{ + return rb_enc_coderange_clean_p(RBIMPL_CAST((int)cr)); +} + +RBIMPL_ATTR_PURE_UNLESS_DEBUG() +/** + * Queries the (inline) code range of the passed object. The object must be + * capable of having inline encoding. Using this macro needs deep + * understanding of bit level object binary layout. + * + * @param[in] obj Target object. + * @return An enum ::ruby_coderange_type. + */ +static inline enum ruby_coderange_type +RB_ENC_CODERANGE(VALUE obj) +{ + VALUE ret = RB_FL_TEST_RAW(obj, RUBY_ENC_CODERANGE_MASK); + + return RBIMPL_CAST((enum ruby_coderange_type)ret); +} + +RBIMPL_ATTR_PURE_UNLESS_DEBUG() +/** + * Queries the (inline) code range of the passed object is + * ::RUBY_ENC_CODERANGE_7BIT. The object must be capable of having inline + * encoding. Using this macro needs deep understanding of bit level object + * binary layout. + * + * @param[in] obj Target object. + * @retval 1 It is ascii only. + * @retval 0 Otherwise (including cases when the range is not known). + */ +static inline bool +RB_ENC_CODERANGE_ASCIIONLY(VALUE obj) +{ + return RB_ENC_CODERANGE(obj) == RUBY_ENC_CODERANGE_7BIT; +} + +/** + * Destructively modifies the passed object so that its (inline) code range is + * the passed one. The object must be capable of having inline encoding. + * Using this macro needs deep understanding of bit level object binary layout. + * + * @param[out] obj Target object. + * @param[out] cr An enum ::ruby_coderange_type. + * @post `obj`'s code range is `cr`. + */ +static inline void +RB_ENC_CODERANGE_SET(VALUE obj, enum ruby_coderange_type cr) +{ + RB_FL_UNSET_RAW(obj, RUBY_ENC_CODERANGE_MASK); + RB_FL_SET_RAW(obj, cr); +} + +/** + * Destructively clears the passed object's (inline) code range. The object + * must be capable of having inline encoding. Using this macro needs deep + * understanding of bit level object binary layout. + * + * @param[out] obj Target object. + * @post `obj`'s code range is ::RUBY_ENC_CODERANGE_UNKNOWN. + */ +static inline void +RB_ENC_CODERANGE_CLEAR(VALUE obj) +{ + RB_FL_UNSET_RAW(obj, RUBY_ENC_CODERANGE_MASK); +} + +RBIMPL_ATTR_CONST() +/* assumed ASCII compatibility */ +/** + * "Mix" two code ranges into one. This is handy for instance when you + * concatenate two strings into one. Consider one of then is valid but the + * other isn't. The result must be invalid. This macro computes that kind of + * mixture. + * + * @param[in] a An enum ::ruby_coderange_type. + * @param[in] b Another enum ::ruby_coderange_type. + * @return The `a` "and" `b`. + */ +static inline enum ruby_coderange_type +RB_ENC_CODERANGE_AND(enum ruby_coderange_type a, enum ruby_coderange_type b) +{ + if (a == RUBY_ENC_CODERANGE_7BIT) { + return b; + } + else if (a != RUBY_ENC_CODERANGE_VALID) { + return RUBY_ENC_CODERANGE_UNKNOWN; + } + else if (b == RUBY_ENC_CODERANGE_7BIT) { + return RUBY_ENC_CODERANGE_VALID; + } + else { + return b; + } +} + +#define ENC_CODERANGE_MASK RUBY_ENC_CODERANGE_MASK /**< @old{RUBY_ENC_CODERANGE_MASK} */ +#define ENC_CODERANGE_UNKNOWN RUBY_ENC_CODERANGE_UNKNOWN /**< @old{RUBY_ENC_CODERANGE_UNKNOWN} */ +#define ENC_CODERANGE_7BIT RUBY_ENC_CODERANGE_7BIT /**< @old{RUBY_ENC_CODERANGE_7BIT} */ +#define ENC_CODERANGE_VALID RUBY_ENC_CODERANGE_VALID /**< @old{RUBY_ENC_CODERANGE_VALID} */ +#define ENC_CODERANGE_BROKEN RUBY_ENC_CODERANGE_BROKEN /**< @old{RUBY_ENC_CODERANGE_BROKEN} */ +#define ENC_CODERANGE_CLEAN_P(cr) RB_ENC_CODERANGE_CLEAN_P(cr) /**< @old{RB_ENC_CODERANGE_CLEAN_P} */ +#define ENC_CODERANGE(obj) RB_ENC_CODERANGE(obj) /**< @old{RB_ENC_CODERANGE} */ +#define ENC_CODERANGE_ASCIIONLY(obj) RB_ENC_CODERANGE_ASCIIONLY(obj) /**< @old{RB_ENC_CODERANGE_ASCIIONLY} */ +#define ENC_CODERANGE_SET(obj,cr) RB_ENC_CODERANGE_SET(obj,cr) /**< @old{RB_ENC_CODERANGE_SET} */ +#define ENC_CODERANGE_CLEAR(obj) RB_ENC_CODERANGE_CLEAR(obj) /**< @old{RB_ENC_CODERANGE_CLEAR} */ +#define ENC_CODERANGE_AND(a, b) RB_ENC_CODERANGE_AND(a, b) /**< @old{RB_ENC_CODERANGE_AND} */ +#define ENCODING_CODERANGE_SET(obj, encindex, cr) RB_ENCODING_CODERANGE_SET(obj, encindex, cr) /**< @old{RB_ENCODING_CODERANGE_SET} */ + +/** @cond INTERNAL_MACRO */ +#define RB_ENC_CODERANGE RB_ENC_CODERANGE +#define RB_ENC_CODERANGE_AND RB_ENC_CODERANGE_AND +#define RB_ENC_CODERANGE_ASCIIONLY RB_ENC_CODERANGE_ASCIIONLY +#define RB_ENC_CODERANGE_CLEAN_P RB_ENC_CODERANGE_CLEAN_P +#define RB_ENC_CODERANGE_CLEAR RB_ENC_CODERANGE_CLEAR +#define RB_ENC_CODERANGE_SET RB_ENC_CODERANGE_SET +/** @endcond */ + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_INTERNAL_ENCODING_CODERANGE_H */ diff --git a/include/ruby/internal/encoding/ctype.h b/include/ruby/internal/encoding/ctype.h new file mode 100644 index 0000000000..05c314aeb3 --- /dev/null +++ b/include/ruby/internal/encoding/ctype.h @@ -0,0 +1,258 @@ +#ifndef RUBY_INTERNAL_ENCODING_CTYPE_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_CTYPE_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 Routines to query chacater types. + */ + +#include "ruby/onigmo.h" +#include "ruby/internal/attr/const.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/encoding/encoding.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * Queries if the passed pointer points to a newline character. What is a + * newline and what is not depends on the passed encoding. + * + * @param[in] p Pointer to a possibly-middle of a character. + * @param[in] end End of the string. + * @param[in] enc Encoding. + * @retval false It isn't. + * @retval true It is. + */ +static inline bool +rb_enc_is_newline(const char *p, const char *e, rb_encoding *enc) +{ + OnigUChar *up = RBIMPL_CAST((OnigUChar *)p); + OnigUChar *ue = RBIMPL_CAST((OnigUChar *)e); + + return ONIGENC_IS_MBC_NEWLINE(enc, up, ue); +} + +/** + * Queries if the passed code point is of passed character type in the passed + * encoding. The "character type" here is a set of macros defined in onigmo.h, + * like `ONIGENC_CTYPE_PUNCT`. + * + * @param[in] c An `OnigCodePoint` value. + * @param[in] t An `OnigCtype` value. + * @param[in] enc A `rb_encoding*` value. + * @retval true `c` is of `t` in `enc`. + * @retval false Otherwise. + */ +static inline bool +rb_enc_isctype(OnigCodePoint c, OnigCtype t, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_CTYPE(enc, c, t); +} + +/** + * Identical to rb_isascii(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval false `c` is out of range of ASCII character set in `enc`. + * @retval true Otherwise. + * + * @internal + * + * `enc` is ignored. This is at least an intentional implementation detail + * (not a bug). But there could be rooms for future extensions. + */ +static inline bool +rb_enc_isascii(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_ASCII(c); +} + +/** + * Identical to rb_isalpha(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "ALPHA". + * @retval false Otherwise. + */ +static inline bool +rb_enc_isalpha(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_ALPHA(enc, c); +} + +/** + * Identical to rb_islower(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "LOWER". + * @retval false Otherwise. + */ +static inline bool +rb_enc_islower(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_LOWER(enc, c); +} + +/** + * Identical to rb_isupper(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "UPPER". + * @retval false Otherwise. + */ +static inline bool +rb_enc_isupper(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_UPPER(enc, c); +} + +/** + * Identical to rb_iscntrl(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "CNTRL". + * @retval false Otherwise. + */ +static inline bool +rb_enc_iscntrl(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_CNTRL(enc, c); +} + +/** + * Identical to rb_ispunct(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "PUNCT". + * @retval false Otherwise. + */ +static inline bool +rb_enc_ispunct(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_PUNCT(enc, c); +} + +/** + * Identical to rb_isalnum(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "ANUM". + * @retval false Otherwise. + */ +static inline bool +rb_enc_isalnum(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_ALNUM(enc, c); +} + +/** + * Identical to rb_isprint(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "PRINT". + * @retval false Otherwise. + */ +static inline bool +rb_enc_isprint(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_PRINT(enc, c); +} + +/** + * Identical to rb_isspace(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "PRINT". + * @retval false Otherwise. + */ +static inline bool +rb_enc_isspace(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_SPACE(enc, c); +} + +/** + * Identical to rb_isdigit(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @retval true `enc` classifies `c` as "DIGIT". + * @retval false Otherwise. + */ +static inline bool +rb_enc_isdigit(OnigCodePoint c, rb_encoding *enc) +{ + return ONIGENC_IS_CODE_DIGIT(enc, c); +} + +RBIMPL_ATTR_CONST() +/** + * Identical to rb_toupper(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @return `c`'s (Ruby's definition of) upper case counterpart. + * + * @internal + * + * As `RBIMPL_ATTR_CONST` implies this function ignores `enc`. + */ +int rb_enc_toupper(int c, rb_encoding *enc); + +RBIMPL_ATTR_CONST() +/** + * Identical to rb_tolower(), except it additionally takes an encoding. + * + * @param[in] c A code point. + * @param[in] enc An encoding. + * @return `c`'s (Ruby's definition of) lower case counterpart. + * + * @internal + * + * As `RBIMPL_ATTR_CONST` implies this function ignores `enc`. + */ +int rb_enc_tolower(int c, rb_encoding *enc); + +RBIMPL_SYMBOL_EXPORT_END() + +/** @cond INTERNAL_MACRO */ +#define rb_enc_is_newline rb_enc_is_newline +#define rb_enc_isalnum rb_enc_isalnum +#define rb_enc_isalpha rb_enc_isalpha +#define rb_enc_isascii rb_enc_isascii +#define rb_enc_isctype rb_enc_isctype +#define rb_enc_isdigit rb_enc_isdigit +#define rb_enc_islower rb_enc_islower +#define rb_enc_isprint rb_enc_isprint +#define rb_enc_iscntrl rb_enc_iscntrl +#define rb_enc_ispunct rb_enc_ispunct +#define rb_enc_isspace rb_enc_isspace +#define rb_enc_isupper rb_enc_isupper +/** @endcond */ + +#endif /* RUBY_INTERNAL_ENCODING_CTYPE_H */ diff --git a/include/ruby/internal/encoding/encoding.h b/include/ruby/internal/encoding/encoding.h new file mode 100644 index 0000000000..a58f9f2b15 --- /dev/null +++ b/include/ruby/internal/encoding/encoding.h @@ -0,0 +1,1044 @@ +#ifndef RUBY_INTERNAL_ENCODING_ENCODING_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_ENCODING_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 Defines ::rb_encoding + */ + +#include "ruby/oniguruma.h" +#include "ruby/internal/attr/const.h" +#include "ruby/internal/attr/deprecated.h" +#include "ruby/internal/attr/noalias.h" +#include "ruby/internal/attr/pure.h" +#include "ruby/internal/attr/returns_nonnull.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/encoding/coderange.h" +#include "ruby/internal/value.h" +#include "ruby/internal/core/rbasic.h" +#include "ruby/internal/fl_type.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * `Encoding` class. + * + * @ingroup object + */ +RUBY_EXTERN VALUE rb_cEncoding; + +/** + * @private + * + * Bit constants used when embedding encodings into ::RBasic::flags. Extension + * libraries must not bother such things. + */ +enum ruby_encoding_consts { + + /** Max possible number of embeddable encodings. */ + RUBY_ENCODING_INLINE_MAX = 127, + + /** Where inline encodings reside. */ + RUBY_ENCODING_SHIFT = (RUBY_FL_USHIFT+10), + + /** Bits we use to store inline encodings. */ + RUBY_ENCODING_MASK = (RUBY_ENCODING_INLINE_MAX<<RUBY_ENCODING_SHIFT + /* RUBY_FL_USER10..RUBY_FL_USER16 */), + + /** Max possible length of an encoding name. */ + RUBY_ENCODING_MAXNAMELEN = 42 +}; + +#define ENCODING_INLINE_MAX RUBY_ENCODING_INLINE_MAX /**< @old{RUBY_ENCODING_INLINE_MAX} */ +#define ENCODING_SHIFT RUBY_ENCODING_SHIFT /**< @old{RUBY_ENCODING_SHIFT} */ +#define ENCODING_MASK RUBY_ENCODING_MASK /**< @old{RUBY_ENCODING_MASK} */ + +/** + * Destructively assigns the passed encoding to the passed object. The object + * must be capable of having inline encoding. Using this macro needs deep + * understanding of bit level object binary layout. + * + * @param[out] obj Target object to modify. + * @param[in] ecindex Encoding in encindex format. + * @post `obj`'s encoding is `encindex`. + */ +static inline void +RB_ENCODING_SET_INLINED(VALUE obj, int encindex) +{ + VALUE f = /* upcast */ RBIMPL_CAST((VALUE)encindex); + + f <<= RUBY_ENCODING_SHIFT; + RB_FL_UNSET_RAW(obj, RUBY_ENCODING_MASK); + RB_FL_SET_RAW(obj, f); +} + +/** + * Queries the encoding of the passed object. The encoding must be smaller + * than ::RUBY_ENCODING_INLINE_MAX, which means you have some assumption on the + * return value. This means the API is for internal use only. + * + * @param[in] obj Target object. + * @return `obj`'s encoding index. + */ +static inline int +RB_ENCODING_GET_INLINED(VALUE obj) +{ + VALUE ret = RB_FL_TEST_RAW(obj, RUBY_ENCODING_MASK) >> RUBY_ENCODING_SHIFT; + + return RBIMPL_CAST((int)ret); +} + +#define ENCODING_SET_INLINED(obj,i) RB_ENCODING_SET_INLINED(obj,i) /**< @old{RB_ENCODING_SET_INLINED} */ +#define ENCODING_SET(obj,i) RB_ENCODING_SET(obj,i) /**< @old{RB_ENCODING_SET} */ +#define ENCODING_GET_INLINED(obj) RB_ENCODING_GET_INLINED(obj) /**< @old{RB_ENCODING_GET_INLINED} */ +#define ENCODING_GET(obj) RB_ENCODING_GET(obj) /**< @old{RB_ENCODING_GET} */ +#define ENCODING_IS_ASCII8BIT(obj) RB_ENCODING_IS_ASCII8BIT(obj) /**< @old{RB_ENCODING_IS_ASCII8BIT} */ +#define ENCODING_MAXNAMELEN RUBY_ENCODING_MAXNAMELEN /**< @old{RUBY_ENCODING_MAXNAMELEN} */ + +/** + * The type of encoding. Our design here is we take Oniguruma/Onigmo's + * multilingualisation schema as our base data structure. + */ +typedef const OnigEncodingType rb_encoding; + +RBIMPL_ATTR_NOALIAS() +/** + * Converts a character option to its encoding. It only supports a very + * limited set of Japanese encodings due to its Japanese origin. Ruby still + * has this in-core for backwards compatibility. But new codes must not bother + * such concept like one-character encoding option. Consider deprecated in + * practice. + * + * @param[in] c One of `['n', 'e', 's', 'u', 'i', 'x', 'm']`. + * @param[out] option Return buffer. + * @param[out] kcode Return buffer. + * @retval 1 `c` understood properly. + * @retval 0 `c` is not understood. + * @post `option` is a ::OnigOptionType. + * @post `kcode` is an enum `ruby_preserved_encindex`. + * + * @internal + * + * `kcode` is opaque because `ruby_preserved_encindex` is not visible from + * extension libraries. But who cares? + */ +int rb_char_to_option_kcode(int c, int *option, int *kcode); + +/** + * Creates a new "dummy" encoding. Roughly speaking, an encoding is dummy when + * it is stateful. Notable example of dummy encoding are those defined in + * ISO/IEC 2022 + * + * @param[in] name Name of the creating encoding. + * @exception rb_eArgError Duplicated or malformed `name`. + * @return New dummy encoding's index. + * @post Encoding named `name` is created, whose index is the return + * value. + */ +int rb_define_dummy_encoding(const char *name); + +RBIMPL_ATTR_PURE() +/** + * Queries if the passed encoding is dummy. + * + * @param[in] enc Encoding in question. + * @retval 1 It is. + * @retval 0 It isn't. + */ +int rb_enc_dummy_p(rb_encoding *enc); + +RBIMPL_ATTR_PURE() +/** + * Queries the index of the encoding. An encoding's index is a Ruby-local + * concept. It is a (sequential) number assigned to each encoding. + * + * @param[in] enc Encoding in question. + * @return Its index. + * @note You can pass null pointers to this function. It is equivalent + * to rb_usascii_encindex() then. + */ +int rb_enc_to_index(rb_encoding *enc); + +/** + * Queries the index of the encoding of the passed object, if any. + * + * @param[in] obj Object in question. + * @retval -1 `obj` is incapable of having an encoding. + * @retval otherwise `obj`'s encoding's index. + */ +int rb_enc_get_index(VALUE obj); + +/** + * @alias{rb_enc_get_index} + * + * @internal + * + * Implementation wise this is not a verbatim alias of rb_enc_get_index(). But + * the API is consistent. Don't bother. + */ +static inline int +RB_ENCODING_GET(VALUE obj) +{ + int encindex = RB_ENCODING_GET_INLINED(obj); + + if (encindex == RUBY_ENCODING_INLINE_MAX) { + return rb_enc_get_index(obj); + } + else { + return encindex; + } +} + +/** + * Destructively assigns an encoding (via its index) to an object. + * + * @param[out] obj Object in question. + * @param[in] encindex An encoding index. + * @exception rb_eFrozenError `obj` is frozen. + * @exception rb_eArgError `obj` is incapable of having an encoding. + * @exception rb_eEncodingError `encindex` is out of bounds. + * @exception rb_eLoadError Failed to load the encoding. + */ +void rb_enc_set_index(VALUE obj, int encindex); + +/** @alias{rb_enc_set_index} */ +static inline void +RB_ENCODING_SET(VALUE obj, int encindex) +{ + rb_enc_set_index(obj, encindex); +} + +/** + * This is #RB_ENCODING_SET + RB_ENC_CODERANGE_SET combo. The object must be + * capable of having inline encoding. Using this macro needs deep + * understanding of bit level object binary layout. + * + * @param[out] obj Target object. + * @param[in] encindex Encoding in encindex format. + * @param[in] cr An enum ::ruby_coderange_type. + * @post `obj`'s encoding is `encindex`. + * @post `obj`'s code range is `cr`. + */ +static inline void +RB_ENCODING_CODERANGE_SET(VALUE obj, int encindex, enum ruby_coderange_type cr) +{ + RB_ENCODING_SET(obj, encindex); + RB_ENC_CODERANGE_SET(obj, cr); +} + +RBIMPL_ATTR_PURE() +/** + * Queries if the passed object can have its encoding. + * + * @param[in] obj Object in question. + * @retval 1 It can. + * @retval 0 It cannot. + */ +int rb_enc_capable(VALUE obj); + +/** + * Queries the index of the encoding. + * + * @param[in] name Name of the encoding to find. + * @exception rb_eArgError No such encoding named `name`. + * @retval -1 `name` exists, but unable to load. + * @retval otherwise Index of encoding named `name`. + */ +int rb_enc_find_index(const char *name); + +/** + * Registers an "alias" name. In the wild, an encoding can be called using + * multiple names. For instance an encoding known as `"CP932"` is also called + * `"SJIS"` on occasions. This API registers such relationships. + * + * @param[in] alias New name. + * @param[in] orig Old name. + * @exception rb_eArgError `alias` is duplicated or malformed. + * @retval -1 Failed to load `orig`. + * @retval otherwise The index of `orig` and `alias`. + * @post `alias` is a synonym of `orig`. They refer to the identical + * encoding. + */ +int rb_enc_alias(const char *alias, const char *orig); + +/** + * Obtains a encoding index from a wider range of objects (than + * rb_enc_find_index()). + * + * @param[in] obj An ::rb_cEncoding, or its name in ::rb_cString. + * @retval -1 `obj` is unexpected type/contents. + * @retval otherwise Index corresponding to `obj`. + */ +int rb_to_encoding_index(VALUE obj); + +/** + * Identical to rb_find_encoding(), except it raises an exception instead of + * returning NULL. + * + * @param[in] obj An ::rb_cEncoding, or its name in ::rb_cString. + * @exception rb_eTypeError `obj` is neither ::rb_cEncoding nor ::rb_cString. + * @exception rb_eArgError `obj` is an unknown encoding name. + * @return Encoding of `obj`. + */ +rb_encoding *rb_to_encoding(VALUE obj); + +/** + * Identical to rb_to_encoding_index(), except the return type. + * + * @param[in] obj An ::rb_cEncoding, or its name in ::rb_cString. + * @exception rb_eTypeError `obj` is neither ::rb_cEncoding nor ::rb_cString. + * @retval NULL No such encoding. + * @return otherwise Encoding of `obj`. + */ +rb_encoding *rb_find_encoding(VALUE obj); + +/** + * Identical to rb_enc_get_index(), except the return type. + * + * @param[in] obj Object in question. + * @retval NULL Obj is incapable of having an encoding. + * @retval otherwise `obj`'s encoding. + */ +rb_encoding *rb_enc_get(VALUE obj); + +/** + * Look for the "common" encoding between the two. One character can or cannot + * be expressed depending on an encoding. This function finds the super-set of + * encodings that satisfy contents of both arguments. If that is impossible + * returns NULL. + * + * @param[in] str1 An object. + * @param[in] str2 Another object. + * @retval NULL No encoding can satisfy both at once. + * @retval otherwise Common encoding between the two. + * @note Arguments can be non-string, e.g. Regexp. + */ +rb_encoding *rb_enc_compatible(VALUE str1, VALUE str2); + +/** + * Identical to rb_enc_compatible(), except it raises an exception instead of + * returning NULL. + * + * @param[in] str1 An object. + * @param[in] str2 Another object. + * @exception rb_eEncCompatError No encoding can satisfy both. + * @return Common encoding between the two. + * @note Arguments can be non-string, e.g. Regexp. + */ +rb_encoding *rb_enc_check(VALUE str1,VALUE str2); + +/** + * Identical to rb_enc_set_index(), except it additionally does contents fix-up + * depending on the passed object. It for instance changes the byte length of + * terminating `U+0000` according to the passed encoding. + * + * @param[out] obj Object in question. + * @param[in] encindex An encoding index. + * @exception rb_eFrozenError `obj` is frozen. + * @exception rb_eArgError `obj` is incapable of having an encoding. + * @exception rb_eEncodingError `encindex` is out of bounds. + * @exception rb_eLoadError Failed to load the encoding. + * @return The passed `obj`. + * @post `obj`'s contents might be fixed according to `encindex`. + */ +VALUE rb_enc_associate_index(VALUE obj, int encindex); + +/** + * Identical to rb_enc_associate_index(), except it takes an encoding itself + * instead of its index. + * + * @param[out] obj Object in question. + * @param[in] enc An encoding. + * @exception rb_eFrozenError `obj` is frozen. + * @exception rb_eArgError `obj` is incapable of having an encoding. + * @return The passed `obj`. + * @post `obj`'s contents might be fixed according to `enc`. + */ +VALUE rb_enc_associate(VALUE obj, rb_encoding *enc); + +/** + * Destructively copies the encoding of the latter object to that of former + * one. It can also be seen as a routine identical to + * rb_enc_associate_index(), except it takes an object's encoding instead of an + * encoding's index. + * + * @param[out] dst Object to modify. + * @param[in] src Object to reference. + * @exception rb_eFrozenError `dst` is frozen. + * @exception rb_eArgError `dst` is incapable of having an encoding. + * @exception rb_eEncodingError `src` is incapable of having an encoding. + * @post `dst`'s encoding is that of `src`'s. + */ +void rb_enc_copy(VALUE dst, VALUE src); + + +/** + * Identical to rb_find_encoding(), except it takes an encoding index instead + * of a Ruby object. + * + * @param[in] idx An encoding index. + * @retval NULL No such encoding. + * @retval otherwise An encoding whose index is `idx`. + */ +rb_encoding *rb_enc_from_index(int idx); + +/** + * Identical to rb_find_encoding(), except it takes a C's string instead of + * Ruby's. + * + * @param[in] name Name of the encoding to query. + * @retval NULL No such encoding. + * @retval otherwise An encoding whose index is `idx`. + */ +rb_encoding *rb_enc_find(const char *name); + +/** + * Queries the (canonical) name of the passed encoding. + * + * @param[in] enc An encoding. + * @return Its name. + */ +static inline const char * +rb_enc_name(rb_encoding *enc) +{ + return enc->name; +} + +/** + * Queries the minimum number of bytes that the passed encoding needs to + * represent a character. For ASCII and compatible encodings this is typically + * 1. There are however encodings whose minimum is not 1; they are + * historically called wide characters. + * + * @param[in] enc An encoding. + * @return Its least possible number of bytes except 0. + */ +static inline int +rb_enc_mbminlen(rb_encoding *enc) +{ + return enc->min_enc_len; +} + +/** + * Queries the maximum number of bytes that the passed encoding needs to + * represent a character. Fixed-width encodings have the same value for this + * one and #rb_enc_mbminlen. However there are variable-width encodings. + * UTF-8, for instance, takes from 1 up to 6 bytes. + * + * @param[in] enc An encoding. + * @return Its maximum possible number of bytes of a character. + */ +static inline int +rb_enc_mbmaxlen(rb_encoding *enc) +{ + return enc->max_enc_len; +} + +/** + * Queries the number of bytes of the character at the passed pointer. + * + * @param[in] p Pointer to a character's first byte. + * @param[in] e End of the string that has `p`. + * @param[in] enc Encoding of the string. + * @return If the character at `p` does not end until `e`, number of bytes + * between `p` and `e`. Otherwise the number of bytes that the + * character at `p` is encoded. + * + * @internal + * + * Strictly speaking there are chances when `p` points to a middle byte of a + * wide character. This function returns "the number of bytes from `p` to + * nearest of either `e` or the next character boundary", if you go strict. + */ +int rb_enc_mbclen(const char *p, const char *e, rb_encoding *enc); + +/** + * Identical to rb_enc_mbclen() unless the character at `p` overruns `e`. That + * can happen for instance when you read from a socket and its partial read + * cuts a wide character in-between. In those situations this function + * "estimates" theoretical length of the character in question. Typically it + * tends to be possible to know how many bytes a character needs before + * actually reaching its end; for instance UTF-8 encodes a character's length + * in the first byte of it. This function returns that info. + * + * @note This implies that the string is not broken. + * + * @param[in] p Pointer to the character's first byte. + * @param[in] e End of the string that has `p`. + * @param[in] enc Encoding of the string. + * @return Number of bytes of character at `p`, measured or estimated. + */ +int rb_enc_fast_mbclen(const char *p, const char *e, rb_encoding *enc); + +/** + * Queries the number of bytes of the character at the passed pointer. This + * function returns 3 different types of information: + * + * ```CXX + * auto n = rb_enc_precise_mbclen(p, q, r); + * + * if (ONIGENC_MBCLEN_CHARFOUND_P(n)) { + * // Character found. Normal return. + * auto found_length = ONIGENC_MBCLEN_CHARFOUND_LEN(n); + * } + * else if (ONIGENC_MBCLEN_NEEDMORE_P(n)) { + * // Character overruns past `q`; needs more. + * auto requested_length = ONIGENC_MBCLEN_NEEDMORE_LEN(n); + * } + * else { + * // `p` is broken. + * assert(ONIGENC_MBCLEN_INVALID_P(n)); + * } + * ``` + * + * @param[in] p Pointer to the character's first byte. + * @param[in] e End of the string that has `p`. + * @param[in] enc Encoding of the string. + * @return Encoded read/needed number of bytes (see above). + */ +int rb_enc_precise_mbclen(const char *p, const char *e, rb_encoding *enc); + +#define MBCLEN_CHARFOUND_P(ret) ONIGENC_MBCLEN_CHARFOUND_P(ret) /**< @old{ONIGENC_MBCLEN_CHARFOUND_P} */ +#define MBCLEN_CHARFOUND_LEN(ret) ONIGENC_MBCLEN_CHARFOUND_LEN(ret) /**< @old{ONIGENC_MBCLEN_CHARFOUND_LEN} */ +#define MBCLEN_INVALID_P(ret) ONIGENC_MBCLEN_INVALID_P(ret) /**< @old{ONIGENC_MBCLEN_INVALID_P} */ +#define MBCLEN_NEEDMORE_P(ret) ONIGENC_MBCLEN_NEEDMORE_P(ret) /**< @old{ONIGENC_MBCLEN_NEEDMORE_P} */ +#define MBCLEN_NEEDMORE_LEN(ret) ONIGENC_MBCLEN_NEEDMORE_LEN(ret) /**< @old{ONIGENC_MBCLEN_NEEDMORE_LEN} */ + +/** + * Queries the code point of character pointed by the passed pointer. If that + * code point is included in ASCII that code point is returned. Otherwise -1. + * This can be different from just looking at the first byte. For instance it + * reads 2 bytes in case of UTF-16BE. + * + * @param[in] p Pointer to the character's first byte. + * @param[in] e End of the string that has `p`. + * @param[in] len Return buffer. + * @param[in] enc Encoding of the string. + * @retval -1 The character at `p` is not i ASCII. + * @retval otherwise A code point of the character at `p`. + * @post `len` (if set) is the number of bytes of `p`. + */ +int rb_enc_ascget(const char *p, const char *e, int *len, rb_encoding *enc); + +/** + * Queries the code point of character pointed by the passed pointer. + * Exceptions happen in case of broken input. + * + * @param[in] p Pointer to the character's first byte. + * @param[in] e End of the string that has `p`. + * @param[in] len Return buffer. + * @param[in] enc Encoding of the string. + * @exception rb_eArgError `p` is broken. + * @return Code point of the character pointed by `p`. + * @post `len` (if set) is the number of bytes of `p`. + */ +unsigned int rb_enc_codepoint_len(const char *p, const char *e, int *len, rb_encoding *enc); + +/** + * Queries the code point of character pointed by the passed pointer. + * Exceptions happen in case of broken input. + * + * @deprecated Use rb_enc_codepoint_len() instead. + * @param[in] p Pointer to the character's first byte. + * @param[in] e End of the string that has `p`. + * @param[in] enc Encoding of the string. + * @exception rb_eArgError `p` is broken. + * @return Code point of the character pointed by `p`. + * + * @internal + * + * @matz says in commit 91e5ba1cb865a2385d3e1cbfacd824496898e098 that the line + * below is a "prototype for obsolete function". However even today there + * still are some use cases of it throughout our repository. It seems it has + * its own niche. + */ +static inline unsigned int +rb_enc_codepoint(const char *p, const char *e, rb_encoding *enc) +{ + return rb_enc_codepoint_len(p, e, 0, enc); + /* ^^^ + * This can be `NULL` in C, `nullptr` in C++, and `0` for both. + * We choose the most portable one here. + */ +} + + +/** + * Identical to rb_enc_codepoint(), except it assumes the passed character is + * not broken. + * + * @param[in] p Pointer to the character's first byte. + * @param[in] e End of the string that has `p`. + * @param[in] enc Encoding of the string. + * @return Code point of the character pointed by `p`. + */ +static inline OnigCodePoint +rb_enc_mbc_to_codepoint(const char *p, const char *e, rb_encoding *enc) +{ + const OnigUChar *up = RBIMPL_CAST((const OnigUChar *)p); + const OnigUChar *ue = RBIMPL_CAST((const OnigUChar *)e); + + return ONIGENC_MBC_TO_CODE(enc, up, ue); +} + +/** + * Queries the number of bytes requested to represent the passed code point + * using the passed encoding. + * + * @param[in] code Code point in question. + * @param[in] enc Encoding to convert the code into a byte sequence. + * @exception rb_eArgError `enc` does not glean `code`. + * @return Number of bytes requested to represent `code` using `enc`. + */ +int rb_enc_codelen(int code, rb_encoding *enc); + +/** + * Identical to rb_enc_codelen(), except it returns 0 for invalid code points. + * + * @param[in] c Code point in question. + * @param[in] enc Encoding to convert `c` into a byte sequence. + * @retval 0 `c` is invalid. + * @return otherwise Number of bytes needed for `enc` to encode `c`. + */ +static inline int +rb_enc_code_to_mbclen(int c, rb_encoding *enc) +{ + OnigCodePoint uc = RBIMPL_CAST((OnigCodePoint)c); + + return ONIGENC_CODE_TO_MBCLEN(enc, uc); +} + +/** + * Identical to rb_enc_uint_chr(), except it writes back to the passed buffer + * instead of allocating one. + * + * @param[in] c Code point. + * @param[out] buf Return buffer. + * @param[in] enc Target encoding scheme. + * @retval <= 0 `c` is invalid in `enc`. + * @return otherwise Number of bytes written to `buf`. + * @post `c` is encoded according to `enc`, then written to `buf`. + * + * @internal + * + * The second argument must be typed. But its current usages prevent us from + * being any stricter than this. :FIXME: + */ +static inline int +rb_enc_mbcput(unsigned int c, void *buf, rb_encoding *enc) +{ + OnigCodePoint uc = RBIMPL_CAST((OnigCodePoint)c); + OnigUChar *ubuf = RBIMPL_CAST((OnigUChar *)buf); + + return ONIGENC_CODE_TO_MBC(enc, uc, ubuf); +} + +/** + * Queries the previous (left) character. + * + * @param[in] s Start of the string. + * @param[in] p Pointer to a character. + * @param[in] e End of the string. + * @param[in] enc Encoding. + * @retval NULL No previous character. + * @retval otherwise Pointer to the head of the previous character. + */ +static inline char * +rb_enc_prev_char(const char *s, const char *p, const char *e, rb_encoding *enc) +{ + const OnigUChar *us = RBIMPL_CAST((const OnigUChar *)s); + const OnigUChar *up = RBIMPL_CAST((const OnigUChar *)p); + const OnigUChar *ue = RBIMPL_CAST((const OnigUChar *)e); + OnigUChar *ur = onigenc_get_prev_char_head(enc, us, up, ue); + + return RBIMPL_CAST((char *)ur); +} + +/** + * Queries the left boundary of a character. This function takes a pointer + * that is not necessarily a head of a character, and searches for its head. + * + * @param[in] s Start of the string. + * @param[in] p Pointer to a possibly-middle of a character. + * @param[in] e End of the string. + * @param[in] enc Encoding. + * @return Pointer to the head of the character that contains `p`. + */ +static inline char * +rb_enc_left_char_head(const char *s, const char *p, const char *e, rb_encoding *enc) +{ + const OnigUChar *us = RBIMPL_CAST((const OnigUChar *)s); + const OnigUChar *up = RBIMPL_CAST((const OnigUChar *)p); + const OnigUChar *ue = RBIMPL_CAST((const OnigUChar *)e); + OnigUChar *ur = onigenc_get_left_adjust_char_head(enc, us, up, ue); + + return RBIMPL_CAST((char *)ur); +} + +/** + * Queries the right boundary of a character. This function takes a pointer + * that is not necessarily a head of a character, and searches for its tail. + * + * @param[in] s Start of the string. + * @param[in] p Pointer to a possibly-middle of a character. + * @param[in] e End of the string. + * @param[in] enc Encoding. + * @return Pointer to the end of the character that contains `p`. + */ +static inline char * +rb_enc_right_char_head(const char *s, const char *p, const char *e, rb_encoding *enc) +{ + const OnigUChar *us = RBIMPL_CAST((const OnigUChar *)s); + const OnigUChar *up = RBIMPL_CAST((const OnigUChar *)p); + const OnigUChar *ue = RBIMPL_CAST((const OnigUChar *)e); + OnigUChar *ur = onigenc_get_right_adjust_char_head(enc, us, up, ue); + + return RBIMPL_CAST((char *)ur); +} + +/** + * Scans the string backwards for n characters. + * + * @param[in] s Start of the string. + * @param[in] p Pointer to a character. + * @param[in] e End of the string. + * @param[in] n Steps. + * @param[in] enc Encoding. + * @retval NULL There are no `n` characters left. + * @retval otherwise Pointer to `n` character before `p`. + */ +static inline char * +rb_enc_step_back(const char *s, const char *p, const char *e, int n, rb_encoding *enc) +{ + const OnigUChar *us = RBIMPL_CAST((const OnigUChar *)s); + const OnigUChar *up = RBIMPL_CAST((const OnigUChar *)p); + const OnigUChar *ue = RBIMPL_CAST((const OnigUChar *)e); + const OnigUChar *ur = onigenc_step_back(enc, us, up, ue, n); + + return RBIMPL_CAST((char *)ur); +} + +/** + * @private + * + * This is an implementation detail of rb_enc_asciicompat(). People don't use + * it directly. Just always use rb_enc_asciicompat(). + * + * @param[in] enc Encoding in question. + * @retval 1 It is ASCII compatible. + * @retval 0 It isn't. + */ +static inline int +rb_enc_asciicompat_inline(rb_encoding *enc) +{ + return rb_enc_mbminlen(enc)==1 && !rb_enc_dummy_p(enc); +} + +/** + * Queries if the passed encoding is _in some sense_ compatible with ASCII. + * The concept of ASCII compatibility is nuanced, and private to our + * implementation. For instance SJIS is ASCII compatible to us, despite their + * having different characters at code point `0x5C`. This is based on some + * practical consideration that Japanese people confuses SJIS to be "upper + * compatible" with ASCII (which is in fact a wrong idea, but we just don't go + * strict here). An example of ASCII incompatible encoding is UTF-16. UTF-16 + * shares code points with ASCII, but employs a completely different encoding + * scheme. + * + * @param[in] enc Encoding in question. + * @retval 0 It is incompatible. + * @retval 1 It is compatible. + */ +static inline bool +rb_enc_asciicompat(rb_encoding *enc) +{ + if (rb_enc_mbminlen(enc) != 1) { + return false; + } + else if (rb_enc_dummy_p(enc)) { + return false; + } + else { + return true; + } +} + +/** + * Queries if the passed string is in an ASCII-compatible encoding. + * + * @param[in] str A Ruby's string to query. + * @retval 0 `str` is not a String, or an ASCII-incompatible string. + * @retval 1 Otherwise. + */ +static inline bool +rb_enc_str_asciicompat_p(VALUE str) +{ + rb_encoding *enc = rb_enc_get(str); + + return rb_enc_asciicompat(enc); +} + +/** + * Queries the Ruby-level counterpart instance of ::rb_cEncoding that + * corresponds to the passed encoding. + * + * @param[in] enc An encoding + * @retval RUBY_Qnil `enc` is a null pointer. + * @retval otherwise An instance of ::rb_cEncoding. + */ +VALUE rb_enc_from_encoding(rb_encoding *enc); + +RBIMPL_ATTR_PURE() +/** + * Queries if the passed encoding is either one of UTF-8/16/32. + * + * @note It does not take UTF-7, which we actually support, into account. + * + * @param[in] enc Encoding in question. + * @retval 0 It is not a Unicode variant. + * @retval otherwise It is. + * + * @internal + * + * In reality it returns 1/0, but the value is abstracted as + * `ONIGENC_FLAG_UNICODE`. + */ +int rb_enc_unicode_p(rb_encoding *enc); + +RBIMPL_ATTR_RETURNS_NONNULL() +/** + * Queries the encoding that represents ASCII-8BIT a.k.a. binary. + * + * @return The encoding that represents ASCII-8BIT. + * + * @internal + * + * This can not return NULL once the process properly boots up. + */ +rb_encoding *rb_ascii8bit_encoding(void); + +RBIMPL_ATTR_RETURNS_NONNULL() +/** + * Queries the encoding that represents UTF-8. + * + * @return The encoding that represents UTF-8. + * + * @internal + * + * This can not return NULL once the process properly boots up. + */ +rb_encoding *rb_utf8_encoding(void); + +RBIMPL_ATTR_RETURNS_NONNULL() +/** + * Queries the encoding that represents US-ASCII. + * + * @return The encoding that represents US-ASCII. + * + * @internal + * + * This can not return NULL once the process properly boots up. + */ +rb_encoding *rb_usascii_encoding(void); + +/** + * Queries the encoding that represents the current locale. + * + * @return The encoding that represents the process' locale. + * + * @internal + * + * This is dynamic. If you change the process' locale by e.g. calling + * `setlocale(3)`, that should also change the return value of this function. + * + * There is no official way for Ruby scripts to manipulate locales, though. + */ +rb_encoding *rb_locale_encoding(void); + +/** + * Queries the "filesystem" encoding. This is the encoding that ruby expects + * info from the OS' file system are in. This affects for instance return + * value of rb_dir_getwd(). Most notably on Windows it can be an alias of OS + * codepage. Most notably on Linux users can set this via default external + * encoding. + * + * @return The "filesystem" encoding. + */ +rb_encoding *rb_filesystem_encoding(void); + +/** + * Queries the "default external" encoding. This is used to interact with + * outer-process things such as File. Though not recommended, you can set this + * using rb_enc_set_default_external(). + * + * @return The "default external" encoding. + */ +rb_encoding *rb_default_external_encoding(void); + +/** + * Queries the "default internal" encoding. This could be a null pointer. + * Otherwise, outer-process info are transcoded from default external encoding + * to this one during reading from an IO. + * + * @return The "default internal" encoding (if any). + */ +rb_encoding *rb_default_internal_encoding(void); + +#ifndef rb_ascii8bit_encindex +RBIMPL_ATTR_CONST() +/** + * Identical to rb_ascii8bit_encoding(), except it returns the encoding's index + * instead of the encoding itself. + * + * @return The index of encoding of ASCII-8BIT. + * + * @internal + * + * This happens to be 0. + */ +int rb_ascii8bit_encindex(void); +#endif + +/** + * Queries if the passed object is in ascii 8bit (== binary) encoding. The + * object must be capable of having inline encoding. Using this macro needs + * deep understanding of bit level object binary layout. + * + * @param[in] obj An object to check. + * @retval 1 It is. + * @retval 0 It isn't. + */ +static inline bool +RB_ENCODING_IS_ASCII8BIT(VALUE obj) +{ + return RB_ENCODING_GET_INLINED(obj) == rb_ascii8bit_encindex(); +} + +#ifndef rb_utf8_encindex +RBIMPL_ATTR_CONST() +/** + * Identical to rb_utf8_encoding(), except it returns the encoding's index + * instead of the encoding itself. + * + * @return The index of encoding of UTF-8. + */ +int rb_utf8_encindex(void); +#endif + +#ifndef rb_usascii_encindex +RBIMPL_ATTR_CONST() +/** + * Identical to rb_usascii_encoding(), except it returns the encoding's index + * instead of the encoding itself. + * + * @return The index of encoding of UTF-8. + */ +int rb_usascii_encindex(void); +#endif + +/** + * Identical to rb_locale_encoding(), except it returns the encoding's index + * instead of the encoding itself. + * + * @return The index of the locale encoding. + */ +int rb_locale_encindex(void); + +/** + * Identical to rb_filesystem_encoding(), except it returns the encoding's + * index instead of the encoding itself. + * + * @return The index of the filesystem encoding. + */ +int rb_filesystem_encindex(void); + +/** + * Identical to rb_default_external_encoding(), except it returns the + * Ruby-level counterpart instance of ::rb_cEncoding that corresponds to the + * default external encoding. + * + * @return An instance of ::rb_cEncoding of default external. + */ +VALUE rb_enc_default_external(void); + +/** + * Identical to rb_default_internal_encoding(), except it returns the + * Ruby-level counterpart instance of ::rb_cEncoding that corresponds to the + * default internal encoding. + * + * @return An instance of ::rb_cEncoding of default internal. + */ +VALUE rb_enc_default_internal(void); + +/** + * Destructively assigns the passed encoding as the default external encoding. + * You should not use this API. It has process-global side effects. Also it + * doesn't change encodings of strings that have already been read. + * + * @param[in] encoding Ruby level encoding. + * @exception rb_eArgError `encoding` is ::RUBY_Qnil. + * @post The default external encoding is `encoding`. + */ +void rb_enc_set_default_external(VALUE encoding); + +/** + * Destructively assigns the passed encoding as the default internal encoding. + * You should not use this API. It has process-global side effects. Also it + * doesn't change encodings of strings that have already been read. + * + * @param[in] encoding Ruby level encoding. + * @post The default internal encoding is `encoding`. + * @note Unlike rb_enc_set_default_external() you can pass ::RUBY_Qnil. + */ +void rb_enc_set_default_internal(VALUE encoding); + +/** + * Returns a platform-depended "charmap" of the current locale. This + * information is called a "Codeset name" in IEEE 1003.1 section 13 + * (`<langinfo.h>`). This is a very low-level API. The return value can have + * no corresponding encoding when passed to rb_find_encoding(). + * + * @param[in] klass Ignored for no reason (why...) + * @return The low-level locale charmap, in Ruby's String. + */ +VALUE rb_locale_charmap(VALUE klass); + +RBIMPL_SYMBOL_EXPORT_END() + +/** @cond INTERNAL_MACRO */ +#define RB_ENCODING_GET RB_ENCODING_GET +#define RB_ENCODING_GET_INLINED RB_ENCODING_GET_INLINED +#define RB_ENCODING_IS_ASCII8BIT RB_ENCODING_IS_ASCII8BIT +#define RB_ENCODING_SET RB_ENCODING_SET +#define RB_ENCODING_SET_INLINED RB_ENCODING_SET_INLINED +#define rb_enc_asciicompat rb_enc_asciicompat +#define rb_enc_code_to_mbclen rb_enc_code_to_mbclen +#define rb_enc_codepoint rb_enc_codepoint +#define rb_enc_left_char_head rb_enc_left_char_head +#define rb_enc_mbc_to_codepoint rb_enc_mbc_to_codepoint +#define rb_enc_mbcput rb_enc_mbcput +#define rb_enc_mbmaxlen rb_enc_mbmaxlen +#define rb_enc_mbminlen rb_enc_mbminlen +#define rb_enc_name rb_enc_name +#define rb_enc_prev_char rb_enc_prev_char +#define rb_enc_right_char_head rb_enc_right_char_head +#define rb_enc_step_back rb_enc_step_back +#define rb_enc_str_asciicompat_p rb_enc_str_asciicompat_p +/** @endcond */ + +#endif /* RUBY_INTERNAL_ENCODING_ENCODING_H */ diff --git a/include/ruby/internal/encoding/pathname.h b/include/ruby/internal/encoding/pathname.h new file mode 100644 index 0000000000..0b5e85a524 --- /dev/null +++ b/include/ruby/internal/encoding/pathname.h @@ -0,0 +1,184 @@ +#ifndef RUBY_INTERNAL_ENCODING_PATHNAME_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_PATHNAME_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 Routines to manipulate encodings of pathnames. + */ + +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/encoding/encoding.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() +RBIMPL_ATTR_NONNULL(()) +/** + * Returns a path component directly adjacent to the passed pointer. + * + * ``` + * "/multi/byte/encoded/pathname.txt" + * ^ ^ ^ + * | | +--- end + * | +--- @return + * +--- path + * ``` + * + * @param[in] path Where to start scanning. + * @param[in] end End of the path string. + * @param[in] enc Encoding of the string. + * @return A pointer in the passed string where the next path component + * resides, or `end` if there is no next path component. + */ +char *rb_enc_path_next(const char *path, const char *end, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL(()) +/** + * Seeks for non-prefix part of a pathname. This can be a no-op when the OS + * has no such concept like a path prefix. But there are OSes where path + * prefixes do exist. + * + * ``` + * "C:\multi\byte\encoded\pathname.txt" + * ^ ^ ^ + * | | +--- end + * | +--- @return + * +--- path + * ``` + * + * @param[in] path Where to start scanning. + * @param[in] end End of the path string. + * @param[in] enc Encoding of the string. + * @return A pointer in the passed string where non-prefix part starts, or + * `path` if the OS does not have path prefix. + */ +char *rb_enc_path_skip_prefix(const char *path, const char *end, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL(()) +/** + * Returns the last path component. + * + * ``` + * "/multi/byte/encoded/pathname.txt" + * ^ ^ ^ + * | | +--- end + * | +--- @return + * +--- path + * ``` + * + * @param[in] path Where to start scanning. + * @param[in] end End of the path string. + * @param[in] enc Encoding of the string. + * @return A pointer in the passed string where the last path component + * resides, or `end` if there is no more path component. + */ +char *rb_enc_path_last_separator(const char *path, const char *end, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL(()) +/** + * This just returns the passed end basically. It makes difference in case the + * passed string ends with tons of path separators like the following: + * + * ``` + * "/path/that/ends/with/lots/of/slashes//////////////" + * ^ ^ ^ + * | | +--- end + * | +--- @return + * +--- path + * ``` + * + * @param[in] path Where to start scanning. + * @param[in] end End of the path string. + * @param[in] enc Encoding of the string. + * @return A pointer in the passed string where the trailing path + * separators start, or `end` if there is no trailing path + * separators. + * + * @internal + * + * It seems this function was introduced to mimic what POSIX says about + * `basename(3)`. + */ +char *rb_enc_path_end(const char *path, const char *end, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL((1, 4)) +/** + * Our own encoding-aware version of `basename(3)`. Normally, this function + * returns the last path component of the given name. However in case the + * passed name ends with a path separator, it returns the name of the + * directory, not the last (empty) component. Also if the passed name is a + * root directory, it returns that root directory. Note however that Windows + * filesystem have drive letters, which this function does not return. + * + * @param[in] name Target path. + * @param[out] baselen Return buffer. + * @param[in,out] alllen Number of bytes of `name`. + * @param[enc] enc Encoding of `name`. + * @return The rightmost component of `name`. + * @post `baselen`, if passed, is updated to be the number of bytes + * of the returned basename. + * @post `alllen`, if passed, is updated to be the number of bytes of + * strings not considered as the basename. + */ +const char *ruby_enc_find_basename(const char *name, long *baselen, long *alllen, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL((1, 3)) +/** + * Our own encoding-aware version of `extname`. This function first applies + * rb_enc_path_last_separator() to the passed name and only concerns its return + * value (ignores any parent directories). This function returns complicated + * results: + * + * ```CXX + * auto path = "..."; + * auto len = strlen(path); + * auto ret = ruby_enc_find_extname(path, &len, rb_ascii8bit_encoding()); + * + * switch(len) { + * case 0: + * if (ret == 0) { + * // `path` is a file without extensions. + * } + * else { + * // `path` is a dotfile. + * // `ret` is the file's name. + * } + * break; + * + * case 1: + * // `path` _ends_ with a dot. + * // `ret` is that dot. + * break; + * + * default: + * // `path` has an extension. + * // `ret` is that extension. + * } + * ``` + * + * @param[in] name Target path. + * @param[in,out] len Number of bytes of `name`. + * @param[in] enc Encoding of `name`. + * @return See above. + * @post `len`, if passed, is updated (see above). + */ +const char *ruby_enc_find_extname(const char *name, long *len, rb_encoding *enc); + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_INTERNAL_ENCODING_PATHNAME_H */ diff --git a/include/ruby/internal/encoding/re.h b/include/ruby/internal/encoding/re.h new file mode 100644 index 0000000000..d0de23bc83 --- /dev/null +++ b/include/ruby/internal/encoding/re.h @@ -0,0 +1,46 @@ +#ifndef RUBY_INTERNAL_ENCODING_RE_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_RE_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 Routines to manipulate encodings of symbols. + */ + +#include "ruby/internal/dllexport.h" +#include "ruby/internal/encoding/encoding.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * Identical to rb_reg_new(), except it additionally takes an encoding. + * + * @param[in] ptr A memory region of `len` bytes length. + * @param[in] len Length of `ptr`, in bytes, not including the + * terminating NUL character. + * @param[in] enc Encoding of `ptr`. + * @param[in] opts Options e.g. ONIG_OPTION_MULTILINE. + * @exception rb_eRegexpError Failed to compile `ptr`. + * @return An allocated new instance of ::rb_cRegexp, of `enc` encoding, + * whose expression is compiled according to `ptr`. + */ +VALUE rb_enc_reg_new(const char *ptr, long len, rb_encoding *enc, int opts); + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_INTERNAL_ENCODING_RE_H */ diff --git a/include/ruby/internal/encoding/sprintf.h b/include/ruby/internal/encoding/sprintf.h new file mode 100644 index 0000000000..cb8737b414 --- /dev/null +++ b/include/ruby/internal/encoding/sprintf.h @@ -0,0 +1,78 @@ +#ifndef RUBY_INTERNAL_ENCODING_SPRINTF_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_SPRINTF_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 Routines to manipulate encodings of symbols. + */ +#include "ruby/internal/config.h" +#include <stdarg.h> +#include "ruby/internal/attr/format.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/attr/noreturn.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/encoding/encoding.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() +RBIMPL_ATTR_NONNULL((2)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 3) +/** + * Identical to rb_sprintf(), except it additionally takes an encoding. The + * passed encoding rules both the incoming format specifier and the resulting + * string. + * + * @param[in] enc Encoding of `fmt`. + * @param[in] fmt A `printf`-like format specifier. + * @param[in] ... Variadic number of contents to format. + * @return A rendered new instance of ::rb_cString, of `enc` encoding. + */ +VALUE rb_enc_sprintf(rb_encoding *enc, const char *fmt, ...); + +RBIMPL_ATTR_NONNULL((2)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 0) +/** + * Identical to rb_enc_sprintf(), except it takes a `va_list` instead of + * variadic arguments. It can also be seen as a routine identical to + * rb_vsprintf(), except it additionally takes an encoding. + * + * @param[in] enc Encoding of `fmt`. + * @param[in] fmt A `printf`-like format specifier. + * @param[in] ap Contents to format. + * @return A rendered new instance of ::rb_cString, of `enc` encoding. + */ +VALUE rb_enc_vsprintf(rb_encoding *enc, const char *fmt, va_list ap); + +RBIMPL_ATTR_NORETURN() +RBIMPL_ATTR_NONNULL((3)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 3, 4) +/** + * Identical to rb_raise(), except it additionally takes an encoding. + * + * @param[in] enc Encoding of the generating exception. + * @param[in] exc A subclass of ::rb_eException. + * @param[in] fmt Format specifier string compatible with rb_sprintf(). + * @param[in] ... Contents of the message. + * @exception exc The specified exception. + * @note It never returns. + */ +void rb_enc_raise(rb_encoding *enc, VALUE exc, const char *fmt, ...); + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_INTERNAL_ENCODING_SPRINTF_H */ diff --git a/include/ruby/internal/encoding/string.h b/include/ruby/internal/encoding/string.h new file mode 100644 index 0000000000..2cfa91c01e --- /dev/null +++ b/include/ruby/internal/encoding/string.h @@ -0,0 +1,346 @@ +#ifndef RUBY_INTERNAL_ENCODING_STRING_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_STRING_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 Routines to manipulate encodings of strings. + */ + +#include "ruby/internal/dllexport.h" +#include "ruby/internal/value.h" +#include "ruby/internal/encoding/encoding.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/intern/string.h" /* rbimpl_strlen */ + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * Identical to rb_str_new(), except it additionally takes an encoding. + * + * @param[in] ptr A memory region of `len` bytes length. + * @param[in] len Length of `ptr`, in bytes, not including the + * terminating NUL character. + * @param[in] enc Encoding of `ptr`. + * @exception rb_eNoMemError Failed to allocate `len+1` bytes. + * @exception rb_eArgError `len` is negative. + * @return An instance of ::rb_cString, of `len` bytes length, of `enc` + * encoding, whose contents are verbatim copy of `ptr`. + * @pre At least `len` bytes of continuous memory region shall be + * accessible via `ptr`. + * @note `enc` can be a null pointer. It can also be seen as a routine + * identical to rb_usascii_str_new() then. + */ +VALUE rb_enc_str_new(const char *ptr, long len, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Identical to rb_enc_str_new(), except it assumes the passed pointer is a + * pointer to a C string. It can also be seen as a routine identical to + * rb_str_new_cstr(), except it additionally takes an encoding. + * + * @param[in] ptr A C string. + * @param[in] enc Encoding of `ptr`. + * @exception rb_eNoMemError Failed to allocate memory. + * @return An instance of ::rb_cString, of `enc` encoding, whose contents + * are verbatim copy of `ptr`. + * @pre `ptr` must not be a null pointer. + * @pre Because `ptr` is a C string it makes no sense for `enc` to be + * something like UTF-32. + * @note `enc` can be a null pointer. It can also be seen as a routine + * identical to rb_usascii_str_new_cstr() then. + */ +VALUE rb_enc_str_new_cstr(const char *ptr, rb_encoding *enc); + +/** + * Identical to rb_enc_str_new(), except it takes a C string literal. It can + * also be seen as a routine identical to rb_str_new_static(), except it + * additionally takes an encoding. + * + * @param[in] ptr A C string literal. + * @param[in] len `strlen(ptr)`. + * @param[in] enc Encoding of `ptr`. + * @exception rb_eArgError `len` out of range of `size_t`. + * @pre `ptr` must be a C string constant. + * @return An instance of ::rb_cString, of `enc` encoding, whose backend + * storage is the passed C string literal. + * @warning It is a very bad idea to write to a C string literal (often + * immediate SEGV shall occur). Consider return values of this + * function be read-only. + * @note `enc` can be a null pointer. It can also be seen as a routine + * identical to rb_usascii_str_new_static() then. + */ +VALUE rb_enc_str_new_static(const char *ptr, long len, rb_encoding *enc); + +/** + * Identical to rb_enc_str_new(), except it returns a "f"string. It can also + * be seen as a routine identical to rb_interned_str(), except it additionally + * takes an encoding. + * + * @param[in] ptr A memory region of `len` bytes length. + * @param[in] len Length of `ptr`, in bytes, not including the + * terminating NUL character. + * @param[in] enc Encoding of `ptr`. + * @exception rb_eArgError `len` is negative. + * @return A found or created instance of ::rb_cString, of `len` bytes + * length, of `enc` encoding, whose contents are identical to that + * of `ptr`. + * @pre At least `len` bytes of continuous memory region shall be + * accessible via `ptr`. + * @note `enc` can be a null pointer. + */ +VALUE rb_enc_interned_str(const char *ptr, long len, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Identical to rb_enc_str_new_cstr(), except it returns a "f"string. It can + * also be seen as a routine identical to rb_interned_str_cstr(), except it + * additionally takes an encoding. + * + * @param[in] ptr A memory region of `len` bytes length. + * @param[in] enc Encoding of `ptr`. + * @return A found or created instance of ::rb_cString of `enc` encoding, + * whose contents are identical to that of `ptr`. + * @pre At least `len` bytes of continuous memory region shall be + * accessible via `ptr`. + * @note `enc` can be a null pointer. + */ +VALUE rb_enc_interned_str_cstr(const char *ptr, rb_encoding *enc); + +/** + * Counts the number of characters of the passed string, according to the + * passed encoding. This has to be complicated. The passed string could be + * invalid and/or broken. This routine would scan from the beginning til the + * end, byte by byte, to seek out character boundaries. Could be super slow. + * + * @param[in] head Leftmost pointer to the string. + * @param[in] tail Rightmost pointer to the string. + * @param[in] enc Encoding of the string. + * @return Number of characters exist in `head` .. `tail`. The definition + * of "character" depends on the passed `enc`. + */ +long rb_enc_strlen(const char *head, const char *tail, rb_encoding *enc); + +/** + * Queries the n-th character. Like rb_enc_strlen() this function can be fast + * or slow depending on the contents. Don't expect characters to be uniformly + * distributed across the entire string. + * + * @param[in] head Leftmost pointer to the string. + * @param[in] tail Rightmost pointer to the string. + * @param[in] nth Requested index of characters. + * @param[in] enc Encoding of the string. + * @return Pointer to the first byte of the character that is `nth` + * character ahead of `head`, or `tail` if there is no such + * character (OOB etc). The definition of "character" depends on + * the passed `enc`. + */ +char *rb_enc_nth(const char *head, const char *tail, long nth, rb_encoding *enc); + +/** + * Identical to rb_enc_get_index(), except the return type. + * + * @param[in] obj Object in question. + * @exception rb_eTypeError `obj` is incapable of having an encoding. + * @return `obj`'s encoding. + */ +VALUE rb_obj_encoding(VALUE obj); + +/** + * Identical to rb_str_cat(), except it additionally takes an encoding. + * + * @param[out] str Destination object. + * @param[in] ptr Contents to append. + * @param[in] len Length of `src`, in bytes. + * @param[in] enc Encoding of `ptr`. + * @exception rb_eArgError `len` is negative. + * @exception rb_eEncCompatError `enc` is not compatible with `str`. + * @return The passed `dst`. + * @post The contents of `ptr` is copied, transcoded into `dst`'s + * encoding, then pasted into `dst`'s end. + */ +VALUE rb_enc_str_buf_cat(VALUE str, const char *ptr, long len, rb_encoding *enc); + +/** + * Encodes the passed code point into a series of bytes. + * + * @param[in] code Code point. + * @param[in] enc Target encoding scheme. + * @exception rb_eRangeError `enc` does not glean `code`. + * @return An instance of ::rb_cString, of `enc` encoding, whose sole + * contents is `code` represented in `enc`. + * @note No way to encode code points bigger than UINT_MAX. + * + * @internal + * + * In other languages, APIs like this one could be seen as the primitive + * routines where encodings' "encode" feature are implemented. However in case + * of Ruby this is not the primitive one. We directly manipulate encoded + * strings. Encoding conversion routines transcode an encoded string directly + * to another one; not via a code point array. + */ +VALUE rb_enc_uint_chr(unsigned int code, rb_encoding *enc); + +/** + * Identical to rb_external_str_new(), except it additionally takes an + * encoding. However the whole point of rb_external_str_new() is to encode a + * string into default external encoding. Being able to specify arbitrary + * encoding just ruins the designed purpose the function meseems. + * + * @param[in] ptr A memory region of `len` bytes length. + * @param[in] len Length of `ptr`, in bytes, not including the + * terminating NUL character. + * @param[in] enc Target encoding scheme. + * @exception rb_eArgError `len` is negative. + * @return An instance of ::rb_cString. In case encoding conversion from + * "default internal" to `enc` is fully defined over the given + * contents, then the return value is a string of `enc` encoding, + * whose contents are the converted ones. Otherwise the string is + * a junk. + * @warning It doesn't raise on a conversion failure and silently ends up in + * a corrupted output. You can know the failure by querying + * `valid_encoding?` of the result object. + * + * @internal + * + * @shyouhei has no idea why this one does not follow the naming convention + * that others obey. It seems to him that this should have been called + * `rb_enc_external_str_new`. + */ +VALUE rb_external_str_new_with_enc(const char *ptr, long len, rb_encoding *enc); + +/** + * Identical to rb_str_export(), except it additionally takes an encoding. + * + * @param[in] obj Target object. + * @param[in] enc Target encoding. + * @exception rb_eTypeError No implicit conversion to String. + * @return Converted ruby string of `enc` encoding. + */ +VALUE rb_str_export_to_enc(VALUE obj, rb_encoding *enc); + +/** + * Encoding conversion main routine. + * + * @param[in] str String to convert. + * @param[in] from Source encoding. + * @param[in] to Destination encoding. + * @return A copy of `str`, with conversion from `from` to `to` applied. + * @note `from` can be a null pointer. `str`'s encoding is taken then. + * @note `to` can be a null pointer. No-op then. + */ +VALUE rb_str_conv_enc(VALUE str, rb_encoding *from, rb_encoding *to); + +/** + * Identical to rb_str_conv_enc(), except it additionally takes IO encoder + * options. The extra arguments can be constructed using io_extract_modeenc() + * etc. + * + * @param[in] str String to convert. + * @param[in] from Source encoding. + * @param[in] to Destination encoding. + * @param[in] ecflags A set of enum ::ruby_econv_flag_type. + * @param[in] ecopts Optional hash. + * @return A copy of `str`, with conversion from `from` to `to` applied. + * @note `from` can be a null pointer. `str`'s encoding is taken then. + * @note `to` can be a null pointer. No-op then. + * @note `ecopts` can be ::RUBY_Qnil, which is equivalent to passing an + * empty hash. + */ +VALUE rb_str_conv_enc_opts(VALUE str, rb_encoding *from, rb_encoding *to, int ecflags, VALUE ecopts); + +/** + * Scans the passed string to collect its code range. Because a Ruby's string + * is mutable, its contents change from time to time; so does its code range. + * A long-lived string tends to fall back to ::RUBY_ENC_CODERANGE_UNKNOWN. + * This API scans it and re-assigns a fine-grained code range constant. + * + * @param[out] str A string. + * @return An enum ::ruby_coderange_type. + */ +int rb_enc_str_coderange(VALUE str); + +/** + * Scans the passed string until it finds something odd. Returns the number of + * bytes scanned. As the name implies this is suitable for repeated call. One + * of its application is `IO#readlines`. The method reads from its receiver's + * read buffer, maybe more than once, looking for newlines. But "newline" can + * be different among encodings. This API is used to detect broken contents to + * properly mark them as such. + * + * @param[in] str String to scan. + * @param[in] end End of `str`. + * @param[in] enc `str`'s encoding. + * @param[out] cr Return buffer. + * @return Distance between `str` and first such byte where broken. + * @post `cr` has the code range type. + */ +long rb_str_coderange_scan_restartable(const char *str, const char *end, rb_encoding *enc, int *cr); + +/** + * Queries if the passed string is "ASCII only". An ASCII only string is a + * string who doesn't have any non-ASCII characters at all. This doesn't + * necessarily mean the string is in ASCII encoding. For instance a String of + * CP932 encoding can quite much be ASCII only, depending on its contents. + * + * @param[in] str String in question. + * @retval 1 It doesn't have non-ASCII characters. + * @retval 0 It has characters that are out of ASCII. + */ +int rb_enc_str_asciionly_p(VALUE str); + +RBIMPL_ATTR_NONNULL(()) +/** + * Looks for the passed string in the passed buffer. + * + * @param[in] x Query string. + * @param[in] m Number of bytes of `x`. + * @param[in] y Buffer that potentially includes `x`. + * @param[in] n Number of bytes of `y`. + * @param[in] enc Encoding of both `x` and `y`. + * @retval -1 Not found. + * @retval otherwise Found index in `y`. + * @note This API can match at a non-character-boundary. + */ +long rb_memsearch(const void *x, long m, const void *y, long n, rb_encoding *enc); + +/** @cond INTERNAL_MACRO */ +RBIMPL_ATTR_NONNULL(()) +static inline VALUE +rbimpl_enc_str_new_cstr(const char *str, rb_encoding *enc) +{ + long len = rbimpl_strlen(str); + + return rb_enc_str_new_static(str, len, enc); +} + +#define rb_enc_str_new(str, len, enc) \ + ((RBIMPL_CONSTANT_P(str) && \ + RBIMPL_CONSTANT_P(len) ? \ + rb_enc_str_new_static: \ + rb_enc_str_new) ((str), (len), (enc))) + +#define rb_enc_str_new_cstr(str, enc) \ + ((RBIMPL_CONSTANT_P(str) ? \ + rbimpl_enc_str_new_cstr : \ + rb_enc_str_new_cstr) ((str), (enc))) + +/** @endcond */ + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_INTERNAL_ENCODING_STRING_H */ diff --git a/include/ruby/internal/encoding/symbol.h b/include/ruby/internal/encoding/symbol.h new file mode 100644 index 0000000000..9cd1b0dbf4 --- /dev/null +++ b/include/ruby/internal/encoding/symbol.h @@ -0,0 +1,100 @@ +#ifndef RUBY_INTERNAL_ENCODING_SYMBOL_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_SYMBOL_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 Routines to manipulate encodings of symbols. + */ + +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/encoding/encoding.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * Identical to rb_intern2(), except it additionally takes an encoding. + * + * @param[in] name The name of the id. + * @param[in] len Length of `name`. + * @param[in] enc `name`'s encoding. + * @exception rb_eRuntimeError Too many symbols. + * @return A (possibly new) id whose value is the given name. + * @note These days Ruby internally has two kinds of symbols + * (static/dynamic). Symbols created using this function would + * become static ones; i.e. would never be garbage collected. It + * is up to you to avoid memory leaks. Think twice before using + * it. + */ +ID rb_intern3(const char *name, long len, rb_encoding *enc); + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_symname_p(), except it additionally takes an encoding. + * + * @param[in] str A C string to check. + * @param[in] enc `str`'s encoding. + * @retval 1 It is a valid symbol name. + * @retval 0 It is invalid as a symbol name. + */ +int rb_enc_symname_p(const char *str, rb_encoding *enc); + +/** + * Identical to rb_enc_symname_p(), except it additionally takes the passed + * string's length. This is needed for strings containing NUL bytes, like in + * case of UTF-32. + * + * @param[in] name A C string to check. + * @param[in] len Number of bytes of `str`. + * @param[in] enc `str`'s encoding. + * @retval 1 It is a valid symbol name. + * @retval 0 It is invalid as a symbol name. + */ +int rb_enc_symname2_p(const char *name, long len, rb_encoding *enc); + +/** + * Identical to rb_check_id(), except it takes a pointer to a memory region + * instead of Ruby's string. + * + * @param[in] ptr A pointer to a memory region. + * @param[in] len Number of bytes of `ptr`. + * @param[in] enc Encoding of `ptr`. + * @exception rb_eEncodingError `ptr` contains non-ASCII according to `enc`. + * @retval 0 No such id ever existed in the history. + * @retval otherwise The id that represents the given name. + */ +ID rb_check_id_cstr(const char *ptr, long len, rb_encoding *enc); + +/** + * Identical to rb_check_id_cstr(), except for the return type. It can also be + * seen as a routine identical to rb_check_symbol(), except it takes a pointer + * to a memory region instead of Ruby's string. + * + * @param[in] ptr A pointer to a memory region. + * @param[in] len Number of bytes of `ptr`. + * @param[in] enc Encoding of `ptr`. + * @exception rb_eEncodingError `ptr` contains non-ASCII according to `enc`. + * @retval RUBY_Qnil No such id ever existed in the history. + * @retval otherwise The id that represents the given name. + */ +VALUE rb_check_symbol_cstr(const char *ptr, long len, rb_encoding *enc); + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_INTERNAL_ENCODING_SYMBOL_H */ diff --git a/include/ruby/internal/encoding/transcode.h b/include/ruby/internal/encoding/transcode.h new file mode 100644 index 0000000000..7f26d2eae9 --- /dev/null +++ b/include/ruby/internal/encoding/transcode.h @@ -0,0 +1,562 @@ +#ifndef RUBY_INTERNAL_ENCODING_TRANSCODE_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RUBY_INTERNAL_ENCODING_TRANSCODE_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 econv stuff + */ + +#include "ruby/internal/dllexport.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** return value of rb_econv_convert() */ +typedef enum { + + /** + * The conversion stopped when it found an invalid sequence. + */ + econv_invalid_byte_sequence, + + /** + * The conversion stopped when it found a character in the input which + * cannot be representable in the output. + */ + econv_undefined_conversion, + + /** + * The conversion stopped because there is no destination. + */ + econv_destination_buffer_full, + + /** + * The conversion stopped because there is no input. + */ + econv_source_buffer_empty, + + /** + * The conversion stopped after converting everything. This is arguably + * the expected normal end of conversion. + */ + econv_finished, + + /** + * The conversion stopped after writing something to somewhere, before + * reading everything. + */ + econv_after_output, + + /** + * The conversion stopped in middle of reading a character, possibly due to + * a partial read of a socket etc. + */ + econv_incomplete_input +} rb_econv_result_t; + +/** An opaque struct that represents a lowest level of encoding conversion. */ +typedef struct rb_econv_t rb_econv_t; + +/** + * Converts the contents of the passed string from its encoding to the passed + * one. + * + * @param[in] str Target string. + * @param[in] to Destination encoding. + * @param[in] ecflags A set of enum + * ::ruby_econv_flag_type. + * @param[in] ecopts A keyword hash, like + * ::rb_io_t::rb_io_enc_t::ecopts. + * @exception rb_eArgError Not fully converted. + * @exception rb_eInvalidByteSequenceError `str` is malformed. + * @exception rb_eUndefinedConversionError `str` has a character not + * representable using `to`. + * @exception rb_eConversionNotFoundError There is no known conversion from + * `str`'s encoding to `to`. + * @return A string whose encoding is `to`, and whose contents is converted + * contents of `str`. + * @note Use rb_econv_prepare_options() to generate `ecopts`. + */ +VALUE rb_str_encode(VALUE str, VALUE to, int ecflags, VALUE ecopts); + +/** + * Queries if there is more than one way to convert between the passed two + * encodings. Encoding conversion are has_and_belongs_to_many relationships. + * There could be no direct conversion defined for the passed pair. Ruby tries + * to find an indirect way to do so then. For instance ISO-8859-1 has no + * direct conversion to ISO-2022-JP. But there is ISO-8859-1 to UTF-8 + * conversion; then there is UTF-8 to EUC-JP conversion; finally there also is + * EUC-JP to ISO-2022-JP conversion. So in short ISO-8859-1 can be converted + * to ISO-2022-JP using that path. This function returns true. Obviously not + * everything that can be represented using UTF-8 can also be represented using + * EUC-JP. Conversions in practice can fail depending on the actual input, and + * that renders exceptions in case of rb_str_encode(). + * + * @param[in] from_encoding One encoding. + * @param[in] to_encoding Another encoding. + * @retval 0 No way to convert the two. + * @retval 1 At least one way to convert the two. + * + * @internal + * + * Practically @shyouhei knows no way for this function to return 0. It seems + * everything can eventually be converted to/from UTF-8, which connects + * everything. + */ +int rb_econv_has_convpath_p(const char* from_encoding, const char* to_encoding); + +/** + * Identical to rb_econv_prepare_opts(), except it additionally takes the + * initial value of flags. The extra bits are bitwise-ORed to the return + * value. + * + * @param[in] opthash Keyword arguments. + * @param[out] ecopts Return buffer. + * @param[in] ecflags Default set of enum ::ruby_econv_flag_type. + * @exception rb_eArgError Unknown/Broken values passed. + * @return Calculated set of enum ::ruby_econv_flag_type. + * @post `ecopts` holds a hash object suitable for + * ::rb_io_t::rb_io_enc_t::ecopts. + */ +int rb_econv_prepare_options(VALUE opthash, VALUE *ecopts, int ecflags); + +/** + * Splits a keyword arguments hash (that for instance `String#encode` took) + * into a set of enum ::ruby_econv_flag_type and a hash storing replacement + * characters etc. + * + * @param[in] opthash Keyword arguments. + * @param[out] ecopts Return buffer. + * @exception rb_eArgError Unknown/Broken values passed. + * @return Calculated set of enum ::ruby_econv_flag_type. + * @post `ecopts` holds a hash object suitable for + * ::rb_io_t::rb_io_enc_t::ecopts. + */ +int rb_econv_prepare_opts(VALUE opthash, VALUE *ecopts); + +/** + * Creates a new instance of struct ::rb_econv_t. + * + * @param[in] source_encoding Name of an encoding. + * @param[in] destination_encoding Name of another encoding. + * @param[in] ecflags A set of enum ::ruby_econv_flag_type. + * @exception rb_eArgError No such encoding. + * @retval NULL Failed to create a struct ::rb_econv_t. + * @retval otherwise Allocated struct ::rb_econv_t. + * @warning Return value must be passed to rb_econv_close() exactly once. + */ +rb_econv_t *rb_econv_open(const char *source_encoding, const char *destination_encoding, int ecflags); + +/** + * Identical to rb_econv_open(), except it additionally takes a hash of + * optional strings. + * + * + * @param[in] source_encoding Name of an encoding. + * @param[in] destination_encoding Name of another encoding. + * @param[in] ecflags A set of enum ::ruby_econv_flag_type. + * @param[in] ecopts Optional set of strings. + * @exception rb_eArgError No such encoding. + * @retval NULL Failed to create a struct ::rb_econv_t. + * @retval otherwise Allocated struct ::rb_econv_t. + * @warning Return value must be passed to rb_econv_close() exactly once. + */ +rb_econv_t *rb_econv_open_opts(const char *source_encoding, const char *destination_encoding, int ecflags, VALUE ecopts); + +/** + * Converts a string from an encoding to another. + * + * Possible flags are either ::RUBY_ECONV_PARTIAL_INPUT (means the source + * buffer is a part of much larger one), ::RUBY_ECONV_AFTER_OUTPUT (instructs + * the converter to stop after output before input), or both of them. + * + * @param[in,out] ec Conversion specification/state etc. + * @param[in] source_buffer_ptr Target string. + * @param[in] source_buffer_end End of target string. + * @param[out] destination_buffer_ptr Return buffer. + * @param[out] destination_buffer_end End of return buffer. + * @param[in] flags Flags (see above). + * @return The status of the conversion. + * @post `destination_buffer_ptr` holds conversion results. + */ +rb_econv_result_t rb_econv_convert(rb_econv_t *ec, + const unsigned char **source_buffer_ptr, const unsigned char *source_buffer_end, + unsigned char **destination_buffer_ptr, unsigned char *destination_buffer_end, + int flags); + +/** + * Destructs a converter. Note that a converter can have a buffer, and can be + * non-empty. Calling this would lose your data then. + * + * @param[out] ec The converter to destroy. + * @post `ec` is no longer a valid pointer. + */ +void rb_econv_close(rb_econv_t *ec); + +/** + * Assigns the replacement string. The string passed here would appear in + * converted string when it cannot represent its source counterpart. This can + * happen for instance you convert an emoji to ISO-8859-1. + * + * @param[out] ec Target converter. + * @param[in] str Replacement string. + * @param[in] len Number of bytes of `str`. + * @param[in] encname Name of encoding of `str`. + * @retval 0 Success. + * @retval -1 Failure (ENOMEM etc.). + * @post `ec`'s replacement string is set to `str`. + */ +int rb_econv_set_replacement(rb_econv_t *ec, const unsigned char *str, size_t len, const char *encname); + +/** + * "Decorate"s a converter. There are special kind of converters that + * transforms the contents, like replacing CR into CRLF. You can add such + * decorators to a converter using this API. By using this function a + * decorator is prepended at the beginning of a conversion sequence: in case of + * CRLF conversion, newlines are converted before encodings are converted. + * + * @param[out] ec Target converter to decorate. + * @param[in] decorator_name Name of decorator to prepend. + * @retval 0 Success. + * @retval -1 Failure (no such decorator etc.). + * @post Decorator works before encoding conversion happens. + * + * @internal + * + * What is the possible value of the `decorator_name` is not public. You have + * to read through `transcode.c` carefully. + */ +int rb_econv_decorate_at_first(rb_econv_t *ec, const char *decorator_name); + +/** + * Identical to rb_econv_decorate_at_first(), except it adds to the opposite + * direction. For instance CRLF conversion would run _after_ encodings are + * converted. + * + * @param[out] ec Target converter to decorate. + * @param[in] decorator_name Name of decorator to prepend. + * @retval 0 Success. + * @retval -1 Failure (no such decorator etc.). + * @post Decorator works after encoding conversion happens. + */ +int rb_econv_decorate_at_last(rb_econv_t *ec, const char *decorator_name); + +/** + * Creates a `rb_eConverterNotFoundError` exception object (but does not + * raise). + * + * @param[in] senc Name of source encoding. + * @param[in] denc Name of destination encoding. + * @param[in] ecflags A set of enum ::ruby_econv_flag_type. + * @return An instance of `rb_eConverterNotFoundError`. + */ +VALUE rb_econv_open_exc(const char *senc, const char *denc, int ecflags); + +/** + * Appends the passed string to the passed converter's output buffer. This can + * be handy when an encoding needs bytes out of thin air; for instance + * ISO-2022-JP has "shift function" which does not correspond to any + * characters. + * + * @param[out] ec Target converter. + * @param[in] str String to insert. + * @param[in] len Number of bytes of `str`. + * @param[in] str_encoding Encoding of `str`. + * @retval 0 Success. + * @retval -1 Failure (conversion error etc.). + * @note `str_encoding` can be anything, and `str` itself is converted + * when necessary. + */ +int rb_econv_insert_output(rb_econv_t *ec, + const unsigned char *str, size_t len, const char *str_encoding); + +/** + * Queries an encoding name which best suits for rb_econv_insert_output()'s + * last parameter. Strings in this encoding need no conversion when inserted; + * can be both time/space efficient. + * + * @param[in] ec Target converter. + * @return Its encoding for insertion. + */ +const char *rb_econv_encoding_to_insert_output(rb_econv_t *ec); + +/** + * This is a rb_econv_make_exception() + rb_exc_raise() combo. + * + * @param[in] ec (Possibly failed) conversion. + * @exception rb_eInvalidByteSequenceError Invalid byte sequence. + * @exception rb_eUndefinedConversionError Conversion undefined. + * @note This function can return when no error. + */ +void rb_econv_check_error(rb_econv_t *ec); + +/** + * This function makes sense right after rb_econv_convert() returns. As listed + * in ::rb_econv_result_t, rb_econv_convert() can bail out for various reasons. + * This function checks the passed converter's internal state and convert it to + * an appropriate exception object. + * + * @param[in] ec Target converter. + * @retval RUBY_Qnil The converter has no error. + * @retval otherwise Conversion error turned into an exception. + */ +VALUE rb_econv_make_exception(rb_econv_t *ec); + +/** + * Queries if rb_econv_putback() makes sense, i.e. there are invalid byte + * sequences remain in the buffer. + * + * @param[in] ec Target converter. + * @return Number of bytes that can be pushed back. + */ +int rb_econv_putbackable(rb_econv_t *ec); + +/** + * Puts back the bytes. In case of ::econv_invalid_byte_sequence, some of + * those invalid bytes are discarded and the others are buffered to be + * converted later. The latter bytes can be put back using this API. + * + * @param[out] ec Target converter (invalid byte sequence). + * @param[out] p Return buffer. + * @param[in] n Max number of bytes to put back. + * @post At most `n` bytes of what was put back is written to `p`. + */ +void rb_econv_putback(rb_econv_t *ec, unsigned char *p, int n); + +/** + * Queries the passed encoding's corresponding ASCII compatible encoding. "The + * corresponding ASCII compatible encoding" in this context is an ASCII + * compatible encoding which can represent exactly the same character sets as + * the given ASCII incompatible encoding. For instance that of UTF-16LE is + * UTF-8. + * + * @param[in] encname Name of an ASCII incompatible encoding. + * @retval NULL `encname` is already ASCII compatible. + * @retval otherwise The corresponding ASCII compatible encoding. + */ +const char *rb_econv_asciicompat_encoding(const char *encname); + +/** + * Identical to rb_econv_convert(), except it takes Ruby's string instead of + * C's pointer. + * + * @param[in,out] ec Target converter. + * @param[in] src Source string. + * @param[in] flags Flags (see rb_econv_convert). + * @exception rb_eArgError Converted string is too long. + * @exception rb_eInvalidByteSequenceError Invalid byte sequence. + * @exception rb_eUndefinedConversionError Conversion undefined. + * @return The conversion result. + */ +VALUE rb_econv_str_convert(rb_econv_t *ec, VALUE src, int flags); + +/** + * Identical to rb_econv_str_convert(), except it converts only a part of the + * passed string. Can be handy when you for instance want to do line-buffered + * conversion. + * + * @param[in,out] ec Target converter. + * @param[in] src Source string. + * @param[in] byteoff Number of bytes to seek. + * @param[in] bytesize Number of bytes to read. + * @param[in] flags Flags (see rb_econv_convert). + * @exception rb_eArgError Converted string is too long. + * @exception rb_eInvalidByteSequenceError Invalid byte sequence. + * @exception rb_eUndefinedConversionError Conversion undefined. + * @return The conversion result. + */ +VALUE rb_econv_substr_convert(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, int flags); + +/** + * Identical to rb_econv_str_convert(), except it appends the conversion result + * to the additionally passed string instead of creating a new string. It can + * also be seen as a routine identical to rb_econv_append(), except it takes a + * Ruby's string instead of C's pointer. + * + * @param[in,out] ec Target converter. + * @param[in] src Source string. + * @param[in] dst Return buffer. + * @param[in] flags Flags (see rb_econv_convert). + * @exception rb_eArgError Converted string is too long. + * @exception rb_eInvalidByteSequenceError Invalid byte sequence. + * @exception rb_eUndefinedConversionError Conversion undefined. + * @return The conversion result. + */ +VALUE rb_econv_str_append(rb_econv_t *ec, VALUE src, VALUE dst, int flags); + +/** + * Identical to rb_econv_str_append(), except it appends only a part of the + * passed string with conversion. It can also be seen as a routine identical + * to rb_econv_substr_convert(), except it appends the conversion result to the + * additionally passed string instead of creating a new string. + * + * @param[in,out] ec Target converter. + * @param[in] src Source string. + * @param[in] byteoff Number of bytes to seek. + * @param[in] bytesize Number of bytes to read. + * @param[in] dst Return buffer. + * @param[in] flags Flags (see rb_econv_convert). + * @exception rb_eArgError Converted string is too long. + * @exception rb_eInvalidByteSequenceError Invalid byte sequence. + * @exception rb_eUndefinedConversionError Conversion undefined. + * @return The conversion result. + */ +VALUE rb_econv_substr_append(rb_econv_t *ec, VALUE src, long byteoff, long bytesize, VALUE dst, int flags); + +/** + * Converts the passed C's pointer according to the passed converter, then + * append the conversion result to the passed Ruby's string. This way buffer + * overflow is properly avoided to resize the destination properly. + * + * @param[in,out] ec Target converter. + * @param[in] bytesrc Target string. + * @param[in] bytesize Number of bytes of `bytesrc`. + * @param[in] dst Return buffer. + * @param[in] flags Flags (see rb_econv_convert). + * @exception rb_eArgError Converted string is too long. + * @exception rb_eInvalidByteSequenceError Invalid byte sequence. + * @exception rb_eUndefinedConversionError Conversion undefined. + * @return The conversion result. + */ +VALUE rb_econv_append(rb_econv_t *ec, const char *bytesrc, long bytesize, VALUE dst, int flags); + +/** + * This badly named function does not set the destination encoding to binary, + * but instead just nullifies newline conversion decorators if any. Other + * ordinal character conversions still happen after this; something non-binary + * would still be generated. + * + * @param[out] ec Target converter to modify. + * @post Any newline conversions, if any, would be killed. + */ +void rb_econv_binmode(rb_econv_t *ec); + +/** + * This enum is kind of omnibus. Gathers various constants. + */ +enum ruby_econv_flag_type { + + /** + * @name Flags for rb_econv_open() + * + * @{ + */ + + /** Mask for error handling related bits. */ + RUBY_ECONV_ERROR_HANDLER_MASK = 0x000000ff, + + /** Special handling of invalid sequences are there. */ + RUBY_ECONV_INVALID_MASK = 0x0000000f, + + /** Invalid sequences shall be replaced. */ + RUBY_ECONV_INVALID_REPLACE = 0x00000002, + + /** Special handling of undefined conversion are there. */ + RUBY_ECONV_UNDEF_MASK = 0x000000f0, + + /** Undefined characters shall be replaced. */ + RUBY_ECONV_UNDEF_REPLACE = 0x00000020, + + /** Undefined characters shall be escaped. */ + RUBY_ECONV_UNDEF_HEX_CHARREF = 0x00000030, + + /** Decorators are there. */ + RUBY_ECONV_DECORATOR_MASK = 0x0001ff00, + + /** Newline converters are there. */ + RUBY_ECONV_NEWLINE_DECORATOR_MASK = 0x00007f00, + + /** (Unclear; seems unused). */ + RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK = 0x00000f00, + + /** (Unclear; seems unused). */ + RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK = 0x00007000, + + /** Universal newline mode. */ + RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR = 0x00000100, + + /** CR to CRLF conversion shall happen. */ + RUBY_ECONV_CRLF_NEWLINE_DECORATOR = 0x00001000, + + /** CRLF to CR conversion shall happen. */ + RUBY_ECONV_CR_NEWLINE_DECORATOR = 0x00002000, + + /** CRLF to LF conversion shall happen. */ + RUBY_ECONV_LF_NEWLINE_DECORATOR = 0x00004000, + + /** Texts shall be XML-escaped. */ + RUBY_ECONV_XML_TEXT_DECORATOR = 0x00008000, + + /** Texts shall be AttrValue escaped */ + RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR = 0x00010000, + + /** (Unclear; seems unused). */ + RUBY_ECONV_STATEFUL_DECORATOR_MASK = 0x00f00000, + + /** Texts shall be AttrValue escaped. */ + RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR = 0x00100000, + + /** Newline decorator's default. */ + RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR = +#if defined(RUBY_TEST_CRLF_ENVIRONMENT) || defined(_WIN32) + RUBY_ECONV_CRLF_NEWLINE_DECORATOR, +#else + 0, +#endif + +#define ECONV_ERROR_HANDLER_MASK RUBY_ECONV_ERROR_HANDLER_MASK /**< @old{RUBY_ECONV_ERROR_HANDLER_MASK} */ +#define ECONV_INVALID_MASK RUBY_ECONV_INVALID_MASK /**< @old{RUBY_ECONV_INVALID_MASK} */ +#define ECONV_INVALID_REPLACE RUBY_ECONV_INVALID_REPLACE /**< @old{RUBY_ECONV_INVALID_REPLACE} */ +#define ECONV_UNDEF_MASK RUBY_ECONV_UNDEF_MASK /**< @old{RUBY_ECONV_UNDEF_MASK} */ +#define ECONV_UNDEF_REPLACE RUBY_ECONV_UNDEF_REPLACE /**< @old{RUBY_ECONV_UNDEF_REPLACE} */ +#define ECONV_UNDEF_HEX_CHARREF RUBY_ECONV_UNDEF_HEX_CHARREF /**< @old{RUBY_ECONV_UNDEF_HEX_CHARREF} */ +#define ECONV_DECORATOR_MASK RUBY_ECONV_DECORATOR_MASK /**< @old{RUBY_ECONV_DECORATOR_MASK} */ +#define ECONV_NEWLINE_DECORATOR_MASK RUBY_ECONV_NEWLINE_DECORATOR_MASK /**< @old{RUBY_ECONV_NEWLINE_DECORATOR_MASK} */ +#define ECONV_NEWLINE_DECORATOR_READ_MASK RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK /**< @old{RUBY_ECONV_NEWLINE_DECORATOR_READ_MASK} */ +#define ECONV_NEWLINE_DECORATOR_WRITE_MASK RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK /**< @old{RUBY_ECONV_NEWLINE_DECORATOR_WRITE_MASK} */ +#define ECONV_UNIVERSAL_NEWLINE_DECORATOR RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR /**< @old{RUBY_ECONV_UNIVERSAL_NEWLINE_DECORATOR} */ +#define ECONV_CRLF_NEWLINE_DECORATOR RUBY_ECONV_CRLF_NEWLINE_DECORATOR /**< @old{RUBY_ECONV_CRLF_NEWLINE_DECORATOR} */ +#define ECONV_CR_NEWLINE_DECORATOR RUBY_ECONV_CR_NEWLINE_DECORATOR /**< @old{RUBY_ECONV_CR_NEWLINE_DECORATOR} */ +#define ECONV_LF_NEWLINE_DECORATOR RUBY_ECONV_LF_NEWLINE_DECORATOR /**< @old{RUBY_ECONV_LF_NEWLINE_DECORATOR} */ +#define ECONV_XML_TEXT_DECORATOR RUBY_ECONV_XML_TEXT_DECORATOR /**< @old{RUBY_ECONV_XML_TEXT_DECORATOR} */ +#define ECONV_XML_ATTR_CONTENT_DECORATOR RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR /**< @old{RUBY_ECONV_XML_ATTR_CONTENT_DECORATOR} */ +#define ECONV_STATEFUL_DECORATOR_MASK RUBY_ECONV_STATEFUL_DECORATOR_MASK /**< @old{RUBY_ECONV_STATEFUL_DECORATOR_MASK} */ +#define ECONV_XML_ATTR_QUOTE_DECORATOR RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR /**< @old{RUBY_ECONV_XML_ATTR_QUOTE_DECORATOR} */ +#define ECONV_DEFAULT_NEWLINE_DECORATOR RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR /**< @old{RUBY_ECONV_DEFAULT_NEWLINE_DECORATOR} */ + /** @} */ + + /** + * @name Flags for rb_econv_convert() + * + * @{ + */ + + /** Indicates the input is a part of much larger one. */ + RUBY_ECONV_PARTIAL_INPUT = 0x00020000, + + /** Instructs the converter to stop after output. */ + RUBY_ECONV_AFTER_OUTPUT = 0x00040000, +#define ECONV_PARTIAL_INPUT RUBY_ECONV_PARTIAL_INPUT /**< @old{RUBY_ECONV_PARTIAL_INPUT} */ +#define ECONV_AFTER_OUTPUT RUBY_ECONV_AFTER_OUTPUT /**< @old{RUBY_ECONV_AFTER_OUTPUT} */ + + RUBY_ECONV_FLAGS_PLACEHOLDER /**< Placeholder (not used) */ +}; + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_INTERNAL_ENCODING_TRANSCODE_H */ diff --git a/include/ruby/internal/error.h b/include/ruby/internal/error.h index 49e2276cb9..5bf82bfe7d 100644 --- a/include/ruby/internal/error.h +++ b/include/ruby/internal/error.h @@ -50,7 +50,23 @@ typedef enum { /** Warning is for experimental features. */ RB_WARN_CATEGORY_EXPERIMENTAL, - RB_WARN_CATEGORY_ALL_BITS = 0x6 /* no RB_WARN_CATEGORY_NONE bit */ + /** Warning is for performance issues (not enabled by -w). */ + RB_WARN_CATEGORY_PERFORMANCE, + + /** Warning is for checking unused block strictly */ + RB_WARN_CATEGORY_STRICT_UNUSED_BLOCK, + + RB_WARN_CATEGORY_DEFAULT_BITS = ( + (1U << RB_WARN_CATEGORY_DEPRECATED) | + (1U << RB_WARN_CATEGORY_EXPERIMENTAL) | + 0), + + RB_WARN_CATEGORY_ALL_BITS = ( + (1U << RB_WARN_CATEGORY_DEPRECATED) | + (1U << RB_WARN_CATEGORY_EXPERIMENTAL) | + (1U << RB_WARN_CATEGORY_PERFORMANCE) | + (1U << RB_WARN_CATEGORY_STRICT_UNUSED_BLOCK) | + 0) } rb_warning_category_t; /** for rb_readwrite_sys_fail first argument */ @@ -405,11 +421,12 @@ void rb_readwrite_syserr_fail(enum rb_io_wait_readwrite waiting, int err, const RBIMPL_ATTR_COLD() RBIMPL_ATTR_NORETURN() /** + * @private + * * Fails with the given object's type incompatibility to the type. * - * It seems this function is visible from extension libraries only because - * RTYPEDDATA_TYPE() uses it on RUBY_DEBUG. So you can basically ignore it; - * use some other fine-grained method instead. + * This is an implementation detail of Check_Type. People don't use it + * directly. * * @param[in] self The object in question. * @param[in] t Expected type of the object. @@ -469,7 +486,7 @@ VALUE *rb_ruby_debug_ptr(void); */ #define ruby_debug (*rb_ruby_debug_ptr()) -/* reports if `-W' specified */ +/* reports if $VERBOSE is true */ RBIMPL_ATTR_NONNULL((1)) RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) /** @@ -484,7 +501,8 @@ RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) * default, the method just emits its passed contents to ::rb_stderr using * rb_io_write(). * - * @note This function is affected by the `-W` flag. + * @note This function is affected by the value of $VERBOSE, it does + * nothing unless $VERBOSE is true. * @param[in] fmt Format specifier string compatible with rb_sprintf(). * * @internal @@ -509,7 +527,7 @@ RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 3, 4) * Issues a compile-time warning that happens at `__file__:__line__`. Purpose * of this function being exposed to CAPI is unclear. * - * @note This function is affected by the `-W` flag. + * @note This function is affected by the value of $VERBOSE. * @param[in] file The path corresponding to Ruby level `__FILE__`. * @param[in] line The number corresponding to Ruby level `__LINE__`. * @param[in] fmt Format specifier string compatible with rb_sprintf(). @@ -522,19 +540,20 @@ RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) * Identical to rb_sys_fail(), except it does not raise an exception to render * a warning instead. * - * @note This function is affected by the `-W` flag. + * @note This function is affected by the value of $VERBOSE. * @param[in] fmt Format specifier string compatible with rb_sprintf(). */ void rb_sys_warning(const char *fmt, ...); -/* reports always */ +/* reports if $VERBOSE is not nil (so if it is true or false) */ RBIMPL_ATTR_COLD() RBIMPL_ATTR_NONNULL((1)) RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) /** - * Identical to rb_warning(), except it reports always regardless of runtime - * `-W` flag. + * Identical to rb_warning(), except it reports unless $VERBOSE is nil. * + * @note This function is affected by the value of $VERBOSE, it does + * nothing if $VERBOSE is nil. * @param[in] fmt Format specifier string compatible with rb_sprintf(). */ void rb_warn(const char *fmt, ...); @@ -543,8 +562,7 @@ RBIMPL_ATTR_COLD() RBIMPL_ATTR_NONNULL((2)) RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 2, 3) /** - * Identical to rb_category_warning(), except it reports always regardless of - * runtime `-W` flag. + * Identical to rb_category_warning(), except it reports unless $VERBOSE is nil. * * @param[in] cat Category e.g. deprecated. * @param[in] fmt Format specifier string compatible with rb_sprintf(). @@ -554,8 +572,7 @@ void rb_category_warn(rb_warning_category_t cat, const char *fmt, ...); RBIMPL_ATTR_NONNULL((1, 3)) RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 3, 4) /** - * Identical to rb_compile_warning(), except it reports always regardless of - * runtime `-W` flag. + * Identical to rb_compile_warning(), except it reports unless $VERBOSE is nil. * * @param[in] file The path corresponding to Ruby level `__FILE__`. * @param[in] line The number corresponding to Ruby level `__LINE__`. diff --git a/include/ruby/internal/eval.h b/include/ruby/internal/eval.h index 34a53849da..23aa1d9580 100644 --- a/include/ruby/internal/eval.h +++ b/include/ruby/internal/eval.h @@ -28,10 +28,12 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() RBIMPL_ATTR_NONNULL(()) /** - * Evaluates the given string in an isolated binding. + * Evaluates the given string. * - * Here "isolated" means that the binding does not inherit any other - * bindings. This behaves same as the binding for required libraries. + * In case it is called from within a C-backended method, the evaluation is + * done under the current binding. However there can be no method. On such + * situation this function evaluates in an isolated binding, like `require` + * runs in a separate one. * * `__FILE__` will be `"(eval)"`, and `__LINE__` starts from 1 in the * evaluation. @@ -39,6 +41,31 @@ RBIMPL_ATTR_NONNULL(()) * @param[in] str Ruby code to evaluate. * @exception rb_eException Raises an exception on error. * @return The evaluated result. + * + * @internal + * + * @shyouhei's old tale about the birth and growth of this function: + * + * At the beginning, there was no rb_eval_string(). @shyouhei heard that + * @shugo, author of Apache httpd's mod_ruby module, requested @matz for this + * API. He wanted a way so that mod_ruby can evaluate ruby scripts one by one, + * separately, in each different contexts. So this function was made. It was + * designed to be a global interpreter entry point like ruby_run_node(). + * + * The way it is implemented however allows extension libraries (not just + * programs like Apache httpd) to call this function. Because its name says + * nothing about the initial design, people started to think of it as an + * orthodox way to call ruby level `eval` method from their extension + * libraries. Even our `extension.rdoc` has had a description of this function + * basically according to this understanding. + * + * The old (mod_ruby like) usage still works. But over time, usages of this + * function from extension libraries got popular, while mod_ruby faded out; is + * no longer maintained now. Devs decided to actively support both. This + * function now auto-detects how it is called, and switches how it works + * depending on it. + * + * @see https://bugs.ruby-lang.org/issues/18780 */ VALUE rb_eval_string(const char *str); @@ -128,7 +155,8 @@ VALUE rb_funcallv(VALUE recv, ID mid, int argc, const VALUE *argv); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eNoMethodError No such method. * @exception rb_eException Any exceptions happen inside. * @return What the method evaluates to. @@ -162,7 +190,8 @@ VALUE rb_funcallv_public(VALUE recv, ID mid, int argc, const VALUE *argv); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eNoMethodError No such method. * @exception rb_eNoMethodError The method is private or protected. * @exception rb_eException Any exceptions happen inside. @@ -234,7 +263,8 @@ VALUE rb_funcall_passing_block(VALUE recv, ID mid, int argc, const VALUE *argv); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eNoMethodError No such method. * @exception rb_eNoMethodError The method is private or protected. * @exception rb_eException Any exceptions happen inside. @@ -280,7 +310,8 @@ VALUE rb_funcall_with_block(VALUE recv, ID mid, int argc, const VALUE *argv, VAL * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eNoMethodError No such method. * @exception rb_eNoMethodError The method is private or protected. * @exception rb_eException Any exceptions happen inside. @@ -308,7 +339,8 @@ VALUE rb_call_super(int argc, const VALUE *argv); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eNoMethodError No super method are there. * @exception rb_eException Any exceptions happen inside. * @return What the super method evaluates to. diff --git a/include/ruby/internal/event.h b/include/ruby/internal/event.h index 04b137a193..1d194ed618 100644 --- a/include/ruby/internal/event.h +++ b/include/ruby/internal/event.h @@ -23,6 +23,10 @@ #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" +#ifdef HAVE_STDINT_H +#include <stdint.h> +#endif + /* These macros are not enums because they are wider than int.*/ /** @@ -54,6 +58,7 @@ #define RUBY_EVENT_THREAD_END 0x0800 /**< Encountered an end of a thread. */ #define RUBY_EVENT_FIBER_SWITCH 0x1000 /**< Encountered a `Fiber#yield`. */ #define RUBY_EVENT_SCRIPT_COMPILED 0x2000 /**< Encountered an `eval`. */ +#define RUBY_EVENT_RESCUE 0x4000 /**< Encountered a `rescue` statement. */ #define RUBY_EVENT_TRACEPOINT_ALL 0xffff /**< Bitmask of extended events. */ /** @} */ diff --git a/include/ruby/internal/fl_type.h b/include/ruby/internal/fl_type.h index 47f054256b..2afb3f1fa3 100644 --- a/include/ruby/internal/fl_type.h +++ b/include/ruby/internal/fl_type.h @@ -57,13 +57,10 @@ #define FL_SINGLETON RBIMPL_CAST((VALUE)RUBY_FL_SINGLETON) /**< @old{RUBY_FL_SINGLETON} */ #define FL_WB_PROTECTED RBIMPL_CAST((VALUE)RUBY_FL_WB_PROTECTED) /**< @old{RUBY_FL_WB_PROTECTED} */ -#define FL_PROMOTED0 RBIMPL_CAST((VALUE)RUBY_FL_PROMOTED0) /**< @old{RUBY_FL_PROMOTED0} */ -#define FL_PROMOTED1 RBIMPL_CAST((VALUE)RUBY_FL_PROMOTED1) /**< @old{RUBY_FL_PROMOTED1} */ +#define FL_PROMOTED RBIMPL_CAST((VALUE)RUBY_FL_PROMOTED) /**< @old{RUBY_FL_PROMOTED} */ #define FL_FINALIZE RBIMPL_CAST((VALUE)RUBY_FL_FINALIZE) /**< @old{RUBY_FL_FINALIZE} */ -#define FL_TAINT RBIMPL_CAST((VALUE)RUBY_FL_TAINT) /**< @old{RUBY_FL_TAINT} */ #define FL_SHAREABLE RBIMPL_CAST((VALUE)RUBY_FL_SHAREABLE) /**< @old{RUBY_FL_SHAREABLE} */ #define FL_UNTRUSTED RBIMPL_CAST((VALUE)RUBY_FL_UNTRUSTED) /**< @old{RUBY_FL_UNTRUSTED} */ -#define FL_SEEN_OBJ_ID RBIMPL_CAST((VALUE)RUBY_FL_SEEN_OBJ_ID) /**< @old{RUBY_FL_SEEN_OBJ_ID} */ #define FL_EXIVAR RBIMPL_CAST((VALUE)RUBY_FL_EXIVAR) /**< @old{RUBY_FL_EXIVAR} */ #define FL_FREEZE RBIMPL_CAST((VALUE)RUBY_FL_FREEZE) /**< @old{RUBY_FL_FREEZE} */ @@ -111,13 +108,6 @@ #define RB_OBJ_FREEZE_RAW RB_OBJ_FREEZE_RAW #define RB_OBJ_FROZEN RB_OBJ_FROZEN #define RB_OBJ_FROZEN_RAW RB_OBJ_FROZEN_RAW -#define RB_OBJ_INFECT RB_OBJ_INFECT -#define RB_OBJ_INFECT_RAW RB_OBJ_INFECT_RAW -#define RB_OBJ_TAINT RB_OBJ_TAINT -#define RB_OBJ_TAINTABLE RB_OBJ_TAINTABLE -#define RB_OBJ_TAINTED RB_OBJ_TAINTED -#define RB_OBJ_TAINTED_RAW RB_OBJ_TAINTED_RAW -#define RB_OBJ_TAINT_RAW RB_OBJ_TAINT_RAW #define RB_OBJ_UNTRUST RB_OBJ_TAINT #define RB_OBJ_UNTRUSTED RB_OBJ_TAINTED /** @endcond */ @@ -183,7 +173,7 @@ RB_GNUC_EXTENSION * @note About the `FL_USER` terminology: the "user" here does not necessarily * mean only you. For instance struct ::RString instances use these * bits to cache their encodings etc. Devs discussed about this topic, - * reached their concensus that ::RUBY_T_DATA is the only valid data + * reached their consensus that ::RUBY_T_DATA is the only valid data * structure that can use these bits; other data structures including * ::RUBY_T_OBJECT use these bits for their own purpose. See also * https://bugs.ruby-lang.org/issues/18059 @@ -207,12 +197,15 @@ ruby_fl_type { RUBY_FL_WB_PROTECTED = (1<<5), /** - * This flag has something to do with our garbage collector. These days - * ruby objects are "generational". There are those who are young and - * those who are old. Young objects are prone to die; monitored relatively - * extensively by the garbage collector. OTOH old objects tend to live - * longer. They are relatively rarely considered. This flag is set when a - * object experienced promotion i.e. survived a garbage collection. + * Ruby objects are "generational". There are young objects & old objects. + * Young objects are prone to die & monitored relatively extensively by the + * garbage collector. Old objects tend to live longer & are monitored less + * frequently. When an object survives a GC, its age is incremented. When + * age is equal to RVALUE_OLD_AGE, the object becomes Old. This flag is set + * when an object becomes old, and is used by the write barrier to check if + * an old object should be considered for marking more frequently - as old + * objects that have references added between major GCs need to be remarked + * to prevent the referred object being mistakenly swept. * * @internal * @@ -220,41 +213,14 @@ ruby_fl_type { * 3rd parties. It must be an implementation detail that they should never * know. Might better be hidden. */ - RUBY_FL_PROMOTED0 = (1<<5), + RUBY_FL_PROMOTED = (1<<5), /** - * This flag has something to do with our garbage collector. These days - * ruby objects are "generational". There are those who are young and - * those who are old. Young objects are prone to die; monitored relatively - * extensively by the garbage collector. OTOH old objects tend to live - * longer. They are relatively rarely considered. This flag is set when a - * object experienced two promotions i.e. survived garbage collections - * twice. + * This flag meaning is type dependent, currently only used by T_DATA. * * @internal - * - * But honestly, @shyouhei doesn't think this flag should be visible from - * 3rd parties. It must be an implementation detail that they should never - * know. Might better be hidden. */ - RUBY_FL_PROMOTED1 = (1<<6), - - /** - * This flag has something to do with our garbage collector. These days - * ruby objects are "generational". There are those who are young and - * those who are old. Young objects are prone to die; monitored relatively - * extensively by the garbage collector. OTOH old objects tend to live - * longer. They are relatively rarely considered. This flag is set when a - * object experienced promotions i.e. survived more than one garbage - * collections. - * - * @internal - * - * But honestly, @shyouhei doesn't think this flag should be visible from - * 3rd parties. It must be an implementation detail that they should never - * know. Might better be hidden. - */ - RUBY_FL_PROMOTED = RUBY_FL_PROMOTED0 | RUBY_FL_PROMOTED1, + RUBY_FL_USERPRIV0 = (1<<6), /** * This flag has something to do with finalisers. A ruby object can have @@ -271,19 +237,19 @@ ruby_fl_type { RUBY_FL_FINALIZE = (1<<7), /** - * @deprecated This flag once was a thing back in the old days, but makes - * no sense any longer today. Exists here for backwards + * @deprecated This flag was an implementation detail that should never have + * no been exposed. Exists here for backwards * compatibility only. You can safely forget about it. */ - RUBY_FL_TAINT + RUBY_FL_EXIVAR #if defined(RBIMPL_HAVE_ENUM_ATTRIBUTE) - RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) + RBIMPL_ATTR_DEPRECATED(("FL_EXIVAR is an outdated implementation detail, it should not be used.")) #elif defined(_MSC_VER) -# pragma deprecated(RUBY_FL_TAINT) +# pragma deprecated(RUBY_FL_EXIVAR) #endif - = (1<<8), + = 0, /** * This flag has something to do with Ractor. Multiple Ractors run without @@ -297,52 +263,19 @@ ruby_fl_type { */ RUBY_FL_SHAREABLE = (1<<8), - /** - * @deprecated This flag once was a thing back in the old days, but makes - * no sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - */ - RUBY_FL_UNTRUSTED - -#if defined(RBIMPL_HAVE_ENUM_ATTRIBUTE) - RBIMPL_ATTR_DEPRECATED(("trustedness turned out to be a wrong idea.")) -#elif defined(_MSC_VER) -# pragma deprecated(RUBY_FL_UNTRUSTED) -#endif - - = (1<<8), - - /** - * This flag has something to do with object IDs. Unlike in the old days, - * an object's object ID (that a user can query using `Object#object_id`) - * is no longer its physical address represented using Ruby level integers. - * It is now a monotonic-increasing integer unrelated to the underlying - * memory arrangement. Object IDs are assigned when necessary; objects are - * born without one, and will eventually have such property when queried. - * The interpreter has to manage which one is which. This is the flag that - * helps the management. Objects with this flag set are the ones with - * object IDs assigned. - * - * @internal - * - * But honestly, @shyouhei doesn't think this flag should be visible from - * 3rd parties. It must be an implementation detail that they should never - * know. Might better be hidden. - */ - RUBY_FL_SEEN_OBJ_ID = (1<<9), + /** + * This object weakly refers to other objects. + * + * @internal + */ + RUBY_FL_WEAK_REFERENCE = (1<<9), - /** - * This flag has something to do with instance variables. 3rd parties need - * not know, but there are several ways to store an object's instance - * variables. Objects with this flag use so-called "generic" backend - * storage. This distinction is purely an implementation detail. People - * need not be aware of this working behind-the-scene. - * - * @internal - * - * As of writing everything except ::RObject and RModule use this scheme. - */ - RUBY_FL_EXIVAR = (1<<10), + /** + * This flag is no longer in use + * + * @internal + */ + RUBY_FL_UNUSED10 = (1<<10), /** * This flag has something to do with data immutability. When this flag is @@ -402,7 +335,7 @@ ruby_fl_type { * 3rd parties. It must be an implementation detail that they should never * know. Might better be hidden. */ - RUBY_ELTS_SHARED = RUBY_FL_USER2, + RUBY_ELTS_SHARED = RUBY_FL_USER0, /** * This flag has something to do with an object's class. There are kind of @@ -427,36 +360,13 @@ ruby_fl_type { * 3rd parties. It must be an implementation detail that they should never * know. Might better be hidden. */ - RUBY_FL_SINGLETON = RUBY_FL_USER0, -}; - -enum { - /** - * @deprecated This flag once was a thing back in the old days, but makes - * no sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - */ - RUBY_FL_DUPPED - -#if defined(RBIMPL_HAVE_ENUM_ATTRIBUTE) - RBIMPL_ATTR_DEPRECATED(("It seems there is no actual usage of this enum.")) -#elif defined(_MSC_VER) -# pragma deprecated(RUBY_FL_DUPPED) -#endif - - = (int)RUBY_T_MASK | (int)RUBY_FL_EXIVAR + RUBY_FL_SINGLETON = RUBY_FL_USER1, }; #undef RBIMPL_HAVE_ENUM_ATTRIBUTE RBIMPL_SYMBOL_EXPORT_BEGIN() /** - * @deprecated Does nothing. This method is deprecated and will be removed in - * Ruby 3.2. - */ -void rb_obj_infect(VALUE victim, VALUE carrier); - -/** * This is an implementation detail of #RB_OBJ_FREEZE(). People don't use it * directly. * @@ -484,10 +394,8 @@ RB_FL_ABLE(VALUE obj) if (RB_SPECIAL_CONST_P(obj)) { return false; } - else if (RB_TYPE_P(obj, RUBY_T_NODE)) { - return false; - } else { + RBIMPL_ASSERT_OR_ASSUME(!RB_TYPE_P(obj, RUBY_T_NODE)); return true; } } @@ -495,7 +403,7 @@ RB_FL_ABLE(VALUE obj) RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /** - * This is an implenentation detail of RB_FL_TEST(). 3rd parties need not use + * This is an implementation detail of RB_FL_TEST(). 3rd parties need not use * this. Just always use RB_FL_TEST(). * * @param[in] obj Object in question. @@ -543,7 +451,7 @@ RB_FL_TEST(VALUE obj, VALUE flags) RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /** - * This is an implenentation detail of RB_FL_ANY(). 3rd parties need not use + * This is an implementation detail of RB_FL_ANY(). 3rd parties need not use * this. Just always use RB_FL_ANY(). * * @param[in] obj Object in question. @@ -577,7 +485,7 @@ RB_FL_ANY(VALUE obj, VALUE flags) RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() /** - * This is an implenentation detail of RB_FL_ALL(). 3rd parties need not use + * This is an implementation detail of RB_FL_ALL(). 3rd parties need not use * this. Just always use RB_FL_ALL(). * * @param[in] obj Object in question. @@ -613,7 +521,7 @@ RBIMPL_ATTR_ARTIFICIAL() /** * @private * - * This is an implenentation detail of RB_FL_SET(). 3rd parties need not use + * This is an implementation detail of RB_FL_SET(). 3rd parties need not use * this. Just always use RB_FL_SET(). * * @param[out] obj Object in question. @@ -633,7 +541,7 @@ rbimpl_fl_set_raw_raw(struct RBasic *obj, VALUE flags) RBIMPL_ATTR_ARTIFICIAL() /** - * This is an implenentation detail of RB_FL_SET(). 3rd parties need not use + * This is an implementation detail of RB_FL_SET(). 3rd parties need not use * this. Just always use RB_FL_SET(). * * @param[out] obj Object in question. @@ -673,7 +581,7 @@ RBIMPL_ATTR_ARTIFICIAL() /** * @private * - * This is an implenentation detail of RB_FL_UNSET(). 3rd parties need not use + * This is an implementation detail of RB_FL_UNSET(). 3rd parties need not use * this. Just always use RB_FL_UNSET(). * * @param[out] obj Object in question. @@ -693,7 +601,7 @@ rbimpl_fl_unset_raw_raw(struct RBasic *obj, VALUE flags) RBIMPL_ATTR_ARTIFICIAL() /** - * This is an implenentation detail of RB_FL_UNSET(). 3rd parties need not use + * This is an implementation detail of RB_FL_UNSET(). 3rd parties need not use * this. Just always use RB_FL_UNSET(). * * @param[out] obj Object in question. @@ -728,7 +636,7 @@ RBIMPL_ATTR_ARTIFICIAL() /** * @private * - * This is an implenentation detail of RB_FL_REVERSE(). 3rd parties need not + * This is an implementation detail of RB_FL_REVERSE(). 3rd parties need not * use this. Just always use RB_FL_REVERSE(). * * @param[out] obj Object in question. @@ -748,7 +656,7 @@ rbimpl_fl_reverse_raw_raw(struct RBasic *obj, VALUE flags) RBIMPL_ATTR_ARTIFICIAL() /** - * This is an implenentation detail of RB_FL_REVERSE(). 3rd parties need not + * This is an implementation detail of RB_FL_REVERSE(). 3rd parties need not * use this. Just always use RB_FL_REVERSE(). * * @param[out] obj Object in question. @@ -781,121 +689,8 @@ RB_FL_REVERSE(VALUE obj, VALUE flags) RBIMPL_ATTR_PURE_UNLESS_DEBUG() RBIMPL_ATTR_ARTIFICIAL() -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return false always. - */ -static inline bool -RB_OBJ_TAINTABLE(VALUE obj) -{ - return false; -} - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) /** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return false always. - */ -static inline VALUE -RB_OBJ_TAINTED_RAW(VALUE obj) -{ - return false; -} - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return false always. - */ -static inline bool -RB_OBJ_TAINTED(VALUE obj) -{ - return false; -} - -RBIMPL_ATTR_ARTIFICIAL() -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - */ -static inline void -RB_OBJ_TAINT_RAW(VALUE obj) -{ - return; -} - -RBIMPL_ATTR_ARTIFICIAL() -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - */ -static inline void -RB_OBJ_TAINT(VALUE obj) -{ - return; -} - -RBIMPL_ATTR_ARTIFICIAL() -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] dst Victim object. - * @param[in] src Infectant object. - */ -static inline void -RB_OBJ_INFECT_RAW(VALUE dst, VALUE src) -{ - return; -} - -RBIMPL_ATTR_ARTIFICIAL() -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] dst Victim object. - * @param[in] src Infectant object. - */ -static inline void -RB_OBJ_INFECT(VALUE dst, VALUE src) -{ - return; -} - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -/** - * This is an implenentation detail of RB_OBJ_FROZEN(). 3rd parties need not + * This is an implementation detail of RB_OBJ_FROZEN(). 3rd parties need not * use this. Just always use RB_OBJ_FROZEN(). * * @param[in] obj Object in question. @@ -934,34 +729,29 @@ RB_OBJ_FROZEN(VALUE obj) } } -RBIMPL_ATTR_ARTIFICIAL() +RUBY_SYMBOL_EXPORT_BEGIN /** - * This is an implenentation detail of RB_OBJ_FREEZE(). 3rd parties need not - * use this. Just always use RB_OBJ_FREEZE(). + * Prevents further modifications to the given object. ::rb_eFrozenError shall + * be raised if modification is attempted. * - * @param[out] obj Object in question. + * @param[out] x Object in question. + * @exception rb_eNoMemError Failed to allocate memory for the frozen + * representation of the object. */ -static inline void -RB_OBJ_FREEZE_RAW(VALUE obj) -{ - RB_FL_SET_RAW(obj, RUBY_FL_FREEZE); -} +void rb_obj_freeze_inline(VALUE obj); +RUBY_SYMBOL_EXPORT_END +RBIMPL_ATTR_ARTIFICIAL() /** - * Prevents further modifications to the given object. ::rb_eFrozenError shall - * be raised if modification is attempted. + * This is an implementation detail of RB_OBJ_FREEZE(). 3rd parties need not + * use this. Just always use RB_OBJ_FREEZE(). * - * @param[out] x Object in question. + * @param[out] obj Object in question. */ static inline void -rb_obj_freeze_inline(VALUE x) +RB_OBJ_FREEZE_RAW(VALUE obj) { - if (RB_FL_ABLE(x)) { - RB_OBJ_FREEZE_RAW(x); - if (RBASIC_CLASS(x) && !(RBASIC(x)->flags & RUBY_FL_SINGLETON)) { - rb_freeze_singleton_class(x); - } - } + rb_obj_freeze_inline(obj); } #endif /* RBIMPL_FL_TYPE_H */ diff --git a/include/ruby/internal/gc.h b/include/ruby/internal/gc.h index 66fc14e511..21c2b670b3 100644 --- a/include/ruby/internal/gc.h +++ b/include/ruby/internal/gc.h @@ -20,16 +20,379 @@ * extension libraries. They could be written in C++98. * @brief Registering values to the GC. */ +#include "ruby/internal/config.h" + +#ifdef STDC_HEADERS +# include <stddef.h> /* size_t */ +#endif + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> /* ssize_t */ +#endif + +#include "ruby/assert.h" +#include "ruby/internal/attr/cold.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/attr/noreturn.h" +#include "ruby/internal/attr/artificial.h" +#include "ruby/internal/attr/maybe_unused.h" +#include "ruby/internal/attr/pure.h" #include "ruby/internal/dllexport.h" +#include "ruby/internal/special_consts.h" +#include "ruby/internal/stdbool.h" #include "ruby/internal/value.h" RBIMPL_SYMBOL_EXPORT_BEGIN() +#define RUBY_REF_EDGE(s, p) offsetof(s, p) +#define RUBY_REFS_LIST_PTR(l) (RUBY_DATA_FUNC)(uintptr_t)(l) +#define RUBY_REF_END SIZE_MAX +#define RUBY_REFERENCES(t) static const size_t t[] +#define RUBY_REFERENCES_START(t) RUBY_REFERENCES(t) = { +#define RUBY_REFERENCES_END RUBY_REF_END, }; + +/* gc.c */ + +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_NORETURN() +/** + * Triggers out-of-memory error. If possible it raises ::rb_eNoMemError. But + * because we are running out of memory that is not always doable. This + * function tries hard to show something, but ultimately can die silently. + * + * @exception rb_eNoMemError Raises it if possible. + */ +void rb_memerror(void); + +RBIMPL_ATTR_PURE() +/** + * Queries if the GC is busy. + * + * @retval 0 It isn't. + * @retval 1 It is. + */ +int rb_during_gc(void); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Marks objects between the two pointers. This is one of the GC utility + * functions that you can call when you design your own + * ::rb_data_type_struct::dmark. + * + * @pre Continuous memory region from `start` to `end` shall be fully + * addressable. + * @param[out] start Pointer to an array of objects. + * @param[out] end Pointer that terminates the array of objects. + * @post Objects from `start` (included) to `end` (excluded) are marked. + * + * @internal + * + * `end` can be NULL... But that just results in no-op. + */ +void rb_gc_mark_locations(const VALUE *start, const VALUE *end); + +/** + * Identical to rb_mark_hash(), except it marks only values of the table and + * leave their associated keys unmarked. This is one of the GC utility + * functions that you can call when you design your own + * ::rb_data_type_struct::dmark. + * + * @warning Of course it can break GC. Leave it unused if unsure. + * @param[in] tbl A table to mark. + * @post Values stored in `tbl` are marked. + */ +void rb_mark_tbl(struct st_table *tbl); + +/** + * Identical to rb_mark_tbl(), except it marks objects using + * rb_gc_mark_movable(). This is one of the GC utility functions that you can + * call when you design your own ::rb_data_type_struct::dmark. + * + * @warning Of course it can break GC. Leave it unused if unsure. + * @param[in] tbl A table to mark. + * @post Values stored in `tbl` are marked. + */ +void rb_mark_tbl_no_pin(struct st_table *tbl); + +/** + * Identical to rb_mark_hash(), except it marks only keys of the table and + * leave their associated values unmarked. This is one of the GC utility + * functions that you can call when you design your own + * ::rb_data_type_struct::dmark. + * + * @warning Of course it can break GC. Leave it unused if unsure. + * @param[in] tbl A table to mark. + * @post Keys stored in `tbl` are marked. + */ +void rb_mark_set(struct st_table *tbl); + /** - * Inform the garbage collector that `valptr` points to a live Ruby object that - * should not be moved. Note that extensions should use this API on global - * constants instead of assuming constants defined in Ruby are always alive. - * Ruby code can remove global constants. + * Marks keys and values associated inside of the given table. This is one of + * the GC utility functions that you can call when you design your own + * ::rb_data_type_struct::dmark. + * + * @param[in] tbl A table to mark. + * @post Objects stored in `tbl` are marked. + */ +void rb_mark_hash(struct st_table *tbl); + +/** + * Updates references inside of tables. After you marked values using + * rb_mark_tbl_no_pin(), the objects inside of the table could of course be + * moved. This function is to fixup those references. You can call this from + * your ::rb_data_type_struct::dcompact. + * + * @param[out] ptr A table that potentially includes moved references. + * @post Moved references, if any, are corrected. + */ +void rb_gc_update_tbl_refs(st_table *ptr); + +/** + * Identical to rb_gc_mark(), except it allows the passed value be a + * non-object. For instance pointers to different type of memory regions are + * allowed here. Such values are silently ignored. This is one of the GC + * utility functions that you can call when you design your own + * ::rb_data_type_struct::dmark. + * + * @param[out] obj A possible object. + * @post `obj` is marked, if possible. + */ +void rb_gc_mark_maybe(VALUE obj); + +/** + * Marks an object. This is one of the GC utility functions that you can call + * when you design your own ::rb_data_type_struct::dmark. + * + * @param[out] obj Arbitrary Ruby object. + * @post `obj` is marked. + */ +void rb_gc_mark(VALUE obj); + +/** + * Maybe this is the only function provided for C extensions to control the + * pinning of objects, so let us describe it in detail. These days Ruby's GC + * is copying. As far as an object's physical address is guaranteed unused, it + * can move around the object space. Our GC engine rearranges these objects + * after it reclaims unreachable objects from our object space, so that the + * space is compact (improves memory locality). This is called the + * "compaction" phase, and works well most of the time... as far as there are + * no C extensions. C extensions complicate the scenario because Ruby core + * cannot detect any use of the physical address of an object inside of C + * functions. In order to prevent memory corruptions, objects observable from + * C extensions are "pinned"; they stick to where they are born until they die, + * just in case any C extensions touch their raw pointers. This variant of + * scheme is called "Mostly-Copying" garbage collector. Authors of C + * extensions, however, can extremely carefully write them to become + * compaction-aware. To do so avoid referring to a Ruby object from inside of + * your struct in the first place. But if that is not possible, use this + * function from your ::rb_data_type_struct::dmark then. This way objects + * marked using it are considered movable. If you chose this way you have to + * manually fix up locations of such moved pointers using rb_gc_location(). + * + * @see Bartlett, Joel F., "Compacting Garbage Collection with Ambiguous + * Roots", ACM SIGPLAN Lisp Pointers Volume 1 Issue 6 pp. 3-12, + * April-May-June, 1988. https://doi.org/10.1145/1317224.1317225 + * + * @param[in] obj Object that is movable. + * @post Values stored in `tbl` are marked. + */ +void rb_gc_mark_movable(VALUE obj); + +/** + * Finds a new "location" of an object. An object can be moved on compaction. + * This function projects its new abode, or just returns the passed object if + * not moved. This is one of the GC utility functions that you can call when + * you design your own ::rb_data_type_struct::dcompact. + * + * @param[in] obj An object, possibly already moved to somewhere else. + * @return An object, which holds the current contents of former `obj`. + */ +VALUE rb_gc_location(VALUE obj); + +/** + * Triggers a GC process. This was the only GC entry point that we had at the + * beginning. Over time our GC evolved. Now what this function does is just a + * very simplified variation of the entire GC algorithms. A series of + * procedures kicked by this API is called a "full" GC. + * + * - It immediately scans the entire object space to sort the dead. + * - It immediately reclaims any single dead bodies to reuse later. + * + * It is worth noting that the procedures above do not include evaluations of + * finalisers. They run later. + * + * @internal + * + * Finalisers are deferred until we can handle interrupts. See + * `rb_postponed_job_flush` in vm_trace.c. + * + * Of course there are GC that are not "full". For instance this one and the + * GC which runs when we are running out of memory are different. See + * `gc_profile_record_flag` defined in gc.c for the kinds of GC. + * + * In spite of the name this is not what everything that a GC can trigger. As + * of writing it seems this function does not trigger compaction. But this + * might change in future. + */ +void rb_gc(void); + +/** + * Copy&paste an object's finaliser to another. This is one of the GC utility + * functions that you can call when you design your own `initialize_copy`, + * `initialize_dup`, `initialize_clone`. + * + * @param[out] dst Destination object. + * @param[in] src Source object. + * @post `dst` and `src` share the same finaliser. + * + * @internal + * + * But isn't it easier for you to call super, and let `Object#initialize_copy` + * call this function instead? + */ +void rb_gc_copy_finalizer(VALUE dst, VALUE src); + +/** + * (Re-) enables GC. This makes sense only after you called rb_gc_disable(). + * + * @retval RUBY_Qtrue GC was disabled before. + * @retval RUBY_Qfalse GC was enabled before. + * @post GC is enabled. + * + * @internal + * + * This is one of such exceptional functions that does not raise both Ruby + * exceptions and C++ exceptions. + */ +VALUE rb_gc_enable(void); + +/** + * Disables GC. This prevents automatic GC runs when the process is running + * out of memory. Such situations shall result in rb_memerror(). However this + * does not prevent users from manually invoking rb_gc(). That should work. + * People abused this by disabling GC at the beginning of an event loop, + * process events without GC overheads, then manually force reclaiming garbage + * at the bottom of the loop. However because our GC is now much smarter than + * just calling rb_gc(), this technique is proven to be sub-optimal these days. + * It is believed that there is currently practically no needs of this + * function. + * + * @retval RUBY_Qtrue GC was disabled before. + * @retval RUBY_Qfalse GC was enabled before. + * @post GC is disabled. + */ +VALUE rb_gc_disable(void); + +/** + * Identical to rb_gc(), except the return value. + * + * @return Always returns ::RUBY_Qnil. + */ +VALUE rb_gc_start(void); + +/** + * Assigns a finaliser for an object. Each objects can have objects (typically + * blocks) that run immediately after that object dies. They are called + * finalisers of an object. This function associates a finaliser object with a + * target object. + * + * @note Note that finalisers run _after_ the object they finalise dies. You + * cannot for instance call its methods. + * @note If your finaliser references the object it finalises that object + * loses any chance to become a garbage; effectively leaks memory until + * the end of the process. + * + * @param[in] obj Target to finalise. + * @param[in] block Something `call`able. + * @exception rb_eRuntimeError Somehow `obj` cannot have finalisers. + * @exception rb_eFrozenError `obj` is frozen. + * @exception rb_eArgError `block` doesn't respond to `call`. + * @return The passed `block`. + * @post `block` runs after `obj` dies. + */ +VALUE rb_define_finalizer(VALUE obj, VALUE block); + +/** + * Modifies the object so that it has no finalisers at all. This function is + * mainly provided for symmetry. No practical usages can be thought of. + * + * @param[out] obj Object to clear its finalisers. + * @exception rb_eFrozenError `obj` is frozen. + * @return The passed `obj`. + * @post `obj` has no finalisers. + * @note There is no way to undefine a specific part of many finalisers + * that `obj` could have. All you can do is to clear them all. + */ +VALUE rb_undefine_finalizer(VALUE obj); + +/** + * Identical to rb_gc_stat(), with "count" parameter. + * + * @return Lifetime total number of runs of GC. + */ +size_t rb_gc_count(void); + +/** + * Obtains various GC related profiles. The parameter can be either a Symbol + * or a Hash. If a Hash is passed, it is filled with everything currently + * available. If a Symbol is passed just that portion is returned. + * + * Possible variations of keys you can pass here change from version to + * version. You can get the list of known keys by passing an empty hash and + * let it be filled. + * + * @param[in,out] key_or_buf A Symbol, or a Hash. + * @exception rb_eTypeError Neither Symbol nor Hash. + * @exception rb_eFrozenError Frozen hash is passed. + * @return In case a Hash is passed it returns 0. Otherwise the + * profile value associated with the given key is returned. + * @post In case a Hash is passed it is filled with values. + */ +size_t rb_gc_stat(VALUE key_or_buf); + +/** + * Obtains various info regarding the most recent GC run. This includes for + * instance the reason of the GC. The parameter can be either a Symbol or a + * Hash. If a Hash is passed, it is filled with everything currently + * available. If a Symbol is passed just that portion is returned. + * + * Possible variations of keys you can pass here change from version to + * version. You can get the list of known keys by passing an empty hash and + * let it be filled. + * + * @param[in,out] key_or_buf A Symbol, or a Hash. + * @exception rb_eTypeError Neither Symbol nor Hash. + * @exception rb_eFrozenError Frozen hash is passed. + * @return In case a Hash is passed it returns that hash. Otherwise + * the profile value associated with the given key is returned. + * @post In case a Hash is passed it is filled with values. + */ +VALUE rb_gc_latest_gc_info(VALUE key_or_buf); + +/** + * Informs that there are external memory usages. Our GC runs when we are + * running out of memory. The amount of memory, however, can increase/decrease + * behind-the-scene. For instance DLLs can allocate memories using `mmap(2)` + * etc, which are opaque to us. Registering such external allocations using + * this function enables proper detection of how much memories an object used + * as a whole. That will trigger GCs more often than it would otherwise. You + * can also pass negative numbers here, to indicate that such external + * allocations are gone. + * + * @param[in] diff Amount of memory increased(+)/decreased(-). + */ +void rb_gc_adjust_memory_usage(ssize_t diff); + +/** + * Inform the garbage collector that the global or static variable pointed by + * `valptr` stores a live Ruby object that should not be moved. Note that + * extensions should use this API on global constants instead of assuming + * constants defined in Ruby are always alive. Ruby code can remove global + * constants. + * + * Because this registration itself has a possibility to trigger a GC, this + * function must be called before any GC-able objects is assigned to the + * address pointed by `valptr`. */ void rb_gc_register_address(VALUE *valptr); @@ -54,4 +417,410 @@ void rb_gc_register_mark_object(VALUE object); RBIMPL_SYMBOL_EXPORT_END() +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ +#undef USE_RGENGC +#define USE_RGENGC 1 + +/** + * @deprecated This macro seems broken. Setting this to anything other than + * zero just doesn't compile. We need to KonMari. + */ +#ifndef USE_RGENGC_LOGGING_WB_UNPROTECT +# define USE_RGENGC_LOGGING_WB_UNPROTECT 0 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RArray. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_ARRAY +# define RGENGC_WB_PROTECTED_ARRAY 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RHash. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_HASH +# define RGENGC_WB_PROTECTED_HASH 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RStruct. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_STRUCT +# define RGENGC_WB_PROTECTED_STRUCT 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RString. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_STRING +# define RGENGC_WB_PROTECTED_STRING 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RObject. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_OBJECT +# define RGENGC_WB_PROTECTED_OBJECT 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RRegexp. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_REGEXP +# define RGENGC_WB_PROTECTED_REGEXP 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RMatch. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_MATCH +# define RGENGC_WB_PROTECTED_MATCH 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RClass. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_CLASS +# define RGENGC_WB_PROTECTED_CLASS 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RFloat. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_FLOAT +# define RGENGC_WB_PROTECTED_FLOAT 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RComplex. It has to be set at the time ruby itself compiles. + * Makes no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_COMPLEX +# define RGENGC_WB_PROTECTED_COMPLEX 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RRational. It has to be set at the time ruby itself compiles. + * Makes no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_RATIONAL +# define RGENGC_WB_PROTECTED_RATIONAL 1 +#endif + +/** + * @private + * + * This is a compile-time flag to enable/disable write barrier for + * struct ::RBignum. It has to be set at the time ruby itself compiles. Makes + * no sense for 3rd parties. + */ +#ifndef RGENGC_WB_PROTECTED_BIGNUM +# define RGENGC_WB_PROTECTED_BIGNUM 1 +#endif + +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + * + * @internal + * + * @shyouhei doesn't think anybody uses this right now. + */ +#ifndef RGENGC_WB_PROTECTED_NODE_CREF +# define RGENGC_WB_PROTECTED_NODE_CREF 1 +#endif + +/** + * @defgroup rgengc Write barrier (WB) interfaces: + * + * @note The following core interfaces can be changed in the future. Please + * catch up if you want to insert WB into C-extensions correctly. + * + * @{ + */ + +/** + * Declaration of a "back" pointer. This is a write barrier for new reference + * from "old" generation to "young" generation. It writes `young` into + * `*slot`, which is a pointer inside of `old`. + * + * @param[in] old An old object. + * @param[in] slot A pointer inside of `old`. + * @param[out] young A young object. + */ +#define RB_OBJ_WRITE(old, slot, young) \ + RBIMPL_CAST(rb_obj_write((VALUE)(old), (VALUE *)(slot), (VALUE)(young), __FILE__, __LINE__)) + +/** + * Identical to #RB_OBJ_WRITE(), except it doesn't write any values, but only a + * WB declaration. `oldv` is replaced value with `b` (not used in current + * Ruby). + * + * @param[in] old An old object. + * @param[in] oldv An object previously stored inside of `old`. + * @param[out] young A young object. + */ +#define RB_OBJ_WRITTEN(old, oldv, young) \ + RBIMPL_CAST(rb_obj_written((VALUE)(old), (VALUE)(oldv), (VALUE)(young), __FILE__, __LINE__)) +/** @} */ + +#define OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW /**< @old{RB_OBJ_PROMOTED_RAW} */ +#define OBJ_PROMOTED RB_OBJ_PROMOTED /**< @old{RB_OBJ_PROMOTED} */ +#define OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT /**< @old{RB_OBJ_WB_UNPROTECT} */ + +/** + * Asserts that the passed object is not fenced by write barriers. Objects of + * such property do not contribute to generational GCs. They are scanned + * always. + * + * @param[out] x An object that would not be protected by the barrier. + */ +#define RB_OBJ_WB_UNPROTECT(x) rb_obj_wb_unprotect(x, __FILE__, __LINE__) + +/** + * Identical to #RB_OBJ_WB_UNPROTECT(), except it can also assert that the + * given object is of given type. + * + * @param[in] type One of `ARRAY`, `STRING`, etc. + * @param[out] obj An object of `type` that would not be protected. + * + * @internal + * + * @shyouhei doesn't understand why this has to be visible from extensions. + */ +#define RB_OBJ_WB_UNPROTECT_FOR(type, obj) \ + (RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj) + +/** + * @private + * + * This is an implementation detail of rb_obj_wb_unprotect(). People don't use + * it directly. + */ +#define RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging + +/** @cond INTERNAL_MACRO */ +#define RB_OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW +#define RB_OBJ_PROMOTED RB_OBJ_PROMOTED +/** @endcond */ + +RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * This is the implementation of #RB_OBJ_WRITE(). People don't use it + * directly. + * + * @param[in] old An object that points to `young`. + * @param[out] young An object that is referenced from `old`. + */ +void rb_gc_writebarrier(VALUE old, VALUE young); + +/** + * This is the implementation of #RB_OBJ_WB_UNPROTECT(). People don't use it + * directly. + * + * @param[out] obj An object that does not participate in WB. + */ +void rb_gc_writebarrier_unprotect(VALUE obj); + +#if USE_RGENGC_LOGGING_WB_UNPROTECT +/** + * @private + * + * This is the implementation of #RGENGC_LOGGING_WB_UNPROTECT(). People + * don't use it directly. + * + * @param[in] objptr Don't know why this is a pointer to void but in + * reality this is a pointer to an object that is about + * to be un-protected. + * @param[in] filename Pass C's `__FILE__` here. + * @param[in] line Pass C's `__LINE__` here. + */ +void rb_gc_unprotect_logging(void *objptr, const char *filename, int line); +#endif + +RBIMPL_SYMBOL_EXPORT_END() + +RBIMPL_ATTR_PURE_UNLESS_DEBUG() +RBIMPL_ATTR_ARTIFICIAL() +/** + * This is the implementation of #RB_OBJ_PROMOTED(). People don't use it + * directly. + * + * @param[in] obj An object to query. + * @retval true The object is "promoted". + * @retval false The object is young. Have not experienced GC at all. + */ +static inline bool +RB_OBJ_PROMOTED_RAW(VALUE obj) +{ + RBIMPL_ASSERT_OR_ASSUME(RB_FL_ABLE(obj)); + return RB_FL_ANY_RAW(obj, RUBY_FL_PROMOTED); +} + +RBIMPL_ATTR_PURE_UNLESS_DEBUG() +RBIMPL_ATTR_ARTIFICIAL() +/** + * Tests if the object is "promoted" -- that is, whether the object experienced + * one or more GC marks. + * + * @param[in] obj An object to query. + * @retval true The object is "promoted". + * @retval false The object is young. Have not experienced GC at all. + * @note Hello, is anyone actively calling this function? @shyouhei have + * never seen any actual usages outside of the GC implementation + * itself. + */ +static inline bool +RB_OBJ_PROMOTED(VALUE obj) +{ + if (! RB_FL_ABLE(obj)) { + return false; + } + else { + return RB_OBJ_PROMOTED_RAW(obj); + } +} + +/** + * This is the implementation of #RB_OBJ_WB_UNPROTECT(). People don't use it + * directly. + * + * @param[out] x An object that does not participate in WB. + * @param[in] filename C's `__FILE__` of the caller function. + * @param[in] line C's `__LINE__` of the caller function. + * @return x + */ +static inline VALUE +rb_obj_wb_unprotect( + VALUE x, + RBIMPL_ATTR_MAYBE_UNUSED() + const char *filename, + RBIMPL_ATTR_MAYBE_UNUSED() + int line) +{ +#if USE_RGENGC_LOGGING_WB_UNPROTECT + RGENGC_LOGGING_WB_UNPROTECT(RBIMPL_CAST((void *)x), filename, line); +#endif + rb_gc_writebarrier_unprotect(x); + return x; +} + +/** + * @private + * + * This is the implementation of #RB_OBJ_WRITTEN(). People don't use it + * directly. + * + * @param[in] a An old object. + * @param[in] oldv An object previously stored inside of `old`. + * @param[out] b A young object. + * @param[in] filename C's `__FILE__` of the caller function. + * @param[in] line C's `__LINE__` of the caller function. + * @return a + */ +static inline VALUE +rb_obj_written( + VALUE a, + RBIMPL_ATTR_MAYBE_UNUSED() + VALUE oldv, + VALUE b, + RBIMPL_ATTR_MAYBE_UNUSED() + const char *filename, + RBIMPL_ATTR_MAYBE_UNUSED() + int line) +{ +#if USE_RGENGC_LOGGING_WB_UNPROTECT + RGENGC_LOGGING_OBJ_WRITTEN(a, oldv, b, filename, line); +#endif + + if (!RB_SPECIAL_CONST_P(b)) { + rb_gc_writebarrier(a, b); + } + + return a; +} + +/** + * @private + * + * This is the implementation of #RB_OBJ_WRITE(). People don't use it + * directly. + * + * @param[in] a An old object. + * @param[in] slot A pointer inside of `old`. + * @param[out] b A young object. + * @param[in] filename C's `__FILE__` of the caller function. + * @param[in] line C's `__LINE__` of the caller function. + * @return a + */ +static inline VALUE +rb_obj_write( + VALUE a, VALUE *slot, VALUE b, + RBIMPL_ATTR_MAYBE_UNUSED() + const char *filename, + RBIMPL_ATTR_MAYBE_UNUSED() + int line) +{ +#ifdef RGENGC_LOGGING_WRITE + RGENGC_LOGGING_WRITE(a, slot, b, filename, line); +#endif + + *slot = b; + + rb_obj_written(a, RUBY_Qundef /* ignore `oldv' now */, b, filename, line); + return a; +} + #endif /* RBIMPL_GC_H */ diff --git a/include/ruby/internal/globals.h b/include/ruby/internal/globals.h index b478e30b04..9beb215c0c 100644 --- a/include/ruby/internal/globals.h +++ b/include/ruby/internal/globals.h @@ -68,6 +68,7 @@ RUBY_EXTERN VALUE rb_cBasicObject; /**< `BasicObject` class. */ RUBY_EXTERN VALUE rb_cObject; /**< `Object` class. */ RUBY_EXTERN VALUE rb_cArray; /**< `Array` class. */ RUBY_EXTERN VALUE rb_cBinding; /**< `Binding` class. */ +RUBY_EXTERN VALUE rb_cBox; /**< `Ruby::Box` class. */ RUBY_EXTERN VALUE rb_cClass; /**< `Class` class. */ RUBY_EXTERN VALUE rb_cDir; /**< `Dir` class. */ RUBY_EXTERN VALUE rb_cEncoding; /**< `Encoding` class. */ @@ -82,6 +83,7 @@ RUBY_EXTERN VALUE rb_cInteger; /**< `Module` class. */ RUBY_EXTERN VALUE rb_cMatch; /**< `MatchData` class. */ RUBY_EXTERN VALUE rb_cMethod; /**< `Method` class. */ RUBY_EXTERN VALUE rb_cModule; /**< `Module` class. */ +RUBY_EXTERN VALUE rb_cRefinement; /**< `Refinement` class. */ RUBY_EXTERN VALUE rb_cNameErrorMesg; /**< `NameError::Message` class. */ RUBY_EXTERN VALUE rb_cNilClass; /**< `NilClass` class. */ RUBY_EXTERN VALUE rb_cNumeric; /**< `Numeric` class. */ @@ -90,10 +92,11 @@ RUBY_EXTERN VALUE rb_cRandom; /**< `Random` class. */ RUBY_EXTERN VALUE rb_cRange; /**< `Range` class. */ RUBY_EXTERN VALUE rb_cRational; /**< `Rational` class. */ RUBY_EXTERN VALUE rb_cRegexp; /**< `Regexp` class. */ +RUBY_EXTERN VALUE rb_cSet; /**< `Set` class. */ RUBY_EXTERN VALUE rb_cStat; /**< `File::Stat` class. */ RUBY_EXTERN VALUE rb_cString; /**< `String` class. */ RUBY_EXTERN VALUE rb_cStruct; /**< `Struct` class. */ -RUBY_EXTERN VALUE rb_cSymbol; /**< `Sumbol` class. */ +RUBY_EXTERN VALUE rb_cSymbol; /**< `Symbol` class. */ RUBY_EXTERN VALUE rb_cThread; /**< `Thread` class. */ RUBY_EXTERN VALUE rb_cTime; /**< `Time` class. */ RUBY_EXTERN VALUE rb_cTrueClass; /**< `TrueClass` class. */ diff --git a/include/ruby/internal/has/builtin.h b/include/ruby/internal/has/builtin.h index 957aff8375..8e7fb173d8 100644 --- a/include/ruby/internal/has/builtin.h +++ b/include/ruby/internal/has/builtin.h @@ -48,13 +48,16 @@ # /* https://gcc.gnu.org/bugzilla/show_bug.cgi?id=66970 */ # define RBIMPL_HAS_BUILTIN(_) (RBIMPL_HAS_BUILTIN_ ## _) # define RBIMPL_HAS_BUILTIN___builtin_add_overflow RBIMPL_COMPILER_SINCE(GCC, 5, 1, 0) +# define RBIMPL_HAS_BUILTIN___builtin_add_overflow_p RBIMPL_COMPILER_SINCE(GCC, 7, 0, 0) # define RBIMPL_HAS_BUILTIN___builtin_alloca RBIMPL_COMPILER_SINCE(GCC, 0, 0, 0) # define RBIMPL_HAS_BUILTIN___builtin_alloca_with_align RBIMPL_COMPILER_SINCE(GCC, 6, 1, 0) # define RBIMPL_HAS_BUILTIN___builtin_assume 0 # /* See http://gcc.gnu.org/bugzilla/show_bug.cgi?id=52624 for bswap16. */ # define RBIMPL_HAS_BUILTIN___builtin_bswap16 RBIMPL_COMPILER_SINCE(GCC, 4, 8, 0) +#ifndef __OpenBSD__ # define RBIMPL_HAS_BUILTIN___builtin_bswap32 RBIMPL_COMPILER_SINCE(GCC, 3, 6, 0) # define RBIMPL_HAS_BUILTIN___builtin_bswap64 RBIMPL_COMPILER_SINCE(GCC, 3, 6, 0) +#endif # define RBIMPL_HAS_BUILTIN___builtin_clz RBIMPL_COMPILER_SINCE(GCC, 3, 6, 0) # define RBIMPL_HAS_BUILTIN___builtin_clzl RBIMPL_COMPILER_SINCE(GCC, 3, 6, 0) # define RBIMPL_HAS_BUILTIN___builtin_clzll RBIMPL_COMPILER_SINCE(GCC, 3, 6, 0) @@ -73,17 +76,15 @@ # define RBIMPL_HAS_BUILTIN___builtin_rotateright32 0 # define RBIMPL_HAS_BUILTIN___builtin_rotateright64 0 # define RBIMPL_HAS_BUILTIN___builtin_sub_overflow RBIMPL_COMPILER_SINCE(GCC, 5, 1, 0) +# define RBIMPL_HAS_BUILTIN___builtin_sub_overflow_p RBIMPL_COMPILER_SINCE(GCC, 7, 0, 0) # define RBIMPL_HAS_BUILTIN___builtin_unreachable RBIMPL_COMPILER_SINCE(GCC, 4, 5, 0) # /* Note that "0, 0, 0" might be inaccurate. */ -#elif RBIMPL_COMPILER_IS(MSVC) -# /* MSVC has UNREACHABLE, but that is not __builtin_unreachable. */ -# define RBIMPL_HAS_BUILTIN(_) 0 - #else # /* Take config.h definition when available */ # define RBIMPL_HAS_BUILTIN(_) ((RBIMPL_HAS_BUILTIN_ ## _)+0) # define RBIMPL_HAS_BUILTIN___builtin_add_overflow HAVE_BUILTIN___BUILTIN_ADD_OVERFLOW +# define RBIMPL_HAS_BUILTIN___builtin_add_overflow_p HAVE_BUILTIN___BUILTIN_ADD_OVERFLOW_P # define RBIMPL_HAS_BUILTIN___builtin_alloca 0 # define RBIMPL_HAS_BUILTIN___builtin_alloca_with_align HAVE_BUILTIN___BUILTIN_ALLOCA_WITH_ALIGN # define RBIMPL_HAS_BUILTIN___builtin_assume 0 @@ -109,7 +110,8 @@ # define RBIMPL_HAS_BUILTIN___builtin_rotateright64 0 # define RBIMPL_HAS_BUILTIN___builtin_popcountll HAVE_BUILTIN___BUILTIN_POPCOUNTLL # define RBIMPL_HAS_BUILTIN___builtin_sub_overflow HAVE_BUILTIN___BUILTIN_SUB_OVERFLOW -# if defined(UNREACHABLE) +# define RBIMPL_HAS_BUILTIN___builtin_sub_overflow_p HAVE_BUILTIN___BUILTIN_SUB_OVERFLOW_P +# if defined(HAVE___BUILTIN_UNREACHABLE) # define RBIMPL_HAS_BUILTIN___builtin_unreachable 1 # else # define RBIMPL_HAS_BUILTIN___builtin_unreachable 0 diff --git a/include/ruby/internal/has/c_attribute.h b/include/ruby/internal/has/c_attribute.h index c5c48867bf..69b0f402cd 100644 --- a/include/ruby/internal/has/c_attribute.h +++ b/include/ruby/internal/has/c_attribute.h @@ -21,11 +21,23 @@ * @brief Defines #RBIMPL_HAS_C_ATTRIBUTE. */ +#include "ruby/internal/has/extension.h" +#include "ruby/internal/has/warning.h" + /** Wraps (or simulates) `__has_c_attribute`. */ #if defined(__cplusplus) # /* Makes no sense. */ # define RBIMPL_HAS_C_ATTRIBUTE(_) 0 +#elif RBIMPL_HAS_EXTENSION(c_attributes) +# /* Hmm. It seems Clang 17 has this macro defined even when -std=c99 mode, +# * _and_ fails to compile complaining that attributes are C2X feature. We +# * need to work around this nonsense. */ +# define RBIMPL_HAS_C_ATTRIBUTE(_) __has_c_attribute(_) + +#elif RBIMPL_HAS_WARNING("-Wc2x-extensions") +# define RBIMPL_HAS_C_ATTRIBUTE(_) 0 + #elif defined(__has_c_attribute) # define RBIMPL_HAS_C_ATTRIBUTE(_) __has_c_attribute(_) diff --git a/include/ruby/internal/intern/array.h b/include/ruby/internal/intern/array.h index 6e93c4c42a..b2cc6b132d 100644 --- a/include/ruby/internal/intern/array.h +++ b/include/ruby/internal/intern/array.h @@ -20,58 +20,643 @@ * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_cArray. */ +#include "ruby/internal/attr/noalias.h" +#include "ruby/internal/attr/noexcept.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/attr/pure.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" RBIMPL_SYMBOL_EXPORT_BEGIN() /* array.c */ -void rb_mem_clear(VALUE*, long); -VALUE rb_assoc_new(VALUE, VALUE); -VALUE rb_check_array_type(VALUE); + +RBIMPL_ATTR_NONNULL(()) +RBIMPL_ATTR_NOALIAS() +/** + * Fills the memory region with a series of ::RUBY_Qnil. + * + * @param[out] buf Buffer to squash. + * @param[in] len Number of objects of `buf`. + * @post `buf` is filled with ::RUBY_Qnil. + */ +void rb_mem_clear(VALUE *buf, long len) + RBIMPL_ATTR_NOEXCEPT(true) + ; + +/** + * Identical to rb_ary_new_from_values(), except it expects exactly two + * parameters. + * + * @param[in] car Arbitrary ruby object. + * @param[in] cdr Arbitrary ruby object. + * @return An allocated new array, of length 2, whose contents are the + * passed objects. + */ +VALUE rb_assoc_new(VALUE car, VALUE cdr); + +/** + * Try converting an object to its array representation using its `to_ary` + * method, if any. If there is no such thing, returns ::RUBY_Qnil. + * + * @param[in] obj Arbitrary ruby object to convert. + * @exception rb_eTypeError `obj.to_ary` returned something non-Array. + * @retval RUBY_Qnil No conversion from `obj` to array defined. + * @retval otherwise Converted array representation of `obj`. + * @see rb_io_check_io + * @see rb_check_string_type + * @see rb_check_hash_type + */ +VALUE rb_check_array_type(VALUE obj); + +/** + * Allocates a new, empty array. + * + * @return An allocated new array, whose length is 0. + */ VALUE rb_ary_new(void); + +/** + * Identical to rb_ary_new(), except it additionally specifies how many rooms + * of objects it should allocate. This way you can create an array whose + * capacity is bigger than the length of it. If you can say that an array + * grows to a specific amount, this could be effective than resizing an array + * over and over again and again. + * + * @param[in] capa Designed capacity of the generating array. + * @return An empty array, whose capacity is `capa`. + */ VALUE rb_ary_new_capa(long capa); + +/** + * Constructs an array from the passed objects. + * + * @param[in] n Number of passed objects. + * @param[in] ... Arbitrary ruby objects, filled into the returning array. + * @return An array of size `n`, whose contents are the passed objects. + */ VALUE rb_ary_new_from_args(long n, ...); + +/** + * Identical to rb_ary_new_from_args(), except how objects are passed. + * + * @param[in] n Number of objects of `elts`. + * @param[in] elts Arbitrary ruby objects, filled into the returning array. + * @return An array of size `n`, whose contents are the passed objects. + */ VALUE rb_ary_new_from_values(long n, const VALUE *elts); -VALUE rb_ary_tmp_new(long); -void rb_ary_free(VALUE); -void rb_ary_modify(VALUE); -VALUE rb_ary_freeze(VALUE); -VALUE rb_ary_shared_with_p(VALUE, VALUE); -VALUE rb_ary_aref(int, const VALUE*, VALUE); -VALUE rb_ary_subseq(VALUE, long, long); -void rb_ary_store(VALUE, long, VALUE); -VALUE rb_ary_dup(VALUE); + +/** + * Allocates a hidden (no class) empty array. + * + * @param[in] capa Designed capacity of the array. + * @return A hidden, empty array. + * @see rb_obj_hide() + */ +VALUE rb_ary_hidden_new(long capa); +#define rb_ary_tmp_new rb_ary_hidden_new + +/** + * Destroys the given array for no reason. + * + * @warning DO NOT USE IT. + * @warning Leave this task to our GC. + * @warning It was a wrong indea at the first place to let you know about it. + * + * @param[out] ary The array to be executed. + * @post The given array no longer exists. + * @note Maybe `Array#clear` could be what you want. + * + * @internal + * + * Should have moved this to `internal/array.h`. + */ +void rb_ary_free(VALUE ary); + +/** + * Declares that the array is about to be modified. This for instance let the + * array have a dedicated backend storage. + * + * @param[out] ary Array about to be modified. + * @exception rb_eFrozenError `ary` is frozen. + * @post Upon successful return the passed array is eligible to be + * modified. + */ +void rb_ary_modify(VALUE ary); + +/** + * Freeze an array, preventing further modifications. The underlying buffer may + * be shrunk before freezing to conserve memory. + * + * @param[out] obj Object assumed to be an array to freeze. + * @see RB_OBJ_FREEZE() + */ +VALUE rb_ary_freeze(VALUE obj); + +RBIMPL_ATTR_PURE() +/** + * Queries if the passed two arrays share the same backend storage. A use-case + * for knowing such property is to take a snapshot of an array (using + * e.g. rb_ary_replace()), then check later if that snapshot still shares the + * storage with the original. Taking a snapshot is ultra-cheap. If nothing + * happens the impact shall be minimal. But if someone modifies the original, + * that entity shall pay the cost of copy-on-write. You can detect that using + * this API. + * + * @param[in] lhs Comparison LHS. + * @param[in] rhs Comparison RHS. + * @retval RUBY_Qtrue They share the same backend storage. + * @retval RUBY_Qfalse They are distinct. + * @pre Both arguments must be of ::RUBY_T_ARRAY. + */ +VALUE rb_ary_shared_with_p(VALUE lhs, VALUE rhs); + +/** + * Queries element(s) of an array. This is complicated! Refer `Array#slice` + * document for the complete description of how it behaves. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Up to 2 objects. + * @param[in] ary Target array. + * @exception rb_eTypeError `argv` (or its part) includes non-Integer. + * @exception rb_eRangeError rb_cArithSeq is passed, and is OOB. + * @return An element (if requested), or an array of elements (if + * requested), or ::RUBY_Qnil (if index OOB). + * + * @internal + * + * ```rbs + * # "int" is ::Integer or `#to_int`, defined in builtin.rbs + * + * class ::Array[unchecked out T] + * def slice + * : (int i) -> T? + * | (int beg, int len) -> ::Array[T]? + * | (Range[int] r) -> ::Array[T]? + * | (ArithmeticSequence as) -> ::Array[T]? # This also raises RangeError. + * end + * ``` + */ +VALUE rb_ary_aref(int argc, const VALUE *argv, VALUE ary); + +/** + * Obtains a part of the passed array. + * + * @param[in] ary Target array. + * @param[in] beg Subpart index. + * @param[in] len Requested length of returning array. + * @retval RUBY_Qnil Requested range out of bounds of `ary`. + * @retval otherwise An allocated new array whose contents are `ary`'s + * `beg` to `len`. + * @note Return array can be shorter than `len` when for instance + * `[0, 1, 2, 3]`'s 4th to 1,000,000,000th is requested. + */ +VALUE rb_ary_subseq(VALUE ary, long beg, long len); + +/** + * Destructively stores the passed value to the passed array's passed index. + * It also resizes the array's backend storage so that the requested index is + * not out of bounds. + * + * @param[out] ary Target array to modify. + * @param[in] key Where to store `val`. + * @param[in] val What to store at `key`. + * @exception rb_eFrozenError `ary` is frozen. + * @exception rb_eIndexError `key` is negative. + * @post `ary`'s `key`th position is occupied with `val`. + * @post Depending on `key` and previous length of `ary` this operation + * can also create a series of "hole" positions inside of the + * backend storage. They are filled with ::RUBY_Qnil. + */ +void rb_ary_store(VALUE ary, long key, VALUE val); + +/** + * Duplicates an array. + * + * @param[in] ary Target to duplicate. + * @return An allocated new array whose contents are identical to `ary`. + * + * @internal + * + * Not sure why this has to be something different from `ary_make_shared_copy`, + * which seems much efficient. + */ +VALUE rb_ary_dup(VALUE ary); + +/** + * I guess there is no use case of this function in extension libraries, but + * this is a routine identical to rb_ary_dup(). This makes the most sense when + * the passed array is formerly hidden by rb_obj_hide(). + * + * @param[in] ary An array, possibly hidden. + * @return A duplicated new instance of ::rb_cArray. + */ VALUE rb_ary_resurrect(VALUE ary); -VALUE rb_ary_to_ary(VALUE); -VALUE rb_ary_to_s(VALUE); -VALUE rb_ary_cat(VALUE, const VALUE *, long); -VALUE rb_ary_push(VALUE, VALUE); -VALUE rb_ary_pop(VALUE); -VALUE rb_ary_shift(VALUE); -VALUE rb_ary_unshift(VALUE, VALUE); -VALUE rb_ary_entry(VALUE, long); -VALUE rb_ary_each(VALUE); -VALUE rb_ary_join(VALUE, VALUE); -VALUE rb_ary_reverse(VALUE); -VALUE rb_ary_rotate(VALUE, long); -VALUE rb_ary_sort(VALUE); -VALUE rb_ary_sort_bang(VALUE); -VALUE rb_ary_delete(VALUE, VALUE); -VALUE rb_ary_delete_at(VALUE, long); -VALUE rb_ary_clear(VALUE); -VALUE rb_ary_plus(VALUE, VALUE); -VALUE rb_ary_concat(VALUE, VALUE); -VALUE rb_ary_assoc(VALUE, VALUE); -VALUE rb_ary_rassoc(VALUE, VALUE); -VALUE rb_ary_includes(VALUE, VALUE); -VALUE rb_ary_cmp(VALUE, VALUE); + +/** + * Force converts an object to an array. It first tries its `#to_ary` method. + * Takes the result if any. Otherwise creates an array of size 1 whose sole + * element is the passed object. + * + * @param[in] obj Arbitrary ruby object. + * @return An array representation of `obj`. + * @note Unlike rb_str_to_str() which is a variant of + * rb_check_string_type(), rb_ary_to_ary() is not a variant of + * rb_check_array_type(). + */ +VALUE rb_ary_to_ary(VALUE obj); + +/** + * Converts an array into a human-readable string. Historically its behaviour + * changed over time. Currently it is identical to calling `inspect` method. + * This behaviour is from that of python (!!) circa 2006. + * + * @param[in] ary Array to inspect. + * @return Recursively inspected representation of `ary`. + * @see `[ruby-dev:29520]` + */ +VALUE rb_ary_to_s(VALUE ary); + +/** + * Destructively appends multiple elements at the end of the array. + * + * @param[out] ary Where to push `train`. + * @param[in] train Arbitrary ruby objects to push to `ary`. + * @param[in] len Number of objects of `train`. + * @exception rb_eIndexError `len` too large. + * @exception rb_eFrozenError `ary` is frozen. + * @return The passed `ary`. + * @post `ary` has contents from `train` appended at its end. + */ +VALUE rb_ary_cat(VALUE ary, const VALUE *train, long len); + +/** + * Special case of rb_ary_cat() that it adds only one element. + * + * @param[out] ary Where to push `elem`. + * @param[in] elem Arbitrary ruby object to push. + * @exception rb_eFrozenError `ary` is frozen. + * @return The passed `ary`. + * @post `ary` has `elem` appended at its end. + */ +VALUE rb_ary_push(VALUE ary, VALUE elem); + +/** + * Destructively deletes an element from the end of the passed array and + * returns what was deleted. + * + * @param[out] ary Target array to modify. + * @exception rb_eFrozenError `ary` is frozen. + * @return What was at the end of `ary`, or ::RUBY_Qnil if there is + * nothing to remove. + * @post `ary`'s last element, if any, is removed. + * @note There is no way to distinguish whether `ary` was an 1-element + * array whose content was ::RUBY_Qnil, or was empty. + */ +VALUE rb_ary_pop(VALUE ary); + +/** + * Destructively deletes an element from the beginning of the passed array and + * returns what was deleted. It can also be seen as a routine identical to + * rb_ary_pop(), except which side of the array to scrub. + * + * @param[out] ary Target array to modify. + * @exception rb_eFrozenError `ary` is frozen. + * @return What was at the beginning of `ary`, or ::RUBY_Qnil if there is + * nothing to remove. + * @post `ary`'s first element, if any, is removed. As the name implies + * everything else remaining in `ary` gets moved towards `ary`'s + * beginning. + * @note There is no way to distinguish whether `ary` was an 1-element + * array whose content was ::RUBY_Qnil, or was empty. + */ +VALUE rb_ary_shift(VALUE ary); + +/** + * Destructively prepends the passed item at the beginning of the passed array. + * It can also be seen as a routine identical to rb_ary_push(), except which + * side of the array to modify. + * + * @param[out] ary Target array to modify. + * @param[in] elem Arbitrary ruby object to unshift. + * @exception rb_eFrozenError `ary` is frozen. + * @return The passed `ary`. + * @post `ary` has `elem` prepended at this beginning. + */ +VALUE rb_ary_unshift(VALUE ary, VALUE elem); + +RBIMPL_ATTR_PURE() +/** + * Queries an element of an array. When passed offset is negative it counts + * backwards. + * + * @param[in] ary An array to look into. + * @param[in] off Offset (can be negative). + * @return ::RUBY_Qnil when `off` is out of bounds of `ary`. Otherwise + * what is stored at `off`-th position of `ary`. + * @note `ary`'s `off`-th element can happen to be ::RUBY_Qnil. + */ +VALUE rb_ary_entry(VALUE ary, long off); + +/** + * Iteratively yields each element of the passed array to the implicitly passed + * block if any. In case there is no block given, an enumerator that does the + * thing is generated instead. + * + * @param[in] ary Array to iterate over. + * @retval ary Passed block was evaluated. + * @retval otherwise An instance of ::rb_cEnumerator for `Array#each`. + */ +VALUE rb_ary_each(VALUE ary); + +/** + * Recursively stringises the elements of the passed array, flattens that + * result, then joins the sequence using the passed separator. + * + * @param[in] ary Target array to convert. + * @param[in] sep Separator. Either a string, or ::RUBY_Qnil + * if you want no separator. + * @exception rb_eArgError Infinite recursion in `ary`. + * @exception rb_eTypeError `sep` is not a string. + * @exception rb_eEncCompatError Strings do not agree with their encodings. + * @return An instance of ::rb_cString which concatenates stringised + * contents of `ary`, using `sep` as separator. + */ +VALUE rb_ary_join(VALUE ary, VALUE sep); + +/** + * _Destructively_ reverses the passed array in-place. + * + * @warning This is `Array#reverse!`, not `Array#reverse`. + * @param[out] ary Target array to modify. + * @exception rb_eFrozenError `ary` is frozen. + * @return Passed `ary`. + * @post `ary` is reversed. + */ +VALUE rb_ary_reverse(VALUE ary); + +/** + * _Destructively_ rotates the passed array in-place to towards its end. The + * amount can be negative. Would rotate to the opposite direction then. + * + * @warning This is `Array#rotate!`, not `Array#rotate`. + * @param[out] ary Target array to modify. + * @param[in] rot Amount of rotation. + * @exception rb_eFrozenError `ary` is frozen. + * @retval RUBY_Qnil Not rotated. + * @retval ary Rotated. + * @post `ary` is rotated. + */ +VALUE rb_ary_rotate(VALUE ary, long rot); + +/** + * Creates a copy of the passed array, whose elements are sorted according to + * their `<=>` result. + * + * @param[in] ary Array to sort. + * @exception rb_eArgError Comparison not defined among elements. + * @exception rb_eRuntimeError Infinite recursion in `<=>`. + * @return A copy of `ary`, sorted. + * @note As of writing this function uses `qsort` as backend algorithm, + * which means the result is unstable (in terms of sort stability). + */ +VALUE rb_ary_sort(VALUE ary); + +/** + * Destructively sorts the passed array in-place, according to each elements' + * `<=>` result. + * + * @param[in] ary Target array to modify. + * @exception rb_eArgError Comparison not defined among elements. + * @exception rb_eRuntimeError Infinite recursion in `<=>`. + * @return Passed `ary`. + * @post `ary` is sorted. + * @note As of writing this function uses `qsort` as backend algorithm, + * which means the result is unstable (in terms of sort stability). + */ +VALUE rb_ary_sort_bang(VALUE ary); + +/** + * Destructively removes elements from the passed array, so that there would be + * no elements inside that satisfy `==` relationship with the passed object. + * Returns the last deleted element if any. But in case there was nothing to + * delete it gets complicated. It checks for the implicitly passed block. If + * there is a block the return value would be what the block evaluates to. + * Otherwise it resorts to ::RUBY_Qnil. + * + * @param[out] ary Target array to modify. + * @param[in] elem Template object to match against each element. + * @exception rb_eFrozenError `ary` is frozen. + * @return What was deleted, or what was the block returned, or + * ::RUBY_Qnil (see above). + * @post All elements that have `==` relationship with `elem` are purged + * from `ary`. Elements shift their positions so that `ary` gets + * compact. + * + * @internal + * + * Internally there also is `rb_ary_delete_same`, which compares by identity. + */ +VALUE rb_ary_delete(VALUE ary, VALUE elem); + +/** + * Destructively removes an element which resides at the specific index of the + * passed array. Unlike rb_ary_stre() the index can be negative, which means + * the index counts backwards from the array's tail. + * + * @param[out] ary Target array to modify. + * @param[in] pos Position (can be negative). + * @exception rb_eFrozenError `ary` is frozen. + * @return What was deleted, or ::RUBY_Qnil in case of OOB. + * @post `ary`'s `pos`-th element is deleted if any. + * @note There is no way to distinguish whether `pos` is out of bound, + * or `pos` did exist but stored ::RUBY_Qnil as an ordinal value. + */ +VALUE rb_ary_delete_at(VALUE ary, long pos); + +/** + * Destructively removes everything form an array. + * + * @param[out] ary Target array to modify. + * @exception rb_eFrozenError `ary` is frozen. + * @return The passed `ary`. + * @post `ary` is an empty array. + */ +VALUE rb_ary_clear(VALUE ary); + +/** + * Creates a new array, concatenating the former to the latter. + * + * @param[in] lhs Source array #1. + * @param[in] rhs Source array #2. + * @exception rb_eIndexError Result array too big. + * @return A new array containing `rhs` concatenated to `lhs`. + * @note This operation doesn't commute. Don't get confused by the + * "plus" terminology. For historical reasons there are some + * noncommutative `+`s in Ruby. This is one of such things. There + * has been a long discussion around `+`s in programming languages. + * + * @internal + * + * rb_ary_concat() is not a destructive version of rb_ary_plus(). They raise + * different exceptions. Don't know why though. + */ +VALUE rb_ary_plus(VALUE lhs, VALUE rhs); + +/** + * Destructively appends the contents of latter into the end of former. + * + * @param[out] lhs Destination array. + * @param[in] rhs Source array. + * @exception rb_eFrozenError `lhs` is frozen. + * @exception rb_eIndexError Result array too big. + * @exception rb_eTypeError `rhs` doesn't respond to `#to_ary`. + * @return The passed `lhs`. + * @post `lhs` has contents of `rhs` appended to its end. + */ +VALUE rb_ary_concat(VALUE lhs, VALUE rhs); + +/** + * Looks up the passed key, assuming the passed array is an alist. An "alist" + * here is a list of "association"s, much like that of Emacs. Emacs has + * `assoc` function that behaves exactly the same as this one. + * + * ```ruby + * # This is an example of aliist. + * auto_mode_alist = [ + * [ /\.[ch]\z/, :"c-mode" ], + * [ /\.[ch]pp\z/, :"c++-mode" ], + * [ /\.awk\z/, :"awk-mode" ], + * [ /\.cs\z/, :"csharp-mode" ], + * [ /\.go\z/, :"go-mode" ], + * [ /\.java\z/, :"java-mode" ], + * [ /\.pas\z/, :"pascal-mode" ], + * [ /\.rs\z/, :"rust-mode" ], + * [ /\.txt\z/, :"text-mode" ], + * ] + * ``` + * + * This function scans the passed array looking for an element, which itself is + * an array, whose first element is the passed key. If no such element is + * found, returns ::RUBY_Qnil. + * + * Although this function expects the passed array be an array of arrays, it + * can happily accept non-array elements; it just ignores such things. + * + * @param[in] alist An array of arrays. + * @param[in] key Needle. + * @retval RUBY_Qnil Nothing was found. + * @retval otherwise An element in `alist` whose first element is in `==` + * relationship with `key`. + */ +VALUE rb_ary_assoc(VALUE alist, VALUE key); + +/** + * Identical to rb_ary_assoc(), except it scans the passed array from the + * opposite direction. + * + * @param[in] alist An array of arrays. + * @param[in] key Needle. + * @retval RUBY_Qnil Nothing was found. + * @retval otherwise An element in `alist` whose first element is in `==` + * relationship with `key`. + */ +VALUE rb_ary_rassoc(VALUE alist, VALUE key); + +/** + * Queries if the passed array has the passed entry. + * + * @param[in] ary Target array to scan. + * @param[in] elem Target array to find. + * @retval RUBY_Qfalse No element in `ary` is in `==` relationship with + * `elem`. + * @retval RUBY_Qtrue There is at least one element in `ary` which is in + * `==` relationship with `elem`. + * + * @internal + * + * This is the only function in the entire C API that is named using third + * person singular form of a verb (except #ISASCII etc., which are not our + * naming). The counterpart Ruby API of this function is `Array#include?`. + */ +VALUE rb_ary_includes(VALUE ary, VALUE elem); + +/** + * Recursively compares each elements of the two arrays one-by-one using `<=>`. + * + * @param[in] lhs Comparison LHS. + * @param[in] rhs Comparison RHS. + * @retval RUBY_Qnil `lhs` and `rhs` are not comparable. + * @retval -1 `lhs` is less than `rhs`. + * @retval 0 They are equal. + * @retval 1 `rhs` is less then `lhs`. + */ +VALUE rb_ary_cmp(VALUE lhs, VALUE rhs); + +/** + * Replaces the contents of the former object with the contents of the latter. + * + * @param[out] copy Destination object. + * @param[in] orig Source object. + * @exception rb_eTypeError `orig` has no implicit conversion to Array. + * @exception rb_eFrozenError `copy` is frozen. + * @return The passed `copy`. + * @post `copy`'s former components are abandoned. It now has the + * identical length and contents to `orig`. + */ VALUE rb_ary_replace(VALUE copy, VALUE orig); -VALUE rb_get_values_at(VALUE, long, int, const VALUE*, VALUE(*)(VALUE,long)); + +/** + * This _was_ a generalisation of `Array#values_at`, `Struct#values_at`, and + * `MatchData#values_at`. It begun its life as a refactoring effort. However + * as Ruby evolves over time, as of writing none of aforementioned methods + * share their implementations at all. This function is not deprecated; still + * works as it has been. But it is now kind of like a rudimentum. + * + * This function takes an object, which is a receiver, and a series of + * "indices", which are either integers, or ranges of integers. Calls the + * passed callback for each of those indices, along with the receiver. This + * callback is expected to do something like rb_ary_aref(), rb_struct_aref(), + * etc. In case of a range index rb_range_beg_len() expands the range. + * Finally return values of the callback are gathered as an array, then + * returned. + * + * @param[in] obj Arbitrary ruby object. + * @param[in] olen "Length" of `obj`. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv List of "indices", described above. + * @param[in] func Callback function. + * @return A new instance of ::rb_cArray gathering `func`outputs. + * + * @internal + * + * `Array#values_at` no longer uses this function. There is no reason apart + * from historical ones to list this function here. + */ +VALUE rb_get_values_at(VALUE obj, long olen, int argc, const VALUE *argv, VALUE (*func)(VALUE obj, long oidx)); + +/** + * Expands or shrinks the passed array to the passed length. + * + * @param[out] ary An array to modify. + * @param[in] len Desired length of `ary`. + * @exception rb_eFrozenError `ary` is frozen. + * @exception rb_eIndexError `len` too long. + * @return The passed `ary`. + * @post `ary`'s length is `len`. + * @post Depending on `len` and previous length of `ary` this operation + * can also create a series of "hole" positions inside of the + * backend storage. They are filled with ::RUBY_Qnil. + * + * @internal + * + * `len` is signed. Intentional or...? + */ VALUE rb_ary_resize(VALUE ary, long len); -#define rb_ary_new2 rb_ary_new_capa -#define rb_ary_new3 rb_ary_new_from_args -#define rb_ary_new4 rb_ary_new_from_values + +#define rb_ary_new2 rb_ary_new_capa /**< @old{rb_ary_new_capa} */ +#define rb_ary_new3 rb_ary_new_from_args /**< @old{rb_ary_new_from_args} */ +#define rb_ary_new4 rb_ary_new_from_values /**< @old{rb_ary_new_from_values} */ RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/intern/bignum.h b/include/ruby/internal/intern/bignum.h index 124d065505..c27f77a1fb 100644 --- a/include/ruby/internal/intern/bignum.h +++ b/include/ruby/internal/intern/bignum.h @@ -26,6 +26,7 @@ # include <stddef.h> #endif +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" #include "ruby/backward/2/long_long.h" @@ -33,71 +34,811 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* bignum.c */ -VALUE rb_big_new(size_t, int); + +/** + * Allocates a bignum object. + * + * @param[in] len Length of the bignum's backend storage, in words. + * @param[in] sign Sign of the bignum. + * @return An allocated new bignum instance. + * @note This only allocates an object, doesn't fill its value in. + * + * @internal + * + * @shyouhei finds it hard to use from extension libraries. `len` is per + * `BDIGIT` but its definition is hidden. + */ +VALUE rb_big_new(size_t len, int sign); + +/** + * Queries if the passed bignum instance is a "bigzero". What is a bigzero? + * Well, bignums are for very big integers, but can also represent tiny ones + * like -1, 0, 1. Bigzero are instances of bignums whose values are zero. + * Knowing if a bignum is bigzero can be handy on occasions, like for instance + * detecting division by zero situation. + * + * @param[in] x A bignum. + * @retval 1 It is a bigzero. + * @retval 0 Otherwise. + */ int rb_bigzero_p(VALUE x); -VALUE rb_big_clone(VALUE); -void rb_big_2comp(VALUE); -VALUE rb_big_norm(VALUE); + +/** + * Duplicates the given bignum. + * + * @param[in] num A bignum. + * @return An allocated bignum, who is equivalent to `num`. + */ +VALUE rb_big_clone(VALUE num); + +/** + * Destructively modify the passed bignum into 2's complement representation. + * + * @note By default bignums are in signed magnitude system. + * + * @param[out] num A bignum to modify. + */ +void rb_big_2comp(VALUE num); + +/** + * Normalises the passed bignum. It for instance returns a fixnum of the same + * value if fixnum can represent that number. + * + * @param[out] x Target bignum (can be destructively modified). + * @return An integer of the identical value (can be `x` itself). + */ +VALUE rb_big_norm(VALUE x); + +/** + * Destructively resizes the backend storage of the passed bignum. + * + * @param[out] big A bignum. + * @param[in] len New length of `big`'s backend, in words. + */ void rb_big_resize(VALUE big, size_t len); -VALUE rb_cstr_to_inum(const char*, int, int); -VALUE rb_str_to_inum(VALUE, int, int); -VALUE rb_cstr2inum(const char*, int); -VALUE rb_str2inum(VALUE, int); -VALUE rb_big2str(VALUE, int); -long rb_big2long(VALUE); + +RBIMPL_ATTR_NONNULL(()) +/** + * Parses C's string to convert into a Ruby's integer. It understands prefixes + * (e.g. `0x`) and underscores. + * + * @param[in] str Stringised representation of the return value. + * @param[in] base Base of conversion. Must be `-36..36` inclusive, + * except `1`. `2..36` means the conversion is done + * according to it, with unmatched prefix understood + * as a part of the result. `-36..-2` means the + * conversion honours prefix when present, or use + * `-base` when absent. `0` is equivalent to `-10`. + * `-1` mandates a prefix. `1` is an error. + * @param[in] badcheck Whether to raise ::rb_eArgError on failure. If + * `0` is passed here this function can return + * `INT2FIX(0)` for parse errors. + * @exception rb_eArgError Failed to parse (and `badcheck` is truthy). + * @return An instance of ::rb_cInteger, which is a numeric interpretation + * of what is written in `str`. + * + * @internal + * + * Not sure if it intentionally accepts `base == -1` or is just buggy. Nobody + * practically uses negative bases these days. + */ +VALUE rb_cstr_to_inum(const char *str, int base, int badcheck); + +/** + * Identical to rb_cstr2inum(), except it takes Ruby's strings instead of C's. + * + * @param[in] str Stringised representation of the return + * value. + * @param[in] base Base of conversion. Must be `-36..36` + * inclusive, except `1`. `2..36` means the + * conversion is done according to it, with + * unmatched prefix understood as a part of the + * result. `-36..-2` means the conversion + * honours prefix when present, or use `-base` + * when absent. `0` is equivalent to `-10`. + * `-1` mandates a prefix. `1` is an error. + * @param[in] badcheck Whether to raise ::rb_eArgError on failure. + * If `0` is passed here this function can + * return `INT2FIX(0)` for parse errors. + * @exception rb_eArgError Failed to parse (and `badcheck` is truthy). + * @exception rb_eTypeError `str` is not a string. + * @exception rb_eEncCompatError `str` is not ASCII compatible. + * @return An instance of ::rb_cInteger, which is a numeric interpretation + * of what is written in `str`. + */ +VALUE rb_str_to_inum(VALUE str, int base, int badcheck); + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_cstr_to_inum(), except the second argument controls the base + * and badcheck at once. It basically doesn't raise for parse errors, unless + * the base is zero. + * + * This is an older API. New codes might prefer rb_cstr_to_inum(). + * + * @param[in] str Stringised representation of the return value. + * @param[in] base Base of conversion. Must be `-36..36` inclusive, + * except `1`. `2..36` means the conversion is done + * according to it, with unmatched prefix understood + * as a part of the result. `-36..-2` means the + * conversion honours prefix when present, or use + * `-base` when absent. `0` is equivalent to `-10`. + * `-1` mandates a prefix. `1` is an error. + * @exception rb_eArgError Failed to parse (and `base` is zero). + * @return An instance of ::rb_cInteger, which is a numeric interpretation + * of what is written in `str`. + */ +VALUE rb_cstr2inum(const char *str, int base); + +/** + * Identical to rb_str_to_inum(), except the second argument controls the base + * and badcheck at once. It can also be seen as a routine identical to + * rb_cstr2inum(), except it takes Ruby's strings instead of C's. + * + * This is an older API. New codes might prefer rb_cstr_to_inum(). + * + * @param[in] str Stringised representation of the return + * value. + * @param[in] base Base of conversion. Must be `-36..36` + * inclusive, except `1`. `2..36` means the + * conversion is done according to it, with + * unmatched prefix understood as a part of the + * result. `-36..-2` means the conversion + * honours prefix when present, or use `-base` + * when absent. `0` is equivalent to `-10`. + * `-1` mandates a prefix. `1` is an error. + * @exception rb_eArgError Failed to parse (and `base` is zero). + * @exception rb_eTypeError `str` is not a string. + * @exception rb_eEncCompatError `str` is not ASCII compatible. + * @return An instance of ::rb_cInteger, which is a numeric interpretation + * of what is written in `str`. + */ +VALUE rb_str2inum(VALUE str, int base); + +/** + * Generates a place-value representation of the passed integer. + * + * @param[in] x An integer to stringify. + * @param[in] base `2` to `36` inclusive for each radix. + * @exception rb_eArgError `base` is out of range. + * @exception rb_eRangeError `x` is too big, cannot represent in string. + * @return An instance of ::rb_cString which represents `x`. + */ +VALUE rb_big2str(VALUE x, int base); + +/** + * Converts a bignum into C's `long`. + * + * @param[in] x A bignum. + * @exception rb_eRangeError `x` is out of range of `long`. + * @return The passed value converted into C's `long`. + */ +long rb_big2long(VALUE x); + +/** @alias{rb_big2long} */ #define rb_big2int(x) rb_big2long(x) -unsigned long rb_big2ulong(VALUE); + +/** + * Converts a bignum into C's `unsigned long`. + * + * @param[in] x A bignum. + * @exception rb_eRangeError `x` is out of range of `unsigned long`. + * @return The passed value converted into C's `unsigned long`. + * + * @internal + * + * This function can generate a very large positive integer for a negative + * input. For instance applying Ruby's -4,611,686,018,427,387,905 to this + * function yields C's 13,835,058,055,282,163,711 on my machine. This is how + * it has been. Cannot change any longer. + */ +unsigned long rb_big2ulong(VALUE x); + +/** @alias{rb_big2long} */ #define rb_big2uint(x) rb_big2ulong(x) + #if HAVE_LONG_LONG +/** + * Converts a bignum into C's `long long`. + * + * @param[in] x A bignum. + * @exception rb_eRangeError `x` is out of range of `long long`. + * @return The passed value converted into C's `long long`. + */ LONG_LONG rb_big2ll(VALUE); + +/** + * Converts a bignum into C's `unsigned long long`. + * + * @param[in] x A bignum. + * @exception rb_eRangeError `x` is out of range of `unsigned long long`. + * @return The passed value converted into C's `unsigned long long`. + * + * @internal + * + * This function can generate a very large positive integer for a negative + * input. For instance applying Ruby's -4,611,686,018,427,387,905 to this + * function yields C's 13,835,058,055,282,163,711 on my machine. This is how + * it has been. Cannot change any longer. + */ unsigned LONG_LONG rb_big2ull(VALUE); + #endif /* HAVE_LONG_LONG */ + +RBIMPL_ATTR_NONNULL(()) +/** + * Converts a bignum into a series of its parts. + * + * @param[in] val An integer. + * @param[out] buf Return buffer. + * @param[in] num_longs Number of words of `buf`. + * @exception rb_eTypeError `val` doesn't respond to `#to_int`. + * @post `buf` is filled with `val`'s 2's complement representation, in + * the host CPU's native byte order, from least significant word + * towards the most significant one, for `num_longs` words. + * @note The "pack" terminology comes from `Array#pack`. + */ void rb_big_pack(VALUE val, unsigned long *buf, long num_longs); + +RBIMPL_ATTR_NONNULL(()) +/** + * Constructs a (possibly very big) bignum from a series of integers. `buf[0]` + * would be the return value's least significant word; `buf[num_longs-1]` would + * be that of most significant. + * + * @param[in] buf A series of integers. + * @param[in] num_longs Number of words of `buf`. + * @exception rb_eArgError Result would be too big. + * @return An instance of ::rb_cInteger which is an "unpack"-ed value of + * the parameters. + * @note The "unpack" terminology comes from `String#pack`. + */ VALUE rb_big_unpack(unsigned long *buf, long num_longs); -int rb_uv_to_utf8(char[6],unsigned long); -VALUE rb_dbl2big(double); -double rb_big2dbl(VALUE); -VALUE rb_big_cmp(VALUE, VALUE); -VALUE rb_big_eq(VALUE, VALUE); -VALUE rb_big_eql(VALUE, VALUE); -VALUE rb_big_plus(VALUE, VALUE); -VALUE rb_big_minus(VALUE, VALUE); -VALUE rb_big_mul(VALUE, VALUE); -VALUE rb_big_div(VALUE, VALUE); -VALUE rb_big_idiv(VALUE, VALUE); -VALUE rb_big_modulo(VALUE, VALUE); -VALUE rb_big_divmod(VALUE, VALUE); -VALUE rb_big_pow(VALUE, VALUE); -VALUE rb_big_and(VALUE, VALUE); -VALUE rb_big_or(VALUE, VALUE); -VALUE rb_big_xor(VALUE, VALUE); -VALUE rb_big_lshift(VALUE, VALUE); -VALUE rb_big_rshift(VALUE, VALUE); - -/* For rb_integer_pack and rb_integer_unpack: */ -/* "MS" in MSWORD and MSBYTE means "most significant" */ -/* "LS" in LSWORD and LSBYTE means "least significant" */ + +/* pack.c */ + +RBIMPL_ATTR_NONNULL(()) +/** + * Encodes a Unicode codepoint into its UTF-8 representation. + * + * @param[out] buf Return buffer, must at least be 6 bytes width. + * @param[in] uv An Unicode codepoint. + * @exception rb_eRangeError `uv` is out of Unicode. + * @return Number of bytes written to `buf` + * @post `buf` holds a UTF-8 representation of `uv`. + */ +int rb_uv_to_utf8(char buf[6], unsigned long uv); + +/* bignum.c */ + +/** + * Converts a C's `double` into a bignum. + * + * @param[in] d A value to convert. + * @exception rb_eFloatDomainError `d` is Inf/NaN. + * @return An instance of ::rb_cInteger whose value is approximately `d`. + * + * @internal + * + * @shyouhei is not sure if the result is guaranteed to be the nearest integer + * of `d`. + */ +VALUE rb_dbl2big(double d); + +/** + * Converts a bignum into C's `double`. + * + * @param[in] x A bignum. + * @return The passed value converted into C's `double`. + * + * @internal + * + * @shyouhei is not sure if the result is guaranteed to be `x`'s nearest value + * that a `double` can represent. + */ +double rb_big2dbl(VALUE x); + +/** + * Compares the passed two bignums. + * + * @param[in] lhs Comparison LHS. + * @param[in] rhs Comparison RHS. + * @retval -1 `rhs` is bigger than `lhs`. + * @retval 0 They are identical. + * @retval 1 `lhs` is bigger than `rhs`. + * @see rb_num_coerce_cmp() + */ +VALUE rb_big_cmp(VALUE lhs, VALUE rhs); + +/** + * Equality, in terms of `==`. This checks if the _value_ is the same, not the + * identity. For instance `1 == 1.0` must hold. + * + * @param[in] lhs Comparison LHS. + * @param[in] rhs Comparison RHS. + * @retval RUBY_Qtrue They are the same. + * @retval RUBY_Qfalse They are different. + */ +VALUE rb_big_eq(VALUE lhs, VALUE rhs); + +/** + * Equality, in terms of `eql?`. Unlike rb_big_eq() it does not convert + * ::rb_cFloat etc. This function returns ::RUBY_Qtrue if and only if both + * parameters are bignums, which represent the identical numerical value. + * + * @param[in] lhs Comparison LHS. + * @param[in] rhs Comparison RHS. + * @retval RUBY_Qtrue They are identical. + * @retval RUBY_Qfalse They are distinct. + */ +VALUE rb_big_eql(VALUE lhs, VALUE rhs); + +/** + * Performs addition of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x + y` evaluates to. + * @see rb_num_coerce_bin() + */ +VALUE rb_big_plus(VALUE x, VALUE y); + +/** + * Performs subtraction of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x - y` evaluates to. + * @see rb_num_coerce_bin() + */ +VALUE rb_big_minus(VALUE x, VALUE y); + +/** + * Performs multiplication of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x * y` evaluates to. + * @see rb_num_coerce_bin() + */ +VALUE rb_big_mul(VALUE x, VALUE y); + +/** + * Performs division of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x / y` evaluates to. + * @see rb_num_coerce_bin() + */ +VALUE rb_big_div(VALUE x, VALUE y); + +/** + * Performs "integer division". This is different from rb_big_div(). + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x.div y` evaluates to. + * @see rb_num_coerce_bin() + */ +VALUE rb_big_idiv(VALUE x, VALUE y); + +/** + * Performs modulo of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x % y` evaluates to. + * @see rb_num_coerce_bin() + * + * @internal + * + * There also is `rb_big_remainder()` internally, which is different from this + * one. + */ +VALUE rb_big_modulo(VALUE x, VALUE y); + +/** + * Performs "divmod" operation. The operation in bignum's context is that it + * calculates rb_big_idiv() and rb_big_modulo() at once. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x.divmod y` evaluates to. + * @see rb_num_coerce_bin() + */ +VALUE rb_big_divmod(VALUE x, VALUE y); + +/** + * Raises `x` to the powerof `y`. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x ** y` evaluates to. + * @see rb_num_coerce_bin() + * @note This can return an instance of ::rb_cFloat, even when both `x` + * and `y` are bignums. Or an instance of ::rb_cRational, when for + * instance `y` is negative. + */ +VALUE rb_big_pow(VALUE x, VALUE y); + +/** + * Performs bitwise and of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x & y` evaluates to. + * @see rb_num_coerce_bit() + */ +VALUE rb_big_and(VALUE x, VALUE y); + +/** + * Performs bitwise or of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x | y` evaluates to. + * @see rb_num_coerce_bit() + */ +VALUE rb_big_or(VALUE x, VALUE y); + +/** + * Performs exclusive or of the passed two objects. + * + * @param[in] x A bignum. + * @param[in] y Arbitrary ruby object. + * @return What `x ^ y` evaluates to. + * @see rb_num_coerce_bit() + */ +VALUE rb_big_xor(VALUE x, VALUE y); + +/** + * Performs shift left. + * + * @param[in] x A bignum. + * @param[in] y Shift amount. + * @exception rb_eTypeError `y` is not an integer. + * @exception rb_eArgError `y` is too big. + * @return `x` shifted left to `y` bits. + * @note `y` can be negative. Shifts right then. + */ +VALUE rb_big_lshift(VALUE x, VALUE y); + +/** + * Performs shift right. + * + * @param[in] x A bignum. + * @param[in] y Shift amount. + * @exception rb_eTypeError `y` is not an integer. + * @return `x` shifted right to `y` bits. + * @note This is arithmetic. Because bignums are not bitfields there is + * no shift right logical operator. + */ +VALUE rb_big_rshift(VALUE x, VALUE y); + +/** + * @name Flags for rb_integer_pack()/rb_integer_unpack() + * @{ + */ + +/** Stores/interprets the most significant word as the first word. */ #define INTEGER_PACK_MSWORD_FIRST 0x01 + +/** Stores/interprets the least significant word as the first word. */ #define INTEGER_PACK_LSWORD_FIRST 0x02 + +/** + * Stores/interprets the most significant byte in a word as the first byte in + * the word. + */ #define INTEGER_PACK_MSBYTE_FIRST 0x10 + +/** + * Stores/interprets the least significant byte in a word as the first byte in + * the word. + */ #define INTEGER_PACK_LSBYTE_FIRST 0x20 + +/** + * Means either #INTEGER_PACK_MSBYTE_FIRST or #INTEGER_PACK_LSBYTE_FIRST, + * depending on the host processor's endian. + */ #define INTEGER_PACK_NATIVE_BYTE_ORDER 0x40 + +/** Uses 2's complement representation. */ #define INTEGER_PACK_2COMP 0x80 + +/** Uses "generic" implementation (handy on test). */ #define INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION 0x400 -/* For rb_integer_unpack: */ + +/** + * Always generates a bignum object even if the integer can be representable + * using fixnum scheme (unpack only) + */ #define INTEGER_PACK_FORCE_BIGNUM 0x100 + +/** + * Interprets the input as a signed negative number (unpack only). If not + * specified returns a positive number. + */ #define INTEGER_PACK_NEGATIVE 0x200 -/* Combinations: */ + +/** Little endian combination. */ #define INTEGER_PACK_LITTLE_ENDIAN \ (INTEGER_PACK_LSWORD_FIRST | \ INTEGER_PACK_LSBYTE_FIRST) + +/** Big endian combination */ #define INTEGER_PACK_BIG_ENDIAN \ (INTEGER_PACK_MSWORD_FIRST | \ INTEGER_PACK_MSBYTE_FIRST) + +/** @} */ + +RBIMPL_ATTR_NONNULL(()) +/** + * Exports an integer into a buffer. This function fills the buffer specified + * by `words` and `numwords` as `val` in the format specified by `wordsize`, + * `nails` and `flags`. + * + * @param[in] val Integer or integer-like object which has + * `#to_int` method. + * @param[out] words Return buffer. + * @param[in] numwords Number of words of `words`. + * @param[in] wordsize Number of bytes per word. + * @param[in] nails Number of padding bits in a word. Most + * significant nails bits of each word are filled + * by zero. + * @param[in] flags Bitwise or of constants whose name starts + * "INTEGER_PACK_". + * @exception rb_eTypeError `val` doesn't respond to `#to_int`. + * + * Possible flags are: + * + * - #INTEGER_PACK_MSWORD_FIRST: + * Stores the most significant word as the first word. + * + * - #INTEGER_PACK_LSWORD_FIRST: + * Stores the least significant word as the first word. + * + * - #INTEGER_PACK_MSBYTE_FIRST: + * Stores the most significant byte in a word as the first byte in the + * word. + * + * - #INTEGER_PACK_LSBYTE_FIRST: + * Stores the least significant byte in a word as the first byte in the + * word. + * + * - #INTEGER_PACK_NATIVE_BYTE_ORDER: + * Either #INTEGER_PACK_MSBYTE_FIRST or #INTEGER_PACK_LSBYTE_FIRST + * corresponding to the host's endian. + * + * - #INTEGER_PACK_2COMP: + * Uses 2's complement representation. + * + * - #INTEGER_PACK_LITTLE_ENDIAN: Shorthand of + * `INTEGER_PACK_LSWORD_FIRST|INTEGER_PACK_LSBYTE_FIRST`. + * + * - #INTEGER_PACK_BIG_ENDIAN: Shorthand of + * `INTEGER_PACK_MSWORD_FIRST|INTEGER_PACK_MSBYTE_FIRST`. + * + * - #INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION: + * Uses generic implementation (for test and debug). + * + * This function fills the buffer specified by `words` as `val`'s 2's + * complement representation if #INTEGER_PACK_2COMP is specified in `flags`. + * Otherwise it fills `words` as `abs(val)` and signedness is returned via the + * return value. + * + * @return The signedness and overflow condition. The overflow condition + * depends on #INTEGER_PACK_2COMP. + * + * When #INTEGER_PACK_2COMP is not specified: + * + * - `-2` : + * Negative overflow. `val <= -2**(numwords*(wordsize*CHAR_BIT-nails))` + * + * - `-1` : + * Negative without overflow. + * `-2**(numwords*(wordsize*CHAR_BIT-nails)) < val < 0` + * + * - `0` : zero. `val == 0` + * + * - `1` : + * Positive without overflow. + * `0 < val < 2**(numwords*(wordsize*CHAR_BIT-nails))` + * + * - `2` : + * Positive overflow. `2**(numwords*(wordsize*CHAR_BIT-nails)) <= val` + * + * When #INTEGER_PACK_2COMP is specified: + * + * - `-2` : + * Negative overflow. `val < -2**(numwords*(wordsize*CHAR_BIT-nails))` + * + * - `-1` : + * Negative without overflow. + * `-2**(numwords*(wordsize*CHAR_BIT-nails)) <= val < 0` + * + * - `0` : zero. `val == 0` + * + * - `1` : + * Positive without overflow. + * `0 < val < 2**(numwords*(wordsize*CHAR_BIT-nails))` + * + * - `2` : + * Positive overflow. `2**(numwords*(wordsize*CHAR_BIT-nails)) <= val` + * + * The value, `-2**(numwords*(wordsize*CHAR_BIT-nails))`, is representable in + * 2's complement representation but not representable in absolute value. So + * `-1` is returned for the value if #INTEGER_PACK_2COMP is specified but + * returns `-2` if #INTEGER_PACK_2COMP is not specified. + * + * The least significant words are filled in the buffer when overflow occur. + */ int rb_integer_pack(VALUE val, void *words, size_t numwords, size_t wordsize, size_t nails, int flags); + +RBIMPL_ATTR_NONNULL(()) +/** + * Import an integer from a buffer. + * + * @param[in] words Buffer to import. + * @param[in] numwords Number of words of `words`. + * @param[in] wordsize Number of bytes per word. + * @param[in] nails Number of padding bits in a word. Most + * significant nails bits of each word are ignored. + * @param[in] flags Bitwise or of constants whose name starts + * "INTEGER_PACK_". + * @exception rb_eArgError `numwords * wordsize` too big. + * + * Possible flags are: + * + * - #INTEGER_PACK_MSWORD_FIRST: + * Interpret the first word as the most significant word. + * + * - #INTEGER_PACK_LSWORD_FIRST: + * Interpret the first word as the least significant word. + * + * - #INTEGER_PACK_MSBYTE_FIRST: + * Interpret the first byte in a word as the most significant byte in the + * word. + * + * - #INTEGER_PACK_LSBYTE_FIRST: + * Interpret the first byte in a word as the least significant byte in + * the word. + * + * - #INTEGER_PACK_NATIVE_BYTE_ORDER: + * Either #INTEGER_PACK_MSBYTE_FIRST or #INTEGER_PACK_LSBYTE_FIRST + * corresponding to the host's endian. + * + * - #INTEGER_PACK_2COMP: + * Uses 2's complement representation. + * + * - #INTEGER_PACK_LITTLE_ENDIAN: Shorthand of + * `INTEGER_PACK_LSWORD_FIRST|INTEGER_PACK_LSBYTE_FIRST` + * + * - #INTEGER_PACK_BIG_ENDIAN: Shorthand of + * `INTEGER_PACK_MSWORD_FIRST|INTEGER_PACK_MSBYTE_FIRST` + * + * - #INTEGER_PACK_FORCE_BIGNUM: + * Returns a bignum even if its value is representable as a fixnum. + * + * - #INTEGER_PACK_NEGATIVE: + * Returns a non-positive value. (Returns a non-negative value if not + * specified.) + * + * - #INTEGER_PACK_FORCE_GENERIC_IMPLEMENTATION: + * Uses generic implementation (for test and debug). + * + * @return An instance of ::rb_cInteger whose value is the interpreted + * `words`. The range of the result value depends on + * #INTEGER_PACK_2COMP and #INTEGER_PACK_NEGATIVE. + * + * When #INTEGER_PACK_2COMP is not set: + * + * - `0 <= val < 2**(numwords*(wordsize*CHAR_BIT-nails))` if + * `!INTEGER_PACK_NEGATIVE` + * + * - `-2**(numwords*(wordsize*CHAR_BIT-nails)) < val <= 0` if + * `INTEGER_PACK_NEGATIVE` + * + * When #INTEGER_PACK_2COMP is set: + * + * - `-2**(numwords*(wordsize*CHAR_BIT-nails)-1)` `<= val <=` + * `2**(numwords*(wordsize*CHAR_BIT-nails)-1)-1` if + * `!INTEGER_PACK_NEGATIVE` + * + * - `-2**(numwords*(wordsize*CHAR_BIT-nails)) <= val <= -1` if + * `INTEGER_PACK_NEGATIVE` + * + * Passing #INTEGER_PACK_2COMP without #INTEGER_PACK_NEGATIVE means sign + * extension. #INTEGER_PACK_2COMP with #INTEGER_PACK_NEGATIVE means assuming + * the higher bits are `1`. + * + * Note that this function returns 0 when `numwords` is zero and + * #INTEGER_PACK_2COMP is set but #INTEGER_PACK_NEGATIVE is not set. + */ VALUE rb_integer_unpack(const void *words, size_t numwords, size_t wordsize, size_t nails, int flags); + +/** + * Calculates the number of bytes needed to represent the absolute value of the + * passed integer. + * + * @param[in] val Integer or integer-like object which has + * `#to_int` method. + * @param[out] nlz_bits_ret Number of leading zero bits in the most + * significant byte is returned if not `NULL`. + * @exception rb_eTypeError `val` doesn't respond to `#to_int`. + * @return `((val_numbits * CHAR_BIT + CHAR_BIT - 1) / CHAR_BIT)`, where + * val_numbits is the number of bits of `abs(val)`. + * @post If `nlz_bits_ret` is not `NULL`, + * `(return_value * CHAR_BIT - val_numbits)` is stored in + * `*nlz_bits_ret`. In this case, + * `0 <= *nlz_bits_ret < CHAR_BIT`. + * + * This function should not overflow. + */ size_t rb_absint_size(VALUE val, int *nlz_bits_ret); + +/** + * Calculates the number of words needed represent the absolute value of the + * passed integer. Unlike rb_absint_size() this function can overflow. It + * returns `(size_t)-1` then. + * + * @param[in] val Integer or integer-like object which has + * `#to_int` method. + * @param[in] word_numbits Number of bits per word. + * @param[out] nlz_bits_ret Number of leading zero bits in the most + * significant word is returned if not `NULL`. + * @exception rb_eTypeError `val` doesn't respond to `#to_int`. + * @retval (size_t)-1 Overflowed. + * @retval otherwise + * `((val_numbits * CHAR_BIT + word_numbits - 1) / word_numbits)`, + * where val_numbits is the number of bits of `abs(val)`. + * @post If `nlz_bits_ret` is not `NULL` and there is no overflow, + * `(return_value * word_numbits - val_numbits)` is stored in + * `*nlz_bits_ret`. In this case, + * `0 <= *nlz_bits_ret < word_numbits.` + * + */ size_t rb_absint_numwords(VALUE val, size_t word_numbits, size_t *nlz_bits_ret); + +/** + * Tests `abs(val)` consists only of a bit or not. + * + * @param[in] val Integer or integer-like object which has + * `#to_int` method. + * @exception rb_eTypeError `val` doesn't respond to `#to_int`. + * @retval 1 `abs(val) == 1 << n` for some `n >= 0`. + * @retval 0 Otherwise. + * + * rb_absint_singlebit_p() can be used to determine required buffer size for + * rb_integer_pack() used with #INTEGER_PACK_2COMP (two's complement). + * + * Following example calculates number of bits required to represent val in + * two's complement number, without sign bit. + * + * ```CXX + * size_t size; + * int neg = FIXNUM_P(val) ? FIX2LONG(val) < 0 : BIGNUM_NEGATIVE_P(val); + * size = rb_absint_numwords(val, 1, NULL) + * if (size == (size_t)-1) ...overflow... + * if (neg && rb_absint_singlebit_p(val)) + * size--; + * ``` + * + * Following example calculates number of bytes required to represent val in + * two's complement number, with sign bit. + * + * ```CXX + * size_t size; + * int neg = FIXNUM_P(val) ? FIX2LONG(val) < 0 : BIGNUM_NEGATIVE_P(val); + * int nlz_bits; + * size = rb_absint_size(val, &nlz_bits); + * if (nlz_bits == 0 && !(neg && rb_absint_singlebit_p(val))) + * size++; + * ``` + */ int rb_absint_singlebit_p(VALUE val); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/intern/class.h b/include/ruby/internal/intern/class.h index d80fd9739e..357af5d176 100644 --- a/include/ruby/internal/intern/class.h +++ b/include/ruby/internal/intern/class.h @@ -27,30 +27,367 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* class.c */ -VALUE rb_class_new(VALUE); -VALUE rb_mod_init_copy(VALUE, VALUE); -VALUE rb_singleton_class_clone(VALUE); -void rb_singleton_class_attached(VALUE,VALUE); -void rb_check_inheritable(VALUE); -VALUE rb_define_class_id(ID, VALUE); -VALUE rb_define_class_id_under(VALUE, ID, VALUE); + +/** + * Creates a new, anonymous class. + * + * @param[in] super What would become a parent class. + * @exception rb_eTypeError `super` is not something inheritable. + * @return An anonymous class that inherits `super`. + */ +VALUE rb_class_new(VALUE super); + +/** + * The comment that comes with this function says `:nodoc:`. Not sure what + * that means though. + * + * @param[out] clone Destination object. + * @param[in] orig Source object. + * @exception rb_eTypeError Cannot copy `orig`. + * @return The passed `clone`. + */ +VALUE rb_mod_init_copy(VALUE clone, VALUE orig); + +/** + * Asserts that the given class can derive a child class. A class might or + * might not be able to do so; for instance a singleton class cannot. + * + * @param[in] super Possible super class. + * @exception rb_eTypeError No it cannot. + * @post Upon successful return `super` can derive. + */ +void rb_check_inheritable(VALUE super); + +/** + * This is a very badly designed API that creates an anonymous class. + * + * @param[in] id Discarded for no reason (why...). + * @param[in] super What would become a parent class. 0 means + * ::rb_cObject. + * @exception rb_eTypeError `super` is not something inheritable. + * @return An anonymous class that inherits `super`. + * @warning You must explicitly name the return value. + */ +VALUE rb_define_class_id(ID id, VALUE super); + +/** + * Identical to rb_define_class_under(), except it takes the name in ::ID + * instead of C's string. + * + * @param[out] outer A class which contains the new class. + * @param[in] id Name of the new class + * @param[in] super A class from which the new class will derive. + * 0 means ::rb_cObject. + * @exception rb_eTypeError The constant name `id` is already taken but the + * constant is not a class. + * @exception rb_eTypeError The class is already defined but the class can + * not be reopened because its superclass is not + * `super`. + * @exception rb_eArgError `super` is NULL. + * @return The created class. + * @post `outer::id` refers the returned class. + * @note If a class named `id` is already defined and its superclass is + * `super`, the function just returns the defined class. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. + */ +VALUE rb_define_class_id_under(VALUE outer, ID id, VALUE super); + +/** + * Creates a new, anonymous module. + * + * @return An anonymous module. + */ VALUE rb_module_new(void); -VALUE rb_define_module_id(ID); -VALUE rb_define_module_id_under(VALUE, ID); -VALUE rb_mod_included_modules(VALUE); -VALUE rb_mod_include_p(VALUE, VALUE); -VALUE rb_mod_ancestors(VALUE); -VALUE rb_class_instance_methods(int, const VALUE*, VALUE); -VALUE rb_class_public_instance_methods(int, const VALUE*, VALUE); -VALUE rb_class_protected_instance_methods(int, const VALUE*, VALUE); -VALUE rb_class_private_instance_methods(int, const VALUE*, VALUE); -VALUE rb_obj_singleton_methods(int, const VALUE*, VALUE); -void rb_define_method_id(VALUE, ID, VALUE (*)(ANYARGS), int); -void rb_undef(VALUE, ID); -void rb_define_protected_method(VALUE, const char*, VALUE (*)(ANYARGS), int); -void rb_define_private_method(VALUE, const char*, VALUE (*)(ANYARGS), int); -void rb_define_singleton_method(VALUE, const char*, VALUE(*)(ANYARGS), int); -VALUE rb_singleton_class(VALUE); + + +/** + * Creates a new, anonymous refinement. + * + * @return An anonymous refinement. + */ +VALUE rb_refinement_new(void); + +/** + * This is a very badly designed API that creates an anonymous module. + * + * @param[in] id Discarded for no reason (why...). + * @return An anonymous module. + * @warning You must explicitly name the return value. + */ +VALUE rb_define_module_id(ID id); + +/** + * Identical to rb_define_module_under(), except it takes the name in ::ID + * instead of C's string. + * + * @param[out] outer A class which contains the new module. + * @param[in] id Name of the new module + * @exception rb_eTypeError The constant name `id` is already taken but the + * constant is not a module. + * @return The created module. + * @post `outer::id` refers the returned module. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. + */ +VALUE rb_define_module_id_under(VALUE outer, ID id); + +/** + * Queries the list of included modules. It can also be seen as a routine to + * first call rb_mod_ancestors(), then rejects non-modules from the return + * value. + * + * @param[in] mod Class or Module. + * @return An array of modules that are either included or prepended in any + * of `mod`'s ancestry tree (including itself). + */ +VALUE rb_mod_included_modules(VALUE mod); + +/** + * Queries if the passed module is included by the module. It can also be seen + * as a routine to first call rb_mod_included_modules(), then see if the return + * value contains the passed module. + * + * @param[in] child A Module. + * @param[in] parent Another Module. + * @exception rb_eTypeError `child` is not an instance of ::rb_cModule. + * @retval RUBY_Qtrue `parent` is either included or prepended in any + * of `child`'s ancestry tree (including itself). + * @return RUBY_Qfalse Otherwise. + */ +VALUE rb_mod_include_p(VALUE child, VALUE parent); + +/** + * Queries the module's ancestors. This routine gathers classes and modules + * that the passed module either inherits, includes, or prepends, then + * recursively applies that routine again and again to the collected entries + * until the list doesn't grow up. + * + * @param[in] mod A module or a class. + * @return An array of classes or modules that `mod` possibly recursively + * inherits, includes, or prepends. + * + * @internal + * + * Above description is written in a recursive language but in practice it + * computes the return value iteratively. + */ +VALUE rb_mod_ancestors(VALUE mod); + +/** + * Queries the class's descendants. This routine gathers classes that are + * subclasses of the given class (or subclasses of those subclasses, etc.), + * returning an array of classes that have the given class as an ancestor. + * The returned array does not include the given class or singleton classes. + * + * @param[in] klass A class. + * @return An array of classes where `klass` is an ancestor. + * + * @internal + */ +VALUE rb_class_descendants(VALUE klass); + +/** + * Queries the class's direct descendants. This routine gathers classes that are + * direct subclasses of the given class, + * returning an array of classes that have the given class as a superclass. + * The returned array does not include singleton classes. + * + * @param[in] klass A class. + * @return An array of classes where `klass` is the `superclass`. + * + * @internal + */ +VALUE rb_class_subclasses(VALUE klass); + + +/** + * Returns the attached object for a singleton class. + * If the given class is not a singleton class, raises a TypeError. + * + * @param[in] klass A class. + * @return The object which has the singleton class `klass`. + * + * @internal + */ +VALUE rb_class_attached_object(VALUE klass); + +/** + * Generates an array of symbols, which are the list of method names defined in + * the passed class. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Array of at most one object, which controls (if + * any) whether the return array includes the names + * of methods defined in ancestors or not. + * @param[in] mod A module or a class. + * @exception rb_eArgError `argc` out of range. + * @return An array of symbols collecting names of instance methods that + * are not private, defined at `mod`. + */ +VALUE rb_class_instance_methods(int argc, const VALUE *argv, VALUE mod); + +/** + * Identical to rb_class_instance_methods(), except it returns names of methods + * that are public only. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Array of at most one object, which controls (if + * any) whether the return array includes the names + * of methods defined in ancestors or not. + * @param[in] mod A module or a class. + * @exception rb_eArgError `argc` out of range. + * @return An array of symbols collecting names of instance methods that + * are public, defined at `mod`. + */ +VALUE rb_class_public_instance_methods(int argc, const VALUE *argv, VALUE mod); + +/** + * Identical to rb_class_instance_methods(), except it returns names of methods + * that are protected only. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Array of at most one object, which controls (if + * any) whether the return array includes the names + * of methods defined in ancestors or not. + * @param[in] mod A module or a class. + * @exception rb_eArgError `argc` out of range. + * @return An array of symbols collecting names of instance methods that + * are protected, defined at `mod`. + */ +VALUE rb_class_protected_instance_methods(int argc, const VALUE *argv, VALUE mod); + +/** + * Identical to rb_class_instance_methods(), except it returns names of methods + * that are private only. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Array of at most one object, which controls (if + * any) whether the return array includes the names + * of methods defined in ancestors or not. + * @param[in] mod A module or a class. + * @exception rb_eArgError `argc` out of range. + * @return An array of symbols collecting names of instance methods that + * are protected, defined at `mod`. + */ +VALUE rb_class_private_instance_methods(int argc, const VALUE *argv, VALUE mod); + +/** + * Identical to rb_class_instance_methods(), except it returns names of + * singleton methods instead of instance methods. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Array of at most one object, which controls (if + * any) whether the return array includes the names + * of methods defined in ancestors or not. + * @param[in] obj Arbitrary ruby object. + * @exception rb_eArgError `argc` out of range. + * @return An array of symbols collecting names of instance methods that + * are not private, defined at the singleton class of `obj`. + */ +VALUE rb_obj_singleton_methods(int argc, const VALUE *argv, VALUE obj); + +/** + * Identical to rb_define_method(), except it takes the name of the method in + * ::ID instead of C's string. + * + * @param[out] klass A module or a class. + * @param[in] mid Name of the function. + * @param[in] func The method body. + * @param[in] arity The number of parameters. See @ref defmethod. + * @note There are in fact 18 different prototypes for func. + * @see ::ruby::backward::cxxanyargs::define_method::rb_define_method_id + */ +void rb_define_method_id(VALUE klass, ID mid, VALUE (*func)(ANYARGS), int arity); + +/* vm_method.c */ + +/** + * Inserts a method entry that hides previous method definition of the given + * name. This is not a deletion of a method. Method of the same name defined + * in a parent class is kept invisible in this way. + * + * @param[out] mod The module to insert an undef. + * @param[in] mid Name of the undef. + * @exception rb_eTypeError `klass` is a non-module. + * @exception rb_eFrozenError `klass` is frozen. + * @exception rb_eNameError No such method named `klass#name`. + * @post `klass#name` is undefined. + * @see rb_undef_method + * + * @internal + * + * @shyouhei doesn't understand why this is not the ::ID -taking variant of + * rb_undef_method(), given rb_remove_method() has its ::ID -taking counterpart + * named rb_remove_method_id(). + */ +void rb_undef(VALUE mod, ID mid); + +/* class.c */ + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_define_method(), except it defines a protected method. + * + * @param[out] klass A module or a class. + * @param[in] mid Name of the function. + * @param[in] func The method body. + * @param[in] arity The number of parameters. See @ref defmethod. + * @note There are in fact 18 different prototypes for func. + * @see ::ruby::backward::cxxanyargs::define_method::rb_define_protected_method + */ +void rb_define_protected_method(VALUE klass, const char *mid, VALUE (*func)(ANYARGS), int arity); + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_define_method(), except it defines a private method. + * + * @param[out] klass A module or a class. + * @param[in] mid Name of the function. + * @param[in] func The method body. + * @param[in] arity The number of parameters. See @ref defmethod. + * @note There are in fact 18 different prototypes for func. + * @see ::ruby::backward::cxxanyargs::define_method::rb_define_protected_method + */ +void rb_define_private_method(VALUE klass, const char *mid, VALUE (*func)(ANYARGS), int arity); + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_define_method(), except it defines a singleton method. + * + * @param[out] obj Arbitrary ruby object. + * @param[in] mid Name of the function. + * @param[in] func The method body. + * @param[in] arity The number of parameters. See @ref defmethod. + * @note There are in fact 18 different prototypes for func. + * @see ::ruby::backward::cxxanyargs::define_method::rb_define_singleton_method + */ +void rb_define_singleton_method(VALUE obj, const char *mid, VALUE(*func)(ANYARGS), int arity); + +/** + * Finds or creates the singleton class of the passed object. + * + * @param[out] obj Arbitrary ruby object. + * @exception rb_eTypeError `obj` cannot have its singleton class. + * @return A (possibly newly allocated) instance of ::rb_cClass. + * @post `obj` has its singleton class, which is the return value. + * @post In case `obj` is a class, the returned singleton class also has + * its own singleton class in order to keep consistency of the + * inheritance structure of metaclasses. + * @note A new singleton class will be created if `obj` did not have + * one. + * @note The singleton classes for ::RUBY_Qnil, ::RUBY_Qtrue, and + * ::RUBY_Qfalse are ::rb_cNilClass, ::rb_cTrueClass, and + * ::rb_cFalseClass respectively. + * + * @internal + * + * You can _create_ a singleton class of a frozen object. Intentional or ...? + * + * Nowadays there are wider range of objects who cannot have singleton classes + * than before. For instance some string instances cannot for some reason. + */ +VALUE rb_singleton_class(VALUE obj); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/intern/compar.h b/include/ruby/internal/intern/compar.h index ede86267a2..dc3b377b01 100644 --- a/include/ruby/internal/intern/compar.h +++ b/include/ruby/internal/intern/compar.h @@ -20,14 +20,42 @@ * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_mComparable. */ +#include "ruby/internal/attr/cold.h" +#include "ruby/internal/attr/noreturn.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" RBIMPL_SYMBOL_EXPORT_BEGIN() +/* bignum.c */ + +/** + * Canonicalises the passed `val`, which is the return value of `a <=> b`, into + * C's `{-1, 0, 1}`. This can be handy when you implement a callback function + * to pass to `qsort(3)` etc. + * + * @param[in] val Return value of a space ship operator. + * @param[in] a Comparison LHS. + * @param[in] b Comparison RHS. + * @exception rb_eArgError `a` and `b` are not comparable each other. + * @retval -1 `val` is less than zero. + * @retval 0 `val` is equal to zero. + * @retval 1 `val` is greater than zero. + */ +int rb_cmpint(VALUE val, VALUE a, VALUE b); + /* compar.c */ -int rb_cmpint(VALUE, VALUE, VALUE); -NORETURN(void rb_cmperr(VALUE, VALUE)); + +RBIMPL_ATTR_COLD() +RBIMPL_ATTR_NORETURN() +/** + * Raises "comparison failed" error. + * + * @param[in] a Comparison LHS. + * @param[in] b Comparison RHS. + * @exception rb_eArgError `a` and `b` are not comparable each other. + */ +void rb_cmperr(VALUE a, VALUE b); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/intern/complex.h b/include/ruby/internal/intern/complex.h index 41c7164ba6..1efc093631 100644 --- a/include/ruby/internal/intern/complex.h +++ b/include/ruby/internal/intern/complex.h @@ -20,6 +20,8 @@ * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_cComplex. */ +#include "ruby/internal/attr/deprecated.h" +#include "ruby/internal/attr/pure.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" #include "ruby/internal/arithmetic/long.h" /* INT2FIX is here. */ @@ -27,32 +29,219 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* complex.c */ -VALUE rb_complex_raw(VALUE, VALUE); + +/** + * Identical to rb_complex_new(), except it assumes both arguments are not + * instances of ::rb_cComplex. It is thus dangerous for extension libraries. + * + * @param[in] real Real part, in any numeric except Complex. + * @param[in] imag Imaginary part, in any numeric except Complex. + * @return An instance of ::rb_cComplex whose value is `real + (imag)i`. + */ +VALUE rb_complex_raw(VALUE real, VALUE imag); + +/** + * Shorthand of `x+0i`. It practically converts `x` into a Complex of the + * identical value. + * + * @param[in] x Any numeric except Complex. + * @return An instance of ::rb_cComplex, whose value is `x + 0i`. + */ #define rb_complex_raw1(x) rb_complex_raw((x), INT2FIX(0)) + +/** @alias{rb_complex_raw} */ #define rb_complex_raw2(x,y) rb_complex_raw((x), (y)) -VALUE rb_complex_new(VALUE, VALUE); + +/** + * Constructs a Complex, by first multiplying the imaginary part with `1i` then + * adds it to the real part. This definition doesn't need both arguments be + * real numbers. It can happily combine two instances of ::rb_cComplex (with + * rotating the latter one). + * + * @param[in] real An instance of ::rb_cNumeric. + * @param[in] imag Another instance of ::rb_cNumeric. + * @return An instance of ::rb_cComplex whose value is `imag * 1i + real`. + */ +VALUE rb_complex_new(VALUE real, VALUE imag); + +/** + * Shorthand of `x+0i`. It practically converts `x` into a Complex of the + * identical value. + * + * @param[in] x Any numeric value. + * @return An instance of ::rb_cComplex, whose value is `x + 0i`. + */ #define rb_complex_new1(x) rb_complex_new((x), INT2FIX(0)) + +/** @alias{rb_complex_new} */ #define rb_complex_new2(x,y) rb_complex_new((x), (y)) + +/** + * Constructs a Complex using polar representations. Unlike rb_complex_new() + * it makes no sense to pass non-real instances to this function. + * + * @param[in] abs Magnitude, in any numeric except Complex. + * @param[in] arg Angle, in radians, in any numeric except Complex. + * @return An instance of ::rb_cComplex which denotes the given polar + * coordinates. + */ VALUE rb_complex_new_polar(VALUE abs, VALUE arg); -DEPRECATED_BY(rb_complex_new_polar, VALUE rb_complex_polar(VALUE abs, VALUE arg)); + +RBIMPL_ATTR_PURE() +/** + * Queries the real part of the passed Complex. + * + * @param[in] z An instance of ::rb_cComplex. + * @return Its real part, which is an instance of ::rb_cNumeric. + */ VALUE rb_complex_real(VALUE z); + +RBIMPL_ATTR_PURE() +/** + * Queries the imaginary part of the passed Complex. + * + * @param[in] z An instance of ::rb_cComplex. + * @return Its imaginary part, which is an instance of ::rb_cNumeric. + */ VALUE rb_complex_imag(VALUE z); + +/** + * Performs addition of the passed two objects. + * + * @param[in] x An instance of ::rb_cComplex. + * @param[in] y Arbitrary ruby object. + * @return What `x + y` evaluates to. + * @see rb_num_coerce_bin() + */ VALUE rb_complex_plus(VALUE x, VALUE y); + +/** + * Performs subtraction of the passed two objects. + * + * @param[in] x An instance of ::rb_cComplex. + * @param[in] y Arbitrary ruby object. + * @return What `x - y` evaluates to. + * @see rb_num_coerce_bin() + */ VALUE rb_complex_minus(VALUE x, VALUE y); + +/** + * Performs multiplication of the passed two objects. + * + * @param[in] x An instance of ::rb_cComplex. + * @param[in] y Arbitrary ruby object. + * @return What `x * y` evaluates to. + * @see rb_num_coerce_bin() + */ VALUE rb_complex_mul(VALUE x, VALUE y); + +/** + * Performs division of the passed two objects. + * + * @param[in] x An instance of ::rb_cComplex. + * @param[in] y Arbitrary ruby object. + * @return What `x / y` evaluates to. + * @see rb_num_coerce_bin() + */ VALUE rb_complex_div(VALUE x, VALUE y); + +/** + * Performs negation of the passed object. + * + * @param[in] z An instance of ::rb_cComplex. + * @return What `-z` evaluates to. + */ VALUE rb_complex_uminus(VALUE z); + +/** + * Performs complex conjugation of the passed object. + * + * @param[in] z An instance of ::rb_cComplex. + * @return Its complex conjugate, in ::rb_cComplex. + */ VALUE rb_complex_conjugate(VALUE z); + +/** + * Queries the absolute (or the magnitude) of the passed object. + * + * @param[in] z An instance of ::rb_cComplex. + * @return Its magnitude, in ::rb_cFloat. + */ VALUE rb_complex_abs(VALUE z); + +/** + * Queries the argument (or the angle) of the passed object. + * + * @param[in] z An instance of ::rb_cComplex. + * @return Its magnitude, in ::rb_cFloat. + */ VALUE rb_complex_arg(VALUE z); + +/** + * Performs exponentiation of the passed two objects. + * + * @param[in] base An instance of ::rb_cComplex. + * @param[in] exp Arbitrary ruby object. + * @return What `base ** exp` evaluates to. + * @see rb_num_coerce_bin() + */ VALUE rb_complex_pow(VALUE base, VALUE exp); + +/** + * Identical to rb_complex_new(), except it takes the arguments as C's double + * instead of Ruby's object. + * + * @param[in] real Real part. + * @param[in] imag Imaginary part. + * @return An instance of ::rb_cComplex whose value is `real + (imag)i`. + */ VALUE rb_dbl_complex_new(double real, double imag); + +/** @alias{rb_complex_plus} */ #define rb_complex_add rb_complex_plus + +/** @alias{rb_complex_minus} */ #define rb_complex_sub rb_complex_minus + +/** @alias{rb_complex_uminus} */ #define rb_complex_nagate rb_complex_uminus -VALUE rb_Complex(VALUE, VALUE); +/** + * Converts various values into a Complex. This function accepts: + * + * - Instances of ::rb_cComplex (taken as-is), + * - Instances of ::rb_cNumeric (adds `0i`), + * - Instances of ::rb_cString (parses), + * - Other objects that respond to `#to_c`. + * + * It (possibly recursively) applies `#to_c` until both sides become a Complex + * value, then computes `imag * 1i + real`. + * + * As a special case, passing ::RUBY_Qundef to `imag` is the same as passing + * `RB_INT2NUM(0)`. + * + * @param[in] real Real part (see above). + * @param[in] imag Imaginary part (see above). + * @exception rb_eTypeError Passed something not described above. + * @return An instance of ::rb_cComplex whose value is `1i * imag + real`. + * + * @internal + * + * This was the implementation of `Kernel#Complex` before, but they diverged. + */ +VALUE rb_Complex(VALUE real, VALUE imag); + +/** + * Shorthand of `x+0i`. It practically converts `x` into a Complex of the + * identical value. + * + * @param[in] x ::rb_cNumeric, ::rb_cString, or something that responds to + * `#to_c`. + * @return An instance of ::rb_cComplex, whose value is `x + 0i`. + */ #define rb_Complex1(x) rb_Complex((x), INT2FIX(0)) + +/** @alias{rb_Complex} */ #define rb_Complex2(x,y) rb_Complex((x), (y)) RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/intern/cont.h b/include/ruby/internal/intern/cont.h index ebecbfbb35..2d813ceb9d 100644 --- a/include/ruby/internal/intern/cont.h +++ b/include/ruby/internal/intern/cont.h @@ -27,20 +27,259 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* cont.c */ -VALUE rb_fiber_new(rb_block_call_func_t, VALUE); + +/** + * Creates a Fiber instance from a C-backended block. + * + * @param[in] func A function, to become the fiber's body. + * @param[in] callback_obj Passed as-is to `func`. + * @return An allocated new instance of rb_cFiber, which is ready to be + * "resume"d. + */ +VALUE rb_fiber_new(rb_block_call_func_t func, VALUE callback_obj); + +/** + * Creates a Fiber instance from a C-backended block with the specified + * storage. + * + * If the given storage is Qundef or Qtrue, this function is equivalent to + * rb_fiber_new() which inherits storage from the current fiber. + * + * Specifying Qtrue is experimental and may be changed in the future. + * + * If the given storage is Qnil, this function will lazy initialize the + * internal storage which starts of empty (without any inheritance). + * + * Otherwise, the given storage is used as the internal storage. + * + * @param[in] func A function, to become the fiber's body. + * @param[in] callback_obj Passed as-is to `func`. + * @param[in] storage The way to set up the storage for the fiber. + * @return An allocated new instance of rb_cFiber, which is ready to be + * "resume"d. + */ +VALUE rb_fiber_new_storage(rb_block_call_func_t func, VALUE callback_obj, VALUE storage); + +/** + * Queries the fiber which is calling this function. Any ruby execution + * context has its fiber, either explicitly or implicitly. + * + * @return The current fiber. + */ VALUE rb_fiber_current(void); -VALUE rb_fiber_alive_p(VALUE); -VALUE rb_obj_is_fiber(VALUE); +/** + * Queries the liveness of the passed fiber. "Alive" in this context means + * that the fiber can still be resumed. Once it reaches is its end of + * execution, this function returns ::RUBY_Qfalse. + * + * @param[in] fiber A target fiber. + * @retval RUBY_Qtrue It is. + * @retval RUBY_Qfalse It isn't. + */ +VALUE rb_fiber_alive_p(VALUE fiber); + +/** + * Queries if an object is a fiber. + * + * @param[in] obj Arbitrary ruby object. + * @retval RUBY_Qtrue It is. + * @retval RUBY_Qfalse It isn't. + */ +VALUE rb_obj_is_fiber(VALUE obj); + +/** + * Resumes the execution of the passed fiber, either from the point at which + * the last rb_fiber_yield() was called if any, or at the beginning of the + * fiber body if it is the first call to this function. + * + * Other arguments are passed into the fiber's body, either as return values of + * rb_fiber_yield() in case it switches to there, or as the block parameter of + * the fiber body if it switches to the beginning of the fiber. + * + * The return value of this function is either the value passed to previous + * rb_fiber_yield() call, or the ultimate evaluated value of the entire fiber + * body if the execution reaches the end of it. + * + * When an exception happens inside of a fiber it propagates to this function. + * + * ```ruby + * f = Fiber.new do |i| + * puts "<x> =>> #{i}" + * puts "<y> <-- #{i + 1}" + * j = Fiber.yield(i + 1) + * puts "<z> =>> #{j}" + * puts "<w> <-- #{j + 1}" + * next j + 1 + * end + * + * puts "[a] <-- 1" + * p = f.resume(1) + * puts "[b] =>> #{p}" + * puts "[c] <-- #{p + 1}" + * q = f.resume(p + 1) + * puts "[d] =>> #{q}" + * ``` + * + * Above program executes in `[a] <x> <y> [b] [c] <z> <w> [d]`. + * + * @param[out] fiber The fiber to resume. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed (somehow) to `fiber`. + * @exception rb_eFiberError `fib` is terminated etc. + * @exception rb_eException Any exceptions happen in `fiber`. + * @return (See above) + * @note This function _does_ return. + * + * @internal + * + * @shyouhei expected this function to raise ::rb_eFrozenError for frozen + * fibers but it doesn't in practice. Intentional or ...? + */ VALUE rb_fiber_resume(VALUE fiber, int argc, const VALUE *argv); + +/** + * Identical to rb_fiber_resume(), except you can specify how to handle the + * last element of the given array. + * + * @param[out] fiber The fiber to resume. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed (somehow) to `fiber`. + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. + * @exception rb_eFiberError `fiber` is terminated etc. + * @exception rb_eException Any exceptions happen in `fiber`. + * @return Either what was yielded or the last value of the fiber body. + */ VALUE rb_fiber_resume_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat); +/** + * Yields the control back to the point where the current fiber was resumed. + * The passed objects would be the return value of rb_fiber_resume(). This + * fiber then suspends its execution until next time it is resumed. + * + * This function can also raise arbitrary exceptions injected from outside of + * the fiber using rb_fiber_raise(). + * + * ```ruby + * exc = Class.new Exception + * + * f = Fiber.new do + * Fiber.yield + * rescue exc => e + * puts e.message + * end + * + * f.resume + * f.raise exc, "Hi!" + * ``` + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed to rb_fiber_resume(). + * @exception rb_eException (See above) + * @return (See rb_fiber_resume() for details) + */ VALUE rb_fiber_yield(int argc, const VALUE *argv); + +/** + * Identical to rb_fiber_yield(), except you can specify how to handle the last + * element of the given array. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed to rb_fiber_resume(). + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. + * @exception rb_eException What was raised using `Fiber#raise`. + * @return (See rb_fiber_resume() for details) + */ VALUE rb_fiber_yield_kw(int argc, const VALUE *argv, int kw_splat); +/** + * Transfers control to another fiber, resuming it from where it last stopped + * or starting it if it was not resumed before. The calling fiber will be + * suspended much like in a call to rb_fiber_yield(). + * + * The fiber which receives the transfer call treats it much like a resume + * call. Arguments passed to transfer are treated like those passed to resume. + * + * The two style of control passing to and from fiber (one is rb_fiber_resume() + * and rb_fiber_yield(), another is rb_fiber_transfer() to and from fiber) + * can't be freely mixed. + * + * - If the Fiber's lifecycle had started with transfer, it will never be + * able to yield or be resumed control passing, only finish or transfer + * back. (It still can resume other fibers that are allowed to be + * resumed.) + * + * - If the Fiber's lifecycle had started with resume, it can yield or + * transfer to another Fiber, but can receive control back only the way + * compatible with the way it was given away: if it had transferred, it + * only can be transferred back, and if it had yielded, it only can be + * resumed back. After that, it again can transfer or yield. + * + * If those rules are broken, rb_eFiberError is raised. + * + * For an individual Fiber design, yield/resume is easier to use (the Fiber + * just gives away control, it doesn't need to think about who the control is + * given to), while transfer is more flexible for complex cases, allowing to + * build arbitrary graphs of Fibers dependent on each other. + * + * @param[out] fiber Explicit control destination. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed to rb_fiber_resume(). + * @exception rb_eFiberError (See above) + * @exception rb_eException What was raised using `Fiber#raise`. + * @return (See rb_fiber_resume() for details) + */ VALUE rb_fiber_transfer(VALUE fiber, int argc, const VALUE *argv); + +/** + * Identical to rb_fiber_transfer(), except you can specify how to handle the + * last element of the given array. + * + * @param[out] fiber Explicit control destination. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Passed to rb_fiber_resume(). + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. + * @exception rb_eFiberError (See above) + * @exception rb_eException What was raised using `Fiber#raise`. + * @return (See rb_fiber_resume() for details) + */ VALUE rb_fiber_transfer_kw(VALUE fiber, int argc, const VALUE *argv, int kw_splat); +/** + * Identical to rb_fiber_resume() but instead of resuming normal execution of + * the passed fiber, it raises the given exception in it. From inside of the + * fiber this would be seen as if rb_fiber_yield() raised. + * + * This function does return in case the passed fiber gracefully handled the + * passed exception. But if it does not, the raised exception propagates out + * of the passed fiber; this function then does not return. + * + * Parameters are passed to rb_make_exception() to create an exception object. + * See its document for what are allowed here. + * + * It is a failure to call this function against a fiber which is resuming, + * have never run yet, or has already finished running. + * + * @param[out] fiber Where exception is raised. + * @param[in] argc Passed as-is to rb_make_exception(). + * @param[in] argv Passed as-is to rb_make_exception(). + * @exception rb_eFiberError `fiber` is terminated etc. + * @return (See rb_fiber_resume() for details) + */ +VALUE rb_fiber_raise(VALUE fiber, int argc, VALUE *argv); + RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_INTERN_CONT_H */ diff --git a/include/ruby/internal/intern/dir.h b/include/ruby/internal/intern/dir.h index 4b2608e5e6..da1873e068 100644 --- a/include/ruby/internal/intern/dir.h +++ b/include/ruby/internal/intern/dir.h @@ -26,6 +26,15 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* dir.c */ + +/** + * Queries the path of the current working directory of the current process. + * + * @return An instance of ::rb_cString that holds the working directory. + * @note The returned string is in "filesystem" encoding. Most notably on + * Linux this is an alias of default external encoding. Most notably + * on Windows it can be an alias of OS codepage. + */ VALUE rb_dir_getwd(void); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/intern/enum.h b/include/ruby/internal/intern/enum.h index e1d65b5c9a..215ad82672 100644 --- a/include/ruby/internal/intern/enum.h +++ b/include/ruby/internal/intern/enum.h @@ -26,7 +26,47 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* enum.c */ -VALUE rb_enum_values_pack(int, const VALUE*); + +/** + * Basically identical to rb_ary_new_form_values(), except it returns something + * different when `argc` < 2. + * + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arbitrary objects. + * @retval RUBY_Qnil `argc` is zero. + * @retval argv[0] `argc` is one. + * @retval otherwise Otherwise. + * + * @internal + * + * What is this business? Well, this function is about `yield`'s taking + * multiple values. Consider following user-defined class: + * + * ```ruby + * class Foo + * include Enumerable + * + * def each + * yield :q, :w, :e, :r + * end + * end + * + * Foo.new.each_with_object([]) do |i, j| + * j << i # ^^^ <- What to expect for `i`? + * end + * ``` + * + * Here, `Foo#each_with_object` is in fact `Enumerable#each_with_object`, which + * doesn't know what would be yielded. Yet, it has to take a block of arity 2. + * This function is used here, to "pack" arbitrary number of yielded objects + * into one. + * + * If people want to implement their own `Enumerable#each_with_object` this API + * can be handy. Though @shyouhei suspects it is relatively rare for 3rd party + * extension libraries to have such things. Also `Enumerable#each_entry` is + * basically this function exposed as a Ruby method. + */ +VALUE rb_enum_values_pack(int argc, const VALUE *argv); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/internal/intern/enumerator.h b/include/ruby/internal/intern/enumerator.h index 2ee88bafe6..00804d786a 100644 --- a/include/ruby/internal/intern/enumerator.h +++ b/include/ruby/internal/intern/enumerator.h @@ -20,6 +20,7 @@ * extension libraries. They could be written in C++98. * @brief Public APIs related to ::rb_cEnumerator. */ +#include "ruby/internal/attr/nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/intern/eval.h" /* rb_frame_this_func */ #include "ruby/internal/iterator.h" /* rb_block_given_p */ @@ -28,52 +29,234 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() -typedef VALUE rb_enumerator_size_func(VALUE, VALUE, VALUE); +/** + * This is the type of functions that rb_enumeratorize_with_size() expects. In + * theory an enumerator can have indefinite number of elements, but in practice + * it often is the case we can compute the size of an enumerator beforehand. + * If your enumerator has such property, supply a function that calculates such + * values. + * + * @param[in] recv The original receiver of the enumerator. + * @param[in] argv Arguments passed to `Object#enum_for` etc. + * @param[in] eobj The enumerator object. + * @return The size of `eobj`, in ::rb_cNumeric, or ::RUBY_Qnil if the size + * is not known until we actually iterate. + */ +typedef VALUE rb_enumerator_size_func(VALUE recv, VALUE argv, VALUE eobj); +/** + * Decomposed `Enumerator::ArithmeicSequence`. This is a subclass of + * ::rb_cEnumerator, which represents a sequence of numbers with common + * difference. Internal data structure of the class is opaque to users, but + * you can obtain a decomposed one using rb_arithmetic_sequence_extract(). + */ typedef struct { - VALUE begin; - VALUE end; - VALUE step; - int exclude_end; + VALUE begin; /**< "Left" or "lowest" endpoint of the sequence. */ + VALUE end; /**< "Right" or "highest" endpoint of the sequence.*/ + VALUE step; /**< Step between a sequence. */ + int exclude_end; /**< Whether the endpoint is open or closed. */ } rb_arithmetic_sequence_components_t; /* enumerator.c */ -VALUE rb_enumeratorize(VALUE, VALUE, int, const VALUE *); -VALUE rb_enumeratorize_with_size(VALUE, VALUE, int, const VALUE *, rb_enumerator_size_func *); -VALUE rb_enumeratorize_with_size_kw(VALUE, VALUE, int, const VALUE *, rb_enumerator_size_func *, int); -int rb_arithmetic_sequence_extract(VALUE, rb_arithmetic_sequence_components_t *); -VALUE rb_arithmetic_sequence_beg_len_step(VALUE, long *begp, long *lenp, long *stepp, long len, int err); + +/** + * Constructs an enumerator. This roughly resembles `Object#enum_for`. + * + * @param[in] recv A receiver of `meth`. + * @param[in] meth Method ID in a symbol object. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to `meth`. + * @exception rb_eTypeError `meth` is not an instance of ::rb_cSymbol. + * @return A new instance of ::rb_cEnumerator which, when yielded, + * enumerates by calling `meth` on `recv` with `argv`. + */ +VALUE rb_enumeratorize(VALUE recv, VALUE meth, int argc, const VALUE *argv); + +/** + * Identical to rb_enumeratorize(), except you can additionally specify the + * size function of return value. + * + * @param[in] recv A receiver of `meth`. + * @param[in] meth Method ID in a symbol object. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to `meth`. + * @param[in] func Size calculator. + * @exception rb_eTypeError `meth` is not an instance of ::rb_cSymbol. + * @return A new instance of ::rb_cEnumerator which, when yielded, + * enumerates by calling `meth` on `recv` with `argv`. + * @note `func` can be zero, which means the size is unknown. + */ +VALUE rb_enumeratorize_with_size(VALUE recv, VALUE meth, int argc, const VALUE *argv, rb_enumerator_size_func *func); + +/** + * Identical to rb_enumeratorize_with_func(), except you can specify how to + * handle the last element of the given array. + * + * @param[in] recv A receiver of `meth`. + * @param[in] meth Method ID in a symbol object. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to `meth`. + * @param[in] func Size calculator. + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. + * @exception rb_eTypeError `meth` is not an instance of ::rb_cSymbol. + * @return A new instance of ::rb_cEnumerator which, when yielded, + * enumerates by calling `meth` on `recv` with `argv`. + * @note `func` can be zero, which means the size is unknown. + */ +VALUE rb_enumeratorize_with_size_kw(VALUE recv, VALUE meth, int argc, const VALUE *argv, rb_enumerator_size_func *func, int kw_splat); + +RBIMPL_ATTR_NONNULL(()) +/** + * Extracts components of the passed arithmetic sequence. This can be seen as + * an extended version of rb_range_values(). + * + * @param[in] as Target instance of `Enumerator::ArithmericSequence`. + * @param[out] buf Decomposed results buffer. + * @return 0 `as` is not `Enumerator::ArithmericSequence`. + * @return 1 Success. + * @post `buf` is filled. + */ +int rb_arithmetic_sequence_extract(VALUE as, rb_arithmetic_sequence_components_t *buf); + +RBIMPL_ATTR_NONNULL(()) +/** + * Identical to rb_range_beg_len(), except it takes an instance of + * `Enumerator::ArithmericSequence`. + * + * @param[in] as An `Enumerator::ArithmericSequence` instance. + * @param[out] begp Return value buffer. + * @param[out] lenp Return value buffer. + * @param[out] stepp Return value buffer. + * @param[in] len Updated length. + * @param[in] err In case `len` is out of range... + * - `0`: returns ::RUBY_Qnil. + * - `1`: raises ::rb_eRangeError. + * - `2`: `beg` and `len` expanded accordingly. + * @exception rb_eRangeError `as` cannot fit into `long`. + * @retval RUBY_Qfalse `as` is not `Enumerator::ArithmericSequence`. + * @retval RUBY_Qnil `len` is out of `as` but `err` is zero. + * @retval RUBY_Qtrue Otherwise. + * @post `beg` is the (possibly updated) left endpoint. + * @post `len` is the (possibly updated) length of the range. + * + * @internal + * + * Currently no 3rd party applications of this function is found. But that can + * be because this function is relatively new. + */ +VALUE rb_arithmetic_sequence_beg_len_step(VALUE as, long *begp, long *lenp, long *stepp, long len, int err); RBIMPL_SYMBOL_EXPORT_END() +/** @cond INTERNAL_MACRO */ #ifndef RUBY_EXPORT # define rb_enumeratorize_with_size(obj, id, argc, argv, size_fn) \ rb_enumeratorize_with_size(obj, id, argc, argv, (rb_enumerator_size_func *)(size_fn)) # define rb_enumeratorize_with_size_kw(obj, id, argc, argv, size_fn, kw_splat) \ rb_enumeratorize_with_size_kw(obj, id, argc, argv, (rb_enumerator_size_func *)(size_fn), kw_splat) #endif +/** @endcond */ +/** + * This is an implementation detail of #RETURN_SIZED_ENUMERATOR(). You could + * use it directly, but can hardly be handy. + * + * @param[in] obj A receiver. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to the current method. + * @param[in] size_fn Size calculator. + * @return A new instance of ::rb_cEnumerator which, when yielded, + * enumerates by calling the current method on `recv` with `argv`. + */ #define SIZED_ENUMERATOR(obj, argc, argv, size_fn) \ rb_enumeratorize_with_size((obj), ID2SYM(rb_frame_this_func()), \ (argc), (argv), (size_fn)) +/** + * This is an implementation detail of #RETURN_SIZED_ENUMERATOR_KW(). You + * could use it directly, but can hardly be handy. + * + * @param[in] obj A receiver. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to the current method. + * @param[in] size_fn Size calculator. + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. + * @return A new instance of ::rb_cEnumerator which, when yielded, + * enumerates by calling the current method on `recv` with `argv`. + */ #define SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat) \ rb_enumeratorize_with_size_kw((obj), ID2SYM(rb_frame_this_func()), \ (argc), (argv), (size_fn), (kw_splat)) +/** + * This roughly resembles `return enum_for(__callee__) unless block_given?`. + * + * @param[in] obj A receiver. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to the current method. + * @param[in] size_fn Size calculator. + * @note This macro may return inside. + */ #define RETURN_SIZED_ENUMERATOR(obj, argc, argv, size_fn) do { \ if (!rb_block_given_p()) \ return SIZED_ENUMERATOR(obj, argc, argv, size_fn); \ } while (0) + +/** + * Identical to #RETURN_SIZED_ENUMERATOR(), except you can specify how to + * handle the last element of the given array. + * + * @param[in] obj A receiver. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to the current method. + * @param[in] size_fn Size calculator. + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. + * @note This macro may return inside. + */ #define RETURN_SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat) do { \ if (!rb_block_given_p()) \ return SIZED_ENUMERATOR_KW(obj, argc, argv, size_fn, kw_splat); \ } while (0) +/** + * Identical to #RETURN_SIZED_ENUMERATOR(), except its size is unknown. + * + * @param[in] obj A receiver. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to the current method. + * @note This macro may return inside. + */ #define RETURN_ENUMERATOR(obj, argc, argv) \ RETURN_SIZED_ENUMERATOR(obj, argc, argv, 0) +/** + * Identical to #RETURN_SIZED_ENUMERATOR_KW(), except its size is unknown. It + * can also be seen as a routine identical to #RETURN_ENUMERATOR(), except you + * can specify how to handle the last element of the given array. + * + * @param[in] obj A receiver. + * @param[in] argc Number of objects of `argv`. + * @param[in] argv Arguments passed to the current method. + * @param[in] kw_splat Handling of keyword parameters: + * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. + * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. + * @note This macro may return inside. + */ #define RETURN_ENUMERATOR_KW(obj, argc, argv, kw_splat) \ RETURN_SIZED_ENUMERATOR_KW(obj, argc, argv, 0, kw_splat) diff --git a/include/ruby/internal/intern/error.h b/include/ruby/internal/intern/error.h index 37d3b8592b..1fd9ec2f51 100644 --- a/include/ruby/internal/intern/error.h +++ b/include/ruby/internal/intern/error.h @@ -38,8 +38,6 @@ #define rb_exc_new3 rb_exc_new_str /**< @old{rb_exc_new_str} */ /** @cond INTERNAL_MACRO */ -#define rb_check_trusted rb_check_trusted -#define rb_check_trusted_inline rb_check_trusted #define rb_check_arity rb_check_arity /** @endcond */ @@ -204,12 +202,6 @@ RBIMPL_ATTR_NORETURN() void rb_error_frozen_object(VALUE what); /** - * @deprecated Does nothing. This method is deprecated and will be removed in - * Ruby 3.2. - */ -void rb_error_untrusted(VALUE); - -/** * Queries if the passed object is frozen. * * @param[in] obj Target object to test frozen-ness. @@ -219,12 +211,6 @@ void rb_error_untrusted(VALUE); void rb_check_frozen(VALUE obj); /** - * @deprecated Does nothing. This method is deprecated and will be removed in - * Ruby 3.2. - */ -void rb_check_trusted(VALUE); - -/** * Ensures that the passed object can be `initialize_copy` relationship. When * you implement your own one you would better call this at the right beginning * of your implementation. @@ -249,7 +235,9 @@ RBIMPL_ATTR_NORETURN() * @param[in] max Maximum allowed `argc`. * @exception rb_eArgError Always. */ -MJIT_STATIC void rb_error_arity(int argc, int min, int max); +void rb_error_arity(int argc, int min, int max); + +void rb_str_modify(VALUE str); RBIMPL_SYMBOL_EXPORT_END() @@ -258,12 +246,7 @@ RBIMPL_SYMBOL_EXPORT_END() * * Does anyone use this? Remain not deleted for compatibility. */ -#define rb_check_frozen_internal(obj) do { \ - VALUE frozen_obj = (obj); \ - if (RB_UNLIKELY(RB_OBJ_FROZEN(frozen_obj))) { \ - rb_error_frozen_object(frozen_obj); \ - } \ - } while (0) +#define rb_check_frozen_internal rb_check_frozen /** @alias{rb_check_frozen} */ static inline void @@ -272,9 +255,16 @@ rb_check_frozen_inline(VALUE obj) if (RB_UNLIKELY(RB_OBJ_FROZEN(obj))) { rb_error_frozen_object(obj); } + + /* ref: internal CHILLED_STRING_P() + This is an implementation detail subject to change. */ + if (RB_UNLIKELY(RB_TYPE_P(obj, T_STRING) && FL_TEST_RAW(obj, RUBY_FL_USER2 | RUBY_FL_USER3))) { // STR_CHILLED + rb_str_modify(obj); + } } -/** @alias{rb_check_frozen} */ +/* rb_check_frozen() is available as a symbol, but have + * the inline version take priority for native consumers. */ #define rb_check_frozen rb_check_frozen_inline /** diff --git a/include/ruby/internal/intern/file.h b/include/ruby/internal/intern/file.h index 8e98ba08f8..8508b7ab9e 100644 --- a/include/ruby/internal/intern/file.h +++ b/include/ruby/internal/intern/file.h @@ -24,6 +24,9 @@ #include "ruby/internal/attr/pure.h" #include "ruby/internal/dllexport.h" #include "ruby/internal/value.h" +#if !defined RUBY_EXPORT && !defined RUBY_NO_OLD_COMPATIBILITY +# include "ruby/backward.h" +#endif RBIMPL_SYMBOL_EXPORT_BEGIN() @@ -187,6 +190,27 @@ RBIMPL_ATTR_PURE() */ int rb_is_absolute_path(const char *path); +/** + * Queries the file size of the given file. Because this function calls + * `fstat(2)` internally, it is a failure to pass a closed file to this + * function. + * + * This function flushes the passed file's buffer if any. Can take time. + * + * @param[in] file A file object. + * @exception rb_eFrozenError `file` is frozen. + * @exception rb_eIOError `file` is closed. + * @exception rb_eSystemCallError Permission denied etc. + * @exception rb_eNoMethodError The given non-file object doesn't respond + * to `#size`. + * @return The size of the passed file. + * @note Passing a non-regular file such as a UNIX domain socket to this + * function is not a failure. But the return value is + * unpredictable. POSIX's `<sys/stat.h>` states that "the use of + * this field is unspecified" then. + */ +rb_off_t rb_file_size(VALUE file); + RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_INTERN_FILE_H */ diff --git a/include/ruby/internal/intern/gc.h b/include/ruby/internal/intern/gc.h deleted file mode 100644 index 1617a7cef6..0000000000 --- a/include/ruby/internal/intern/gc.h +++ /dev/null @@ -1,390 +0,0 @@ -#ifndef RBIMPL_INTERN_GC_H /*-*-C++-*-vi:se ft=cpp:*/ -#define RBIMPL_INTERN_GC_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_mGC. - */ -#include "ruby/internal/config.h" - -#ifdef STDC_HEADERS -# include <stddef.h> /* size_t */ -#endif - -#if HAVE_SYS_TYPES_H -# include <sys/types.h> /* ssize_t */ -#endif - -#include "ruby/internal/attr/cold.h" -#include "ruby/internal/attr/noreturn.h" -#include "ruby/internal/attr/nonnull.h" -#include "ruby/internal/attr/pure.h" -#include "ruby/internal/dllexport.h" -#include "ruby/internal/value.h" - -RBIMPL_SYMBOL_EXPORT_BEGIN() - -/* gc.c */ - -RBIMPL_ATTR_COLD() -RBIMPL_ATTR_NORETURN() -/** - * Triggers out-of-memory error. If possible it raises ::rb_eNoMemError. But - * because we are running out of memory that is not always doable. This - * function tries hard to show something, but ultimately can die silently. - * - * @exception rb_eNoMemError Raises it if possible. - */ -void rb_memerror(void); - -RBIMPL_ATTR_PURE() -/** - * Queries if the GC is busy. - * - * @retval 0 It isn't. - * @retval 1 It is. - */ -int rb_during_gc(void); - -RBIMPL_ATTR_NONNULL((1)) -/** - * Marks objects between the two pointers. This is one of the GC utility - * functions that you can call when you design your own - * ::rb_data_type_struct::dmark. - * - * @pre Continuous memory region from `start` to `end` shall be fully - * addressable. - * @param[out] start Pointer to an array of objects. - * @param[out] end Pointer that terminates the array of objects. - * @post Objects from `start` to `end`, both inclusive, are marked. - * - * @internal - * - * `end` can be NULL... But that just results in no-op. - */ -void rb_gc_mark_locations(const VALUE *start, const VALUE *end); - -/** - * Identical to rb_mark_hash(), except it marks only values of the table and - * leave their associated keys unmarked. This is one of the GC utility - * functions that you can call when you design your own - * ::rb_data_type_struct::dmark. - * - * @warning Of course it can break GC. Leave it unused if unsure. - * @param[in] tbl A table to mark. - * @post Values stored in `tbl` are marked. - */ -void rb_mark_tbl(struct st_table *tbl); - -/** - * Identical to rb_mark_tbl(), except it marks objects using - * rb_gc_mark_movable(). This is one of the GC utility functions that you can - * call when you design your own ::rb_data_type_struct::dmark. - * - * @warning Of course it can break GC. Leave it unused if unsure. - * @param[in] tbl A table to mark. - * @post Values stored in `tbl` are marked. - */ -void rb_mark_tbl_no_pin(struct st_table *tbl); - -/** - * Identical to rb_mark_hash(), except it marks only keys of the table and - * leave their associated values unmarked. This is one of the GC utility - * functions that you can call when you design your own - * ::rb_data_type_struct::dmark. - * - * @warning Of course it can break GC. Leave it unused if unsure. - * @param[in] tbl A table to mark. - * @post Keys stored in `tbl` are marked. - */ -void rb_mark_set(struct st_table *tbl); - -/** - * Marks keys and values associated inside of the given table. This is one of - * the GC utility functions that you can call when you design your own - * ::rb_data_type_struct::dmark. - * - * @param[in] tbl A table to mark. - * @post Objects stored in `tbl` are marked. - */ -void rb_mark_hash(struct st_table *tbl); - -/** - * Updates references inside of tables. After you marked values using - * rb_mark_tbl_no_pin(), the objects inside of the table could of course be - * moved. This function is to fixup those references. You can call this from - * your ::rb_data_type_struct::dcompact. - * - * @param[out] ptr A table that potentially includes moved references. - * @post Moved references, if any, are corrected. - */ -void rb_gc_update_tbl_refs(st_table *ptr); - -/** - * Identical to rb_gc_mark(), except it allows the passed value be a - * non-object. For instance pointers to different type of memory regions are - * allowed here. Such values are silently ignored. This is one of the GC - * utility functions that you can call when you design your own - * ::rb_data_type_struct::dmark. - * - * @param[out] obj A possible object. - * @post `obj` is marked, if possible. - */ -void rb_gc_mark_maybe(VALUE obj); - -/** - * Marks an object. This is one of the GC utility functions that you can call - * when you design your own ::rb_data_type_struct::dmark. - * - * @param[out] obj Arbitrary Ruby object. - * @post `obj` is marked. - */ -void rb_gc_mark(VALUE obj); - -/** - * Maybe this is the only function provided for C extensions to control the - * pinning of objects, so let us describe it in detail. These days Ruby's GC - * is copying. As far as an object's physical address is guaranteed unused, it - * can move around the object space. Our GC engine rearranges these objects - * after it reclaims unreachable objects from our object space, so that the - * space is compact (improves memory locality). This is called the - * "compaction" phase, and works well most of the time... as far as there are - * no C extensions. C extensions complicate the scenario because Ruby core - * cannot detect any use of the physical address of an object inside of C - * functions. In order to prevent memory corruptions, objects observable from - * C extensions are "pinned"; they stick to where they are born until they die, - * just in case any C extensions touch their raw pointers. This variant of - * scheme is called "Mostly-Copying" garbage collector. Authors of C - * extensions, however, can extremely carefully write them to become - * compaction-aware. To do so avoid referring to a Ruby object from inside of - * your struct in the first place. But if that is not possible, use this - * function from your ::rb_data_type_struct::dmark then. This way objects - * marked using it are considered movable. If you chose this way you have to - * manually fix up locations of such moved pointers using rb_gc_location(). - * - * @see Bartlett, Joel F., "Compacting Garbage Collection with Ambiguous - * Roots", ACM SIGPLAN Lisp Pointers Volume 1 Issue 6 pp. 3-12, - * April-May-June, 1988. https://doi.org/10.1145/1317224.1317225 - * - * @param[in] obj Object that is movable. - * @post Values stored in `tbl` are marked. - */ -void rb_gc_mark_movable(VALUE obj); - -/** - * Finds a new "location" of an object. An object can be moved on compaction. - * This function projects its new abode, or just returns the passed object if - * not moved. This is one of the GC utility functions that you can call when - * you design your own ::rb_data_type_struct::dcompact. - * - * @param[in] obj An object, possibly already moved to somewhere else. - * @return An object, which holds the current contents of former `obj`. - */ -VALUE rb_gc_location(VALUE obj); - -/** - * Asserts that the passed object is no longer needed. Such objects are - * reclaimed sooner or later so this function is not mandatory. But sometimes - * you can know from your application knowledge that an object is surely dead - * at some point. Calling this as a hint can be a polite way. - * - * @param[out] obj Object, dead. - * @pre `obj` have never been passed to this function before. - * @post `obj` could be invalidated. - * @warning It is a failure to pass an object multiple times to this - * function. - */ -void rb_gc_force_recycle(VALUE obj); - -/** - * Triggers a GC process. This was the only GC entry point that we had at the - * beginning. Over time our GC evolved. Now what this function does is just a - * very simplified variation of the entire GC algorithms. A series of - * procedures kicked by this API is called a "full" GC. - * - * - It immediately scans the entire object space to sort the dead. - * - It immediately reclaims any single dead bodies to reuse later. - * - * It is worth noting that the procedures above do not include evaluations of - * finalisers. They run later. - * - * @internal - * - * Finalisers are deferred until we can handle interrupts. See - * `rb_postponed_job_flush` in vm_trace.c. - * - * Of course there are GC that are not "full". For instance this one and the - * GC which runs when we are running out of memory are different. See - * `gc_profile_record_flag` defined in gc.c for the kinds of GC. - * - * In spite of the name this is not what everything that a GC can trigger. As - * of writing it seems this function does not trigger compaction. But this - * might change in future. - */ -void rb_gc(void); - -/** - * Copy&paste an object's finaliser to another. This is one of the GC utility - * functions that you can call when you design your own `initialize_copy`, - * `initialize_dup`, `initialize_clone`. - * - * @param[out] dst Destination object. - * @param[in] src Source object. - * @post `dst` and `src` share the same finaliser. - * - * @internal - * - * But isn't it easier for you to call super, and let `Object#intialize_copy` - * call this function instead? - */ -void rb_gc_copy_finalizer(VALUE dst, VALUE src); - -/** - * (Re-) enables GC. This makes sense only after you called rb_gc_disable(). - * - * @retval RUBY_Qtrue GC was disabled before. - * @retval RUBY_Qfalse GC was enabled before. - * @post GC is enabled. - * - * @internal - * - * This is one of such exceptional functions that does not raise both Ruby - * exceptions and C++ exceptions. - */ -VALUE rb_gc_enable(void); - -/** - * Disables GC. This prevents automatic GC runs when the process is running - * out of memory. Such situations shall result in rb_memerror(). However this - * does not prevent users from manually invoking rb_gc(). That should work. - * People abused this by disabling GC at the beginning of an event loop, - * process events without GC overheads, then manually force reclaiming garbage - * at the bottom of the loop. However because our GC is now much smarter than - * just calling rb_gc(), this technique is proven to be sub-optimal these days. - * It is believed that there is currently practically no needs of this - * function. - * - * @retval RUBY_Qtrue GC was disabled before. - * @retval RUBY_Qfalse GC was enabled before. - * @post GC is disabled. - */ -VALUE rb_gc_disable(void); - -/** - * Identical to rb_gc(), except the return value. - * - * @return Always returns ::RUBY_Qnil. - */ -VALUE rb_gc_start(void); - -/** - * Assigns a finaliser for an object. Each objects can have objects (typically - * blocks) that run immediately after that object dies. They are called - * finalisers of an object. This function associates a finaliser object with a - * target object. - * - * @note Note that finalisers run _after_ the object they finalise dies. You - * cannot for instance call its methods. - * @note If your finaliser references the object it finalises that object - * loses any chance to become a garbage; effectively leaks memory until - * the end of the process. - * - * @param[in] obj Target to finalise. - * @param[in] block Something `call`able. - * @exception rb_eRuntimeError Somehow `obj` cannot have finalisers. - * @exception rb_eFrozenError `obj` is frozen. - * @exception rb_eArgError `block` doesn't respond to `call`. - * @return The passed `block`. - * @post `block` runs after `obj` dies. - */ -VALUE rb_define_finalizer(VALUE obj, VALUE block); - -/** - * Modifies the object so that it has no finalisers at all. This function is - * mainly provided for symmetry. No practical usages can be thought of. - * - * @param[out] obj Object to clear its finalisers. - * @exception rb_eFrozenError `obj` is frozen. - * @return The passed `obj`. - * @post `obj` has no finalisers. - * @note There is no way to undefine a specific part of many finalisers - * that `obj` could have. All you can do is to clear them all. - */ -VALUE rb_undefine_finalizer(VALUE obj); - -/** - * Identical to rb_gc_stat(), with "count" parameter. - * - * @return Lifetime total number of runs of GC. - */ -size_t rb_gc_count(void); - -/** - * Obtains various GC related profiles. The parameter can be either a Symbol - * or a Hash. If a Hash is passed, it is filled with everything currently - * available. If a Symbol is passed just that portion is returned. - * - * Possible variations of keys you can pass here change from version to - * version. You can get the list of known keys by passing an empty hash and - * let it be filled. - * - * @param[in,out] key_or_buf A Symbol, or a Hash. - * @exception rb_eTypeError Neither Symbol nor Hash. - * @exception rb_eFrozenError Frozen hash is passed. - * @return In case a Hash is passed it returns 0. Otherwise the - * profile value associated with the given key is returned. - * @post In case a Hash is passed it is filled with values. - */ -size_t rb_gc_stat(VALUE key_or_buf); - -/** - * Obtains various info regarding the most recent GC run. This includes for - * instance the reason of the GC. The parameter can be either a Symbol or a - * Hash. If a Hash is passed, it is filled with everything currently - * available. If a Symbol is passed just that portion is returned. - * - * Possible variations of keys you can pass here change from version to - * version. You can get the list of known keys by passing an empty hash and - * let it be filled. - * - * @param[in,out] key_or_buf A Symbol, or a Hash. - * @exception rb_eTypeError Neither Symbol nor Hash. - * @exception rb_eFrozenError Frozen hash is passed. - * @return In case a Hash is passed it returns that hash. Otherwise - * the profile value associated with the given key is returned. - * @post In case a Hash is passed it is filled with values. - */ -VALUE rb_gc_latest_gc_info(VALUE key_or_buf); - -/** - * Informs that there are external memory usages. Our GC runs when we are - * running out of memory. The amount of memory, however, can increase/decrease - * behind-the-scene. For instance DLLs can allocate memories using `mmap(2)` - * etc, which are opaque to us. Registering such external allocations using - * this function enables proper detection of how much memories an object used - * as a whole. That will trigger GCs more often than it would otherwise. You - * can also pass negative numbers here, to indicate that such external - * allocations are gone. - * - * @param[in] diff Amount of memory increased(+)/decreased(-). - */ -void rb_gc_adjust_memory_usage(ssize_t diff); - -RBIMPL_SYMBOL_EXPORT_END() - -#endif /* RBIMPL_INTERN_GC_H */ diff --git a/include/ruby/internal/intern/hash.h b/include/ruby/internal/intern/hash.h index 9d2ce8279a..504770fa5f 100644 --- a/include/ruby/internal/intern/hash.h +++ b/include/ruby/internal/intern/hash.h @@ -107,6 +107,17 @@ VALUE rb_hash(VALUE obj); VALUE rb_hash_new(void); /** + * Identical to rb_hash_new(), except it additionally specifies how many keys + * it is expected to contain. This way you can create a hash that is large enough + * for your need. For large hashes it means it won't need to be reallocated and + * rehashed as much, improving performance. + * + * @param[in] capa Designed capacity of the hash. + * @return An empty Hash, whose capacity is `capa`. + */ +VALUE rb_hash_new_capa(long capa); + +/** * Duplicates a hash. * * @param[in] hash An instance of ::rb_cHash. @@ -273,29 +284,6 @@ typedef VALUE rb_hash_update_func(VALUE newkey, VALUE oldkey, VALUE value); */ VALUE rb_hash_update_by(VALUE hash1, VALUE hash2, rb_hash_update_func *func); -/* file.c */ - -/** - * This function is mysterious. What it does is not immediately obvious. Also - * what it does seems platform dependent. - * - * @param[in] path A local path. - * @retval 0 The "check" succeeded. - * @retval otherwise The "check" failed. - */ -int rb_path_check(const char *path); - -/* hash.c */ - -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @return 0 always. - */ -int rb_env_path_tainted(void); - /** * Destructively removes every environment variables of the running process. * diff --git a/include/ruby/internal/intern/io.h b/include/ruby/internal/intern/io.h index 02c249723e..b9eb258cc1 100644 --- a/include/ruby/internal/intern/io.h +++ b/include/ruby/internal/intern/io.h @@ -385,7 +385,7 @@ VALUE rb_io_puts(int argc, const VALUE *argv, VALUE io); * @param[in] fd Target file descriptor. * @param[in] flags Flags, e.g. `O_CREAT|O_EXCL` * @param[in] path The path of the file that backs `fd`, for diagnostics. - * @return An allocated instance of ::rb_cIO. + * @return An allocated instance of ::rb_cIO with the autoclose flag set. * @note Leave `path` NULL if you don't know. */ VALUE rb_io_fdopen(int fd, int flags, const char *path); diff --git a/include/ruby/internal/intern/load.h b/include/ruby/internal/intern/load.h index 288a16c2ec..9ceb98c2e4 100644 --- a/include/ruby/internal/intern/load.h +++ b/include/ruby/internal/intern/load.h @@ -177,6 +177,43 @@ VALUE rb_f_require(VALUE self, VALUE feature); 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 * @{ */ diff --git a/include/ruby/internal/intern/object.h b/include/ruby/internal/intern/object.h index 6bb4ccb2fe..3897639a0a 100644 --- a/include/ruby/internal/intern/object.h +++ b/include/ruby/internal/intern/object.h @@ -80,7 +80,8 @@ VALUE rb_class_new_instance(int argc, const VALUE *argv, VALUE klass); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eTypeError `klass`'s allocator is undefined. * @exception rb_eException Any exceptions can happen inside. * @return An allocated new instance of `klass`. @@ -92,8 +93,8 @@ VALUE rb_class_new_instance_kw(int argc, const VALUE *argv, VALUE klass, int kw_ * * @param[in] lhs Comparison left hand side. * @param[in] rhs Comparison right hand side. - * @retval RUBY_Qtrue They are equal. - * @retval RUBY_Qfalse Otherwise. + * @retval non-zero They are equal. + * @retval 0 Otherwise. * @note This function actually calls `lhs.eql?(rhs)` so you cannot * implement your class' `#eql?` method using it. */ @@ -151,13 +152,12 @@ VALUE rb_obj_is_kind_of(VALUE obj, VALUE klass); * @return An allocated, not yet initialised instance of `klass`. * @note It calls the allocator defined by rb_define_alloc_func(). You * cannot use this function to define an allocator. Use - * rb_newobj_of(), #TypedData_Make_Struct or others, instead. + * TypedData_Make_Struct or others, instead. * @note Usually prefer rb_class_new_instance() to rb_obj_alloc() and * rb_obj_call_init(). * @see rb_class_new_instance() * @see rb_obj_call_init() * @see rb_define_alloc_func() - * @see rb_newobj_of() * @see #TypedData_Make_Struct */ VALUE rb_obj_alloc(VALUE klass); @@ -202,74 +202,6 @@ VALUE rb_obj_dup(VALUE obj); */ VALUE rb_obj_init_copy(VALUE src, VALUE dst); -RBIMPL_ATTR_DEPRECATED_EXT(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return Verbatim `obj`. - */ -VALUE rb_obj_taint(VALUE obj); - -RBIMPL_ATTR_PURE() -RBIMPL_ATTR_DEPRECATED_EXT(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return Always returns ::RUBY_Qfalse. - */ -VALUE rb_obj_tainted(VALUE obj); - -RBIMPL_ATTR_DEPRECATED_EXT(("taintedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return Verbatim `obj`. - */ -VALUE rb_obj_untaint(VALUE obj); - -RBIMPL_ATTR_DEPRECATED_EXT(("trustedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return Verbatim `obj`. - */ -VALUE rb_obj_untrust(VALUE obj); - -RBIMPL_ATTR_PURE() -RBIMPL_ATTR_DEPRECATED_EXT(("trustedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return Always returns ::RUBY_Qfalse. - */ -VALUE rb_obj_untrusted(VALUE obj); - -RBIMPL_ATTR_DEPRECATED_EXT(("trustedness turned out to be a wrong idea.")) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] obj Object in question. - * @return Verbatim `obj`. - */ -VALUE rb_obj_trust(VALUE obj); - /** * Just calls rb_obj_freeze_inline() inside. Does this make any sens to * extension libraries? diff --git a/include/ruby/internal/intern/proc.h b/include/ruby/internal/intern/proc.h index b8c3c5e146..2635d672eb 100644 --- a/include/ruby/internal/intern/proc.h +++ b/include/ruby/internal/intern/proc.h @@ -101,7 +101,8 @@ VALUE rb_proc_call(VALUE recv, VALUE args); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `args`' last is not a keyword argument. * - RB_PASS_KEYWORDS `args`' last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eException Any exceptions happen inside. * @return What the proc evaluates to. */ @@ -141,7 +142,8 @@ VALUE rb_proc_call_with_block(VALUE recv, int argc, const VALUE *argv, VALUE pro * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `args`' last is not a keyword argument. * - RB_PASS_KEYWORDS `args`' last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eException Any exceptions happen inside. * @return What the proc evaluates to. */ @@ -245,7 +247,8 @@ VALUE rb_method_call(int argc, const VALUE *argv, VALUE recv); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `args`' last is not a keyword argument. * - RB_PASS_KEYWORDS `args`' last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eTypeError `recv` is not a method. * @exception rb_eException Any exceptions happen inside. * @return What the method returns. @@ -279,7 +282,8 @@ VALUE rb_method_call_with_block(int argc, const VALUE *argv, VALUE recv, VALUE p * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `args`' last is not a keyword argument. * - RB_PASS_KEYWORDS `args`' last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @exception rb_eTypeError `recv` is not a method. * @exception rb_eException Any exceptions happen inside. * @return What the method returns. diff --git a/include/ruby/internal/intern/process.h b/include/ruby/internal/intern/process.h index 7a7b24ed4b..cfa5e13162 100644 --- a/include/ruby/internal/intern/process.h +++ b/include/ruby/internal/intern/process.h @@ -31,6 +31,15 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* process.c */ /** + * Wait for the specified process to terminate, reap it, and return its status. + * + * @param[in] pid The process ID to wait for. + * @param[in] flags The flags to pass to waitpid(2). + * @return VALUE An instance of Process::Status. + */ +VALUE rb_process_status_wait(rb_pid_t pid, int flags); + +/** * Sets the "last status", or the `$?`. * * @param[in] status The termination status, as defined in `waitpid(3posix)`. @@ -247,7 +256,7 @@ rb_pid_t rb_spawn_err(int argc, const VALUE *argv, char *errbuf, size_t buflen); * * @internal * - * This function might or might not exist depending on `./confiugre` result. + * This function might or might not exist depending on `./configure` result. * It must be a portability hell. Better not use. */ VALUE rb_proc_times(VALUE _); diff --git a/include/ruby/internal/intern/re.h b/include/ruby/internal/intern/re.h index 31f5593275..4dd58b469b 100644 --- a/include/ruby/internal/intern/re.h +++ b/include/ruby/internal/intern/re.h @@ -87,11 +87,6 @@ void rb_match_busy(VALUE md); * @retval RUBY_Qfalse There is a `n`-th capture and is empty. * @retval RUBY_Qtrue There is a `n`-th capture that has something. * - * @internal - * - * @shyouhei wonders: why there are both rb_reg_match_defined() and - * rb_match_nth_defined, which are largely the same things, but do not share - * their implementations at all? */ VALUE rb_reg_nth_defined(int n, VALUE md); diff --git a/include/ruby/internal/intern/select.h b/include/ruby/internal/intern/select.h index fabc287cd1..ba75213618 100644 --- a/include/ruby/internal/intern/select.h +++ b/include/ruby/internal/intern/select.h @@ -72,11 +72,13 @@ struct timeval; * someone else, vastly varies among operating systems. You would better avoid * touching an fd from more than one threads. * + * NOTE: this function is used in native extensions, so change its API with care. + * * @internal * * Although any file descriptors are possible here, it makes completely no * sense to pass a descriptor that is not `O_NONBLOCK`. If you want to know - * the reason for this limitatuon in detail, you might find this thread super + * the reason for this limitation in detail, you might find this thread super * interesting: https://lkml.org/lkml/2004/10/6/117 */ int rb_thread_fd_select(int nfds, rb_fdset_t *rfds, rb_fdset_t *wfds, rb_fdset_t *efds, struct timeval *timeout); diff --git a/include/ruby/internal/intern/select/largesize.h b/include/ruby/internal/intern/select/largesize.h index d156f62034..d65f088c06 100644 --- a/include/ruby/internal/intern/select/largesize.h +++ b/include/ruby/internal/intern/select/largesize.h @@ -35,9 +35,6 @@ * `select(2)` documents how to allocate fd_set dynamically. * http://www.openbsd.org/cgi-bin/man.cgi?query=select&manpath=OpenBSD+4.4 * - * - HP-UX documents how to allocate fd_set dynamically. - * http://docs.hp.com/en/B2355-60105/select.2.html - * * - Solaris 8 has `select_large_fdset` * * - Mac OS X 10.7 (Lion) diff --git a/include/ruby/internal/intern/select/posix.h b/include/ruby/internal/intern/select/posix.h index bfde159890..0a9b0b2e51 100644 --- a/include/ruby/internal/intern/select/posix.h +++ b/include/ruby/internal/intern/select/posix.h @@ -95,11 +95,10 @@ RBIMPL_ATTR_NOALIAS() * * @param[out] dst Target fdset. * @param[in] src Source fdset. - * @param[in] n Unused parameter. * @post `dst` is a copy of `src`. */ static inline void -rb_fd_dup(rb_fdset_t *dst, const fd_set *src, int n) +rb_fd_dup(rb_fdset_t *dst, const fd_set *src) { *dst = *src; } @@ -137,7 +136,7 @@ rb_fd_max(const rb_fdset_t *f) } /** @cond INTERNAL_MACRO */ -/* :FIXME: What are these? They don't exist for shibling implementations. */ +/* :FIXME: What are these? They don't exist for sibling implementations. */ #define rb_fd_init_copy(d, s) (*(d) = *(s)) #define rb_fd_term(f) ((void)(f)) /** @endcond */ diff --git a/include/ruby/internal/intern/select/win32.h b/include/ruby/internal/intern/select/win32.h index edaf7a8523..b7301e63f3 100644 --- a/include/ruby/internal/intern/select/win32.h +++ b/include/ruby/internal/intern/select/win32.h @@ -206,7 +206,7 @@ rb_fd_dup(rb_fdset_t *dst, const rb_fdset_t *src) * property we heavily touch the internals of MSVCRT. We `CreateFile` a * `"NUL"` alongside of a socket and directly manipulate its `struct ioinfo`. * This is of course a very dirty hack. If we could design the API today we - * could use `CancellIoEx`. But we are older than that Win32 API. + * could use `CancelIoEx`. But we are older than that Win32 API. */ static inline int rb_fd_select(int n, rb_fdset_t *rfds, rb_fdset_t *wfds, rb_fdset_t *efds, struct timeval *timeout) @@ -253,7 +253,7 @@ rb_fd_max(const rb_fdset_t *f) const fd_set *p = f->fdset; RBIMPL_ASSERT_OR_ASSUME(p); - return p->fd_count; + return RBIMPL_CAST((int)p->fd_count); } #endif /* RBIMPL_INTERN_SELECT_WIN32_H */ diff --git a/include/ruby/internal/intern/set.h b/include/ruby/internal/intern/set.h new file mode 100644 index 0000000000..f4ff8665e2 --- /dev/null +++ b/include/ruby/internal/intern/set.h @@ -0,0 +1,111 @@ +#ifndef RBIMPL_INTERN_SET_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RBIMPL_INTERN_SET_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_cSet. + */ +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/dllexport.h" +#include "ruby/internal/value.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/* set.c */ + +RBIMPL_ATTR_NONNULL(()) +/** + * Iterates over a set. Calls func with each element of the set and the + * argument given. func should return ST_CONTINUE, ST_STOP, or ST_DELETE. + * + * @param[in] set An instance of ::rb_cSet to iterate over. + * @param[in] func Callback function to yield. + * @param[in] arg Passed as-is to `func`. + * @exception rb_eRuntimeError `set` was tampered during iterating. + */ +void rb_set_foreach(VALUE set, int (*func)(VALUE element, VALUE arg), VALUE arg); + +/** + * Creates a new, empty set object. + * + * @return An allocated new instance of ::rb_cSet. + */ +VALUE rb_set_new(void); + +/** + * Identical to rb_set_new(), except it additionally specifies how many elements + * it is expected to contain. This way you can create a set that is large enough + * for your need. For large sets, it means it won't need to be reallocated + * much, improving performance. + * + * @param[in] capa Designed capacity of the set. + * @return An empty Set, whose capacity is `capa`. + */ +VALUE rb_set_new_capa(size_t capa); + +/** + * Whether the set contains the given element. + * + * @param[in] set Set to look into. + * @param[in] element Set element to look for. + * @return true if element is in the set, falst otherwise. + */ +bool rb_set_lookup(VALUE set, VALUE element); + +/** + * Adds element to set. + * + * @param[in] set Target set table to modify. + * @param[in] element Arbitrary Ruby object. + * @exception rb_eFrozenError `set` is frozen. + * @return true if element was not already in set, false otherwise + * @post `element` is in `set`. + */ +bool rb_set_add(VALUE set, VALUE element); + +/** + * Removes all entries from set. + * + * @param[out] set Target to clear. + * @exception rb_eFrozenError `set`is frozen. + * @return The passed `set` + * @post `set` has no elements. + */ +VALUE rb_set_clear(VALUE set); + +/** + * Removes the element from from set. + * + * @param[in] set Target set to modify. + * @param[in] element Key to delete. + * @retval true if element was already in set, false otherwise + * @post `set` does not have `element` as an element. + */ +bool rb_set_delete(VALUE set, VALUE element); + +/** + * Returns the number of elements in the set. + * + * @param[in] set A set object. + * @return The size of the set. + */ +size_t rb_set_size(VALUE set); + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RBIMPL_INTERN_SET_H */ diff --git a/include/ruby/internal/intern/signal.h b/include/ruby/internal/intern/signal.h index 84f7558404..4773788651 100644 --- a/include/ruby/internal/intern/signal.h +++ b/include/ruby/internal/intern/signal.h @@ -97,7 +97,7 @@ RBIMPL_ATTR_NONNULL(()) * - Case #11: When signo and PID are both negative, the behaviour of this * function depends on how `killpg(3)` works. On Linux, it seems such * attempt is strictly prohibited and `Errno::EINVAL` is raised. But on - * macOS, it seems it tries to to send the signal actually to the process + * macOS, it seems it tries to send the signal actually to the process * group. * * @note Above description is in fact different from how `kill(2)` works. @@ -113,12 +113,6 @@ RBIMPL_ATTR_NONNULL(()) */ VALUE rb_f_kill(int argc, const VALUE *argv); -/* This must be private, @shyouhei guesses. */ -#ifdef POSIX_SIGNAL -#define posix_signal ruby_posix_signal -void (*posix_signal(int, void (*)(int)))(int); -#endif - RBIMPL_ATTR_PURE() /** * Queries the name of the signal. It returns for instance `"KILL"` for diff --git a/include/ruby/internal/intern/string.h b/include/ruby/internal/intern/string.h index 1cb33a6441..8bd1ffcfb4 100644 --- a/include/ruby/internal/intern/string.h +++ b/include/ruby/internal/intern/string.h @@ -62,13 +62,13 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() */ VALUE rb_str_new(const char *ptr, long len); -RBIMPL_ATTR_NONNULL(()) /** * Identical to rb_str_new(), except it assumes the passed pointer is a pointer * to a C string. * * @param[in] ptr A C string. * @exception rb_eNoMemError Failed to allocate memory. + * @exception rb_eArgError `ptr` is a null pointer. * @return An instance of ::rb_cString, of "binary" encoding, whose * contents are verbatim copy of `ptr`. * @pre `ptr` must not be a null pointer. @@ -122,37 +122,6 @@ VALUE rb_str_new_frozen(VALUE str); */ VALUE rb_str_new_with_class(VALUE obj, const char *ptr, long len); -RBIMPL_ATTR_NONNULL(()) -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] ptr A C string. - * @exception rb_eNoMemError Failed to allocate memory. - * @return An instance of ::rb_cString, of "binary" encoding, whose - * contents are verbatim copy of `ptr`. - * @pre `ptr` must not be a null pointer. - */ -VALUE rb_tainted_str_new_cstr(const char *ptr); - -/** - * @deprecated This function once was a thing in the old days, but makes no - * sense any longer today. Exists here for backwards - * compatibility only. You can safely forget about it. - * - * @param[in] ptr A memory region of `len` bytes length. - * @param[in] len Length of `ptr`, in bytes, not including the - * terminating NUL character. - * @exception rb_eNoMemError Failed to allocate `len+1` bytes. - * @exception rb_eArgError `len` is negative. - * @return An instance of ::rb_cString, of `len` bytes length, of - * "binary" encoding, whose contents are verbatim copy of `ptr`. - * @pre At least `len` bytes of continuous memory region shall be - * accessible via `ptr`. - */ -VALUE rb_tainted_str_new(const char *ptr, long len); - /** * Identical to rb_str_new(), except it generates a string of "default * external" encoding. @@ -333,7 +302,6 @@ VALUE rb_str_tmp_new(long len); */ VALUE rb_usascii_str_new(const char *ptr, long len); -RBIMPL_ATTR_NONNULL(()) /** * Identical to rb_str_new_cstr(), except it generates a string of "US ASCII" * encoding. It can also be seen as a routine Identical to @@ -342,6 +310,7 @@ RBIMPL_ATTR_NONNULL(()) * * @param[in] ptr A C string. * @exception rb_eNoMemError Failed to allocate memory. + * @exception rb_eArgError `ptr` is a null pointer. * @return An instance of ::rb_cString, of "US ASCII" encoding, whose * contents are verbatim copy of `ptr`. * @pre `ptr` must not be a null pointer. @@ -361,7 +330,6 @@ VALUE rb_usascii_str_new_cstr(const char *ptr); */ VALUE rb_utf8_str_new(const char *ptr, long len); -RBIMPL_ATTR_NONNULL(()) /** * Identical to rb_str_new_cstr(), except it generates a string of "UTF-8" * encoding. It can also be seen as a routine Identical to @@ -370,6 +338,7 @@ RBIMPL_ATTR_NONNULL(()) * * @param[in] ptr A C string. * @exception rb_eNoMemError Failed to allocate memory. + * @exception rb_eArgError `ptr` is a null pointer. * @return An instance of ::rb_cString, of "UTF-8" encoding, whose contents * are verbatim copy of `ptr`. * @pre `ptr` must not be a null pointer. @@ -443,8 +412,8 @@ VALUE rb_utf8_str_new_static(const char *ptr, long len); /** * Identical to rb_interned_str(), except it takes a Ruby's string instead of - * C's. It can also be seen as a routine identical to to rb_str_new_shared(), - * except it returns an infamous "f"string. + * C's and preserves its encoding. It can also be seen as a routine identical + * to rb_str_new_shared(), except it returns an infamous "f"string. * * @param[in] str An object of ::RString. * @return An instance of ::rb_cString, either cached or allocated, which @@ -475,8 +444,9 @@ VALUE rb_str_to_interned_str(VALUE str); * terminating NUL character. * @exception rb_eArgError `len` is negative. * @return A found or created instance of ::rb_cString, of `len` bytes - * length, of "binary" encoding, whose contents are identical to - * that of `ptr`. + * length, whose contents are identical to that of `ptr`. Its + * encoding will be US-ASCII if all bytes are lower ASCII, BINARY + * otherwise. * @pre At least `len` bytes of continuous memory region shall be * accessible via `ptr`. */ @@ -485,15 +455,16 @@ VALUE rb_interned_str(const char *ptr, long len); RBIMPL_ATTR_NONNULL(()) /** * Identical to rb_interned_str(), except it assumes the passed pointer is a - * pointer to a C's string. It can also be seen as a routine identical to to + * pointer to a C's string. It can also be seen as a routine identical to * rb_str_to_interned_str(), except it takes a C's string instead of Ruby's. * Or it can also be seen as a routine identical to rb_str_new_cstr(), except * it returns an infamous "f"string. * * @param[in] ptr A C string. * @exception rb_eNoMemError Failed to allocate memory. - * @return An instance of ::rb_cString, of "binary" encoding, whose - * contents are verbatim copy of `ptr`. + * @return An instance of ::rb_cString, whose contents are verbatim copy + * of `ptr`. Its encoding will be US-ASCII if all bytes are lower + * ASCII, BINARY otherwise. * @pre `ptr` must not be a null pointer. */ VALUE rb_interned_str_cstr(const char *ptr); @@ -622,10 +593,9 @@ void rb_must_asciicompat(VALUE obj); VALUE rb_str_dup(VALUE str); /** - * I guess there is no use case of this function in extension libraries, but - * this is a routine identical to rb_str_dup(), except it always creates an - * instance of ::rb_cString regardless of the given object's class. This makes - * the most sense when the passed string is formerly hidden by rb_obj_hide(). + * Like rb_str_dup(), but always create an instance of ::rb_cString + * regardless of the given object's class. This makes the most sense + * when the passed string is formerly hidden by rb_obj_hide(). * * @param[in] str A string, possibly hidden. * @return A duplicated new instance of ::rb_cString. @@ -873,7 +843,6 @@ VALUE rb_str_resize(VALUE str, long len); */ VALUE rb_str_cat(VALUE dst, const char *src, long srclen); -RBIMPL_ATTR_NONNULL(()) /** * Identical to rb_str_cat(), except it assumes the passed pointer is a pointer * to a C string. @@ -881,6 +850,7 @@ RBIMPL_ATTR_NONNULL(()) * @param[out] dst Destination object. * @param[in] src Contents to append. * @exception rb_eArgError Result string too big. + * @exception rb_eArgError `src` is a null pointer. * @return The passed `dst`. * @pre `dst` must not be any arbitrary objects except ::RString. * @pre `src` must not be a null pointer. @@ -1001,8 +971,8 @@ st_index_t rb_str_hash(VALUE str); * * @param[in] str1 A string. * @param[in] str2 Another string. - * @retval 1 They have identical contents, length, and encodings. - * @retval 0 Otherwise. + * @retval 0 They have identical contents, length, and encodings. + * @retval 1 Otherwise. * @pre Both objects must not be any arbitrary objects except * ::RString. * @@ -1151,7 +1121,6 @@ VALUE rb_str_inspect(VALUE str); */ VALUE rb_str_dump(VALUE str); -RBIMPL_ATTR_NONNULL(()) /** * Divides the given string based on the given delimiter. This is the * 1-argument 0-block version of `String#split`. @@ -1159,6 +1128,7 @@ RBIMPL_ATTR_NONNULL(()) * @param[in] str Object in question to split. * @param[in] delim Delimiter, in C string. * @exception rb_eTypeError `str` has no implicit conversion to String. + * @exception rb_eArgError `delim` is a null pointer. * @return An array of strings, which are substrings of the passed `str`. * If `delim` is an empty C string (i.e. `""`), `str` is split into * each characters. If `delim` is a C string whose sole content is @@ -1398,22 +1368,6 @@ rbimpl_str_new_cstr(const char *str) return rb_str_new_static(str, len); } -RBIMPL_ATTR_DEPRECATED(("taintedness turned out to be a wrong idea.")) -/** - * @private - * - * This is an implementation detail. Don't bother. - * - * @param[in] str A C string literal. - * @return Corresponding Ruby string. - */ -static inline VALUE -rbimpl_tainted_str_new_cstr(const char *str) -{ - long len = rbimpl_strlen(str); - return rb_tainted_str_new(str, len); -} - RBIMPL_ATTR_NONNULL(()) /** * @private @@ -1600,22 +1554,6 @@ rbimpl_exc_new_cstr(VALUE exc, const char *str) rb_utf8_str_new) ((str), (len))) /** - * @deprecated This macro once was a thing in the old days, but makes no sense - * any longer today. Exists here for backwards compatibility - * only. You can safely forget about it. - * - * @param[in] str A C string. - * @exception rb_eNoMemError Failed to allocate memory. - * @return An instance of ::rb_cString, of "binary" encoding, whose - * contents are verbatim copy of `str`. - * @pre `str` must not be a null pointer. - */ -#define rb_tainted_str_new_cstr(str) \ - ((RBIMPL_CONSTANT_P(str) ? \ - rbimpl_tainted_str_new_cstr : \ - rb_tainted_str_new_cstr) (str)) - -/** * Identical to #rb_str_new_cstr, except it generates a string of "US ASCII" * encoding. It can also be seen as a routine Identical to * #rb_usascii_str_new, except it assumes the passed pointer is a pointer to a @@ -1739,7 +1677,6 @@ rbimpl_exc_new_cstr(VALUE exc, const char *str) #define rb_str_new3 rb_str_new_shared /**< @old{rb_str_new_shared} */ #define rb_str_new4 rb_str_new_frozen /**< @old{rb_str_new_frozen} */ #define rb_str_new5 rb_str_new_with_class /**< @old{rb_str_new_with_class} */ -#define rb_tainted_str_new2 rb_tainted_str_new_cstr /**< @old{rb_tainted_str_new_cstr} */ #define rb_str_buf_new2 rb_str_buf_new_cstr /**< @old{rb_str_buf_new_cstr} */ #define rb_usascii_str_new2 rb_usascii_str_new_cstr /**< @old{rb_usascii_str_new_cstr} */ #define rb_str_buf_cat rb_str_cat /**< @alias{rb_str_cat} */ @@ -1750,10 +1687,10 @@ rbimpl_exc_new_cstr(VALUE exc, const char *str) * Length of a string literal. * * @param[in] str A C String literal. - * @return An integer constant expression that represents `str`'s length, - * in bytes, not including the terminating NUL character. + * @return An integer constant expression that represents the number of + * `str`'s elements, not including the terminating NUL character. */ -#define rb_strlen_lit(str) (sizeof(str "") - 1) +#define rb_strlen_lit(str) ((sizeof(str "") / sizeof(str ""[0])) - 1) /** * Identical to rb_str_new_static(), except it cannot take string variables. diff --git a/include/ruby/internal/intern/struct.h b/include/ruby/internal/intern/struct.h index 312cf444e2..16b3fad4e0 100644 --- a/include/ruby/internal/intern/struct.h +++ b/include/ruby/internal/intern/struct.h @@ -46,14 +46,16 @@ VALUE rb_struct_new(VALUE klass, ...); * * @param[in] name Name of the class. * @param[in] ... Arbitrary number of `const char*`, terminated by - * zero. Each of which are the name of fields. + * NULL. Each of which are the name of fields. * @exception rb_eNameError `name` is not a constant name. * @exception rb_eTypeError `name` is already taken. - * @exception rb_eArgError Duplicated field name. + * @exception rb_eArgError Duplicated field name. * @return The defined class. * @post Global toplevel constant `name` is defined. * @note `name` is allowed to be a null pointer. This function creates * an anonymous struct class then. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. * * @internal * @@ -70,14 +72,16 @@ RBIMPL_ATTR_NONNULL((2)) * @param[out] space Namespace that the defining class shall reside. * @param[in] name Name of the class. * @param[in] ... Arbitrary number of `const char*`, terminated by - * zero. Each of which are the name of fields. + * NULL. Each of which are the name of fields. * @exception rb_eNameError `name` is not a constant name. * @exception rb_eTypeError `name` is already taken. - * @exception rb_eArgError Duplicated field name. + * @exception rb_eArgError Duplicated field name. * @return The defined class. * @post `name` is a constant under `space`. * @note In contrast to rb_struct_define(), it doesn't make any sense to * pass a null pointer to this function. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. */ VALUE rb_struct_define_under(VALUE space, const char *name, ...); @@ -164,10 +168,10 @@ VALUE rb_struct_alloc_noinit(VALUE klass); * @param[in] super Superclass of the defining class. * @param[in] func Must be 0 for extension libraries. * @param[in] ... Arbitrary number of `const char*`, terminated by - * zero. Each of which are the name of fields. + * NULL. Each of which are the name of fields. * @exception rb_eNameError `name` is not a constant name. * @exception rb_eTypeError `name` is already taken. - * @exception rb_eArgError Duplicated field name. + * @exception rb_eArgError Duplicated field name. * @return The defined class. * @post Global toplevel constant `name` is defined. * @note `name` is allowed to be a null pointer. This function creates @@ -187,17 +191,35 @@ RBIMPL_ATTR_NONNULL((2)) * @param[in] super Superclass of the defining class. * @param[in] alloc Must be 0 for extension libraries. * @param[in] ... Arbitrary number of `const char*`, terminated by - * zero. Each of which are the name of fields. + * NULL. Each of which are the name of fields. * @exception rb_eNameError `class_name` is not a constant name. * @exception rb_eTypeError `class_name` is already taken. - * @exception rb_eArgError Duplicated field name. + * @exception rb_eArgError Duplicated field name. * @return The defined class. * @post `class_name` is a constant under `outer`. * @note In contrast to rb_struct_define_without_accessor(), it doesn't * make any sense to pass a null name. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. */ VALUE rb_struct_define_without_accessor_under(VALUE outer, const char *class_name, VALUE super, rb_alloc_func_t alloc, ...); +/** + * Defines an anonymous data class. + * + * @endinternal + * + * @param[in] super Superclass of the defining class. Must be a + * descendant of ::rb_cData, or 0 as ::rb_cData. + * @param[in] ... Arbitrary number of `const char*`, terminated by + * NULL. Each of which are the name of fields. + * @exception rb_eArgError Duplicated field name. + * @return The defined class. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. + */ +VALUE rb_data_define(VALUE super, ...); + RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_INTERN_STRUCT_H */ diff --git a/include/ruby/internal/intern/thread.h b/include/ruby/internal/intern/thread.h index c9f476744a..4d87452745 100644 --- a/include/ruby/internal/intern/thread.h +++ b/include/ruby/internal/intern/thread.h @@ -46,7 +46,7 @@ void rb_thread_schedule(void); * * @param[in] fd A file descriptor. * @exception rb_eIOError Closed stream. - * @exception rb_eSystemCalleError Situations like EBADF. + * @exception rb_eSystemCallError Situations like EBADF. */ int rb_thread_wait_fd(int fd); @@ -56,15 +56,15 @@ int rb_thread_wait_fd(int fd); * * @param[in] fd A file descriptor. * @exception rb_eIOError Closed stream. - * @exception rb_eSystemCalleError Situations like EBADF. + * @exception rb_eSystemCallError Situations like EBADF. */ int rb_thread_fd_writable(int fd); /** - * Notifies a closing of a file descriptor to other threads. Multiple threads - * can wait for the given file descriptor at once. If such file descriptor is - * closed, threads need to start propagating their exceptions. This is the API - * to kick that process. + * This funciton is now a no-op. It was previously used to interrupt threads + * that were using the given file descriptor and wait for them to finish. + * + * @deprecated Use IO with RUBY_IO_MODE_EXTERNAL and `rb_io_close` instead. * * @param[in] fd A file descriptor. * @note This function blocks until all the threads waiting for such fd @@ -463,8 +463,17 @@ VALUE rb_mutex_unlock(VALUE mutex); * * This function is called from `ConditionVariable#wait`. So it is not a * deprecated feature. However @shyouhei have never seen any similar mutex - * primitive available in any other language than Ruby. Is this a right - * design? Maybe isn't it too complex a primitive? + * primitive available in any other languages than Ruby. + * + * EDIT: In 2021, @shyouhei asked @ko1 in person about this API. He answered + * that it is his invention. The motivation behind its design is to eliminate + * needs of condition variables as primitives. Unlike other languages, Ruby's + * `ConditionVariable` class was written in pure-Ruby initially. We don't have + * to implement machine-native condition variables in assembly each time we + * port Ruby to a new architecture. This function made it possible. "I felt I + * was a genius when this idea came to me", said @ko1. + * + * `rb_cConditionVariable` is now written in C for speed, though. */ VALUE rb_mutex_sleep(VALUE self, VALUE timeout); diff --git a/include/ruby/internal/intern/vm.h b/include/ruby/internal/intern/vm.h index 562d30a6fe..f0b54c702c 100644 --- a/include/ruby/internal/intern/vm.h +++ b/include/ruby/internal/intern/vm.h @@ -89,7 +89,8 @@ VALUE rb_check_funcall(VALUE recv, ID mid, int argc, const VALUE *argv); * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @retval RUBY_Qundef `recv` doesn't respond to `mid`. * @retval otherwise What the method evaluates to. */ @@ -106,9 +107,11 @@ VALUE rb_check_funcall_kw(VALUE recv, ID mid, int argc, const VALUE *argv, int k * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `arg`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `arg`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @return What the command evaluates to. */ +RBIMPL_ATTR_DEPRECATED_INTERNAL(4.0) VALUE rb_eval_cmd_kw(VALUE cmd, VALUE arg, int kw_splat); /** @@ -229,8 +232,7 @@ void rb_define_alloc_func(VALUE klass, rb_alloc_func_t func); * restrict creation of an instance of a class. For example it rarely makes * sense for a DB adaptor class to allow programmers creating DB row objects * without querying the DB itself. You can kill sporadic creation of such - * objects then, by nullifying the allocator function using this API. Your - * object shall be allocated using #RB_NEWOBJ_OF() directly. + * objects then, by nullifying the allocator function using this API. * * @param[out] klass The class to modify. * @pre `klass` must be an instance of Class. @@ -247,21 +249,17 @@ void rb_undef_alloc_func(VALUE klass); * * @internal * - * Who cares? @shyouhei fins no practical usage of the return value. Maybe we + * Who cares? @shyouhei finds no practical usage of the return value. Maybe we * need KonMari. */ rb_alloc_func_t rb_get_alloc_func(VALUE klass); /** - * Clears the constant cache. Extension libraries should not bother such - * things. Just forget about this API (or even, the presence of constant - * cache). - * - * @internal - * - * Completely no idea why this function is defined in vm_method.c. + * Clears the inline constant caches associated with a particular ID. Extension + * libraries should not bother with such things. Just forget about this API (or + * even, the presence of constant caches). */ -void rb_clear_constant_cache(void); +void rb_clear_constant_cache_for_id(ID id); /** * Resembles `alias`. diff --git a/include/ruby/internal/interpreter.h b/include/ruby/internal/interpreter.h index f8dd9bf88d..a10e7ad2d8 100644 --- a/include/ruby/internal/interpreter.h +++ b/include/ruby/internal/interpreter.h @@ -141,7 +141,7 @@ void ruby_show_copyright(void); * * @param[in] addr A pointer somewhere on the stack, near its bottom. */ -void ruby_init_stack(volatile VALUE *addr); +void ruby_init_stack(void *addr); /** * Initializes the VM and builtin libraries. @@ -168,11 +168,7 @@ int ruby_setup(void); * @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); +int ruby_cleanup(int ex); /** * Runs the VM finalization processes. diff --git a/include/ruby/internal/iterator.h b/include/ruby/internal/iterator.h index 3512b0ac86..891045363e 100644 --- a/include/ruby/internal/iterator.h +++ b/include/ruby/internal/iterator.h @@ -265,43 +265,6 @@ int rb_block_given_p(void); */ void rb_need_block(void); -RBIMPL_ATTR_DEPRECATED(("by: rb_block_call since 1.9")) -/** - * Old way to iterate a block. - * - * @deprecated This is an old API. Use rb_block_call() instead. - * @warning The passed function must at least once call a ruby method - * (to handle interrupts etc.) - * @param[in] func1 A function that could yield a value. - * @param[in,out] data1 Passed to `func1` - * @param[in] proc A function acts as a block. - * @param[in,out] data2 Passed to `proc` as the data2 parameter. - * @return What `func1` returns. - */ -VALUE rb_iterate(VALUE (*func1)(VALUE), VALUE data1, rb_block_call_func_t proc, VALUE data2); - -#ifdef __cplusplus -namespace ruby { -namespace backward { -/** - * Old way to iterate a block. - * - * @deprecated This is an old API. Use rb_block_call() instead. - * @warning The passed function must at least once call a ruby method - * (to handle interrupts etc.) - * @param[in] iter A function that could yield a value. - * @param[in,out] data1 Passed to `func1` - * @param[in] bl A function acts as a block. - * @param[in,out] data2 Passed to `proc` as the data2 parameter. - * @return What `func1` returns. - */ -static inline VALUE -rb_iterate_deprecated(VALUE (*iter)(VALUE), VALUE data1, rb_block_call_func_t bl, VALUE data2) -{ - return ::rb_iterate(iter, data1, bl, data2); -}}} -#endif - /** * Identical to rb_funcallv(), except it additionally passes a function as a * block. When the method yields, `proc` is called with the yielded value as @@ -332,7 +295,8 @@ VALUE rb_block_call(VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_cal * @param[in] kw_splat Handling of keyword parameters: * - RB_NO_KEYWORDS `argv`'s last is not a keyword argument. * - RB_PASS_KEYWORDS `argv`'s last is a keyword argument. - * - RB_PASS_CALLED_KEYWORDS it depends if there is a passed block. + * - RB_PASS_CALLED_KEYWORDS Pass keyword arguments if the current method + * was called with keyword arguments. * @return What `obj.mid` returns. */ VALUE rb_block_call_kw(VALUE obj, ID mid, int argc, const VALUE *argv, rb_block_call_func_t proc, VALUE data2, int kw_splat); diff --git a/include/ruby/internal/memory.h b/include/ruby/internal/memory.h index aa3464465d..cd099f85db 100644 --- a/include/ruby/internal/memory.h +++ b/include/ruby/internal/memory.h @@ -40,7 +40,12 @@ #if defined(_MSC_VER) && defined(_WIN64) # include <intrin.h> +# if defined(_M_AMD64) # pragma intrinsic(_umul128) +# endif +# if defined(_M_ARM64) +# pragma intrinsic(__umulh) +# endif #endif #include "ruby/internal/attr/alloc_size.h" @@ -56,13 +61,14 @@ #include "ruby/internal/has/builtin.h" #include "ruby/internal/stdalign.h" #include "ruby/internal/stdbool.h" +#include "ruby/internal/stdckdint.h" #include "ruby/internal/xmalloc.h" #include "ruby/backward/2/limits.h" #include "ruby/backward/2/long_long.h" #include "ruby/backward/2/assume.h" #include "ruby/defines.h" -/** @cond INTENAL_MACRO */ +/** @cond INTERNAL_MACRO */ /* Make alloca work the best possible way. */ #if defined(alloca) @@ -287,12 +293,12 @@ typedef uint128_t DSIZE_T; RBIMPL_CAST((type *)alloca(rbimpl_size_mul_or_raise(sizeof(type), (n)))) /** - * Identical to #RB_ALLOCV_N(), except it implicitly assumes the type of array - * is ::VALUE. + * Identical to #RB_ALLOCV_N(), except that it allocates a number of bytes and + * returns a void* . * * @param v A variable to hold the just-in-case opaque Ruby object. * @param n Size of allocation, in bytes. - * @return An array of `n` bytes of ::VALUE. + * @return A void pointer to `n` bytes storage. * @note `n` may be evaluated twice. */ #define RB_ALLOCV(v, n) \ @@ -363,7 +369,7 @@ typedef uint128_t DSIZE_T; * @return `p1`. * @post First `n` elements of `p2` are copied into `p1`. */ -#define MEMCPY(p1,p2,type,n) memcpy((p1), (p2), rbimpl_size_mul_or_raise(sizeof(type), (n))) +#define MEMCPY(p1,p2,type,n) ruby_nonempty_memcpy((p1), (p2), rbimpl_size_mul_or_raise(sizeof(type), (n))) /** * Handy macro to call memmove. @@ -402,7 +408,8 @@ typedef uint128_t DSIZE_T; /** * @private * - * This is an implementation detail of rbimpl_size_mul_overflow(). + * This is an implementation detail of rbimpl_size_mul_overflow() and + * rbimpl_size_add_overflow(). * * @internal * @@ -410,9 +417,9 @@ typedef uint128_t DSIZE_T; * nothing more than std::variant<std::size_t> if we could use recent C++, but * reality is we cannot. */ -struct rbimpl_size_mul_overflow_tag { - bool left; /**< Whether overflow happened or not. */ - size_t right; /**< Multiplication result. */ +struct rbimpl_size_overflow_tag { + bool overflowed; /**< Whether overflow happened or not. */ + size_t result; /**< Calculation result. */ }; RBIMPL_SYMBOL_EXPORT_BEGIN() @@ -482,6 +489,18 @@ RBIMPL_ATTR_NORETURN() */ void ruby_malloc_size_overflow(size_t x, size_t y); +RBIMPL_ATTR_NORETURN() +/** + * @private + * + * This is an implementation detail. People don't use this directly. + * + * @param[in] x Arbitrary value. + * @param[in] y Arbitrary value. + * @exception rb_eArgError `x` + `y` would integer overflow. + */ +void ruby_malloc_add_size_overflow(size_t x, size_t y); + #ifdef HAVE_RB_GC_GUARDED_PTR_VAL volatile VALUE *rb_gc_guarded_ptr_val(volatile VALUE *ptr, VALUE val); #endif @@ -554,39 +573,46 @@ RBIMPL_ATTR_CONST() * * @param[in] x Arbitrary value. * @param[in] y Arbitrary value. - * @return `{ left, right }`, where `left` is whether there is an integer - * overflow or not, and `right` is a (possibly overflowed) result - * of `x` * `y`. + * @return `{ overflowed, result }`, where `overflowed` is whether there is + * an integer overflow or not, and `result` is a (possibly + * overflowed) result of `x` * `y`. * * @internal * * This is in fact also an implementation detail of ruby_xmalloc2() etc. */ -static inline struct rbimpl_size_mul_overflow_tag +static inline struct rbimpl_size_overflow_tag rbimpl_size_mul_overflow(size_t x, size_t y) { - struct rbimpl_size_mul_overflow_tag ret = { false, 0, }; + struct rbimpl_size_overflow_tag ret = { false, 0, }; + +#if defined(ckd_mul) + ret.overflowed = ckd_mul(&ret.result, x, y); -#if RBIMPL_HAS_BUILTIN(__builtin_mul_overflow) - ret.left = __builtin_mul_overflow(x, y, &ret.right); +#elif RBIMPL_HAS_BUILTIN(__builtin_mul_overflow) + ret.overflowed = __builtin_mul_overflow(x, y, &ret.result); #elif defined(DSIZE_T) RB_GNUC_EXTENSION DSIZE_T dx = x; RB_GNUC_EXTENSION DSIZE_T dy = y; RB_GNUC_EXTENSION DSIZE_T dz = dx * dy; - ret.left = dz > SIZE_MAX; - ret.right = RBIMPL_CAST((size_t)dz); + ret.overflowed = dz > SIZE_MAX; + ret.result = RBIMPL_CAST((size_t)dz); -#elif defined(_MSC_VER) && defined(_WIN64) +#elif defined(_MSC_VER) && defined(_M_AMD64) unsigned __int64 dp = 0; unsigned __int64 dz = _umul128(x, y, &dp); - ret.left = RBIMPL_CAST((bool)dp); - ret.right = RBIMPL_CAST((size_t)dz); + ret.overflowed = RBIMPL_CAST((bool)dp); + ret.result = RBIMPL_CAST((size_t)dz); + +#elif defined(_MSC_VER) && defined(_M_ARM64) + ret.overflowed = __umulh(x, y) != 0; + ret.result = x * y; #else /* https://wiki.sei.cmu.edu/confluence/display/c/INT30-C.+Ensure+that+unsigned+integer+operations+do+not+wrap */ - ret.left = (y != 0) && (x > SIZE_MAX / y); - ret.right = x * y; + ret.overflowed = (y != 0) && (x > SIZE_MAX / y); + ret.result = x * y; #endif return ret; @@ -610,11 +636,11 @@ rbimpl_size_mul_overflow(size_t x, size_t y) static inline size_t rbimpl_size_mul_or_raise(size_t x, size_t y) { - struct rbimpl_size_mul_overflow_tag size = + struct rbimpl_size_overflow_tag size = rbimpl_size_mul_overflow(x, y); - if (RB_LIKELY(! size.left)) { - return size.right; + if (RB_LIKELY(! size.overflowed)) { + return size.result; } else { ruby_malloc_size_overflow(x, y); @@ -622,6 +648,81 @@ rbimpl_size_mul_or_raise(size_t x, size_t y) } } +#if defined(__DOXYGEN__) +RBIMPL_ATTR_CONSTEXPR(CXX14) +#elif RBIMPL_COMPILER_SINCE(GCC, 7, 0, 0) +RBIMPL_ATTR_CONSTEXPR(CXX14) /* https://gcc.gnu.org/bugzilla/show_bug.cgi?id=70507 */ +#elif RBIMPL_COMPILER_SINCE(Clang, 7, 0, 0) +RBIMPL_ATTR_CONSTEXPR(CXX14) /* https://bugs.llvm.org/show_bug.cgi?id=37633 */ +#endif +RBIMPL_ATTR_CONST() +/** + * @private + * + * This is an implementation detail. People don't use this directly. + * + * @param[in] x Arbitrary value. + * @param[in] y Arbitrary value. + * @return `{ overflowed, result }`, where `overflowed` is whether there is + * an integer overflow or not, and `result` is a (possibly + * overflowed) result of `x` + `y`. + * + * @internal + */ +static inline struct rbimpl_size_overflow_tag +rbimpl_size_add_overflow(size_t x, size_t y) +{ + struct rbimpl_size_overflow_tag ret = { false, 0, }; + +#if defined(ckd_add) + ret.overflowed = ckd_add(&ret.result, x, y); + +#elif RBIMPL_HAS_BUILTIN(__builtin_add_overflow) + ret.overflowed = __builtin_add_overflow(x, y, &ret.result); + +#elif defined(DSIZE_T) + RB_GNUC_EXTENSION DSIZE_T dx = x; + RB_GNUC_EXTENSION DSIZE_T dy = y; + RB_GNUC_EXTENSION DSIZE_T dz = dx + dy; + ret.overflowed = dz > SIZE_MAX; + ret.result = (size_t)dz; + +#else + ret.result = x + y; + ret.overflowed = ret.result < y; + +#endif + + return ret; +} + +/** + * @private + * + * This is an implementation detail. People don't use this directly. + * + * @param[in] x Arbitrary value. + * @param[in] y Arbitrary value. + * @exception rb_eArgError Multiplication could integer overflow. + * @return `x` + `y`. + * + * @internal + */ +static inline size_t +rbimpl_size_add_or_raise(size_t x, size_t y) +{ + struct rbimpl_size_overflow_tag size = + rbimpl_size_add_overflow(x, y); + + if (RB_LIKELY(!size.overflowed)) { + return size.result; + } + else { + ruby_malloc_add_size_overflow(x, y); + RBIMPL_UNREACHABLE_RETURN(0); + } +} + /** * This is an implementation detail of #RB_ALLOCV_N(). People don't use this * directly. @@ -639,12 +740,11 @@ rbimpl_size_mul_or_raise(size_t x, size_t y) static inline void * rb_alloc_tmp_buffer2(volatile VALUE *store, long count, size_t elsize) { - const size_t total_size = rbimpl_size_mul_or_raise(count, elsize); + const size_t total_size = rbimpl_size_mul_or_raise(RBIMPL_CAST((size_t)count), elsize); const size_t cnt = (total_size + sizeof(VALUE) - 1) / sizeof(VALUE); return rb_alloc_tmp_buffer_with_count(store, total_size, cnt); } -#if ! defined(__MINGW32__) && ! defined(__DOXYGEN__) RBIMPL_SYMBOL_EXPORT_BEGIN() RBIMPL_ATTR_NOALIAS() RBIMPL_ATTR_NONNULL((1)) @@ -663,8 +763,5 @@ ruby_nonempty_memcpy(void *dest, const void *src, size_t n) } } RBIMPL_SYMBOL_EXPORT_END() -#undef memcpy -#define memcpy ruby_nonempty_memcpy -#endif #endif /* RBIMPL_MEMORY_H */ diff --git a/include/ruby/internal/module.h b/include/ruby/internal/module.h index d678dd2102..97b0b2b8b0 100644 --- a/include/ruby/internal/module.h +++ b/include/ruby/internal/module.h @@ -56,8 +56,8 @@ RBIMPL_ATTR_NONNULL(()) * @post Top-level constant named `name` refers the returned class. * @note If a class named `name` is already defined and its superclass is * `super`, the function just returns the defined class. - * @note The compaction GC does not move classes returned by this - * function. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. * * @internal * @@ -75,8 +75,8 @@ RBIMPL_ATTR_NONNULL(()) * constant is not a module. * @return The created module. * @post Top-level constant named `name` refers the returned module. - * @note The compaction GC does not move classes returned by this - * function. + * @note The GC does not collect nor move modules returned by this + * function. They are immortal. * * @internal * @@ -103,8 +103,8 @@ RBIMPL_ATTR_NONNULL(()) * @post `outer::name` refers the returned class. * @note If a class named `name` is already defined and its superclass * is `super`, the function just returns the defined class. - * @note The compaction GC does not move classes returned by this - * function. + * @note The GC does not collect nor move classes returned by this + * function. They are immortal. */ VALUE rb_define_class_under(VALUE outer, const char *name, VALUE super); @@ -118,8 +118,8 @@ RBIMPL_ATTR_NONNULL(()) * the constant is not a class. * @return The created module. * @post `outer::name` refers the returned module. - * @note The compaction GC does not move classes returned by this - * function. + * @note The GC does not collect nor move modules returned by this + * function. They are immortal. */ VALUE rb_define_module_under(VALUE outer, const char *name); diff --git a/include/ruby/internal/newobj.h b/include/ruby/internal/newobj.h index a8a5557a25..13030ae279 100644 --- a/include/ruby/internal/newobj.h +++ b/include/ruby/internal/newobj.h @@ -29,63 +29,14 @@ #include "ruby/internal/value.h" #include "ruby/assert.h" -/** - * Declares, allocates, then assigns a new object to the given variable. - * - * @param obj Variable name. - * @param type Variable type. - * @exception rb_eNoMemError No space left. - * @return An allocated object, not initialised. - * @note Modern programs tend to use #NEWOBJ_OF instead. - * - * @internal - * - * :FIXME: Should we deprecate it? - */ -#define RB_NEWOBJ(obj,type) type *(obj) = RBIMPL_CAST((type *)rb_newobj()) - -/** - * Identical to #RB_NEWOBJ, except it also accepts the allocating object's - * class and flags. - * - * @param obj Variable name. - * @param type Variable type. - * @param klass Object's class. - * @param flags Object's flags. - * @exception rb_eNoMemError No space left. - * @return An allocated object, filled with the arguments. - */ -#define RB_NEWOBJ_OF(obj,type,klass,flags) type *(obj) = RBIMPL_CAST((type *)rb_newobj_of(klass, flags)) - -#define NEWOBJ RB_NEWOBJ /**< @old{RB_NEWOBJ} */ -#define NEWOBJ_OF RB_NEWOBJ_OF /**< @old{RB_NEWOBJ_OF} */ #define OBJSETUP rb_obj_setup /**< @old{rb_obj_setup} */ #define CLONESETUP rb_clone_setup /**< @old{rb_clone_setup} */ #define DUPSETUP rb_dup_setup /**< @old{rb_dup_setup} */ RBIMPL_SYMBOL_EXPORT_BEGIN() /** - * This is the implementation detail of #RB_NEWOBJ. - * - * @exception rb_eNoMemError No space left. - * @return An allocated object, not initialised. - */ -VALUE rb_newobj(void); - -/** - * This is the implementation detail of #RB_NEWOBJ_OF. - * - * @param klass Object's class. - * @param flags Object's flags. - * @exception rb_eNoMemError No space left. - * @return An allocated object, filled with the arguments. - */ -VALUE rb_newobj_of(VALUE klass, VALUE flags); - -/** * Fills common fields in the object. * - * @note Prefer rb_newobj_of() to this function. * @param[in,out] obj A Ruby object to be set up. * @param[in] klass `obj` will belong to this class. * @param[in] type One of ::ruby_value_type. @@ -158,38 +109,4 @@ void rb_singleton_class_attached(VALUE klass, VALUE obj); void rb_copy_generic_ivar(VALUE clone, VALUE obj); RBIMPL_SYMBOL_EXPORT_END() -RBIMPL_ATTR_DEPRECATED(("This is no longer how Object#clone works.")) -/** - * @deprecated Not sure exactly when but at some time, the implementation of - * `Object#clone` stopped using this function. It remained - * untouched for a while, and then @shyouhei realised that they - * are no longer doing the same thing. It seems nobody seriously - * uses this function any longer. Let's just abandon it. - * - * @param[out] clone The destination object. - * @param[in] obj The source object. - */ -static inline void -rb_clone_setup(VALUE clone, VALUE obj) -{ - return; -} - -RBIMPL_ATTR_DEPRECATED(("This is no longer how Object#dup works.")) -/** - * @deprecated Not sure exactly when but at some time, the implementation of - * `Object#dup` stopped using this function. It remained - * untouched for a while, and then @shyouhei realised that they - * are no longer the same thing. It seems nobody seriously uses - * this function any longer. Let's just abandon it. - * - * @param[out] dup The destination object. - * @param[in] obj The source object. - */ -static inline void -rb_dup_setup(VALUE dup, VALUE obj) -{ - return; -} - #endif /* RBIMPL_NEWOBJ_H */ diff --git a/include/ruby/internal/rgengc.h b/include/ruby/internal/rgengc.h deleted file mode 100644 index 7ea04442f6..0000000000 --- a/include/ruby/internal/rgengc.h +++ /dev/null @@ -1,443 +0,0 @@ -#ifndef RBIMPL_RGENGC_H /*-*-C++-*-vi:se ft=cpp:*/ -#define RBIMPL_RGENGC_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 RGENGC write-barrier APIs. - * @see Sasada, K., "Gradual write-barrier insertion into a Ruby - * interpreter", in proceedings of the 2019 ACM SIGPLAN - * International Symposium on Memory Management (ISMM 2019), pp - * 115-121, 2019. https://doi.org/10.1145/3315573.3329986 - */ -#include "ruby/internal/attr/artificial.h" -#include "ruby/internal/attr/maybe_unused.h" -#include "ruby/internal/attr/pure.h" -#include "ruby/internal/dllexport.h" -#include "ruby/internal/special_consts.h" -#include "ruby/internal/stdbool.h" -#include "ruby/internal/value.h" -#include "ruby/assert.h" - -/** - * @private - * - * @deprecated This macro once was a thing in the old days, but makes no sense - * any longer today. Exists here for backwards compatibility - * only. You can safely forget about it. - */ -#undef USE_RGENGC -#define USE_RGENGC 1 - -/** - * @private - * - * This is a compile-time flag to enable/disable incremental GC feature. It - * has to be set at the time ruby itself compiles. Makes no sense for 3rd - * parties. It is safe for them to set this though; that just doesn't change - * anything. - */ -#ifndef USE_RINCGC -# define USE_RINCGC 1 -#endif - -/** - * @deprecated This macro seems broken. Setting this to anything other than - * zero just doesn't compile. We need to KonMari. - */ -#ifndef USE_RGENGC_LOGGING_WB_UNPROTECT -# define USE_RGENGC_LOGGING_WB_UNPROTECT 0 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RArray. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_ARRAY -# define RGENGC_WB_PROTECTED_ARRAY 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RHash. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_HASH -# define RGENGC_WB_PROTECTED_HASH 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RStruct. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_STRUCT -# define RGENGC_WB_PROTECTED_STRUCT 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RString. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_STRING -# define RGENGC_WB_PROTECTED_STRING 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RObject. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_OBJECT -# define RGENGC_WB_PROTECTED_OBJECT 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RRegexp. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_REGEXP -# define RGENGC_WB_PROTECTED_REGEXP 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RClass. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_CLASS -# define RGENGC_WB_PROTECTED_CLASS 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RFloat. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_FLOAT -# define RGENGC_WB_PROTECTED_FLOAT 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RComplex. It has to be set at the time ruby itself compiles. - * Makes no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_COMPLEX -# define RGENGC_WB_PROTECTED_COMPLEX 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RRational. It has to be set at the time ruby itself compiles. - * Makes no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_RATIONAL -# define RGENGC_WB_PROTECTED_RATIONAL 1 -#endif - -/** - * @private - * - * This is a compile-time flag to enable/disable write barrier for - * struct ::RBignum. It has to be set at the time ruby itself compiles. Makes - * no sense for 3rd parties. - */ -#ifndef RGENGC_WB_PROTECTED_BIGNUM -# define RGENGC_WB_PROTECTED_BIGNUM 1 -#endif - -/** - * @private - * - * @deprecated This macro once was a thing in the old days, but makes no sense - * any longer today. Exists here for backwards compatibility - * only. You can safely forget about it. - * - * @internal - * - * @shyouhei doesn't think anybody uses this right now. - */ -#ifndef RGENGC_WB_PROTECTED_NODE_CREF -# define RGENGC_WB_PROTECTED_NODE_CREF 1 -#endif - -/** - * @defgroup rgengc Write barrier (WB) interfaces: - * - * @note The following core interfaces can be changed in the future. Please - * catch up if you want to insert WB into C-extensions correctly. - * - * @{ - */ - -/** - * Declaration of a "back" pointer. This is a write barrier for new reference - * from "old" generation to "young" generation. It writes `young` into - * `*slot`, which is a pointer inside of `old`. - * - * @param[in] old An old object. - * @param[in] slot A pointer inside of `old`. - * @param[out] young A young object. - */ -#define RB_OBJ_WRITE(old, slot, young) \ - RBIMPL_CAST(rb_obj_write((VALUE)(old), (VALUE *)(slot), (VALUE)(young), __FILE__, __LINE__)) - -/** - * Identical to #RB_OBJ_WRITE(), except it doesn't write any values, but only a - * WB declaration. `oldv` is replaced value with `b` (not used in current - * Ruby). - * - * @param[in] old An old object. - * @param[in] oldv An object previously stored inside of `old`. - * @param[out] young A young object. - */ -#define RB_OBJ_WRITTEN(old, oldv, young) \ - RBIMPL_CAST(rb_obj_written((VALUE)(old), (VALUE)(oldv), (VALUE)(young), __FILE__, __LINE__)) -/** @} */ - -#define OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW /**< @old{RB_OBJ_PROMOTED_RAW} */ -#define OBJ_PROMOTED RB_OBJ_PROMOTED /**< @old{RB_OBJ_PROMOTED} */ -#define OBJ_WB_UNPROTECT RB_OBJ_WB_UNPROTECT /**< @old{RB_OBJ_WB_UNPROTECT} */ - -/** - * Asserts that the passed object is not fenced by write barriers. Objects of - * such property do not contribute to generational GCs. They are scanned - * always. - * - * @param[out] x An object that would not be protected by the barrier. - */ -#define RB_OBJ_WB_UNPROTECT(x) rb_obj_wb_unprotect(x, __FILE__, __LINE__) - -/** - * Identical to #RB_OBJ_WB_UNPROTECT(), except it can also assert that the - * given object is of given type. - * - * @param[in] type One of `ARRAY`, `STRING`, etc. - * @param[out] obj An object of `type` that would not be protected. - * - * @internal - * - * @shyouhei doesn't understand why this has to be visible from extensions. - */ -#define RB_OBJ_WB_UNPROTECT_FOR(type, obj) \ - (RGENGC_WB_PROTECTED_##type ? OBJ_WB_UNPROTECT(obj) : obj) - -/** - * @private - * - * This is an implementation detail of rb_obj_wb_unprotect(). People don't use - * it directly. - */ -#define RGENGC_LOGGING_WB_UNPROTECT rb_gc_unprotect_logging - -/** @cond INTERNAL_MACRO */ -#define RB_OBJ_PROMOTED_RAW RB_OBJ_PROMOTED_RAW -#define RB_OBJ_PROMOTED RB_OBJ_PROMOTED -/** @endcond */ - -RBIMPL_SYMBOL_EXPORT_BEGIN() -/** - * This is the implementation of #RB_OBJ_WRITE(). People don't use it - * directly. - * - * @param[in] old An object that points to `young`. - * @param[out] young An object that is referenced from `old`. - */ -void rb_gc_writebarrier(VALUE old, VALUE young); - -/** - * This is the implementation of #RB_OBJ_WB_UNPROTECT(). People don't use it - * directly. - * - * @param[out] obj An object that does not participate in WB. - */ -void rb_gc_writebarrier_unprotect(VALUE obj); - -#if USE_RGENGC_LOGGING_WB_UNPROTECT -/** - * @private - * - * This is the implementation of #RGENGC_LOGGING_WB_UNPROTECT(). People - * don't use it directly. - * - * @param[in] objptr Don't know why this is a pointer to void but in - * reality this is a pointer to an object that is about - * to be un-protected. - * @param[in] filename Pass C's `__FILE__` here. - * @param[in] line Pass C's `__LINE__` here. - */ -void rb_gc_unprotect_logging(void *objptr, const char *filename, int line); -#endif - -RBIMPL_SYMBOL_EXPORT_END() - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -/** - * This is the implementation of #RB_OBJ_PROMOTED(). People don't use it - * directly. - * - * @param[in] obj An object to query. - * @retval true The object is "promoted". - * @retval false The object is young. Have not experienced GC at all. - */ -static inline bool -RB_OBJ_PROMOTED_RAW(VALUE obj) -{ - RBIMPL_ASSERT_OR_ASSUME(RB_FL_ABLE(obj)); - return RB_FL_ANY_RAW(obj, RUBY_FL_PROMOTED); -} - -RBIMPL_ATTR_PURE_UNLESS_DEBUG() -RBIMPL_ATTR_ARTIFICIAL() -/** - * Tests if the object is "promoted" -- that is, whether the object experienced - * one or more GC marks. - * - * @param[in] obj An object to query. - * @retval true The object is "promoted". - * @retval false The object is young. Have not experienced GC at all. - * @note Hello, is anyone actively calling this function? @shyouhei have - * never seen any actual usages outside of the GC implementation - * itself. - */ -static inline bool -RB_OBJ_PROMOTED(VALUE obj) -{ - if (! RB_FL_ABLE(obj)) { - return false; - } - else { - return RB_OBJ_PROMOTED_RAW(obj); - } -} - -/** - * This is the implementation of #RB_OBJ_WB_UNPROTECT(). People don't use it - * directly. - * - * @param[out] x An object that does not participate in WB. - * @param[in] filename C's `__FILE__` of the caller function. - * @param[in] line C's `__LINE__` of the caller function. - * @return x - */ -static inline VALUE -rb_obj_wb_unprotect( - VALUE x, - RBIMPL_ATTR_MAYBE_UNUSED() - const char *filename, - RBIMPL_ATTR_MAYBE_UNUSED() - int line) -{ -#if USE_RGENGC_LOGGING_WB_UNPROTECT - RGENGC_LOGGING_WB_UNPROTECT(RBIMPL_CAST((void *)x), filename, line); -#endif - rb_gc_writebarrier_unprotect(x); - return x; -} - -/** - * @private - * - * This is the implementation of #RB_OBJ_WRITTEN(). People don't use it - * directly. - * - * @param[in] a An old object. - * @param[in] oldv An object previously stored inside of `old`. - * @param[out] b A young object. - * @param[in] filename C's `__FILE__` of the caller function. - * @param[in] line C's `__LINE__` of the caller function. - * @return a - */ -static inline VALUE -rb_obj_written( - VALUE a, - RBIMPL_ATTR_MAYBE_UNUSED() - VALUE oldv, - VALUE b, - RBIMPL_ATTR_MAYBE_UNUSED() - const char *filename, - RBIMPL_ATTR_MAYBE_UNUSED() - int line) -{ -#if USE_RGENGC_LOGGING_WB_UNPROTECT - RGENGC_LOGGING_OBJ_WRITTEN(a, oldv, b, filename, line); -#endif - - if (!RB_SPECIAL_CONST_P(b)) { - rb_gc_writebarrier(a, b); - } - - return a; -} - -/** - * @private - * - * This is the implementation of #RB_OBJ_WRITE(). People don't use it - * directly. - * - * @param[in] a An old object. - * @param[in] slot A pointer inside of `old`. - * @param[out] b A young object. - * @param[in] filename C's `__FILE__` of the caller function. - * @param[in] line C's `__LINE__` of the caller function. - * @return a - */ -static inline VALUE -rb_obj_write( - VALUE a, VALUE *slot, VALUE b, - RBIMPL_ATTR_MAYBE_UNUSED() - const char *filename, - RBIMPL_ATTR_MAYBE_UNUSED() - int line) -{ -#ifdef RGENGC_LOGGING_WRITE - RGENGC_LOGGING_WRITE(a, slot, b, filename, line); -#endif - - *slot = b; - - rb_obj_written(a, RUBY_Qundef /* ignore `oldv' now */, b, filename, line); - return a; -} - -#endif /* RBIMPL_RGENGC_H */ diff --git a/include/ruby/internal/scan_args.h b/include/ruby/internal/scan_args.h index cf5b18f77d..2dbc1ee7bc 100644 --- a/include/ruby/internal/scan_args.h +++ b/include/ruby/internal/scan_args.h @@ -75,7 +75,7 @@ * Pass keywords if current method is called with keywords, useful for argument * delegation */ -#define RB_PASS_CALLED_KEYWORDS rb_keyword_given_p() +#define RB_PASS_CALLED_KEYWORDS !!rb_keyword_given_p() /** @} */ @@ -100,7 +100,7 @@ RBIMPL_ATTR_NONNULL((2, 3)) * param-arg-spec := pre-arg-spec [post-arg-spec] / post-arg-spec / * pre-opt-post-arg-spec * pre-arg-spec := num-of-leading-mandatory-args - [num-of-optional-args] + * [num-of-optional-args] * post-arg-spec := sym-for-variable-length-args * [num-of-trailing-mandatory-args] * pre-opt-post-arg-spec := num-of-leading-mandatory-args num-of-optional-args diff --git a/include/ruby/internal/special_consts.h b/include/ruby/internal/special_consts.h index 38934e4da3..1e2636da48 100644 --- a/include/ruby/internal/special_consts.h +++ b/include/ruby/internal/special_consts.h @@ -76,6 +76,8 @@ #define RB_SPECIAL_CONST_P RB_SPECIAL_CONST_P #define RB_STATIC_SYM_P RB_STATIC_SYM_P #define RB_TEST RB_TEST +#define RB_UNDEF_P RB_UNDEF_P +#define RB_NIL_OR_UNDEF_P RB_NIL_OR_UNDEF_P /** @endcond */ /** special constants - i.e. non-zero and non-fixnum constants */ @@ -94,9 +96,9 @@ ruby_special_consts { RUBY_SYMBOL_FLAG, /**< Flag to denote a static symbol. */ #elif USE_FLONUM RUBY_Qfalse = 0x00, /* ...0000 0000 */ + RUBY_Qnil = 0x04, /* ...0000 0100 */ RUBY_Qtrue = 0x14, /* ...0001 0100 */ - RUBY_Qnil = 0x08, /* ...0000 1000 */ - RUBY_Qundef = 0x34, /* ...0011 0100 */ + RUBY_Qundef = 0x24, /* ...0010 0100 */ RUBY_IMMEDIATE_MASK = 0x07, /* ...0000 0111 */ RUBY_FIXNUM_FLAG = 0x01, /* ...xxxx xxx1 */ RUBY_FLONUM_MASK = 0x03, /* ...0000 0011 */ @@ -104,14 +106,14 @@ ruby_special_consts { RUBY_SYMBOL_FLAG = 0x0c, /* ...xxxx 1100 */ #else RUBY_Qfalse = 0x00, /* ...0000 0000 */ - RUBY_Qtrue = 0x02, /* ...0000 0010 */ - RUBY_Qnil = 0x04, /* ...0000 0100 */ - RUBY_Qundef = 0x06, /* ...0000 0110 */ + RUBY_Qnil = 0x02, /* ...0000 0010 */ + RUBY_Qtrue = 0x06, /* ...0000 0110 */ + RUBY_Qundef = 0x0a, /* ...0000 1010 */ RUBY_IMMEDIATE_MASK = 0x03, /* ...0000 0011 */ RUBY_FIXNUM_FLAG = 0x01, /* ...xxxx xxx1 */ RUBY_FLONUM_MASK = 0x00, /* any values ANDed with FLONUM_MASK cannot be FLONUM_FLAG */ RUBY_FLONUM_FLAG = 0x02, /* ...0000 0010 */ - RUBY_SYMBOL_FLAG = 0x0e, /* ...0000 1110 */ + RUBY_SYMBOL_FLAG = 0x0e, /* ...xxxx 1110 */ #endif RUBY_SPECIAL_SHIFT = 8 /**< Least significant 8 bits are reserved. */ @@ -136,16 +138,25 @@ static inline bool RB_TEST(VALUE obj) { /* + * if USE_FLONUM * Qfalse: ....0000 0000 - * Qnil: ....0000 1000 - * ~Qnil: ....1111 0111 + * Qnil: ....0000 0100 + * ~Qnil: ....1111 1011 * v ....xxxx xxxx * ---------------------------- - * RTEST(v) ....xxxx 0xxx + * RTEST(v) ....xxxx x0xx + * + * if ! USE_FLONUM + * Qfalse: ....0000 0000 + * Qnil: ....0000 0010 + * ~Qnil: ....1111 1101 + * v ....xxxx xxxx + * ---------------------------- + * RTEST(v) ....xxxx xx0x * * RTEST(v) can be 0 if and only if (v == Qfalse || v == Qnil). */ - return obj & ~RUBY_Qnil; + return obj & RBIMPL_CAST((VALUE)~RUBY_Qnil); } RBIMPL_ATTR_CONST() @@ -168,6 +179,62 @@ RBIMPL_ATTR_CONST() RBIMPL_ATTR_CONSTEXPR(CXX11) RBIMPL_ATTR_ARTIFICIAL() /** + * Checks if the given object is undef. + * + * @param[in] obj An arbitrary ruby object. + * @retval true `obj` is ::RUBY_Qundef. + * @retval false Anything else. + */ +static inline bool +RB_UNDEF_P(VALUE obj) +{ + return obj == RUBY_Qundef; +} + +RBIMPL_ATTR_CONST() +RBIMPL_ATTR_CONSTEXPR(CXX14) +RBIMPL_ATTR_ARTIFICIAL() +/** + * Checks if the given object is nil or undef. Can be used to see if + * a keyword argument is not given or given `nil`. + * + * @param[in] obj An arbitrary ruby object. + * @retval true `obj` is ::RUBY_Qnil or ::RUBY_Qundef. + * @retval false Anything else. + */ +static inline bool +RB_NIL_OR_UNDEF_P(VALUE obj) +{ + /* + * if USE_FLONUM + * Qundef: ....0010 0100 + * Qnil: ....0000 0100 + * mask: ....1101 1111 + * common_bits: ....0000 0100 + * --------------------------------- + * Qnil & mask ....0000 0100 + * Qundef & mask ....0000 0100 + * + * if ! USE_FLONUM + * Qundef: ....0000 1010 + * Qnil: ....0000 0010 + * mask: ....1111 0111 + * common_bits: ....0000 0010 + * ---------------------------- + * Qnil & mask ....0000 0010 + * Qundef & mask ....0000 0010 + * + * NIL_OR_UNDEF_P(v) can be true only when v is Qundef or Qnil. + */ + const VALUE mask = RBIMPL_CAST((VALUE)~(RUBY_Qundef ^ RUBY_Qnil)); + const VALUE common_bits = RUBY_Qundef & RUBY_Qnil; + return (obj & mask) == common_bits; +} + +RBIMPL_ATTR_CONST() +RBIMPL_ATTR_CONSTEXPR(CXX11) +RBIMPL_ATTR_ARTIFICIAL() +/** * Checks if the given object is a so-called Fixnum. * * @param[in] obj An arbitrary ruby object. @@ -259,7 +326,7 @@ RBIMPL_ATTR_ARTIFICIAL() static inline bool RB_SPECIAL_CONST_P(VALUE obj) { - return RB_IMMEDIATE_P(obj) || ! RB_TEST(obj); + return (obj == RUBY_Qfalse) || RB_IMMEDIATE_P(obj); } RBIMPL_ATTR_CONST() @@ -279,7 +346,7 @@ RBIMPL_ATTR_CONSTEXPR(CXX11) static inline VALUE rb_special_const_p(VALUE obj) { - return RB_SPECIAL_CONST_P(obj) * RUBY_Qtrue; + return (unsigned int)RB_SPECIAL_CONST_P(obj) * RUBY_Qtrue; } /** diff --git a/include/ruby/internal/static_assert.h b/include/ruby/internal/static_assert.h index 594c2b2917..30bfd3bb79 100644 --- a/include/ruby/internal/static_assert.h +++ b/include/ruby/internal/static_assert.h @@ -23,13 +23,14 @@ #include <assert.h> #include "ruby/internal/has/extension.h" #include "ruby/internal/compiler_since.h" +#include "ruby/internal/attr/maybe_unused.h" /** @cond INTERNAL_MACRO */ #if defined(__cplusplus) && defined(__cpp_static_assert) # /* https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations */ # define RBIMPL_STATIC_ASSERT0 static_assert -#elif defined(__cplusplus) && RBIMPL_COMPILER_SINCE(MSVC, 16, 0, 0) +#elif defined(__cplusplus) && RBIMPL_COMPILER_IS(MSVC) # define RBIMPL_STATIC_ASSERT0 static_assert #elif defined(__INTEL_CXX11_MODE__) @@ -71,7 +72,7 @@ #else # define RBIMPL_STATIC_ASSERT(name, expr) \ - typedef int static_assert_ ## name ## _check[1 - 2 * !(expr)] + RBIMPL_ATTR_MAYBE_UNUSED() typedef int static_assert_ ## name ## _check[1 - 2 * !(expr)] #endif #endif /* RBIMPL_STATIC_ASSERT_H */ diff --git a/include/ruby/internal/stdbool.h b/include/ruby/internal/stdbool.h index b15321cb00..5d9026434b 100644 --- a/include/ruby/internal/stdbool.h +++ b/include/ruby/internal/stdbool.h @@ -27,25 +27,13 @@ #elif defined(__cplusplus) # /* bool is a keyword in C++. */ -# if defined(HAVE_STDBOOL_H) && (__cplusplus >= 201103L) -# include <cstdbool> -# endif -# # ifndef __bool_true_false_are_defined # define __bool_true_false_are_defined # endif -#elif defined(HAVE_STDBOOL_H) -# /* Take stdbool.h definition. */ -# include <stdbool.h> - #else -typedef unsigned char _Bool; -# /* See also http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2229.htm */ -# define bool _Bool -# define true ((_Bool)+1) -# define false ((_Bool)+0) -# define __bool_true_false_are_defined +# /* Take stdbool.h definition. It exists since GCC 3.0 and VS 2015. */ +# include <stdbool.h> #endif #endif /* RBIMPL_STDBOOL_H */ diff --git a/include/ruby/internal/stdckdint.h b/include/ruby/internal/stdckdint.h new file mode 100644 index 0000000000..e5b5b8b751 --- /dev/null +++ b/include/ruby/internal/stdckdint.h @@ -0,0 +1,68 @@ +#ifndef RBIMPL_STDCKDINT_H /*-*-C++-*-vi:se ft=cpp:*/ +#define RBIMPL_STDCKDINT_H +/** + * @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 C23 shim for <stdckdint.h> + */ +#include "ruby/internal/config.h" +#include "ruby/internal/cast.h" +#include "ruby/internal/has/builtin.h" +#include "ruby/internal/stdbool.h" + +#ifdef __has_include +# if __has_include(<stdckdint.h>) +# /* Conforming C23 situation; e.g. recent clang */ +# define RBIMPL_HAVE_STDCKDINT_H +# endif +#endif + +#ifdef HAVE_STDCKDINT_H +# /* Some OSes (most notably FreeBSD) have this file. */ +# define RBIMPL_HAVE_STDCKDINT_H +#endif + +#ifdef __cplusplus +# /* It seems OS/Compiler provided stdckdint.h tend not support C++ yet. +# * Situations could improve someday but in a meantime let us work around. +# */ +# undef RBIMPL_HAVE_STDCKDINT_H +#endif + +#ifdef RBIMPL_HAVE_STDCKDINT_H +# /* Take that. */ +# include <stdckdint.h> + +#elif RBIMPL_HAS_BUILTIN(__builtin_add_overflow) +# define ckd_add(x, y, z) RBIMPL_CAST((bool)__builtin_add_overflow((y), (z), (x))) +# define ckd_sub(x, y, z) RBIMPL_CAST((bool)__builtin_sub_overflow((y), (z), (x))) +# define ckd_mul(x, y, z) RBIMPL_CAST((bool)__builtin_mul_overflow((y), (z), (x))) +# define __STDC_VERSION_STDCKDINT_H__ 202311L + +#/* elif defined(__cplusplus) */ +#/* :TODO: if we assume C++11 we can use `<type_traits>` to implement them. */ + +#else +# /* intentionally leave them undefined */ +# /* to make `#ifdef ckd_add` etc. work as intended. */ +# undef ckd_add +# undef ckd_sub +# undef ckd_mul +# undef __STDC_VERSION_STDCKDINT_H__ +#endif + +#endif /* RBIMPL_STDCKDINT_H */ diff --git a/include/ruby/internal/symbol.h b/include/ruby/internal/symbol.h index 869a31115c..8bfd686fbe 100644 --- a/include/ruby/internal/symbol.h +++ b/include/ruby/internal/symbol.h @@ -101,12 +101,11 @@ ID rb_intern(const char *name); ID rb_intern2(const char *name, long len); /** - * Identical to rb_intern(), except it takes an instance of ::rb_cString. + * Identical to rb_intern(), except it takes a `T_STRING` object. * * @param[in] str The name of the id. - * @pre `str` must either be an instance of ::rb_cSymbol, or an instance - * of ::rb_cString, or responds to `#to_str` method. - * @exception rb_eTypeError Can't convert `str` into ::rb_cString. + * @pre `rb_type(str)` must be `T_STRING`. + * @exception rb_eEncodingError `str` contains invalid character(s). * @exception rb_eRuntimeError Too many symbols. * @return A (possibly new) id whose value is the given str. * @note These days Ruby internally has two kinds of symbols @@ -121,10 +120,17 @@ ID rb_intern_str(VALUE str); * Retrieves the name mapped to the given id. * * @param[in] id An id to query. - * @retval NULL No such id ever existed in the history. + * @retval NULL Unknown id. * @retval otherwise A name that the id represents. * @note The return value is managed by the interpreter. Don't pass it * to free(). + * @note The underlying name can contain internal NUL bytes, so the return + * value might be a truncated representation due to the nature of C + * strings. + * @note This C string is backed by an underlying Ruby string. The Ruby + * string may move during GC compaction which would make this + * C string point to invalid memory. Do not use the return value + * of this function after a potential GC entry point. */ const char *rb_id2name(ID id); @@ -159,34 +165,40 @@ RBIMPL_ATTR_NONNULL(()) * of ::rb_cSymbol, or an instance of ::rb_cString, or responds * to `#to_str` method. * @exception rb_eTypeError Can't convert `*namep` into ::rb_cString. - * @exception rb_eEncodingError Given string is non-ASCII. + * @exception rb_eEncodingError Given string contains invalid character(s). * @retval 0 No such id ever existed in the history. * @retval otherwise The id that represents the given name. * @post The object that `*namep` points to is a converted result * object, which is always an instance of either ::rb_cSymbol * or ::rb_cString. + * @see rb_str_to_str * @see https://bugs.ruby-lang.org/issues/5072 - * - * @internal - * - * @shyouhei doesn't know why this has to raise rb_eEncodingError. */ ID rb_check_id(volatile VALUE *namep); /** - * @copydoc rb_intern_str() - * - * @internal + * Identical to rb_intern_str(), except it tries to convert the parameter object + * to an instance of ::rb_cString or its subclasses. * - * :FIXME: Can anyone tell us what is the difference between this one and - * rb_intern_str()? As far as @shyouhei reads the implementation it seems what - * rb_to_id() does is is just waste some CPU time, then call rb_intern_str(). - * He hopes he is wrong. + * @param[in] str The name of the id. + * @pre `str` must either be an instance of ::rb_cSymbol, or an instance + * of ::rb_cString, or responds to `#to_str` method. + * @exception rb_eTypeError Can't convert `str` into ::rb_cString. + * @exception rb_eEncodingError Given string contains invalid character(s). + * @exception rb_eRuntimeError Too many symbols. + * @return A (possibly new) id whose value is the given str. + * @note These days Ruby internally has two kinds of symbols + * (static/dynamic). Symbols created using this function would + * become static ones; i.e. would never be garbage collected. It + * is up to you to avoid memory leaks. Think twice before using + * it. + * @see rb_str_to_str */ ID rb_to_id(VALUE str); /** - * Identical to rb_id2name(), except it returns a Ruby's String instead of C's. + * Identical to rb_id2name(), except it returns a frozen Ruby String instead of + * a C String. * * @param[in] id An id to query. * @retval RUBY_Qfalse No such id ever existed in the history. @@ -201,14 +213,14 @@ ID rb_to_id(VALUE str); VALUE rb_id2str(ID id); /** - * Identical to rb_id2str(), except it takes an instance of ::rb_cSymbol rather - * than an ::ID. + * Obtain a frozen string representation of a symbol (not including the leading + * colon). Done without any object allocations. * - * @param[in] id An id to query. - * @retval RUBY_Qfalse No such id ever existed in the history. - * @retval otherwise An instance of ::rb_cString with the name of id. + * @param[in] symbol A ::rb_cSymbol instance to query. + * @return A frozen instance of ::rb_cString with the name of `symbol`. + * @note This does not create a permanent ::ID using the symbol. */ -VALUE rb_sym2str(VALUE id); +VALUE rb_sym2str(VALUE symbol); /** * Identical to rb_intern_str(), except it generates a dynamic symbol if @@ -237,17 +249,14 @@ RBIMPL_ATTR_NONNULL(()) * of ::rb_cSymbol, or an instance of ::rb_cString, or responds * to `#to_str` method. * @exception rb_eTypeError Can't convert `*namep` into ::rb_cString. - * @exception rb_eEncodingError Given string is non-ASCII. + * @exception rb_eEncodingError Given string contains invalid character(s). * @retval RUBY_Qnil No such id ever existed in the history. * @retval otherwise The id that represents the given name. * @post The object that `*namep` points to is a converted result * object, which is always an instance of either ::rb_cSymbol * or ::rb_cString. * @see https://bugs.ruby-lang.org/issues/5072 - * - * @internal - * - * @shyouhei doesn't know why this has to raise rb_eEncodingError. + * @see rb_str_to_str */ VALUE rb_check_symbol(volatile VALUE *namep); RBIMPL_SYMBOL_EXPORT_END() @@ -308,8 +317,9 @@ rbimpl_intern_const(ID *ptr, const char *str) } /** - * Old implementation detail of rb_intern(). - * @deprecated Does anyone use it? Preserved for backward compat. + * Returns the cached ID for the given str in var, in compiler + * independent manner. Use this instead of GCC specific rb_intern() + * when you want to cache the ID on all platforms certainly. */ #define RUBY_CONST_ID(var, str) \ do { \ @@ -318,7 +328,8 @@ rbimpl_intern_const(ID *ptr, const char *str) } while (0) #if defined(HAVE_STMT_AND_DECL_IN_EXPR) -/* __builtin_constant_p and statement expression is available +/* GCC specific shorthand for RUBY_CONST_ID(). + * __builtin_constant_p and statement expression is available * since gcc-2.7.2.3 at least. */ #define rb_intern(str) \ (RBIMPL_CONSTANT_P(str) ? \ diff --git a/include/ruby/internal/value_type.h b/include/ruby/internal/value_type.h index 977f60a009..b47d8afb97 100644 --- a/include/ruby/internal/value_type.h +++ b/include/ruby/internal/value_type.h @@ -96,10 +96,11 @@ #define RB_TYPE_P RB_TYPE_P #define Check_Type Check_Type -#if !RUBY_DEBUG -# define RBIMPL_ASSERT_TYPE(v, t) RBIMPL_ASSERT_OR_ASSUME(RB_TYPE_P((v), (t))) +#ifdef RBIMPL_VA_OPT_ARGS +# define RBIMPL_ASSERT_TYPE(v, t) \ + RBIMPL_ASSERT_OR_ASSUME(RB_TYPE_P(v, t), "actual type: %d", rb_type(v)) #else -# define RBIMPL_ASSERT_TYPE Check_Type +# define RBIMPL_ASSERT_TYPE(v, t) RBIMPL_ASSERT_OR_ASSUME(RB_TYPE_P(v, t)) #endif /** @endcond */ @@ -129,8 +130,8 @@ ruby_value_type { RUBY_T_RATIONAL = 0x0f, /**< @see struct ::RRational */ RUBY_T_NIL = 0x11, /**< @see ::RUBY_Qnil */ - RUBY_T_TRUE = 0x12, /**< @see ::RUBY_Qfalse */ - RUBY_T_FALSE = 0x13, /**< @see ::RUBY_Qtrue */ + RUBY_T_TRUE = 0x12, /**< @see ::RUBY_Qtrue */ + RUBY_T_FALSE = 0x13, /**< @see ::RUBY_Qfalse */ RUBY_T_SYMBOL = 0x14, /**< @see struct ::RSymbol */ RUBY_T_FIXNUM = 0x15, /**< Integers formerly known as Fixnums. */ RUBY_T_UNDEF = 0x16, /**< @see ::RUBY_Qundef */ @@ -443,7 +444,7 @@ Check_Type(VALUE v, enum ruby_value_type t) } unexpected_type: - rb_unexpected_type(v, t); + rb_unexpected_type(v, RBIMPL_CAST((int)t)); } #endif /* RBIMPL_VALUE_TYPE_H */ diff --git a/include/ruby/internal/variable.h b/include/ruby/internal/variable.h index 1f84b92db0..c017ffe3f7 100644 --- a/include/ruby/internal/variable.h +++ b/include/ruby/internal/variable.h @@ -147,7 +147,7 @@ RBIMPL_ATTR_NONNULL(()) * init_Foo(void) * { * foo = rb_eval_string("..."); - * rb_define_global_variable("$foo", &foo); + * rb_define_variable("$foo", &foo); * } * ``` * diff --git a/include/ruby/internal/warning_push.h b/include/ruby/internal/warning_push.h index f5981633f8..91d62cb00d 100644 --- a/include/ruby/internal/warning_push.h +++ b/include/ruby/internal/warning_push.h @@ -79,7 +79,7 @@ */ #define RBIMPL_WARNING_IGNORED(flag) __pragma(warning(disable: flag)) -#elif RBIMPL_COMPILER_SINCE(MSVC, 12, 0, 0) +#elif RBIMPL_COMPILER_IS(MSVC) # /* Not sure exactly when but it seems VC++ 6.0 is a version with it.*/ # define RBIMPL_WARNING_PUSH() __pragma(warning(push)) # define RBIMPL_WARNING_POP() __pragma(warning(pop)) diff --git a/include/ruby/internal/xmalloc.h b/include/ruby/internal/xmalloc.h index 57552e4e7d..132bc478ce 100644 --- a/include/ruby/internal/xmalloc.h +++ b/include/ruby/internal/xmalloc.h @@ -283,110 +283,6 @@ void ruby_xfree(void *ptr) RBIMPL_ATTR_NOEXCEPT(free(ptr)) ; -#if USE_GC_MALLOC_OBJ_INFO_DETAILS -# define ruby_xmalloc(s1) ruby_xmalloc_with_location(s1, __FILE__, __LINE__) -# define ruby_xmalloc2(s1, s2) ruby_xmalloc2_with_location(s1, s2, __FILE__, __LINE__) -# define ruby_xcalloc(s1, s2) ruby_xcalloc_with_location(s1, s2, __FILE__, __LINE__) -# define ruby_xrealloc(ptr, s1) ruby_xrealloc_with_location(ptr, s1, __FILE__, __LINE__) -# define ruby_xrealloc2(ptr, s1, s2) ruby_xrealloc2_with_location(ptr, s1, s2, __FILE__, __LINE__) - -RBIMPL_ATTR_NODISCARD() -RBIMPL_ATTR_RESTRICT() -RBIMPL_ATTR_RETURNS_NONNULL() -RBIMPL_ATTR_ALLOC_SIZE((1)) -void *ruby_xmalloc_body(size_t size) -RBIMPL_ATTR_NOEXCEPT(malloc(size)) -; - -RBIMPL_ATTR_NODISCARD() -RBIMPL_ATTR_RESTRICT() -RBIMPL_ATTR_RETURNS_NONNULL() -RBIMPL_ATTR_ALLOC_SIZE((1,2)) -void *ruby_xmalloc2_body(size_t nelems, size_t elemsiz) -RBIMPL_ATTR_NOEXCEPT(malloc(nelems * elemsiz)) -; - -RBIMPL_ATTR_NODISCARD() -RBIMPL_ATTR_RESTRICT() -RBIMPL_ATTR_RETURNS_NONNULL() -RBIMPL_ATTR_ALLOC_SIZE((1,2)) -void *ruby_xcalloc_body(size_t nelems, size_t elemsiz) -RBIMPL_ATTR_NOEXCEPT(calloc(nelems, elemsiz)) -; - -RBIMPL_ATTR_NODISCARD() -RBIMPL_ATTR_RETURNS_NONNULL() -RBIMPL_ATTR_ALLOC_SIZE((2)) -void *ruby_xrealloc_body(void *ptr, size_t newsiz) -RBIMPL_ATTR_NOEXCEPT(realloc(ptr, newsiz)) -; - -RBIMPL_ATTR_NODISCARD() -RBIMPL_ATTR_RETURNS_NONNULL() -RBIMPL_ATTR_ALLOC_SIZE((2,3)) -void *ruby_xrealloc2_body(void *ptr, size_t newelems, size_t newsiz) -RBIMPL_ATTR_NOEXCEPT(realloc(ptr, newelems * newsiz)) -; - -RUBY_EXTERN const char *ruby_malloc_info_file; -RUBY_EXTERN int ruby_malloc_info_line; - -static inline void * -ruby_xmalloc_with_location(size_t s, const char *file, int line) -{ - void *ptr; - ruby_malloc_info_file = file; - ruby_malloc_info_line = line; - ptr = ruby_xmalloc_body(s); - ruby_malloc_info_file = NULL; - return ptr; -} - -static inline void * -ruby_xmalloc2_with_location(size_t s1, size_t s2, const char *file, int line) -{ - void *ptr; - ruby_malloc_info_file = file; - ruby_malloc_info_line = line; - ptr = ruby_xmalloc2_body(s1, s2); - ruby_malloc_info_file = NULL; - return ptr; -} - -static inline void * -ruby_xcalloc_with_location(size_t s1, size_t s2, const char *file, int line) -{ - void *ptr; - ruby_malloc_info_file = file; - ruby_malloc_info_line = line; - ptr = ruby_xcalloc_body(s1, s2); - ruby_malloc_info_file = NULL; - return ptr; -} - -static inline void * -ruby_xrealloc_with_location(void *ptr, size_t s, const char *file, int line) -{ - void *rptr; - ruby_malloc_info_file = file; - ruby_malloc_info_line = line; - rptr = ruby_xrealloc_body(ptr, s); - ruby_malloc_info_file = NULL; - return rptr; -} - -static inline void * -ruby_xrealloc2_with_location(void *ptr, size_t s1, size_t s2, const char *file, int line) -{ - void *rptr; - ruby_malloc_info_file = file; - ruby_malloc_info_line = line; - rptr = ruby_xrealloc2_body(ptr, s1, s2); - ruby_malloc_info_file = NULL; - return rptr; -} -#endif - RBIMPL_SYMBOL_EXPORT_END() #endif /* RBIMPL_XMALLOC_H */ diff --git a/include/ruby/io.h b/include/ruby/io.h index dfef85bbe3..ed0967abad 100644 --- a/include/ruby/io.h +++ b/include/ruby/io.h @@ -20,6 +20,8 @@ #endif #include <errno.h> + +/** @cond INTERNAL_MACRO */ #if defined(HAVE_POLL) # ifdef _AIX # define reqevents events @@ -33,153 +35,1095 @@ # undef revents # endif # define RB_WAITFD_IN POLLIN -# define RB_WAITFD_PRI POLLPRI +# if defined(POLLPRI) +# define RB_WAITFD_PRI POLLPRI +# else +# define RB_WAITFD_PRI 0 +# endif # define RB_WAITFD_OUT POLLOUT #else # define RB_WAITFD_IN 0x001 # define RB_WAITFD_PRI 0x002 # define RB_WAITFD_OUT 0x004 #endif +/** @endcond */ -typedef enum { - RUBY_IO_READABLE = RB_WAITFD_IN, - RUBY_IO_WRITABLE = RB_WAITFD_OUT, - RUBY_IO_PRIORITY = RB_WAITFD_PRI, -} rb_io_event_t; - +#include "ruby/internal/attr/const.h" +#include "ruby/internal/attr/packed_struct.h" +#include "ruby/internal/attr/pure.h" +#include "ruby/internal/attr/noreturn.h" #include "ruby/internal/dllexport.h" +#include "ruby/internal/value.h" + +// IO#wait, IO#wait_readable, IO#wait_writable, IO#wait_priority are defined by this implementation. +#define RUBY_IO_WAIT_METHODS + +// Used as the default timeout argument to `rb_io_wait` to use the `IO#timeout` value. +#define RUBY_IO_TIMEOUT_DEFAULT Qnil + RBIMPL_SYMBOL_EXPORT_BEGIN() -PACKED_STRUCT_UNALIGNED(struct rb_io_buffer_t { - char *ptr; /* off + len <= capa */ - int off; - int len; - int capa; -}); -typedef struct rb_io_buffer_t rb_io_buffer_t; +struct stat; +struct timeval; -typedef struct rb_io_t { - VALUE self; +#if defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC) +# define RUBY_USE_STATX 0 +#elif defined(HAVE_STRUCT_STATX_STX_BTIME) +# define RUBY_USE_STATX 1 +struct statx; +#else +# define RUBY_USE_STATX 0 +#endif - FILE *stdio_file; /* stdio ptr for read/write if available */ - int fd; /* file descriptor */ - int mode; /* mode flags: FMODE_XXXs */ - rb_pid_t pid; /* child's pid (for pipes) */ - int lineno; /* number of lines read */ - VALUE pathv; /* pathname for file */ - void (*finalize)(struct rb_io_t*,int); /* finalize proc */ +#if RUBY_USE_STATX +typedef struct statx rb_io_stat_data; +#else +typedef struct stat rb_io_stat_data; +#endif - rb_io_buffer_t wbuf, rbuf; +/** + * Indicates that a timeout has occurred while performing an IO operation. + */ +RUBY_EXTERN VALUE rb_eIOTimeoutError; - VALUE tied_io_for_writing; +/** + * Type of events that an IO can wait. + * + * @internal + * + * This is visible from extension libraries because `io/wait` wants it. + */ +enum rb_io_event { + RUBY_IO_READABLE = RB_WAITFD_IN, /**< `IO::READABLE` */ + RUBY_IO_WRITABLE = RB_WAITFD_OUT, /**< `IO::WRITABLE` */ + RUBY_IO_PRIORITY = RB_WAITFD_PRI, /**< `IO::PRIORITY` */ +}; - /* - * enc enc2 read action write action - * NULL NULL force_encoding(default_external) write the byte sequence of str - * e1 NULL force_encoding(e1) convert str.encoding to e1 - * e1 e2 convert from e2 to e1 convert str.encoding to e2 - */ - struct rb_io_enc_t { - rb_encoding *enc; - rb_encoding *enc2; - int ecflags; - VALUE ecopts; - } encs; +typedef enum rb_io_event rb_io_event_t; - rb_econv_t *readconv; - rb_io_buffer_t cbuf; +/** + * IO buffers. This is an implementation detail of ::rb_io_t::wbuf and + * ::rb_io_t::rbuf. People don't manipulate it directly. + */ +RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_BEGIN() +struct rb_io_internal_buffer { - rb_econv_t *writeconv; - VALUE writeconv_asciicompat; - int writeconv_initialized; - int writeconv_pre_ecflags; - VALUE writeconv_pre_ecopts; + /** Pointer to the underlying memory region, of at least `capa` bytes. */ + char *ptr; /* off + len <= capa */ - VALUE write_lock; -} rb_io_t; + /** Offset inside of `ptr`. */ + int off; -typedef struct rb_io_enc_t rb_io_enc_t; + /** Length of the buffer. */ + int len; -#define HAVE_RB_IO_T 1 + /** Designed capacity of the buffer. */ + int capa; +} RBIMPL_ATTR_PACKED_STRUCT_UNALIGNED_END(); + +/** @alias{rb_io_buffer_t} */ +typedef struct rb_io_internal_buffer rb_io_buffer_t; + +/** Decomposed encoding flags (e.g. `"enc:enc2""`). */ +/* + * enc enc2 read action write action + * NULL NULL force_encoding(default_external) write the byte sequence of str + * e1 NULL force_encoding(e1) convert str.encoding to e1 + * e1 e2 convert from e2 to e1 convert str.encoding to e2 + */ +struct rb_io_encoding { + /** Internal encoding. */ + rb_encoding *enc; + /** External encoding. */ + rb_encoding *enc2; + /** + * Flags. + * + * @see enum ::ruby_econv_flag_type + */ + int ecflags; + /** + * Flags as Ruby hash. + * + * @internal + * + * This is set. But used from nowhere maybe? + */ + VALUE ecopts; +}; + +/** + * @name Possible flags for ::rb_io_t::mode + * + * @{ + */ +/** The IO is opened for reading. */ #define FMODE_READABLE 0x00000001 + +/** The IO is opened for writing. */ #define FMODE_WRITABLE 0x00000002 + +/** The IO is opened for both read/write. */ #define FMODE_READWRITE (FMODE_READABLE|FMODE_WRITABLE) + +/** + * The IO is in "binary mode". This is not what everything rb_io_binmode() + * concerns. This low-level flag is to stop CR <-> CRLF conversions that would + * happen in the underlying operating system. + * + * Setting this one and #FMODE_TEXTMODE at the same time is a contradiction. + * Setting this one and #ECONV_NEWLINE_DECORATOR_MASK at the same time is also + * a contradiction. + */ #define FMODE_BINMODE 0x00000004 + +/** + * The IO is in "sync mode". All output is immediately flushed to the + * underlying operating system then. Can be set via rb_io_synchronized(), but + * there is no way except calling `IO#sync=` to reset. + */ #define FMODE_SYNC 0x00000008 + +/** + * The IO is a TTY. What is a TTY and what isn't depends on the underlying + * operating system's `isatty(3)` output. You cannot change this. + */ #define FMODE_TTY 0x00000010 + +/** + * Ruby eventually detects that the IO is bidirectional. For instance a TTY + * has such property. There are several other things known to be duplexed. + * Additionally you (extension library authors) can also implement your own + * bidirectional IO subclasses. One of such example is `Socket`. + */ #define FMODE_DUPLEX 0x00000020 + +/** + * The IO is opened for appending. This mode always writes at the end of the + * IO. Ruby manages this flag for record but basically the logic behind this + * mode is at the underlying operating system. We almost do nothing. + */ #define FMODE_APPEND 0x00000040 + +/** + * The IO is opened for creating. This makes sense only when the destination + * file does not exist at the time the IO object was created. This is the + * default mode for writing, but you can pass `"r+"` to `IO.open` etc., to + * reroute this creation. + */ #define FMODE_CREATE 0x00000080 /* #define FMODE_NOREVLOOKUP 0x00000100 */ + +/** + * This flag amends the effect of #FMODE_CREATE, so that if there already is a + * file at the given path the operation fails. Using this you can be sure that + * the file you get is a fresh new one. + */ #define FMODE_EXCL 0x00000400 + +/** + * This flag amends the effect of #FMODE_CREATE, so that if there already is a + * file at the given path it gets truncated. + */ #define FMODE_TRUNC 0x00000800 + +/** + * The IO is in "text mode". On systems where such mode make sense, this flag + * changes the way the IO handles the contents. On POSIX systems it is + * basically a no-op, but with this flag set you can optionally let Ruby + * manually convert newlines, unlike when in binary mode: + * + * ```ruby + * IO.open("/p/a/t/h", "wt", crlf_newline: true) # "wb" is NG. + * ``` + * + * Setting this one and #FMODE_BINMODE at the same time is a contradiction. + */ #define FMODE_TEXTMODE 0x00001000 -/* #define FMODE_PREP 0x00010000 */ +/** + * This flag means that an IO object is wrapping an "external" file descriptor, + * which is owned by something outside the Ruby interpreter (usually a C extension). + * Ruby will not close this file when the IO object is garbage collected. + * If this flag is set, then IO#autoclose? is false, and vice-versa. + * + * This flag was previously called FMODE_PREP internally. + */ +#define FMODE_EXTERNAL 0x00010000 + +/* #define FMODE_SIGNAL_ON_EPIPE 0x00020000 */ + +/** + * This flag amends the encoding of the IO so that the BOM of the contents of + * the IO takes effect. + */ #define FMODE_SETENC_BY_BOM 0x00100000 /* #define FMODE_UNIX 0x00200000 */ /* #define FMODE_INET 0x00400000 */ /* #define FMODE_INET6 0x00800000 */ +/** @} */ + +enum rb_io_mode { + RUBY_IO_MODE_EXTERNAL = FMODE_EXTERNAL, + + RUBY_IO_MODE_READABLE = FMODE_READABLE, + RUBY_IO_MODE_WRITABLE = FMODE_WRITABLE, + RUBY_IO_MODE_READABLE_WRITABLE = (RUBY_IO_MODE_READABLE|RUBY_IO_MODE_WRITABLE), + + RUBY_IO_MODE_BINARY = FMODE_BINMODE, + RUBY_IO_MODE_TEXT = FMODE_TEXTMODE, + RUBY_IO_MODE_TEXT_SET_ENCODING_FROM_BOM = FMODE_SETENC_BY_BOM, + + RUBY_IO_MODE_SYNCHRONISED = FMODE_SYNC, + + RUBY_IO_MODE_TTY = FMODE_TTY, + + RUBY_IO_MODE_DUPLEX = FMODE_DUPLEX, + + RUBY_IO_MODE_APPEND = FMODE_APPEND, + RUBY_IO_MODE_CREATE = FMODE_CREATE, + RUBY_IO_MODE_EXCLUSIVE = FMODE_EXCL, + RUBY_IO_MODE_TRUNCATE = FMODE_TRUNC, +}; + +typedef enum rb_io_mode rb_io_mode_t; + +#ifndef HAVE_RB_IO_T +#define HAVE_RB_IO_T 1 +/** Ruby's IO, metadata and buffers. */ +struct rb_io { + /** The IO's Ruby level counterpart. */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + VALUE self; + + /** stdio ptr for read/write, if available. */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + FILE *stdio_file; + + /** file descriptor. */ + RBIMPL_ATTR_DEPRECATED(("rb_io_descriptor")) + int fd; + + /** mode flags: FMODE_XXXs */ + RBIMPL_ATTR_DEPRECATED(("rb_io_mode")) + enum rb_io_mode mode; + + /** child's pid (for pipes) */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + rb_pid_t pid; + + /** number of lines read */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + int lineno; + + /** pathname for file */ + RBIMPL_ATTR_DEPRECATED(("rb_io_path")) + VALUE pathv; + + /** finalize proc */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + void (*finalize)(struct rb_io*,int); + + /** Write buffer. */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + rb_io_buffer_t wbuf; + + /** + * (Byte) read buffer. Note also that there is a field called + * ::rb_io_t::cbuf, which also concerns read IO. + */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + rb_io_buffer_t rbuf; + + /** + * Duplex IO object, if set. + * + * @see rb_io_set_write_io() + */ + RBIMPL_ATTR_DEPRECATED(("rb_io_get_write_io")) + VALUE tied_io_for_writing; + + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + struct rb_io_encoding encs; /**< Decomposed encoding flags. */ + + /** Encoding converter used when reading from this IO. */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + rb_econv_t *readconv; + + /** + * rb_io_ungetc() destination. This buffer is read before checking + * ::rb_io_t::rbuf + */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + rb_io_buffer_t cbuf; + + /** Encoding converter used when writing to this IO. */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + rb_econv_t *writeconv; + + /** + * This is, when set, an instance of ::rb_cString which holds the "common" + * encoding. Write conversion can convert strings twice... In case + * conversion from encoding X to encoding Y does not exist, Ruby finds an + * encoding Z that bridges the two, so that X to Z to Y conversion happens. + */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + VALUE writeconv_asciicompat; + + /** Whether ::rb_io_t::writeconv is already set up. */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + int writeconv_initialized; + + /** + * Value of ::rb_io_t::rb_io_enc_t::ecflags stored right before + * initialising ::rb_io_t::writeconv. + */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + int writeconv_pre_ecflags; + + /** + * Value of ::rb_io_t::rb_io_enc_t::ecopts stored right before initialising + * ::rb_io_t::writeconv. + */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + VALUE writeconv_pre_ecopts; + + /** + * This is a Ruby level mutex. It avoids multiple threads to write to an + * IO at once; helps for instance rb_io_puts() to ensure newlines right + * next to its arguments. + * + * This of course doesn't help inter-process IO interleaves, though. + */ + RBIMPL_ATTR_DEPRECATED(("with no replacement")) + VALUE write_lock; + + /** + * The timeout associated with this IO when performing blocking operations. + */ + RBIMPL_ATTR_DEPRECATED(("rb_io_timeout/rb_io_set_timeout")) + VALUE timeout; +}; +#endif + +typedef struct rb_io rb_io_t; + +/** @alias{rb_io_enc_t} */ +typedef struct rb_io_encoding rb_io_enc_t; + +/** + * Allocate a new IO object, with the given file descriptor. + */ +VALUE rb_io_open_descriptor(VALUE klass, int descriptor, int mode, VALUE path, VALUE timeout, struct rb_io_encoding *encoding); + +/** + * Returns whether or not the underlying IO is closed. + * + * @return Whether the underlying IO is closed. + */ +VALUE rb_io_closed_p(VALUE io); + +/** + * Queries the underlying IO pointer. + * + * @param[in] obj An IO object. + * @param[out] fp A variable of type ::rb_io_t. + * @exception rb_eFrozenError `obj` is frozen. + * @exception rb_eIOError `obj` is closed. + * @post `fp` holds `obj`'s underlying IO. + */ #define RB_IO_POINTER(obj,fp) rb_io_check_closed((fp) = RFILE(rb_io_taint_check(obj))->fptr) + +/** + * This is an old name of #RB_IO_POINTER. Not sure if we want to deprecate + * this macro. There still are tons of usages out there in the wild. + */ #define GetOpenFile RB_IO_POINTER +/** + * Fills an IO object. This makes the best sense when called from inside of an + * `#initialize` method of a 3rd party extension library that inherits + * ::rb_cIO. + * + * If the passed IO is already opened for something it first closes that and + * opens a new one instead. + * + * @param[out] obj An IO object to fill in. + * @param[out] fp A variable of type ::rb_io_t. + * @exception rb_eTypeError `obj` is not ::RUBY_T_FILE. + * @post `fp` holds `obj`'s underlying IO. + */ #define RB_IO_OPEN(obj, fp) do {\ (fp) = rb_io_make_open_file(obj);\ } while (0) + +/** + * This is an old name of #RB_IO_OPEN. Not sure if we want to deprecate this + * macro. There still are usages out there in the wild. + */ #define MakeOpenFile RB_IO_OPEN +/** + * @private + * + * This is an implementation detail of #RB_IO_OPEN. People don't use it + * directly. + * + * @param[out] obj An IO object to fill in. + * @exception rb_eTypeError `obj` is not ::RUBY_T_FILE. + * @return `obj`'s backend IO. + * @post `obj` is initialised. + */ rb_io_t *rb_io_make_open_file(VALUE obj); +/** + * Finds or creates a stdio's file structure from a Ruby's one. This can be + * handy if you want to call an external API that accepts `FILE *`. + * + * @note Note however, that `FILE`s can have their own buffer. Mixing Ruby's + * and stdio's file are basically dangerous. Use with care. + * + * @param[in,out] fptr Target IO. + * @return A stdio's file, created if absent. + * @post `fptr` has its corresponding stdio's file. + * + * @internal + * + * We had rich support for `FILE` before! In the days of 1.8.x ::rb_io_t was + * like this: + * + * ```CXX + * typedef struct rb_io { + * FILE *f; // stdio ptr for read/write + * FILE *f2; // additional ptr for rw pipes + * int mode; // mode flags + * int pid; // child's pid (for pipes) + * int lineno; // number of lines read + * char *path; // pathname for file + * void (*finalize) _((struct rb_io*,int)); // finalize proc + * } rb_io_t; + *``` + * + * But we eventually abandoned this layout. It was too difficult. We could + * not have fine-grained control over the `f` field. + * + * - `FILE` tends to be an opaque struct. It does not interface well with + * `select(2)` etc. This makes IO multiplexing quite hard. Using stdio, + * there is arguably no portable way to know if `fwrite(3)` blocks. + * + * - Nonblocking mode, which is another core concept that enables IO + * multiplexing, does not interface with stdio routines at all. + * + * - Detection of duplexed IO is also hard for the same reason. + * + * - `feof(3)` is not portable. + * https://mail.python.org/pipermail/python-dev/2001-January/011390.html + * + * - Solaris was a thing back then. They could not have more than 256 `FILE` + * structures at a time. Their file descriptors ware stored in an + * `unsigned char`. + * + * - It is next to impossible to avoid SEGV, especially when a thread tries to + * `ungetc(3)`-ing from a `FILE` which is `fread(3)`-ed by another one. + * + * In short, it is a bad idea to let someone else manage IO buffers, especially + * someone you cannot control. This still applies to extension libraries + * methinks. Ruby doesn't prevent you from shooting yourself in the foot, but + * consider yourself warned here. + */ FILE *rb_io_stdio_file(rb_io_t *fptr); -FILE *rb_fdopen(int, const char*); -int rb_io_modestr_fmode(const char *modestr); +/** + * Identical to rb_io_stdio_file(), except it takes file descriptors instead of + * Ruby's IO. It can also be seen as a compatibility layer to wrap + * `fdopen(3)`. Nowadays all supporting systems, including Windows, have + * `fdopen`. Why not use them. + * + * @param[in] fd A file descriptor. + * @param[in] modestr C string, something like `"r+"`. + * @exception rb_eSystemCallError `fdopen` failed for some reason. + * @return A stdio's file associated with `fd`. + * @note Interpretation of `modestr` depends on the underlying operating + * system. On glibc you might be able to pass e.g. `"rm"`, but + * that's an extension to POSIX. + */ +FILE *rb_fdopen(int fd, const char *modestr); + +/** + * Maps a file mode string (that rb_file_open() takes) into a mixture of + * `FMODE_` flags. This for instance returns + * `FMODE_WRITABLE | FMODE_TRUNC | FMODE_CREATE | FMODE_EXCL` for `"wx"`. + * + * @note You cannot pass this return value to OS provided `open(2)` etc. + * + * @param[in] modestr File mode, in C's string. + * @exception rb_eArgError `modestr` is broken. + * @return A set of flags. + * + * @internal + * + * rb_io_modestr_fmode() is not a pure function because it raises. + */ +enum rb_io_mode rb_io_modestr_fmode(const char *modestr); + +/** + * Identical to rb_io_modestr_fmode(), except it returns a mixture of `O_` + * flags. This for instance returns `O_WRONLY | O_TRUNC | O_CREAT | O_EXCL` for + * `"wx"`. + * + * @param[in] modestr File mode, in C's string. + * @exception rb_eArgError `modestr` is broken. + * @return A set of flags. + * + * @internal + * + * rb_io_modestr_oflags() is not a pure function because it raises. + */ int rb_io_modestr_oflags(const char *modestr); -CONSTFUNC(int rb_io_oflags_fmode(int oflags)); -void rb_io_check_writable(rb_io_t*); -void rb_io_check_readable(rb_io_t*); + +RBIMPL_ATTR_CONST() +/** + * Converts an oflags (that rb_io_modestr_oflags() returns) to a fmode (that + * rb_io_mode_flags() returns). This is a purely functional operation. + * + * @param[in] oflags A set of `O_` flags. + * @return Corresponding set of `FMODE_` flags. + */ +int rb_io_oflags_fmode(int oflags); + +/** + * Asserts that an IO is opened for writing. + * + * @param[in] fptr An IO you want to write to. + * @exception rb_eIOError `fptr` is not for writing. + * @post Upon successful return `fptr` is ready for writing. + * + * @internal + * + * The parameter must have been `const rb_io_t *`. + */ +void rb_io_check_writable(rb_io_t *fptr); + +/** @alias{rb_io_check_byte_readable} */ +void rb_io_check_readable(rb_io_t *fptr); + +/** + * Asserts that an IO is opened for character-based reading. A character can + * be wider than a byte. Because of this we have to buffer reads from + * descriptors. This fiction checks if that is possible. + * + * @param[in] fptr An IO you want to read characters from. + * @exception rb_eIOError `fptr` is not for reading. + * @post Upon successful return `fptr` is ready for reading characters. + * + * @internal + * + * Unlike rb_io_check_writable() the parameter cannot be `const rb_io_t *`. + * Behind the scene this operation flushes its write buffers. This is because + * of OpenSSL. They mandate this way. + * + * @see "Can I use OpenSSL's SSL library with non-blocking I/O?" + * https://www.openssl.org/docs/faq.html + */ void rb_io_check_char_readable(rb_io_t *fptr); + +/** + * Asserts that an IO is opened for byte-based reading. Byte-based and + * character-based reading operations cannot be mixed at a time. + * + * @param[in] fptr An IO you want to read characters from. + * @exception rb_eIOError `fptr` is not for reading. + * @post Upon successful return `fptr` is ready for reading bytes. + */ void rb_io_check_byte_readable(rb_io_t *fptr); -int rb_io_fptr_finalize(rb_io_t*); -void rb_io_synchronized(rb_io_t*); -void rb_io_check_initialized(rb_io_t*); -void rb_io_check_closed(rb_io_t*); + +/** + * Destroys the given IO. Any pending operations are flushed. + * + * @note It makes no sense to call this function from anywhere outside of your + * class' ::rb_data_type_struct::dfree. + * + * @param[out] fptr IO to close. + * @post `fptr` is no longer a valid pointer. + */ +int rb_io_fptr_finalize(rb_io_t *fptr); + +/** + * Sets #FMODE_SYNC. + * + * @note There is no way for C extensions to undo this operation. + * + * @param[out] fptr IO to set the flag. + * @exception rb_eIOError `fptr` is not opened. + * @post `fptr` is in sync mode. + */ +void rb_io_synchronized(rb_io_t *fptr); + +/** + * Asserts that the passed IO is initialised. + * + * @param[in] fptr IO that you expect be initialised. + * @exception rb_eIOError `fptr` is not initialised. + * @post `fptr` is initialised. + */ +void rb_io_check_initialized(rb_io_t *fptr); + +/** + * This badly named function asserts that the passed IO is _open_. + * + * @param[in] fptr An IO + * @exception rb_eIOError `fptr` is closed. + * @post `fptr` is open. + */ +void rb_io_check_closed(rb_io_t *fptr); + +/** + * Identical to rb_io_check_io(), except it raises exceptions on conversion + * failures. + * + * @param[in] io Target object. + * @exception rb_eTypeError No implicit conversion to IO. + * @return Return value of `obj.to_io`. + * @see rb_str_to_str + * @see rb_ary_to_ary + */ VALUE rb_io_get_io(VALUE io); + +/** + * Try converting an object to its IO representation using its `to_io` method, + * if any. If there is no such thing, returns ::RUBY_Qnil. + * + * @param[in] io Arbitrary ruby object to convert. + * @exception rb_eTypeError `obj.to_io` returned something non-IO. + * @retval RUBY_Qnil No conversion from `obj` to IO defined. + * @retval otherwise Converted IO representation of `obj`. + * @see rb_check_array_type + * @see rb_check_string_type + * @see rb_check_hash_type + */ VALUE rb_io_check_io(VALUE io); + +/** + * Queries the tied IO for writing. An IO can be duplexed. Fine. The thing + * is, that characteristics could sometimes be achieved by the underlying + * operating system (for instance a socket's duplexity is by nature) but + * sometimes by us. Notable example is a bidirectional pipe. Suppose you + * have: + * + * ```ruby + * fp = IO.popen("-", "r+") + * ``` + * + * This pipe is duplexed (the `"r+"`). You can both read from/write to it. + * However your operating system may or may not implement bidirectional pipes. + * FreeBSD is one of such operating systems known to have one; OTOH Linux is + * known to lack such things. So to achieve maximum portability, Ruby's + * bidirectional pipes are done purely in user land. A pipe in ruby can have + * multiple file descriptors; one for reading and the other for writing. This + * API is to obtain the IO port which corresponds to the passed one, for + * writing. + * + * @param[in] io An IO. + * @return Its tied IO for writing, if any, or `io` itself otherwise. + */ VALUE rb_io_get_write_io(VALUE io); + +/** + * Assigns the tied IO for writing. See rb_io_get_write_io() for what a "tied + * IO for writing" is. + * + * @param[out] io An IO. + * @param[in] w Another IO. + * @retval RUBY_Qnil There was no tied IO for writing for `io`. + * @retval otherwise The IO formerly tied to `io`. + * @post `io` ties `w` for writing. + * + * @internal + * + * @shyouhei doesn't think there is any needs of this function for 3rd party + * extension libraries. + */ VALUE rb_io_set_write_io(VALUE io, VALUE w); + +/** + * Instructs the OS to put its internal file structure into "nonblocking mode". + * This is an in-Kernel concept. Reading from/writing to that file using C + * function calls would return -1 with errno set. However when it comes to a + * ruby program, we hide that error behind our `IO#read` method. Ruby level + * `IO#read` blocks regardless of this flag. If you want to avoid blocking, + * you should consider using methods like `IO#readpartial`. + * + * ```ruby + * require 'io/nonblock' + * STDIN.nonblock = true + * STDIN.gets # blocks. + * ``` + * + * As of writing there is a room of this API in Fiber schedulers. A Fiber + * scheduler could be written in a way its behaviour depends on this property. + * You need an in-depth understanding of how schedulers work to properly + * leverage this, though. + * + * @note Note however that nonblocking-ness propagates across process + * boundaries. You must really carefully watch your step when turning + * for instance `stderr` into nonblock mode (it tends to be shared + * across many processes). Also it is a complete disaster to mix a + * nonblocking file and stdio, and `stderr` tends to be under control of + * stdio in other processes. + * + * @param[out] fptr An IO that is to ne nonblocking. + * @post Descriptor that `fptr` describes is under nonblocking mode. + * + * @internal + * + * There is `O_NONBLOCK` but not `FMODE_NONBLOCK`. You cannot atomically + * create a nonblocking file descriptor using our API. + */ void rb_io_set_nonblock(rb_io_t *fptr); -int rb_io_extract_encoding_option(VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, int *fmode_p); -void rb_io_extract_modeenc(VALUE *vmode_p, VALUE *vperm_p, VALUE opthash, int *oflags_p, int *fmode_p, rb_io_enc_t *convconfig_p); + +/** + * Returns the path for the given IO. + * + */ +VALUE rb_io_path(VALUE io); + +/** + * Returns an integer representing the numeric file descriptor for + * <em>io</em>. + * + * @param[in] io An IO. + * @retval int A file descriptor. + */ +int rb_io_descriptor(VALUE io); + +/** + * Get the mode of the IO. + * + */ +int rb_io_mode(VALUE io); + +/** + * This function breaks down the option hash that `IO#initialize` takes into + * components. This is an implementation detail of rb_io_extract_modeenc() + * today. People prefer that API instead. + * + * @param[in] opt The hash to decompose. + * @param[out] enc_p Return value buffer. + * @param[out] enc2_p Return value buffer. + * @param[out] fmode_p Return value buffer. + * @exception rb_eTypeError `opt` is broken. + * @exception rb_eArgError Specified encoding does not exist. + * @retval 1 Components got extracted. + * @retval 0 Otherwise. + * @post `enc_p` is the specified internal encoding. + * @post `enc2_p` is the specified external encoding. + * @post `fmode_p` is the specified set of `FMODE_` modes. + */ +int rb_io_extract_encoding_option(VALUE opt, rb_encoding **enc_p, rb_encoding **enc2_p, enum rb_io_mode *fmode_p); + +/** + * This function can be seen as an extended version of + * rb_io_extract_encoding_option() that not only concerns the option hash but + * also mode string and so on. This should be mixed with rb_scan_args() like: + * + * ```CXX + * // This method mimics File.new + * static VALUE + * your_method(int argc, const VALUE *argv, VALUE self) + * { + * VALUE f; // file name + * VALUE m; // open mode + * VALUE p; // permission (O_CREAT) + * VALUE k; // keywords + * rb_io_enc_t c; // converter + * int oflags; + * int fmode; + * + * int n = rb_scan_args(argc, argv, "12:", &f, &m, &p, &k); + * rb_io_extract_modeenc(&m, &p, k, &oflags, &fmode, &c); + * + * // Every local variables declared so far has been properly filled here. + * ... + * } + * ``` + * + * @param[in,out] vmode_p Pointer to a mode object. + * @param[in,out] vperm_p Pointer to a permission object. + * @param[in] opthash Keyword arguments + * @param[out] oflags_p `O_` flags return buffer. + * @param[out] fmode_p `FMODE_` flags return buffer. + * @param[out] convconfig_p Encoding config return buffer. + * @exception rb_eTypeError Unexpected object (e.g. Time) passed. + * @exception rb_eArgError Contradiction inside of params. + * @post `*vmode_p` is a mode object (filled if any). + * @post `*vperm_p` is a permission object (filled if any). + * @post `*oflags_p` is filled with `O_` flags. + * @post `*fmode_p` is filled with `FMODE_` flags. + * @post `*convconfig_p` is filled with conversion instructions. + * + * @internal + * + * ```rbs + * class File + * def initialize: ( + * (String | int) path, + * ?(String | int) fmode, + * ?(String | int) perm, + * ?mode: (String | int), + * ?flags: int, + * ?external_encoding: (Encoding | String), + * ?internal_encoding: (Encoding | String), + * ?encoding: String, + * ?textmode: bool, + * ?binmode: bool, + * ?autoclose: bool, + * ?invalid: :replace, + * ?undef: :replace, + * ?replace: String, + * ?fallback: (Hash | Proc | Method), + * ?xml: (:text | :attr), + * ?crlf_newline: bool, + * ?cr_newline: bool, + * ?universal_newline: bool + * ) -> void + * ``` + */ +void rb_io_extract_modeenc(VALUE *vmode_p, VALUE *vperm_p, VALUE opthash, int *oflags_p, enum rb_io_mode *fmode_p, rb_io_enc_t *convconfig_p); + +/* :TODO: can this function be __attribute__((warn_unused_result)) or not? */ +/** + * Buffered write to the passed IO. + * + * @param[out] io Destination IO. + * @param[in] buf Contents to go to `io`. + * @param[in] size Number of bytes of `buf`. + * @exception rb_eFrozenError `io` is frozen. + * @exception rb_eIOError `io` is not open for writing. + * @exception rb_eSystemCallError `writev(2)` failed for some reason. + * @retval -1 Write failed. + * @retval otherwise Number of bytes actually written. + * @post `buf` is written to `io`. + * @note Partial write is a thing. It is a failure not to check the + * return value. + */ ssize_t rb_io_bufwrite(VALUE io, const void *buf, size_t size); //RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_readable")) +/** + * Blocks until the passed file descriptor gets readable. + * + * @deprecated We now prefer rb_io_maybe_wait_readable() over this one. + * @param[in] fd The file descriptor to wait. + * @exception rb_eIOError Bad file descriptor. + * @return 0 or 1 (meaning unclear). + * @post `fd` is ready for reading. + */ int rb_io_wait_readable(int fd); //RBIMPL_ATTR_DEPRECATED(("use rb_io_maybe_wait_writable")) +/** + * Blocks until the passed file descriptor gets writable. + * + * @deprecated We now prefer rb_io_maybe_wait_writable() over this one. + * @param[in] fd The file descriptor to wait. + * @exception rb_eIOError Bad file descriptor. + * @return 0 or 1 (meaning unclear). + */ int rb_io_wait_writable(int fd); //RBIMPL_ATTR_DEPRECATED(("use rb_io_wait")) +/** + * Blocks until the passed file descriptor is ready for the passed events. + * + * @deprecated We now prefer rb_io_maybe_wait() over this one. + * @param[in] fd The file descriptor to wait. + * @param[in] events A set of enum ::rb_io_event_t. + * @param[in,out] tv Timeout. + * @retval 0 Operation timed out. + * @retval -1 `select(2)` failed for some reason. + * @retval otherwise A set of enum ::rb_io_event_t. + * @note Depending on your operating system `tv` might or might not + * be updated (POSIX permits both). Portable programs must + * have no assumptions. + */ int rb_wait_for_single_fd(int fd, int events, struct timeval *tv); +/** + * Get the timeout associated with the specified io object. + * + * @param[in] io An IO object. + * @retval RUBY_Qnil There is no associated timeout. + * @retval Otherwise The timeout value. + */ +VALUE rb_io_timeout(VALUE io); + +/** + * Set the timeout associated with the specified io object. This timeout is + * used as a best effort timeout to prevent operations from blocking forever. + * + * @param[in] io An IO object. + * @param[in] timeout A timeout value. Must respond to #to_f. + * @ + */ +VALUE rb_io_set_timeout(VALUE io, VALUE timeout); + +/** + * Blocks until the passed IO is ready for the passed events. The "events" + * here is a Ruby level integer, which is an OR-ed value of `IO::READABLE`, + * `IO::WRITable`, and `IO::PRIORITY`. + * + * If timeout is `Qnil`, it will use the default timeout as given by + * `rb_io_timeout(io)`. + * + * @param[in] io An IO object to wait. + * @param[in] events See above. + * @param[in] timeout Time, or numeric seconds since UNIX epoch. + * If Qnil, use the default timeout. If Qfalse + * or Qundef, wait forever. + * @exception rb_eIOError `io` is not open. + * @exception rb_eRangeError `timeout` is out of range. + * @exception rb_eSystemCallError `select(2)` failed for some reason. + * @retval RUBY_Qfalse Operation timed out. + * @retval Otherwise Actual events reached. + */ VALUE rb_io_wait(VALUE io, VALUE events, VALUE timeout); + +/** + * Identical to rb_io_wait() except it additionally takes previous errno. If + * the passed errno indicates for instance `EINTR`, this function returns + * immediately. This is expected to be called in a loop. + * + * ```CXX + * while (true) { + * + * ... // Your interesting operation here + * // `errno` could be updated + * + * rb_io_maybe_wait(errno, io, ev, Qnil); + * } + * ``` + * + * On timeout, ::RUBY_Qfalse is returned. Unless you are specifically handling + * the timeouts, you should typically raise ::rb_eIOTimeoutError in this case. + * + * @param[in] error System errno. + * @param[in] io An IO object to wait. + * @param[in] events An integer set of interests. + * @param[in] timeout Time, or numeric seconds since UNIX epoch. + * @exception rb_eIOError `io` is not open. + * @exception rb_eRangeError `timeout` is out of range. + * @exception rb_eSystemCallError `select(2)` failed for some reason. + * @retval RUBY_Qfalse Operation timed out. + * @retval RUBY_Qnil Operation failed for some other reason (errno). + * @retval Otherwise Actual events reached. + * + */ VALUE rb_io_maybe_wait(int error, VALUE io, VALUE events, VALUE timeout); + +/** + * Blocks until the passed IO is ready for reading, if that makes sense for the + * passed errno. This is a special case of rb_io_maybe_wait() that is + * only concerned with reading and handles the timeout. + * + * If you do not want the default timeout handling, consider using + * ::rb_io_maybe_wait directly. + * + * @param[in] error System errno. + * @param[in] io An IO object to wait. + * @param[in] timeout Time, or numeric seconds since UNIX epoch. + * @exception rb_eIOError `io` is not open. + * @exception rb_eRangeError `timeout` is out of range. + * @exception rb_eSystemCallError `select(2)` failed for some reason. + * @exception rb_eIOTimeoutError The wait operation timed out. + * @retval Otherwise Always returns ::RUBY_IO_READABLE. + */ int rb_io_maybe_wait_readable(int error, VALUE io, VALUE timeout); + +/** + * Blocks until the passed IO is ready for writing, if that makes sense for the + * passed errno. This is a special case of rb_io_maybe_wait() that is + * only concerned with writing, and handles the timeout. + * + * If you do not want the default timeout handling, consider using + * ::rb_io_maybe_wait directly. + * + * @param[in] error System errno. + * @param[in] io An IO object to wait. + * @param[in] timeout Time, or numeric seconds since UNIX epoch. + * @exception rb_eIOError `io` is not open. + * @exception rb_eRangeError `timeout` is out of range. + * @exception rb_eSystemCallError `select(2)` failed for some reason. + * @exception rb_eIOTimeoutError The wait operation timed out. + * @retval Otherwise Always returns ::RUBY_IO_WRITABLE. + */ int rb_io_maybe_wait_writable(int error, VALUE io, VALUE timeout); +/** @cond INTERNAL_MACRO */ /* compatibility for ruby 1.8 and older */ #define rb_io_mode_flags(modestr) [<"rb_io_mode_flags() is obsolete; use rb_io_modestr_fmode()">] #define rb_io_modenum_flags(oflags) [<"rb_io_modenum_flags() is obsolete; use rb_io_oflags_fmode()">] +/** @endcond */ + +/** + * @deprecated This function once was a thing in the old days, but makes no + * sense any longer today. Exists here for backwards + * compatibility only. You can safely forget about it. + * + * @param[in] obj Object in question. + * @exception rb_eFrozenError obj is frozen. + * @return The passed `obj` + */ +VALUE rb_io_taint_check(VALUE obj); -VALUE rb_io_taint_check(VALUE); -NORETURN(void rb_eof_error(void)); +RBIMPL_ATTR_NORETURN() +/** + * Utility function to raise ::rb_eEOFError. + * + * @exception rb_eEOFError End of file situation. + * @note It never returns. + */ +void rb_eof_error(void); -void rb_io_read_check(rb_io_t*); -int rb_io_read_pending(rb_io_t*); +/** + * Blocks until there is a pending read in the passed IO. If there already is + * it just returns. + * + * @param[out] fptr An IO to wait for reading. + * @post The are bytes to be read. + */ +void rb_io_read_check(rb_io_t *fptr); -struct stat; -VALUE rb_stat_new(const struct stat *); +RBIMPL_ATTR_PURE() +/** + * Queries if the passed IO has any pending reads. Unlike rb_io_read_check() + * this doesn't block; has no side effects. + * + * @param[in] fptr An IO which can have pending reads. + * @retval 0 The IO is empty. + * @retval 1 There is something buffered. + */ +int rb_io_read_pending(rb_io_t *fptr); + +/** + * Constructs an instance of ::rb_cStat from the passed information. + * + * @param[in] st A stat. + * @return Allocated new instance of ::rb_cStat. + */ +VALUE rb_stat_new(const struct stat *st); + +#if RUBY_USE_STATX +/** + * Constructs an instance of ::rb_cStat from the passed information. + * + * @param[in] st A stat. + * @return Allocated new instance of ::rb_cStat. + */ +VALUE rb_statx_new(const rb_io_stat_data *st); +#else +# define rb_statx_new rb_stat_new +#endif /* gc.c */ diff --git a/include/ruby/io/buffer.h b/include/ruby/io/buffer.h new file mode 100644 index 0000000000..e4d98bf051 --- /dev/null +++ b/include/ruby/io/buffer.h @@ -0,0 +1,110 @@ +#ifndef RUBY_IO_BUFFER_H +#define RUBY_IO_BUFFER_H +/** + * @file + * @author Samuel Williams + * @date Fri 2 Jul 2021 16:29:01 NZST + * @copyright Copyright (C) 2021 Samuel Williams + * @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. + */ + +#pragma once + +#include "ruby/ruby.h" +#include "ruby/internal/config.h" + +RBIMPL_SYMBOL_EXPORT_BEGIN() + +// WARNING: This entire interface is experimental and may change in the future! +#define RB_IO_BUFFER_EXPERIMENTAL 1 + +#define RUBY_IO_BUFFER_VERSION 2 + +// The `IO::Buffer` class. +RUBY_EXTERN VALUE rb_cIOBuffer; + +// The operating system page size. +RUBY_EXTERN size_t RUBY_IO_BUFFER_PAGE_SIZE; + +// The default buffer size, usually a (small) multiple of the page size. +// Can be overridden by the RUBY_IO_BUFFER_DEFAULT_SIZE environment variable. +RUBY_EXTERN size_t RUBY_IO_BUFFER_DEFAULT_SIZE; + +// Represents the internal state of the buffer. +// More than one flag can be set at a time. +enum rb_io_buffer_flags { + // The memory in the buffer is owned by someone else. + // More specifically, it means that someone else owns the buffer and we shouldn't try to resize it. + RB_IO_BUFFER_EXTERNAL = 1, + // The memory in the buffer is allocated internally. + RB_IO_BUFFER_INTERNAL = 2, + // The memory in the buffer is mapped. + // A non-private mapping is marked as external. + RB_IO_BUFFER_MAPPED = 4, + + // A mapped buffer that is also shared. + RB_IO_BUFFER_SHARED = 8, + + // The buffer is locked and cannot be resized. + // More specifically, it means we can't change the base address or size. + // A buffer is typically locked before a system call that uses the data. + RB_IO_BUFFER_LOCKED = 32, + + // The buffer mapping is private and will not impact other processes or the underlying file. + RB_IO_BUFFER_PRIVATE = 64, + + // The buffer is read-only and cannot be modified. + RB_IO_BUFFER_READONLY = 128, + + // The buffer is backed by a file. + RB_IO_BUFFER_FILE = 256, +}; + +// Represents the endian of the data types. +enum rb_io_buffer_endian { + // The least significant units are put first. + RB_IO_BUFFER_LITTLE_ENDIAN = 4, + RB_IO_BUFFER_BIG_ENDIAN = 8, + +#if defined(WORDS_BIGENDIAN) + RB_IO_BUFFER_HOST_ENDIAN = RB_IO_BUFFER_BIG_ENDIAN, +#else + RB_IO_BUFFER_HOST_ENDIAN = RB_IO_BUFFER_LITTLE_ENDIAN, +#endif + + RB_IO_BUFFER_NETWORK_ENDIAN = RB_IO_BUFFER_BIG_ENDIAN +}; + +VALUE rb_io_buffer_new(void *base, size_t size, enum rb_io_buffer_flags flags); +VALUE rb_io_buffer_map(VALUE io, size_t size, rb_off_t offset, enum rb_io_buffer_flags flags); + +VALUE rb_io_buffer_lock(VALUE self); +VALUE rb_io_buffer_unlock(VALUE self); +int rb_io_buffer_try_unlock(VALUE self); + +VALUE rb_io_buffer_free(VALUE self); +VALUE rb_io_buffer_free_locked(VALUE self); + +// Access the internal buffer and flags. Validates the pointers. +// The points may not remain valid if the source buffer is manipulated. +// Consider using rb_io_buffer_lock if needed. +enum rb_io_buffer_flags rb_io_buffer_get_bytes(VALUE self, void **base, size_t *size); +void rb_io_buffer_get_bytes_for_reading(VALUE self, const void **base, size_t *size); +void rb_io_buffer_get_bytes_for_writing(VALUE self, void **base, size_t *size); + +VALUE rb_io_buffer_transfer(VALUE self); +void rb_io_buffer_resize(VALUE self, size_t size); +void rb_io_buffer_clear(VALUE self, uint8_t value, size_t offset, size_t length); + +// The length is the minimum required length. +VALUE rb_io_buffer_read(VALUE self, VALUE io, size_t length, size_t offset); +VALUE rb_io_buffer_pread(VALUE self, VALUE io, rb_off_t from, size_t length, size_t offset); +VALUE rb_io_buffer_write(VALUE self, VALUE io, size_t length, size_t offset); +VALUE rb_io_buffer_pwrite(VALUE self, VALUE io, rb_off_t from, size_t length, size_t offset); + +RBIMPL_SYMBOL_EXPORT_END() + +#endif /* RUBY_IO_BUFFER_H */ diff --git a/include/ruby/memory_view.h b/include/ruby/memory_view.h index a67c1c0045..42309d5afc 100644 --- a/include/ruby/memory_view.h +++ b/include/ruby/memory_view.h @@ -1,4 +1,4 @@ -#ifndef RUBY_MEMORY_VIEW_H +#ifndef RUBY_MEMORY_VIEW_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_MEMORY_VIEW_H 1 /** * @file @@ -10,11 +10,25 @@ * @brief Memory View. */ -#include "ruby/internal/dllexport.h" -#include "ruby/internal/stdbool.h" -#include "ruby/internal/value.h" -#include "ruby/intern.h" +#include "ruby/internal/config.h" +#ifdef STDC_HEADERS +# include <stddef.h> /* size_t */ +#endif + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> /* ssize_t */ +#endif + +#include "ruby/internal/attr/pure.h" /* RBIMPL_ATTR_PURE */ +#include "ruby/internal/core/rtypeddata.h" /* rb_data_type_t */ +#include "ruby/internal/dllexport.h" /* RUBY_EXTERN */ +#include "ruby/internal/stdbool.h" /* bool */ +#include "ruby/internal/value.h" /* VALUE */ + +/** + * Flags passed to rb_memory_view_get(), then to ::rb_memory_view_get_func_t. + */ enum ruby_memory_view_flags { RUBY_MEMORY_VIEW_SIMPLE = 0, RUBY_MEMORY_VIEW_WRITABLE = (1<<0), @@ -27,29 +41,56 @@ enum ruby_memory_view_flags { RUBY_MEMORY_VIEW_INDIRECT = (1<<6) | RUBY_MEMORY_VIEW_STRIDES, }; +/** Memory view component metadata. */ typedef struct { + /** @see ::rb_memory_view_t::format */ char format; - unsigned native_size_p: 1; - unsigned little_endian_p: 1; + + /** :FIXME: what is a "native" size is unclear. */ + bool native_size_p; + + /** Endian of the component */ + bool little_endian_p; + + /** The component's offset. */ size_t offset; + + /** The component's size. */ size_t size; + + /** + * How many numbers of components are there. For instance "CCC"'s repeat is + * 3. + */ size_t repeat; } rb_memory_view_item_component_t; +/** + * A MemoryView structure, `rb_memory_view_t`, is used for exporting objects' + * MemoryView. + * + * This structure contains the reference of the object, which is the owner of + * the MemoryView, the pointer to the head of exported memory, and the metadata + * that describes the structure of the memory. The metadata can describe + * multidimensional arrays with strides. + */ typedef struct { - /* The original object that has the memory exported via this memory view. */ + /** + * The original object that has the memory exported via this memory view. + */ VALUE obj; - /* The pointer to the exported memory. */ + /** The pointer to the exported memory. */ void *data; - /* The number of bytes in data. */ + /** The number of bytes in data. */ ssize_t byte_size; - /* true for readonly memory, false for writable memory. */ + /** true for readonly memory, false for writable memory. */ bool readonly; - /* A string to describe the format of an element, or NULL for unsigned bytes. + /** + * A string to describe the format of an element, or NULL for unsigned bytes. * The format string is a sequence of the following pack-template specifiers: * * c, C, s, s!, S, S!, n, v, i, i!, I, I!, l, l!, L, L!, @@ -69,83 +110,204 @@ typedef struct { */ const char *format; - /* The number of bytes in each element. + /** + * The number of bytes in each element. * item_size should equal to rb_memory_view_item_size_from_format(format). */ ssize_t item_size; + /** Description of each components. */ struct { - /* The array of rb_memory_view_item_component_t that describes the + /** + * The array of rb_memory_view_item_component_t that describes the * item structure. rb_memory_view_prepare_item_desc and * rb_memory_view_get_item allocate this memory if needed, * and rb_memory_view_release frees it. */ const rb_memory_view_item_component_t *components; - /* The number of components in an item. */ + /** The number of components in an item. */ size_t length; } item_desc; - /* The number of dimension. */ + /** The number of dimension. */ ssize_t ndim; - /* ndim size array indicating the number of elements in each dimension. + /** + * ndim size array indicating the number of elements in each dimension. * This can be NULL when ndim == 1. */ const ssize_t *shape; - /* ndim size array indicating the number of bytes to skip to go to the + /** + * ndim size array indicating the number of bytes to skip to go to the * next element in each dimension. */ const ssize_t *strides; - /* The offset in each dimension when this memory view exposes a nested array. + /** + * The offset in each dimension when this memory view exposes a nested array. * Or, NULL when this memory view exposes a flat array. */ const ssize_t *sub_offsets; - /* the private data for managing this exported memory */ + /** The private data for managing this exported memory */ void *private_data; + + /** DO NOT TOUCH THIS: The memory view entry for the internal use */ + const struct rb_memory_view_entry *_memory_view_entry; } rb_memory_view_t; +/** Type of function of ::rb_memory_view_entry_t::get_func. */ typedef bool (* rb_memory_view_get_func_t)(VALUE obj, rb_memory_view_t *view, int flags); + +/** Type of function of ::rb_memory_view_entry_t::release_func. */ typedef bool (* rb_memory_view_release_func_t)(VALUE obj, rb_memory_view_t *view); + +/** Type of function of ::rb_memory_view_entry_t::available_p_func. */ typedef bool (* rb_memory_view_available_p_func_t)(VALUE obj); -typedef struct { +/** Operations applied to a specific kind of a memory view. */ +typedef struct rb_memory_view_entry { + /** + * Exports a memory view from a Ruby object. + */ rb_memory_view_get_func_t get_func; + + /** + * Releases a memory view that was previously generated using + * ::rb_memory_view_entry_t::get_func. + */ rb_memory_view_release_func_t release_func; + + /** + * Queries if an object understands memory view protocol. + */ rb_memory_view_available_p_func_t available_p_func; } rb_memory_view_entry_t; RBIMPL_SYMBOL_EXPORT_BEGIN() /* memory_view.c */ + +/** + * Associates the passed class with the passed memory view entry. This has to + * be called before actually creating a memory view from an instance. + */ bool rb_memory_view_register(VALUE klass, const rb_memory_view_entry_t *entry); RBIMPL_ATTR_PURE() +/** + * Return `true` if the data in the MemoryView `view` is row-major contiguous. + * + * Return `false` otherwise. + */ bool rb_memory_view_is_row_major_contiguous(const rb_memory_view_t *view); + RBIMPL_ATTR_PURE() +/** + * Return `true` if the data in the MemoryView `view` is column-major + * contiguous. + * + * Return `false` otherwise. + */ bool rb_memory_view_is_column_major_contiguous(const rb_memory_view_t *view); + RBIMPL_ATTR_NOALIAS() +/** + * Fill the `strides` array with byte-Strides of a contiguous array of the + * given shape with the given element size. + */ void rb_memory_view_fill_contiguous_strides(const ssize_t ndim, const ssize_t item_size, const ssize_t *const shape, const bool row_major_p, ssize_t *const strides); + RBIMPL_ATTR_NOALIAS() +/** + * Fill the members of `view` as an 1-dimensional byte array. + */ bool rb_memory_view_init_as_byte_array(rb_memory_view_t *view, VALUE obj, void *data, const ssize_t len, const bool readonly); + +/** + * Deconstructs the passed format string, as describe in + * ::rb_memory_view_t::format. + */ ssize_t rb_memory_view_parse_item_format(const char *format, rb_memory_view_item_component_t **members, size_t *n_members, const char **err); + +/** + * Calculate the number of bytes occupied by an element. + * + * When the calculation fails, the failed location in `format` is stored into + * `err`, and returns `-1`. + */ ssize_t rb_memory_view_item_size_from_format(const char *format, const char **err); + +/** + * Calculate the location of the item indicated by the given `indices`. + * + * The length of `indices` must equal to `view->ndim`. + * + * This function initializes `view->item_desc` if needed. + */ void *rb_memory_view_get_item_pointer(rb_memory_view_t *view, const ssize_t *indices); + +/** + * Return a value that consists of item members. + * + * When an item is a single member, the return value is a single value. + * + * When an item consists of multiple members, an array will be returned. + */ VALUE rb_memory_view_extract_item_members(const void *ptr, const rb_memory_view_item_component_t *members, const size_t n_members); + +/** Fill the `item_desc` member of `view`. */ void rb_memory_view_prepare_item_desc(rb_memory_view_t *view); + +/** * Return a value that consists of item members in the given memory view. */ VALUE rb_memory_view_get_item(rb_memory_view_t *view, const ssize_t *indices); +/** + * Return `true` if `obj` supports to export a MemoryView. Return `false` + * otherwise. + * + * If this function returns `true`, it doesn't mean the function + * `rb_memory_view_get` will succeed. + */ bool rb_memory_view_available_p(VALUE obj); + +/** + * If the given `obj` supports to export a MemoryView that conforms the given + * `flags`, this function fills `view` by the information of the MemoryView and + * returns `true`. In this case, the reference count of `obj` is increased. + * + * If the given combination of `obj` and `flags` cannot export a MemoryView, + * this function returns `false`. The content of `view` is not touched in this + * case. + * + * The exported MemoryView must be released by `rb_memory_view_release` when + * the MemoryView is no longer needed. + */ bool rb_memory_view_get(VALUE obj, rb_memory_view_t* memory_view, int flags); + +/** + * Release the given MemoryView `view` and decrement the reference count of + * `memory_view->obj`. + * + * Consumers must call this function when the MemoryView is no longer needed. + * Missing to call this function leads memory leak. + */ bool rb_memory_view_release(rb_memory_view_t* memory_view); /* for testing */ +/** @cond INTERNAL_MACRO */ RUBY_EXTERN VALUE rb_memory_view_exported_object_registry; RUBY_EXTERN const rb_data_type_t rb_memory_view_exported_object_registry_data_type; +/** @endcond */ RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_PURE() +/** + * Return `true` if the data in the MemoryView `view` is row-major or + * column-major contiguous. + * + * Return `false` otherwise. + */ static inline bool rb_memory_view_is_contiguous(const rb_memory_view_t *view) { diff --git a/include/ruby/missing.h b/include/ruby/missing.h index 824d5fe198..aea6c9088d 100644 --- a/include/ruby/missing.h +++ b/include/ruby/missing.h @@ -1,7 +1,6 @@ #ifndef RUBY_MISSING_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_MISSING_H 1 /** - * @file * @author $Author$ * @date Sat May 11 23:46:03 JST 2002 * @copyright This file is a part of the programming language Ruby. @@ -34,11 +33,24 @@ # include <sys/time.h> #endif +#ifdef HAVE_SYS_STAT_H +# include <sys/stat.h> +#endif + +#ifdef HAVE_UNISTD_H +# include <unistd.h> +#endif + +#ifdef HAVE_STDIO_H +# include <stdio.h> +#endif + #ifdef HAVE_IEEEFP_H # include <ieeefp.h> #endif #include "ruby/internal/dllexport.h" +#include "ruby/internal/attr/format.h" #ifndef M_PI # define M_PI 3.14159265358979323846 @@ -212,6 +224,7 @@ RUBY_EXTERN int ruby_close(int); #endif #ifndef HAVE_SETPROCTITLE +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2) RUBY_EXTERN void setproctitle(const char *fmt, ...); #endif @@ -223,6 +236,107 @@ RUBY_EXTERN void setproctitle(const char *fmt, ...); RUBY_EXTERN void explicit_bzero(void *b, size_t len); #endif +#ifndef HAVE_TZSET +RUBY_EXTERN void tzset(void); +#endif + +#ifndef HAVE_POSIX_MADVISE +RUBY_EXTERN int posix_madvise(void *, size_t, int); +#endif + +#ifndef HAVE_GETEUID +RUBY_EXTERN rb_uid_t geteuid(void); +#endif + +#ifndef HAVE_GETUID +RUBY_EXTERN rb_uid_t getuid(void); +#endif + +#ifndef HAVE_GETEGID +RUBY_EXTERN rb_gid_t getegid(void); +#endif + +#ifndef HAVE_GETGID +RUBY_EXTERN rb_gid_t getgid(void); +#endif + +#ifndef HAVE_GETLOGIN +RUBY_EXTERN char *getlogin(void); +#endif + +#ifndef HAVE_GETPPID +RUBY_EXTERN rb_pid_t getppid(void); +#endif + +#ifndef HAVE_UMASK +RUBY_EXTERN rb_mode_t umask(rb_mode_t); +#endif + +#ifndef HAVE_CHMOD +RUBY_EXTERN int chmod(const char *, rb_mode_t); +#endif + +#ifndef HAVE_CHOWN +RUBY_EXTERN int chown(const char *, rb_uid_t, rb_gid_t); +#endif + +#ifndef HAVE_PCLOSE +RUBY_EXTERN int pclose(FILE *); +#endif + +#ifndef HAVE_POPEN +RUBY_EXTERN FILE *popen(const char *, const char *); +#endif + +#ifndef HAVE_PIPE +RUBY_EXTERN int pipe(int [2]); +#endif + +#ifndef HAVE_DUP +RUBY_EXTERN int dup(int); +#endif + +#ifndef HAVE_DUP2 +RUBY_EXTERN int dup2(int, int); +#endif + +#ifndef HAVE_KILL +RUBY_EXTERN int kill(rb_pid_t, int); +#endif + +#ifndef HAVE_EXECL +RUBY_EXTERN int execl(const char *, const char *, ...); +#endif + +#ifndef HAVE_EXECLE +RUBY_EXTERN int execle(const char *, const char *, ...); +#endif + +#ifndef HAVE_EXECV +RUBY_EXTERN int execv(const char *, char *const []); +#endif + +#ifndef HAVE_EXECVE +RUBY_EXTERN int execve(const char *, char *const [], char *const []); +#endif + +#ifndef HAVE_SHUTDOWN +RUBY_EXTERN int shutdown(int, int); +#endif + +#ifndef HAVE_SYSTEM +RUBY_EXTERN int system(const char *); +#endif + +#ifndef WNOHANG +# define WNOHANG 0 +#endif + +#ifndef HAVE_WAITPID +# define HAVE_WAITPID 1 +RUBY_EXTERN rb_pid_t waitpid(rb_pid_t, int *, int); +#endif + RBIMPL_SYMBOL_EXPORT_END() #endif /* RUBY_MISSING_H */ diff --git a/include/ruby/onigmo.h b/include/ruby/onigmo.h index 6187b37dc3..9dcddee829 100644 --- a/include/ruby/onigmo.h +++ b/include/ruby/onigmo.h @@ -4,8 +4,8 @@ onigmo.h - Onigmo (Oniguruma-mod) (regular expression library) **********************************************************************/ /*- - * Copyright (c) 2002-2009 K.Kosako <sndgk393 AT ybb DOT ne DOT jp> - * Copyright (c) 2011-2017 K.Takata <kentkt AT csc DOT jp> + * Copyright (c) 2002-2016 K.Kosako <sndgk393 AT ybb DOT ne DOT jp> + * Copyright (c) 2011-2019 K.Takata <kentkt AT csc DOT jp> * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -38,8 +38,8 @@ extern "C" { #endif #define ONIGMO_VERSION_MAJOR 6 -#define ONIGMO_VERSION_MINOR 1 -#define ONIGMO_VERSION_TEENY 3 +#define ONIGMO_VERSION_MINOR 2 +#define ONIGMO_VERSION_TEENY 0 #ifndef ONIG_EXTERN # ifdef RUBY_EXTERN @@ -356,9 +356,9 @@ int onigenc_ascii_only_case_map(OnigCaseFoldType* flagP, const OnigUChar** pp, c #define ONIGENC_PRECISE_MBC_ENC_LEN(enc,p,e) (enc)->precise_mbc_enc_len(p,e,enc) ONIG_EXTERN -int onigenc_mbclen_approximate(const OnigUChar* p,const OnigUChar* e, const struct OnigEncodingTypeST* enc); +int onigenc_mbclen(const OnigUChar* p,const OnigUChar* e, const struct OnigEncodingTypeST* enc); -#define ONIGENC_MBC_ENC_LEN(enc,p,e) onigenc_mbclen_approximate(p,e,enc) +#define ONIGENC_MBC_ENC_LEN(enc,p,e) onigenc_mbclen(p,e,enc) #define ONIGENC_MBC_MAXLEN(enc) ((enc)->max_enc_len) #define ONIGENC_MBC_MAXLEN_DIST(enc) ONIGENC_MBC_MAXLEN(enc) #define ONIGENC_MBC_MINLEN(enc) ((enc)->min_enc_len) @@ -636,6 +636,7 @@ ONIG_EXTERN const OnigSyntaxType* OnigDefaultSyntax; #define ONIGERR_PARSE_DEPTH_LIMIT_OVER -16 #define ONIGERR_DEFAULT_ENCODING_IS_NOT_SET -21 #define ONIGERR_SPECIFIED_ENCODING_CANT_CONVERT_TO_WIDE_CHAR -22 +#define ONIGERR_TIMEOUT -23 /* general error */ #define ONIGERR_INVALID_ARGUMENT -30 /* syntax error */ @@ -788,11 +789,18 @@ typedef struct re_pattern_buffer { unsigned char *exact; unsigned char *exact_end; unsigned char map[ONIG_CHAR_TABLE_SIZE]; /* used as BM skip or char-map */ - int *int_map; /* BM skip for exact_len > 255 */ - int *int_map_backward; /* BM skip for backward search */ + int *reserved1; + int *reserved2; OnigDistance dmin; /* min-distance of exact or map */ OnigDistance dmax; /* max-distance of exact or map */ + /* rb_hrtime_t from hrtime.h */ +#ifdef MY_RUBY_BUILD_MAY_TIME_TRAVEL + int128_t timelimit; +#else + uint64_t timelimit; +#endif + /* regex_t link chain */ struct re_pattern_buffer* chain; /* escape compile-conflict */ } OnigRegexType; @@ -837,6 +845,8 @@ void onig_free(OnigRegex); ONIG_EXTERN void onig_free_body(OnigRegex); ONIG_EXTERN +int onig_reg_copy(OnigRegex* reg, OnigRegex orig_reg); +ONIG_EXTERN OnigPosition onig_scan(OnigRegex reg, const OnigUChar* str, const OnigUChar* end, OnigRegion* region, OnigOptionType option, int (*scan_callback)(OnigPosition, OnigPosition, OnigRegion*, void*), void* callback_arg); ONIG_EXTERN OnigPosition onig_search(OnigRegex, const OnigUChar* str, const OnigUChar* end, const OnigUChar* start, const OnigUChar* range, OnigRegion* region, OnigOptionType option); @@ -845,6 +855,8 @@ OnigPosition onig_search_gpos(OnigRegex, const OnigUChar* str, const OnigUChar* ONIG_EXTERN OnigPosition onig_match(OnigRegex, const OnigUChar* str, const OnigUChar* end, const OnigUChar* at, OnigRegion* region, OnigOptionType option); ONIG_EXTERN +int onig_check_linear_time(OnigRegex reg); +ONIG_EXTERN OnigRegion* onig_region_new(void); ONIG_EXTERN void onig_region_init(OnigRegion* region); diff --git a/include/ruby/ractor.h b/include/ruby/ractor.h index 1d6687456c..8cfca21621 100644 --- a/include/ruby/ractor.h +++ b/include/ruby/ractor.h @@ -1,4 +1,4 @@ -#ifndef RUBY_RACTOR_H +#ifndef RUBY_RACTOR_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_RACTOR_H 1 /** @@ -11,50 +11,246 @@ * modify this file, provided that the conditions mentioned in the * file COPYING are met. Consult the file for details. */ +#include "internal/dllexport.h" /* RUBY_EXTERN is here */ +#include "internal/fl_type.h" /* FL_TEST_RAW is here */ +#include "internal/special_consts.h" /* RB_SPECIAL_CONSTS_P is here */ +#include "internal/stdbool.h" /* bool is here */ +#include "internal/value.h" /* VALUE is here */ +/** Type that defines a ractor-local storage. */ struct rb_ractor_local_storage_type { + + /** + * A function to mark a ractor-local storage. + * + * @param[out] ptr A ractor-local storage. + * @post Ruby objects inside of `ptr` are marked. + */ void (*mark)(void *ptr); + + /** + * A function to destruct a ractor-local storage. + * + * @param[out] ptr A ractor-local storage. + * @post `ptr` is not a valid pointer. + */ void (*free)(void *ptr); // TODO: update }; +/** (Opaque) struct that holds a ractor-local storage key. */ typedef struct rb_ractor_local_key_struct *rb_ractor_local_key_t; -RUBY_SYMBOL_EXPORT_BEGIN +RBIMPL_SYMBOL_EXPORT_BEGIN() + +/** + * `Ractor` class. + * + * @ingroup object + */ RUBY_EXTERN VALUE rb_cRactor; +/** + * Queries the standard input of the current Ractor that is calling this + * function. + * + * @return An IO. + * @note This can be different from the process-global one. + */ VALUE rb_ractor_stdin(void); + +/** + * Queries the standard output of the current Ractor that is calling this + * function. + * + * @return An IO. + * @note This can be different from the process-global one. + */ VALUE rb_ractor_stdout(void); + +/** + * Queries the standard error of the current Ractor that is calling this + * function. + * + * @return An IO. + * @note This can be different from the process-global one. + */ VALUE rb_ractor_stderr(void); -void rb_ractor_stdin_set(VALUE); -void rb_ractor_stdout_set(VALUE); -void rb_ractor_stderr_set(VALUE); +/** + * Assigns an IO to the standard input of the Ractor that is calling this + * function. + * + * @param[in] io An IO. + * @post `io` is the standard input of the current ractor. + * @post In case the calling Ractor is the main Ractor, it also updates + * the process global ::rb_stdin. + */ +void rb_ractor_stdin_set(VALUE io); + +/** + * Assigns an IO to the standard output of the Ractor that is calling this + * function. + * + * @param[in] io An IO. + * @post `io` is the standard input of the current ractor. + * @post In case the calling Ractor is the main Ractor, it also updates + * the process global ::rb_stdout. + */ +void rb_ractor_stdout_set(VALUE io); + +/** + * Assigns an IO to the standard error of the Ractor that is calling this + * function. + * + * @param[in] io An IO. + * @post `io` is the standard input of the current ractor. + * @post In case the calling Ractor is the main Ractor, it also updates + * the process global ::rb_stderr. + */ +void rb_ractor_stderr_set(VALUE io); + +/** + * Issues a new key. + * + * @return A newly issued ractor-local storage key. Keys issued using this + * key can be associated to a Ruby object per Ractor. + */ rb_ractor_local_key_t rb_ractor_local_storage_value_newkey(void); + +/** + * Queries the key. + * + * @param[in] key A ractor-local storage key to lookup. + * @retval RUBY_Qnil No such key. + * @retval otherwise A value corresponds to `key` in the current Ractor. + * @note This cannot distinguish between a nonexistent key and a key + * exists and corresponds to ::RUBY_Qnil. + */ VALUE rb_ractor_local_storage_value(rb_ractor_local_key_t key); + +/** + * Queries the key. + * + * @param[in] key A ractor-local storage key to lookup. + * @param[out] val Return value buffer. + * @retval false `key` not found. + * @retval true `key` found. + * @post `val` is updated so that it has the value corresponds to `key` + * in the current Ractor. + */ bool rb_ractor_local_storage_value_lookup(rb_ractor_local_key_t key, VALUE *val); + +/** + * Associates the passed value to the passed key. + * + * @param[in] key A ractor-local storage key. + * @param[in] val Arbitrary ruby object. + * @post `val` corresponds to `key` in the current Ractor. + */ void rb_ractor_local_storage_value_set(rb_ractor_local_key_t key, VALUE val); +/** + * A type of ractor-local storage that destructs itself using ::ruby_xfree. + * + * @internal + * + * Why it is visible from 3rd party extension libraries is not obvious to + * @shyouhei. + */ RUBY_EXTERN const struct rb_ractor_local_storage_type rb_ractor_local_storage_type_free; + +/** @alias{rb_ractor_local_storage_type_free} */ #define RB_RACTOR_LOCAL_STORAGE_TYPE_FREE (&rb_ractor_local_storage_type_free) +/** + * Extended version of rb_ractor_local_storage_value_newkey(). It additionally + * takes the type of the issuing key. + * + * @param[in] type How the value associated with the issuing key should + * behave. + * @return A newly issued ractor-local storage key, of type `type`. + */ rb_ractor_local_key_t rb_ractor_local_storage_ptr_newkey(const struct rb_ractor_local_storage_type *type); + +/** + * Identical to rb_ractor_local_storage_value() except the return type. + * + * @param[in] key A ractor-local storage key to lookup. + * @retval NULL No such key. + * @retval otherwise A value corresponds to `key` in the current Ractor. + */ void *rb_ractor_local_storage_ptr(rb_ractor_local_key_t key); + +/** + * Identical to rb_ractor_local_storage_value_set() except the parameter type. + * + * @param[in] key A ractor-local storage key. + * @param[in] ptr A pointer that conforms `key`'s type. + * @post `ptr` corresponds to `key` in the current Ractor. + */ void rb_ractor_local_storage_ptr_set(rb_ractor_local_key_t key, void *ptr); +/** + * Destructively transforms the passed object so that multiple Ractors can + * share it. What is a shareable object and what is not is a nuanced concept, + * and @ko1 says the definition can still change. However extension library + * authors might interest to learn how to use #RUBY_TYPED_FROZEN_SHAREABLE. + * + * @param[out] obj Arbitrary ruby object to modify. + * @exception rb_eRactorError Ractors cannot share `obj` by nature. + * @return Passed `obj`. + * @post Multiple Ractors can share `obj`. + * + * @internal + * + * In case an exception is raised, `obj` remains in an intermediate state where + * some of its part is frozen and others are not. @shyouhei is not sure if it + * is either an intended behaviour, current implementation limitation, or + * simply a bug. Note also that there is no way to "melt" a frozen object. + */ VALUE rb_ractor_make_shareable(VALUE obj); + +/** + * Identical to rb_ractor_make_shareable(), except it returns a (deep) copy of + * the passed one instead of modifying it in-place. + * + * @param[in] obj Arbitrary ruby object to duplicate. + * @exception rb_eRactorError Ractors cannot share `obj` by nature. + * @return A deep copy of `obj` which is shareable among Ractors. + */ VALUE rb_ractor_make_shareable_copy(VALUE obj); -RUBY_SYMBOL_EXPORT_END +RBIMPL_SYMBOL_EXPORT_END() +/** + * Queries if the passed object has previously classified as shareable or not. + * This doesn't mean anything in practice... Objects can be shared later. + * Always use rb_ractor_shareable_p() instead. + * + * @param[in] obj Object in question. + * @retval RUBY_FL_SHAREABLE It once was shareable before. + * @retval 0 Otherwise. + */ #define RB_OBJ_SHAREABLE_P(obj) FL_TEST_RAW((obj), RUBY_FL_SHAREABLE) +/** + * Queries if multiple Ractors can share the passed object or not. Ractors run + * without protecting each other. Sharing an object among them is basically + * dangerous, disabled by default. However there are objects that are + * extremely carefully implemented to be Ractor-safe; for instance integers + * have such property. This function can classify that. + * + * @param[in] obj Arbitrary ruby object. + * @retval true `obj` is capable of shared across ractors. + * @retval false `obj` cannot travel across ractor boundaries. + */ static inline bool rb_ractor_shareable_p(VALUE obj) { bool rb_ractor_shareable_p_continue(VALUE obj); - if (SPECIAL_CONST_P(obj)) { + if (RB_SPECIAL_CONST_P(obj)) { return true; } else if (RB_OBJ_SHAREABLE_P(obj)) { @@ -65,4 +261,18 @@ rb_ractor_shareable_p(VALUE obj) } } +// TODO: optimize on interpreter core +#ifndef RB_OBJ_SET_SHAREABLE +VALUE rb_obj_set_shareable(VALUE obj); // ractor.c +#define RB_OBJ_SET_SHAREABLE(obj) rb_obj_set_shareable(obj) +#endif + +static inline VALUE +RB_OBJ_SET_FROZEN_SHAREABLE(VALUE obj) +{ + RB_OBJ_FREEZE(obj); + RB_OBJ_SET_SHAREABLE(obj); + return obj; +} + #endif /* RUBY_RACTOR_H */ diff --git a/include/ruby/random.h b/include/ruby/random.h index 56b2dd413f..740be6bdad 100644 --- a/include/ruby/random.h +++ b/include/ruby/random.h @@ -1,4 +1,4 @@ -#ifndef RUBY_RANDOM_H +#ifndef RUBY_RANDOM_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_RANDOM_H 1 /** * @file @@ -8,79 +8,348 @@ * 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. + * + * This is a set of APIs to roll your own subclass of ::rb_cRandom. An + * illustrative example of such PRNG can be found at + * `ext/-test-/random/loop.c`. */ #include "ruby/ruby.h" +/* + * version + * 0: before versioning; deprecated + * 1: added version, flags and init_32bit function + */ +#define RUBY_RANDOM_INTERFACE_VERSION_MAJOR 1 +#define RUBY_RANDOM_INTERFACE_VERSION_MINOR 0 + +#define RUBY_RANDOM_PASTE_VERSION_SUFFIX(x, y, z) x##_##y##_##z +#define RUBY_RANDOM_WITH_VERSION_SUFFIX(name, major, minor) \ + RUBY_RANDOM_PASTE_VERSION_SUFFIX(name, major, minor) +#define rb_random_data_type \ + RUBY_RANDOM_WITH_VERSION_SUFFIX(rb_random_data_type, \ + RUBY_RANDOM_INTERFACE_VERSION_MAJOR, \ + RUBY_RANDOM_INTERFACE_VERSION_MINOR) +#define RUBY_RANDOM_INTERFACE_VERSION_INITIALIZER \ + {RUBY_RANDOM_INTERFACE_VERSION_MAJOR, RUBY_RANDOM_INTERFACE_VERSION_MINOR} +#define RUBY_RANDOM_INTERFACE_VERSION_MAJOR_MAX 0xff +#define RUBY_RANDOM_INTERFACE_VERSION_MINOR_MAX 0xff + RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * Base components of the random interface. + * + * @internal + * + * Ideally this could be an empty class if we could assume C++, but in C a + * struct must have at least one field. + */ struct rb_random_struct { + /** Seed, passed through e.g. `Random.new` */ VALUE seed; }; -typedef struct rb_random_struct rb_random_t; +typedef struct rb_random_struct rb_random_t; /**< @see ::rb_random_struct */ + +RBIMPL_ATTR_NONNULL(()) +/** + * This is the type of functions called when your random object is initialised. + * Passed buffer is the seed object basically. But in Ruby a number can be + * really big. This type of functions accept such big integers as a series of + * machine words. + * + * @param[out] rng Your random struct to fill in. + * @param[in] buf Seed, maybe converted from a bignum. + * @param[in] len Number of words of `buf`. + * @post `rng` is initialised using the passed seeds. + */ +typedef void rb_random_init_func(rb_random_t *rng, const uint32_t *buf, size_t len); + +RBIMPL_ATTR_NONNULL(()) +/** + * This is the type of functions called when your random object is initialised. + * Passed data is the seed integer. + * + * @param[out] rng Your random struct to fill in. + * @param[in] data Seed, single word. + * @post `rng` is initialised using the passed seeds. + */ +typedef void rb_random_init_int32_func(rb_random_t *rng, uint32_t data); + +RBIMPL_ATTR_NONNULL(()) +/** + * This is the type of functions called from your object's `#rand` method. + * + * @param[out] rng Your random struct to extract an integer from. + * @return A random number. + * @post `rng` is consumed somehow. + */ +typedef unsigned int rb_random_get_int32_func(rb_random_t *rng); + +RBIMPL_ATTR_NONNULL(()) +/** + * This is the type of functions called from your object's `#bytes` method. + * + * @param[out] rng Your random struct to extract an integer from. + * @param[out] buf Return buffer of at least `len` bytes length. + * @param[in] len Number of bytes of `buf`. + * @post `rng` is consumed somehow. + * @post `buf` is filled with random bytes. + */ +typedef void rb_random_get_bytes_func(rb_random_t *rng, void *buf, size_t len); -typedef void rb_random_init_func(rb_random_t *, const uint32_t *, size_t); -typedef unsigned int rb_random_get_int32_func(rb_random_t *); -typedef void rb_random_get_bytes_func(rb_random_t *, void *, size_t); -typedef double rb_random_get_real_func(rb_random_t *, int); +RBIMPL_ATTR_NONNULL(()) +/** + * This is the type of functions called from your object's `#rand` method. + * + * @param[out] rng Your random struct to extract an integer from. + * @param[in] excl Pass nonzero value here to indicate you don't want 1.0. + * @return A random number of range 0.0 to 1.0. + * @post `rng` is consumed somehow. + */ +typedef double rb_random_get_real_func(rb_random_t *rng, int excl); +/** PRNG algorithmic interface, analogous to Ruby level classes. */ typedef struct { + /** Number of bits of seed numbers. */ size_t default_seed_bits; + + /** + * Major/minor versions of this interface + */ + struct { + uint8_t major, minor; + } version; + + /** + * Reserved flags + */ + uint16_t flags; + + /** Function to initialize from uint32_t array. */ rb_random_init_func *init; + + /** Function to initialize from single uint32_t. */ + rb_random_init_int32_func *init_int32; + + /** Function to obtain a random integer. */ rb_random_get_int32_func *get_int32; + + /** + * Function to obtain a series of random bytes. If your PRNG have a native + * method to yield arbitrary number of bytes use that to implement this. + * But in case you lack such things, you can do so by using + * rb_rand_bytes_int32() + * + * ```CXX + * extern rb_random_get_int32_func your_get_int32_func; + * + * void + * your_get_byes_func(rb_random_t *rng, void *buf, size_t len) + * { + * rb_rand_bytes_int32(your_get_int32_func, rng, buf, len); + * } + * ``` + */ rb_random_get_bytes_func *get_bytes; + + /** + * Function to obtain a random double. If your PRNG have a native method + * to yield a floating point random number use that to implement this. But + * in case you lack such things, you can do so by using + * rb_int_pair_to_real(). + * + * ```CXX + * extern rb_random_get_int32_func your_get_int32_func; + * + * void + * your_get_real_func(rb_random_t *rng, int excl) + * { + * auto a = your_get_int32_func(rng); + * auto b = your_get_int32_func(rng); + * return rb_int_pair_to_real(a, b, excl); + * } + * ``` + */ rb_random_get_real_func *get_real; } rb_random_interface_t; +/** + * This utility macro defines 4 functions named prefix_init, prefix_init_int32, + * prefix_get_int32, prefix_get_bytes. + */ #define RB_RANDOM_INTERFACE_DECLARE(prefix) \ static void prefix##_init(rb_random_t *, const uint32_t *, size_t); \ + static void prefix##_init_int32(rb_random_t *, uint32_t); \ static unsigned int prefix##_get_int32(rb_random_t *); \ static void prefix##_get_bytes(rb_random_t *, void *, size_t) +/** + * Identical to #RB_RANDOM_INTERFACE_DECLARE except it also declares + * prefix_get_real. + */ #define RB_RANDOM_INTERFACE_DECLARE_WITH_REAL(prefix) \ RB_RANDOM_INTERFACE_DECLARE(prefix); \ static double prefix##_get_real(rb_random_t *, int) +/** + * This utility macro expands to the names declared using + * #RB_RANDOM_INTERFACE_DECLARE. Expected to be used inside of a + * ::rb_random_interface_t initialiser: + * + * ```CXX + * RB_RANDOM_INTERFACE_DECLARE(foo); + * + * static inline constexpr rb_random_interface_t foo_interface = { + * 32768, // bits + * RB_RANDOM_INTERFACE_DEFINE(foo), + * }; + * ``` + */ #define RB_RANDOM_INTERFACE_DEFINE(prefix) \ + RUBY_RANDOM_INTERFACE_VERSION_INITIALIZER, 0, \ prefix##_init, \ + prefix##_init_int32, \ prefix##_get_int32, \ prefix##_get_bytes +/** + * Identical to #RB_RANDOM_INTERFACE_DEFINE except it also defines + * prefix_get_real. + */ #define RB_RANDOM_INTERFACE_DEFINE_WITH_REAL(prefix) \ RB_RANDOM_INTERFACE_DEFINE(prefix), \ prefix##_get_real +#define RB_RANDOM_DEFINE_INIT_INT32_FUNC(prefix) \ + static void prefix##_init_int32(rb_random_t *rnd, uint32_t data) \ + { \ + prefix##_init(rnd, &data, 1); \ + } + #if defined _WIN32 && !defined __CYGWIN__ typedef rb_data_type_t rb_random_data_type_t; # define RB_RANDOM_PARENT 0 #else + +/** This is the type of ::rb_random_data_type. */ typedef const rb_data_type_t rb_random_data_type_t; + +/** + * This utility macro can be used when you define your own PRNG type: + * + * ```CXX + * static inline constexpr rb_random_interface_t your_if = { + * 0, RB_RANDOM_INTERFACE_DEFINE(your), + * }; + * + * static inline constexpr rb_random_data_type_t your_prng_type = { + * "your PRNG", + * { rb_random_mark, }, + * RB_RANDOM_PARENT, // <<-- HERE + * &your_if, + * 0, + * } + * ``` + */ # define RB_RANDOM_PARENT &rb_random_data_type #endif +/** + * This macro is expected to be called exactly once at the beginning of a + * program, possibly from inside of your `Init_Foo()` function. Depending on + * platforms #RB_RANDOM_PARENT can require a fixup. This routine does that + * when necessary. + */ #define RB_RANDOM_DATA_INIT_PARENT(random_data) \ rbimpl_random_data_init_parent(&random_data) +/** + * This is the implementation of ::rb_data_type_struct::dmark for + * ::rb_random_data_type. In case your PRNG does not involve Ruby objects at + * all (which is quite likely), you can simply reuse it. + * + * @param[out] ptr Target to mark, which is a ::rb_random_t this case. + */ void rb_random_mark(void *ptr); + +/** + * Initialises an allocated ::rb_random_t instance. Call it from your own + * initialiser appropriately. + * + * @param[out] rnd Your PRNG's base part. + * @post `rnd` is filled with an initial state. + */ void rb_random_base_init(rb_random_t *rnd); + +/** + * Generates a 64 bit floating point number by concatenating two 32bit unsigned + * integers. + * + * @param[in] a Most significant 32 bits of the result. + * @param[in] b Least significant 32 bits of the result. + * @param[in] excl Whether the result should exclude 1.0 or not. + * @return A double, whose range is either `[0, 1)` or `[0, 1]`. + * @see ::rb_random_interface_t::get_real() + * + * @internal + * + * This in fact has nothing to do with PRNGs. + */ double rb_int_pair_to_real(uint32_t a, uint32_t b, int excl); -void rb_rand_bytes_int32(rb_random_get_int32_func *, rb_random_t *, void *, size_t); + +/** + * Repeatedly calls the passed function over and over again until the passed + * buffer is filled with random bytes. + * + * @param[in] func Generator function. + * @param[out] prng Passed as-is to `func`. + * @param[out] buff Return buffer. + * @param[in] size Number of words of `buff`. + * @post `buff` is filled with random bytes. + * @post `prng` is updated by `func`. + * @see ::rb_random_interface_t::get_bytes() + */ +void rb_rand_bytes_int32(rb_random_get_int32_func *func, rb_random_t *prng, void *buff, size_t size); + +/** + * The data that holds the backend type of ::rb_cRandom. Used as your PRNG's + * ::rb_data_type_struct::parent. + */ RUBY_EXTERN const rb_data_type_t rb_random_data_type; RBIMPL_SYMBOL_EXPORT_END() RBIMPL_ATTR_PURE_UNLESS_DEBUG() /* :TODO: can this function be __attribute__((returns_nonnull)) or not? */ +/** + * Queries the interface of the passed random object. + * + * @param[in] obj An instance (of a subclass) of ::rb_cRandom. + * @return Its corresponding ::rb_random_interface_t interface. + */ static inline const rb_random_interface_t * rb_rand_if(VALUE obj) { + RBIMPL_ASSERT_OR_ASSUME(RB_TYPE_P(obj, T_DATA)); RBIMPL_ASSERT_OR_ASSUME(RTYPEDDATA_P(obj)); + RUBY_ASSERT(rb_typeddata_is_kind_of(obj, &rb_random_data_type)); const struct rb_data_type_struct *t = RTYPEDDATA_TYPE(obj); const void *ret = t->data; return RBIMPL_CAST((const rb_random_interface_t *)ret); } RBIMPL_ATTR_NOALIAS() +/** + * @private + * + * This is an implementation detail of #RB_RANDOM_DATA_INIT_PARENT. People + * don't use it directly. + * + * @param[out] random_data Region to fill. + * @post ::rb_random_data_type is filled appropriately. + */ static inline void rbimpl_random_data_init_parent(rb_random_data_type_t *random_data) { diff --git a/include/ruby/re.h b/include/ruby/re.h index ec0f425db0..f86d6f26cf 100644 --- a/include/ruby/re.h +++ b/include/ruby/re.h @@ -11,23 +11,161 @@ * file COPYING are met. Consult the file for details. */ #include "ruby/internal/config.h" -#include <sys/types.h> + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif + #include <stdio.h> +#include "ruby/onigmo.h" #include "ruby/regex.h" #include "ruby/internal/core/rmatch.h" #include "ruby/internal/dllexport.h" +struct re_registers; /* Defined in onigmo.h */ + RBIMPL_SYMBOL_EXPORT_BEGIN() -VALUE rb_reg_regcomp(VALUE); -long rb_reg_search(VALUE, VALUE, long, int); -VALUE rb_reg_regsub(VALUE, VALUE, struct re_registers *, VALUE); -long rb_reg_adjust_startpos(VALUE, VALUE, long, int); -void rb_match_busy(VALUE); -VALUE rb_reg_quote(VALUE); +/** + * Creates a new instance of ::rb_cRegexp. It can be seen as a specialised + * version of rb_reg_new_str() where it does not take options. + * + * @param[in] str Source code in String. + * @return Allocated new instance of ::rb_cRegexp. + */ +VALUE rb_reg_regcomp(VALUE str); + +/** + * Runs the passed regular expression over the passed string. Unlike + * rb_reg_search() this function also takes position and direction of the + * search, which make it possible for this function to run from in middle of + * the string. + * + * @param[in] re Regular expression to execute. + * @param[in] str Target string to search. + * @param[in] pos Offset in `str` to start searching, in bytes. + * @param[in] dir `pos`' direction; 0 means left-to-right, 1 for + * the opposite. + * @exception rb_eArgError `re` is broken. + * @exception rb_eRegexpError `re` is malformed. + * @retval -1 Match failed. + * @retval otherwise Offset of first such byte where match happened. + * @post `Regexp.last_match` is updated. + * @post `$&`, `$~`, etc., are updated. + * + * @internal + * + * Distinction between raising ::rb_eArgError and ::rb_eRegexpError is not + * obvious, at least to @shyouhei. + */ +long rb_reg_search(VALUE re, VALUE str, long pos, int dir); + +/** + * Substitution. This is basically the implementation of `String#sub`. Also + * `String#gsub` repeatedly calls this function. + * + * @param[in] repl Replacement string, e.g. `"\\1\\2"` + * @param[in] src Source string, to be replaced. + * @param[in] regs Matched data generated by applying `rexp` to `src`. + * @param[in] rexp Regular expression. + * @return A substituted string. + * + * @internal + * + * This function does not check for encoding compatibility. `String#sub!` + * etc. employ their own checker. + * + * `regs` should have been `const struct re_registers *` because it is read + * only. Kept as-is for compatibility. + */ +VALUE rb_reg_regsub(VALUE repl, VALUE src, struct re_registers *regs, VALUE rexp); + +/** + * Tell us if this is a wrong idea, but it seems this function has no usage at + * all. Just remains here for theoretical backwards compatibility. + * + * @param[in] re Regular expression to execute. + * @param[in] str Target string to search. + * @param[in] pos Offset in `str` to start searching, in bytes. + * @param[in] dir `pos`' direction; 0 means left-to-right, 1 for + * the opposite. + * @return Adjusted nearest offset to `pos` inside of `str`, where is a + * character boundary. + * + */ +long rb_reg_adjust_startpos(VALUE re, VALUE str, long pos, int dir); + +/** + * Escapes any characters that would have special meaning in a regular + * expression. + * + * @param[in] str Target string to escape. + * @return A copy of `str` whose contents are escaped. + */ +VALUE rb_reg_quote(VALUE str); + +/** + * Exercises various checks and preprocesses so that the given regular + * expression can be applied to the given string. The preprocess here includes + * (but not limited to) for instance encoding conversion. + * + * @param[in] re Target regular expression. + * @param[in] str What `re` is about to run on. + * @exception rb_eArgError `re` does not fit for `str`. + * @exception rb_eEncCompatError `re` and `str` are incompatible. + * @exception rb_eRegexpError `re` is malformed. + * @return A preprocessesed pattern buffer ready to be applied to `str`. + * @note The return value is manages by our GC. Don't free. + * + * @internal + * + * The return type, `regex_t *`, is defined in `<ruby/onigmo.h>`, _and_ + * _conflicts_ with POSIX's `<regex.h>`. We can no longer save the situation + * at this point. Just don't mix the two. + */ regex_t *rb_reg_prepare_re(VALUE re, VALUE str); -int rb_reg_region_copy(struct re_registers *, const struct re_registers *); + +/** + * Runs a regular expression match using function `match`. Performs preparation, + * error handling, and memory cleanup. + * + * @param[in] re Target regular expression. + * @param[in] str What `re` is about to run on. + * @param[in] match The function to run to match `str` against `re`. + * @param[in] args Pointer to arguments to pass into `match`. + * @param[out] regs Registers on a successful match. + * @exception rb_eArgError `re` does not fit for `str`. + * @exception rb_eEncCompatError `re` and `str` are incompatible. + * @exception rb_eRegexpError `re` is malformed. + * @return Match position on a successful match, `ONIG_MISMATCH` otherwise. + * + * @internal + * + * The type `regex_t *` is defined in `<ruby/onigmo.h>`, _and_ + * _conflicts_ with POSIX's `<regex.h>`. We can no longer save the situation + * at this point. Just don't mix the two. + */ +OnigPosition rb_reg_onig_match(VALUE re, VALUE str, + OnigPosition (*match)(regex_t *reg, VALUE str, struct re_registers *regs, void *args), + void *args, struct re_registers *regs); + +/** + * Duplicates a match data. This is roughly the same as `onig_region_copy()`, + * except it tries to GC when there is not enough memory. + * + * @param[out] dst Target registers to fill. + * @param[in] src Source registers to duplicate. + * @exception rb_eNoMemError Not enough memory. + * @retval 0 Successful + * @retval ONIGERR_MEMORY Not enough memory, even after GC (unlikely). + * @post `dst` has identical contents to `src`. + * + * @internal + * + * It seems this function is here for `ext/strscan` and nothing else. + */ +int rb_reg_region_copy(struct re_registers *dst, const struct re_registers *src); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/regex.h b/include/ruby/regex.h index 22dae3231d..53278173f8 100644 --- a/include/ruby/regex.h +++ b/include/ruby/regex.h @@ -1,7 +1,6 @@ #ifndef ONIGURUMA_REGEX_H /*-*-C++-*-vi:se ft=cpp:*/ #define ONIGURUMA_REGEX_H 1 /** - * @file * @author $Author$ * @copyright Copyright (C) 1993-2007 Yukihiro Matsumoto * @copyright This file is a part of the programming language Ruby. diff --git a/include/ruby/ruby.h b/include/ruby/ruby.h index 341a716953..ca794bcaeb 100644 --- a/include/ruby/ruby.h +++ b/include/ruby/ruby.h @@ -14,6 +14,8 @@ */ #include "ruby/internal/config.h" +/* @shyouhei doesn't understand why we need <intrinsics.h> at this very + * beginning of the entire <ruby.h> circus. */ #ifdef HAVE_INTRINSICS_H # include <intrinsics.h> #endif @@ -21,6 +23,7 @@ #include <stdarg.h> #include "defines.h" +#include "ruby/internal/abi.h" #include "ruby/internal/anyargs.h" #include "ruby/internal/arithmetic.h" #include "ruby/internal/core.h" @@ -40,7 +43,6 @@ #include "ruby/internal/method.h" #include "ruby/internal/module.h" #include "ruby/internal/newobj.h" -#include "ruby/internal/rgengc.h" #include "ruby/internal/scan_args.h" #include "ruby/internal/special_consts.h" #include "ruby/internal/symbol.h" @@ -55,19 +57,59 @@ RBIMPL_SYMBOL_EXPORT_BEGIN() /* Module#methods, #singleton_methods and so on return Symbols */ +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ #define USE_SYMBOL_AS_METHOD_NAME 1 -VALUE rb_get_path(VALUE); +/** + * Converts an object to a path. It first tries `#to_path` method if any, then + * falls back to `#to_str` method. + * + * @param[in] obj Arbitrary ruby object. + * @exception rb_eArgError `obj` contains a NUL byte. + * @exception rb_eTypeError `obj` is not path-ish. + * @exception rb_eEncCompatError No encoding conversion from `obj` to path. + * @return Converted path object. + */ +VALUE rb_get_path(VALUE obj); + +/** + * Ensures that the parameter object is a path. + * + * @param[in,out] v Arbitrary ruby object. + * @exception rb_eArgError `v` contains a NUL byte. + * @exception rb_eTypeError `v` is not path-ish. + * @exception rb_eEncCompatError `v` is not path-compatible. + * @post `v` is a path. + */ #define FilePathValue(v) (RB_GC_GUARD(v) = rb_get_path(v)) +/** + * @deprecated This function is an alias of rb_get_path() now. The part that + * did "no_checksafe" was deleted. It remains here because of no + * harm. + */ VALUE rb_get_path_no_checksafe(VALUE); + +/** + * This macro actually does the same thing as #FilePathValue now. The "String" + * part indicates that this is for when a string is treated like a pathname, + * rather than the actual pathname on the file systems. For examples: + * `Dir.fnmatch?`, `File.join`, `File.basename`, etc. + */ #define FilePathStringValue(v) ((v) = rb_get_path(v)) +/** @cond INTERNAL_MACRO */ #if defined(HAVE_BUILTIN___BUILTIN_CONSTANT_P) && defined(HAVE_STMT_AND_DECL_IN_EXPR) # define rb_varargs_argc_check_runtime(argc, vargc) \ (((argc) <= (vargc)) ? (argc) : \ (rb_fatal("argc(%d) exceeds actual arguments(%d)", \ - argc, vargc), 0)) + argc, vargc), 0)) # define rb_varargs_argc_valid_p(argc, vargc) \ ((argc) == 0 ? (vargc) <= 1 : /* [ruby-core:85266] [Bug #14425] */ \ (argc) == (vargc)) @@ -76,64 +118,305 @@ VALUE rb_get_path_no_checksafe(VALUE); ERRORFUNC((" argument length doesn't match"), int rb_varargs_bad_length(int,int)); # else # define rb_varargs_bad_length(argc, vargc) \ - ((argc)/rb_varargs_argc_valid_p(argc, vargc)) + ((argc)/rb_varargs_argc_valid_p(argc, vargc)) # endif # define rb_varargs_argc_check(argc, vargc) \ __builtin_choose_expr(__builtin_constant_p(argc), \ - (rb_varargs_argc_valid_p(argc, vargc) ? (argc) : \ - rb_varargs_bad_length(argc, vargc)), \ - rb_varargs_argc_check_runtime(argc, vargc)) + (rb_varargs_argc_valid_p(argc, vargc) ? (argc) : \ + rb_varargs_bad_length(argc, vargc)), \ + rb_varargs_argc_check_runtime(argc, vargc)) # else # define rb_varargs_argc_check(argc, vargc) \ - rb_varargs_argc_check_runtime(argc, vargc) + rb_varargs_argc_check_runtime(argc, vargc) # endif #endif +/** @endcond */ -const char *rb_class2name(VALUE); -const char *rb_obj_classname(VALUE); +/** + * Queries the name of the passed class. + * + * @param[in] klass An instance of a class. + * @return The name of `klass`. + * @note Return value is managed by our GC. Don't free. + */ +const char *rb_class2name(VALUE klass); -void rb_p(VALUE); +/** + * Queries the name of the class of the passed object. + * + * @param[in] obj Arbitrary ruby object. + * @return The name of the class of `obj`. + * @note Return value is managed by our GC. Don't free. + */ +const char *rb_obj_classname(VALUE obj); -VALUE rb_equal(VALUE,VALUE); +/** + * Inspects an object. It first calls the argument's `#inspect` method, then + * feeds its result string into ::rb_stdout. + * + * This is identical to Ruby level `Kernel#p`, except it takes only one object. + * + * @internal + * + * Above description is in fact inaccurate. This API interfaces with Ractors. + */ +void rb_p(VALUE obj); + +/** + * This function is an optimised version of calling `#==`. It checks equality + * between two objects by first doing a fast identity check using using C's + * `==` (same as `BasicObject#equal?`). If that check fails, it calls `#==` + * dynamically. This optimisation actually affects semantics, because when + * `#==` returns false for the same object obj, `rb_equal(obj, obj)` would + * still return true. This happens for `Float::NAN`, where `Float::NAN == + * Float::NAN` is `false`, but `rb_equal(Float::NAN, Float::NAN)` is `true`. + * + * @param[in] lhs Comparison LHS. + * @param[in] rhs Comparison RHS. + * @retval RUBY_Qtrue They are the same. + * @retval RUBY_Qfalse They are different. + */ +VALUE rb_equal(VALUE lhs, VALUE rhs); -VALUE rb_require(const char*); +/** + * Identical to rb_require_string(), except it takes C's string instead of + * Ruby's. + * + * @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(const char *feature); #include "ruby/intern.h" +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ #define RUBY_VM 1 /* YARV */ + +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ #define HAVE_NATIVETHREAD + +/** + * Queries if the thread which calls this function is a ruby's thread. + * "Ruby's" in this context is a thread created using one of our APIs like + * rb_thread_create(). There are distinctions between ruby's and other + * threads. For instance calling ruby methods are allowed only from inside of + * a ruby's thread. + * + * @retval 1 The current thread is a Ruby's thread. + * @retval 0 The current thread is a random thread from outside of Ruby. + */ int ruby_native_thread_p(void); +/** + * @private + * + * This macro is for internal use. Must be a mistake to place here. + */ #define InitVM(ext) {void InitVM_##ext(void);InitVM_##ext();} -PRINTF_ARGS(int ruby_snprintf(char *str, size_t n, char const *fmt, ...), 3, 4); +RBIMPL_ATTR_NONNULL((3)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 3, 4) +/** + * Our own locale-insensitive version of `snprintf(3)`. It can also be seen as + * a routine identical to rb_sprintf(), except it writes back to the passed + * buffer instead of allocating a new Ruby object. + * + * @param[out] str Return buffer + * @param[in] n Number of bytes of `str`. + * @param[in] fmt A `printf`-like format specifier. + * @param[in] ... Variadic number of contents to format. + * @return Number of bytes that would have been written to `str`, if `n` + * was large enough. Comparing this to `n` can give you insights + * that the buffer is too small or too big. Especially passing 0 + * to `n` gives you the exact number of bytes necessary to hold + * the result string without writing anything to anywhere. + * @post `str` holds up to `n-1` bytes of formatted contents (and the + * terminating NUL character.) + */ +int ruby_snprintf(char *str, size_t n, char const *fmt, ...); + +RBIMPL_ATTR_NONNULL((3)) +RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 3, 0) +/** + * Identical to ruby_snprintf(), except it takes a `va_list`. It can also be + * seen as a routine identical to rb_vsprintf(), except it writes back to the + * passed buffer instead of allocating a new Ruby object. + * + * @param[out] str Return buffer + * @param[in] n Number of bytes of `str`. + * @param[in] fmt A `printf`-like format specifier. + * @param[in] ap Contents to format. + * @return Number of bytes that would have been written to `str`, if `n` + * was large enough. Comparing this to `n` can give you insights + * that the buffer is too small or too big. Especially passing 0 + * to `n` gives you the exact number of bytes necessary to hold + * the result string without writing anything to anywhere. + * @post `str` holds up to `n-1` bytes of formatted contents (and the + * terminating NUL character.) + */ int ruby_vsnprintf(char *str, size_t n, char const *fmt, va_list ap); +#include <errno.h> + +/** + * @name Errno handling routines for userland threads + * @note POSIX chapter 2 section 3 states that for each thread of a process, + * the value of `errno` shall not be affected by function calls or + * assignments to `errno` by other threads. + * + * Soooo this `#define errno` below seems like a noob mistake at first sight. + * If you look at its actual implementation, the functions are just adding one + * level of indirection. It doesn't make any sense sorry? But yes! @ko1 told + * @shyouhei that this is inevitable. + * + * The ultimate reason is because Ruby now has N:M threads implemented. + * Threads of that sort change their context in user land. A function can be + * "transferred" between threads in middle of their executions. Let us for + * instance consider: + * + * ```cxx + * void foo() + * { + * auto i = errno; + * close(0); + * errno = i; + * } + * ``` + * + * This function (if ran under our Ractor) could change its running thread at + * the `close` function. But the two `errno` invocations are different! Look + * how the source code above is compiled by clang 17 with `-O3` flag @ Linux: + * + * ``` + * foo(int): # @foo(int) + * push rbp + * push r14 + * push rbx + * mov ebx, edi + * call __errno_location@PLT + * mov r14, rax + * mov ebp, dword ptr [rax] + * mov edi, ebx + * call close@PLT + * mov dword ptr [r14], ebp + * pop rbx + * pop r14 + * pop rbp + * ret + * ``` + * + * Notice how `__errno_location@PLT` is `call`-ed only once. The compiler + * assumes that the location of `errno` does not change during a function call. + * Sadly this is no longer true for us. The `close@PLT` now changes threads, + * which should also change where `errno` is stored. + * + * With the `#define errno` below the compilation result changes to this: + * + * ``` + * foo(int): # @foo(int) + * push rbp + * push rbx + * push rax + * mov ebx, edi + * call rb_errno_ptr()@PLT + * mov ebp, dword ptr [rax] + * mov edi, ebx + * call close@PLT + * call rb_errno_ptr()@PLT + * mov dword ptr [rax], ebp + * add rsp, 8 + * pop rbx + * pop rbp + * ret + * ``` + * + * Which fixes the problem. + */ + +/** + * Identical to system `errno`. + * + * @return The last set `errno` number. + */ +int rb_errno(void); + +/** + * Set the errno. + * + * @param err New `errno`. + * @post `errno` is now set to `err`. + */ +void rb_errno_set(int err); + +/** + * The location of `errno` + * + * @return The (thread-specific) location of `errno`. + */ +int *rb_errno_ptr(void); + +/** + * Not sure if it is necessary for extension libraries but this is where the + * "bare" errno is located. + * + * @return The location of `errno`. + */ +static inline int * +rb_orig_errno_ptr(void) +{ + return &errno; +} + +#define rb_orig_errno errno /**< System-provided original `errno`. */ +#undef errno +#define errno (*rb_errno_ptr()) /**< Ractor-aware version of `errno`. */ + +/** @} */ + + +/** @cond INTERNAL_MACRO */ #if RBIMPL_HAS_WARNING("-Wgnu-zero-variadic-macro-arguments") # /* Skip it; clang -pedantic doesn't like the following */ #elif defined(__GNUC__) && defined(HAVE_VA_ARGS_MACRO) && defined(__OPTIMIZE__) # define rb_yield_values(argc, ...) \ __extension__({ \ - const int rb_yield_values_argc = (argc); \ - const VALUE rb_yield_values_args[] = {__VA_ARGS__}; \ - const int rb_yield_values_nargs = \ - (int)(sizeof(rb_yield_values_args) / sizeof(VALUE)); \ - rb_yield_values2( \ - rb_varargs_argc_check(rb_yield_values_argc, rb_yield_values_nargs), \ - rb_yield_values_nargs ? rb_yield_values_args : NULL); \ + const int rb_yield_values_argc = (argc); \ + const VALUE rb_yield_values_args[] = {__VA_ARGS__}; \ + const int rb_yield_values_nargs = \ + (int)(sizeof(rb_yield_values_args) / sizeof(VALUE)); \ + rb_yield_values2( \ + rb_varargs_argc_check(rb_yield_values_argc, rb_yield_values_nargs), \ + rb_yield_values_nargs ? rb_yield_values_args : NULL); \ }) # define rb_funcall(recv, mid, argc, ...) \ __extension__({ \ - const int rb_funcall_argc = (argc); \ - const VALUE rb_funcall_args[] = {__VA_ARGS__}; \ - const int rb_funcall_nargs = \ - (int)(sizeof(rb_funcall_args) / sizeof(VALUE)); \ + const int rb_funcall_argc = (argc); \ + const VALUE rb_funcall_args[] = {__VA_ARGS__}; \ + const int rb_funcall_nargs = \ + (int)(sizeof(rb_funcall_args) / sizeof(VALUE)); \ rb_funcallv(recv, mid, \ - rb_varargs_argc_check(rb_funcall_argc, rb_funcall_nargs), \ - rb_funcall_nargs ? rb_funcall_args : NULL); \ + rb_varargs_argc_check(rb_funcall_argc, rb_funcall_nargs), \ + rb_funcall_nargs ? rb_funcall_args : NULL); \ }) #endif +/** @endcond */ #ifndef RUBY_DONT_SUBST #include "ruby/subst.h" @@ -143,6 +426,21 @@ __extension__({ \ # include "ruby/backward.h" #endif +#ifndef RUBY__ASAN_DEFAULT_OPTIONS +# define RUBY__ASAN_DEFAULT_OPTIONS +#endif + +#define RUBY_GLOBAL_SETUP \ + RUBY__ASAN_DEFAULT_OPTIONS \ + /* RUBY_GLOBAL_SETUP end */ + +#if defined(__wasm__) && !defined(__EMSCRIPTEN__) +int rb_wasm_rt_start(int (*)(int, char **), int, char **); +# define ruby_start_main rb_wasm_rt_start +#else +# define ruby_start_main(main, argc, argv) main(argc, argv) +#endif + RBIMPL_SYMBOL_EXPORT_END() #endif /* RUBY_RUBY_H */ diff --git a/include/ruby/st.h b/include/ruby/st.h index 1e4bb80686..f35ab43603 100644 --- a/include/ruby/st.h +++ b/include/ruby/st.h @@ -98,6 +98,8 @@ struct st_table { enum st_retval {ST_CONTINUE, ST_STOP, ST_DELETE, ST_CHECK, ST_REPLACE}; +size_t rb_st_table_size(const struct st_table *tbl); +#define st_table_size rb_st_table_size st_table *rb_st_init_table(const struct st_hash_type *); #define st_init_table rb_st_init_table st_table *rb_st_init_table_with_size(const struct st_hash_type *, st_index_t); diff --git a/include/ruby/subst.h b/include/ruby/subst.h index cf48a3909c..d7b9a63050 100644 --- a/include/ruby/subst.h +++ b/include/ruby/subst.h @@ -1,7 +1,6 @@ #ifndef RUBY_SUBST_H /*-*-C++-*-vi:se ft=cpp:*/ #define RUBY_SUBST_H 1 /** - * @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 diff --git a/include/ruby/thread.h b/include/ruby/thread.h index b05537badb..2fa01229e2 100644 --- a/include/ruby/thread.h +++ b/include/ruby/thread.h @@ -10,33 +10,336 @@ * modify this file, provided that the conditions mentioned in the * file COPYING are met. Consult the file for details. */ -#include "ruby/intern.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/intern/thread.h" /* rb_unblock_function_t */ #include "ruby/internal/dllexport.h" -/* flags for rb_nogvl */ +/** + * @name Flags for rb_nogvl() + * + * @{ + */ + +/** + * Passing this flag to rb_nogvl() prevents it from checking interrupts. + * Interrupts can impact your program negatively. For instance consider + * following callback function: + * + * ```CXX + * static inline int fd; // set elsewhere. + * static inline auto callback(auto buf) { + * auto tmp = ruby_xmalloc(BUFSIZ); + * auto ret = ruby_xmalloc(sizeof(ssize_t)); // (a) + * auto n = read(fd, tmp, BUFSIZ); // (b) + * memcpy(buf, tmp, n); // (c) + * memcpy(ret, n, sizeof(n)); + * ruby_xfree(tmp); + * return ret; + * } + * ``` + * + * Here, if it gets interrupted at (a) or (b), `read(2)` is cancelled and this + * function leaks memory (which is not a good thing of course, but...). But if + * it gets interrupted at (c), where `read(2)` is already done, interruption is + * way more catastrophic because what was read gets lost. To reroute this kind + * of problem you should set this flag. And check interrupts elsewhere at your + * own risk. + */ #define RB_NOGVL_INTR_FAIL (0x1) + +/** + * Passing this flag to rb_nogvl() indicates that the passed UBF is + * async-signal-safe. An UBF could be async safe, and that makes things + * simpler. However async unsafe UBFs are just okay. If unsure, you can + * safely leave it unspecified. + * + * @internal + * + * This makes sense only in case of POSIX threads. + */ #define RB_NOGVL_UBF_ASYNC_SAFE (0x2) +/** + * Passing this flag to rb_nogvl() indicates that the passed function + * is safe to offload to a background thread or work pool. In other words, the + * function is safe to run using a fiber scheduler's `blocking_operation_wait`. + * hook. + * + * If your function depends on thread-local storage, or thread-specific data + * operations/data structures, you should not set this flag, as + * these operations may behave differently (or fail) when run in a different + * thread/context (e.g. unlocking a mutex). + */ +#define RB_NOGVL_OFFLOAD_SAFE (0x4) + +/** @} */ + RBIMPL_SYMBOL_EXPORT_BEGIN() +RBIMPL_ATTR_NONNULL((1)) +/** + * (Re-)acquires the GVL. This manoeuvre makes it possible for an out-of-GVL + * routine to one-shot call a ruby method. + * + * What this function does: + * + * 1. Blocks until it acquires the GVL. + * 2. Calls the passed function. + * 3. Releases the GVL. + * 4. Returns what was returned form the passed function. + * + * @param[in] func What to call with GVL. + * @param[in,out] data1 Passed as-is to `func`. + * @return What was returned from `func`. + * @warning `func` must not return a Ruby object. If it did such return + * value would escape from GC's scope; would not be marked. + * @warning Global escapes from this function just yield whatever fatal + * undefined behaviours. You must make sure that `func` does + * not raise, by properly rescuing everything using + * e.g. rb_protect(). + * @warning You cannot convert a non-Ruby thread into a Ruby thread + * using this API. This function makes sense only from inside + * of a rb_thread_call_without_gvl()'s callback. + */ void *rb_thread_call_with_gvl(void *(*func)(void *), void *data1); +RBIMPL_ATTR_NONNULL((1)) +/** + * Allows the passed function to run in parallel with other Ruby threads. + * + * What this function does: + * + * 1. Checks (and handles) pending interrupts. + * 2. Releases the GVL. (Others can run here in parallel...) + * 3. Calls the passed function. + * 4. Blocks until it re-acquires the GVL. + * 5. Checks interrupts that happened between 2 to 4. + * + * In case other threads interfaced with this thread using rb_thread_kill() + * etc., the passed UBF is additionally called. See ::rb_unblock_function_t + * for details. + * + * Unlike rb_thread_call_without_gvl2() this function also reacts to signals + * etc. + * + * @param[in] func A function to call without GVL. + * @param[in,out] data1 Passed as-is to `func`. + * @param[in] ubf An UBF to cancel `func`. + * @param[in,out] data2 Passed as-is to `ubf`. + * @return What `func` returned, or 0 in case `ubf` cancelled `func`. + * @warning You cannot use most of Ruby C APIs like calling methods or + * raising exceptions from any of the functions passed to it. + * If that is dead necessary use rb_thread_call_with_gvl() to + * re-acquire the GVL. + * @warning In short, this API is difficult. @ko1 recommends you to use + * other ways if any. We lack experiences to use this API. If + * you find any corner cases etc., please report it to the + * devs. + * @warning Releasing and re-acquiring the GVL are expensive operations. + * For a short-running `func`, it might be faster to just call + * `func` with blocking everything else. Be sure to benchmark + * your code to see if it is actually worth releasing the GVL. + */ void *rb_thread_call_without_gvl(void *(*func)(void *), void *data1, - rb_unblock_function_t *ubf, void *data2); + rb_unblock_function_t *ubf, void *data2); + +RBIMPL_ATTR_NONNULL((1)) +/** + * Identical to rb_thread_call_without_gvl(), except it does not interface with + * signals etc. As described in #RB_NOGVL_INTR_FAIL, interrupts can hurt you. + * In case this function detects an interrupt, it returns immediately. You can + * record progress of your callback and check it after returning from this + * function. + * + * What this function does: + * + * 1. Checks for pending interrupts and if any, just returns. + * 2. Releases the GVL. (Others can run here in parallel...) + * 3. Calls the passed function. + * 4. Blocks until it re-acquires the GVL. + * + * @param[in] func A function to call without GVL. + * @param[in,out] data1 Passed as-is to `func`. + * @param[in] ubf An UBF to cancel `func`. + * @param[in,out] data2 Passed as-is to `ubf`. + * @return What `func` returned, or 0 in case `func` did not return. + */ void *rb_thread_call_without_gvl2(void *(*func)(void *), void *data1, - rb_unblock_function_t *ubf, void *data2); + rb_unblock_function_t *ubf, void *data2); /* * XXX: unstable/unapproved - out-of-tree code should NOT not depend * on this until it hits Ruby 2.6.1 */ + +RBIMPL_ATTR_NONNULL((1)) +/** + * Identical to rb_thread_call_without_gvl(), except it additionally takes + * "flags" that change the behaviour. + * + * @param[in] func A function to call without GVL. + * @param[in,out] data1 Passed as-is to `func`. + * @param[in] ubf An UBF to cancel `func`. + * @param[in,out] data2 Passed as-is to `ubf`. + * @param[in] flags Flags. + * @return What `func` returned, or 0 in case `func` did not return. + */ void *rb_nogvl(void *(*func)(void *), void *data1, rb_unblock_function_t *ubf, void *data2, int flags); +/** + * @private + * + * @deprecated This macro once was a thing in the old days, but makes no sense + * any longer today. Exists here for backwards compatibility + * only. You can safely forget about it. + */ #define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_AFTER 0x01 + +/** + * @private + * @deprecated It seems even in the old days it made no sense...? + */ #define RUBY_CALL_WO_GVL_FLAG_SKIP_CHECK_INTS_ +/** + * Declare the current Ruby thread should acquire a dedicated + * native thread on M:N thread scheduler. + * + * If a C extension (or a library which the extension relies on) should + * keep to run on a native thread (e.g. using thread-local-storage), + * this function allocates a dedicated native thread for the thread. + * + * @return `false` if the thread already running on a dedicated native + * thread. Otherwise `true`. + */ +bool rb_thread_lock_native_thread(void); + +/** + * Triggered when a new thread is started. + * + * @note The callback will be called *without* the GVL held. + */ +#define RUBY_INTERNAL_THREAD_EVENT_STARTED 1 << 0 + +/** +* Triggered when a thread attempt to acquire the GVL. +* +* @note The callback will be called *without* the GVL held. +*/ +#define RUBY_INTERNAL_THREAD_EVENT_READY 1 << 1 /** acquiring GVL */ + +/** + * Triggered when a thread successfully acquired the GVL. + * + * @note The callback will be called *with* the GVL held. + */ +#define RUBY_INTERNAL_THREAD_EVENT_RESUMED 1 << 2 /** acquired GVL */ + +/** + * Triggered when a thread released the GVL. + * + * @note The callback will be called *without* the GVL held. + */ +#define RUBY_INTERNAL_THREAD_EVENT_SUSPENDED 1 << 3 /** released GVL */ + +/** + * Triggered when a thread exits. + * + * @note The callback will be called *without* the GVL held. + */ +#define RUBY_INTERNAL_THREAD_EVENT_EXITED 1 << 4 /** thread terminated */ + +#define RUBY_INTERNAL_THREAD_EVENT_MASK 0xff /** All Thread events */ + +typedef struct rb_internal_thread_event_data { + VALUE thread; +} rb_internal_thread_event_data_t; + +typedef void (*rb_internal_thread_event_callback)(rb_event_flag_t event, + const rb_internal_thread_event_data_t *event_data, + void *user_data); +typedef struct rb_internal_thread_event_hook rb_internal_thread_event_hook_t; + +/** + * Registers a thread event hook function. + * + * @param[in] func A callback. + * @param[in] events A set of events that `func` should run. + * @param[in] data Passed as-is to `func`. + * @return An opaque pointer to the hook, to unregister it later. + * @note This functionality is a noop on Windows and WebAssembly. + * @note The callback will be called without the GVL held, except for the + * RESUMED event. + * @note Callbacks are not guaranteed to be executed on the native threads + * that corresponds to the Ruby thread. To identify which Ruby thread + * the event refers to, you must use `event_data->thread`. + * @warning This function MUST not be called from a thread event callback. + */ +rb_internal_thread_event_hook_t *rb_internal_thread_add_event_hook( + rb_internal_thread_event_callback func, rb_event_flag_t events, + void *data); + + +/** + * Unregister the passed hook. + * + * @param[in] hook. The hook to unregister. + * @return Whether the hook was found and unregistered. + * @note This functionality is a noop on Windows and WebAssembly. + * @warning This function MUST not be called from a thread event callback. +*/ +bool rb_internal_thread_remove_event_hook( + rb_internal_thread_event_hook_t * hook); + + +typedef int rb_internal_thread_specific_key_t; +#define RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX 8 +/** + * Create a key to store thread specific data. + * + * These APIs are designed for tools using + * rb_internal_thread_event_hook APIs. + * + * Note that only `RB_INTERNAL_THREAD_SPECIFIC_KEY_MAX` keys + * can be created. raises `ThreadError` if exceeded. + * + * Usage: + * // at initialize time: + * int tool_key; // gvar + * Init_tool() { + * tool_key = rb_internal_thread_specific_key_create(); + * } + * + * // at any timing: + * rb_internal_thread_specific_set(thread, tool_key, per_thread_data); + * ... + * per_thread_data = rb_internal_thread_specific_get(thread, tool_key); + */ +rb_internal_thread_specific_key_t rb_internal_thread_specific_key_create(void); + +/** + * Get thread and tool specific data. + * + * This function is async signal safe and thread safe. + */ +void *rb_internal_thread_specific_get(VALUE thread_val, rb_internal_thread_specific_key_t key); + +/** + * Set thread and tool specific data. + * + * This function is async signal safe and thread safe. + */ +void rb_internal_thread_specific_set(VALUE thread_val, rb_internal_thread_specific_key_t key, void *data); + +/** + * Whether the current thread is holding the GVL. + * + * @return true if the current thread is holding the GVL, false otherwise. + */ +int ruby_thread_has_gvl_p(void); + RBIMPL_SYMBOL_EXPORT_END() #endif /* RUBY_THREAD_H */ diff --git a/include/ruby/thread_native.h b/include/ruby/thread_native.h index 343c02c30d..8217a67514 100644 --- a/include/ruby/thread_native.h +++ b/include/ruby/thread_native.h @@ -9,9 +9,7 @@ * 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. - */ - -/* + * * This file contains wrapper APIs for native thread primitives * which Ruby interpreter uses. * @@ -21,7 +19,6 @@ * please use Mutex directly. */ - #if defined(_WIN32) #include <windows.h> typedef HANDLE rb_nativethread_id_t; @@ -31,6 +28,11 @@ typedef union rb_thread_lock_union { CRITICAL_SECTION crit; } rb_nativethread_lock_t; +struct rb_thread_cond_struct { + struct cond_event_entry *next; + struct cond_event_entry *prev; +}; + typedef struct rb_thread_cond_struct rb_nativethread_cond_t; #elif defined(HAVE_PTHREAD_H) @@ -40,33 +42,169 @@ typedef pthread_t rb_nativethread_id_t; typedef pthread_mutex_t rb_nativethread_lock_t; typedef pthread_cond_t rb_nativethread_cond_t; +#elif defined(__wasi__) // no-thread platforms + +typedef struct rb_nativethread_id_t *rb_nativethread_id_t; +typedef struct rb_nativethread_lock_t *rb_nativethread_lock_t; +typedef struct rb_nativethread_cond_t *rb_nativethread_cond_t; + +#elif defined(__DOXYGEN__) + +/** Opaque type that holds an ID of a native thread. */ +struct rb_nativethread_id_t; + +/** Opaque type that holds a lock. */ +struct rb_nativethread_lock_t; + +/** Opaque type that holds a condition variable. */ +struct rb_nativethread_cond_t; + #else #error "unsupported thread type" #endif -RUBY_SYMBOL_EXPORT_BEGIN +RBIMPL_SYMBOL_EXPORT_BEGIN() +/** + * Queries the ID of the native thread that is calling this function. + * + * @return The caller thread's native ID. + */ rb_nativethread_id_t rb_nativethread_self(void); +/** + * Fills the passed lock with an initial value. + * + * @param[out] lock A mutex to initialise. + * @post `lock` is updated to its initial state. + * + * @internal + * + * There is no data structure that analogous to pthread_once_t in ruby. It is + * pretty much tricky (if not impossible) to properly initialise a mutex + * exactly once. + */ void rb_nativethread_lock_initialize(rb_nativethread_lock_t *lock); + +/** + * Destroys the passed mutex. + * + * @param[out] lock A mutex to kill. + * @post `lock` is no longer eligible for other functions. + * + * @internal + * + * It is an undefined behaviour (see `pthread_mutex_destroy(3posix)`) to + * destroy a locked mutex. So it has to be unlocked. But an unlocked mutex + * can of course be locked by another thread. That's the ultimate reason why + * we do mutex. There is an inevitable race condition here. 2017 edition of + * IEEE 1003.1 issue 7 says in its rationale that "care must be taken". Care? + * How? + * + * @shyouhei thinks that POSIX is broken by design. + */ void rb_nativethread_lock_destroy(rb_nativethread_lock_t *lock); + +/** + * Blocks until the current thread obtains a lock. + * + * @param[out] lock A mutex to lock. + * @post `lock` is owned by the current native thread. + */ void rb_nativethread_lock_lock(rb_nativethread_lock_t *lock); + +/** + * Releases a lock. + * + * @param[out] lock A mutex to unlock. + * @pre `lock` is owned by the current native thread. + * @post `lock` is not owned by the current native thread. + */ void rb_nativethread_lock_unlock(rb_nativethread_lock_t *lock); +/** @alias{rb_nativethread_lock_lock} */ void rb_native_mutex_lock(rb_nativethread_lock_t *lock); + +/** + * Identical to rb_native_mutex_lock(), except it doesn't block in case + * rb_native_mutex_lock() would. + * + * @param[out] lock A mutex to lock. + * @retval 0 `lock` is successfully owned by the current thread. + * @retval EBUSY `lock` is owned by someone else. + */ int rb_native_mutex_trylock(rb_nativethread_lock_t *lock); + +/** @alias{rb_nativethread_lock_unlock} */ void rb_native_mutex_unlock(rb_nativethread_lock_t *lock); + +/** @alias{rb_nativethread_lock_initialize} */ void rb_native_mutex_initialize(rb_nativethread_lock_t *lock); + +/** @alias{rb_nativethread_lock_destroy} */ void rb_native_mutex_destroy(rb_nativethread_lock_t *lock); +/** + * Signals a condition variable. + * + * @param[out] cond A condition variable to ping. + * @post More than one threads waiting for `cond` gets signalled. + * @note This function can spuriously wake multiple threads up. + * `pthread_cond_signal(3posix)` says it can even be "impossible + * to avoid the unblocking of more than one thread blocked on a + * condition variable". Just brace spurious wakeups. + */ void rb_native_cond_signal(rb_nativethread_cond_t *cond); + +/** + * Signals a condition variable. + * + * @param[out] cond A condition variable to ping. + * @post All threads waiting for `cond` gets signalled. + */ void rb_native_cond_broadcast(rb_nativethread_cond_t *cond); + +/** + * Waits for the passed condition variable to be signalled. + * + * @param[out] cond A condition variable to wait. + * @param[out] mutex A mutex. + * @pre `mutex` is owned by the current thread. + * @post `mutex` is owned by the current thread. + * @note This can wake up spuriously. + */ void rb_native_cond_wait(rb_nativethread_cond_t *cond, rb_nativethread_lock_t *mutex); + +/** + * Identical to rb_native_cond_wait(), except it additionally takes timeout in + * msec resolution. Timeouts can be detected by catching exceptions. + * + * @param[out] cond A condition variable to wait. + * @param[out] mutex A mutex. + * @param[in] msec Timeout. + * @exception rb_eSystemCallError `Errno::ETIMEDOUT` for timeout. + * @pre `mutex` is owned by the current thread. + * @post `mutex` is owned by the current thread. + * @note This can wake up spuriously. + */ void rb_native_cond_timedwait(rb_nativethread_cond_t *cond, rb_nativethread_lock_t *mutex, unsigned long msec); + +/** + * Fills the passed condition variable with an initial value. + * + * @param[out] cond A condition variable to initialise. + * @post `cond` is updated to its initial state. + */ void rb_native_cond_initialize(rb_nativethread_cond_t *cond); -void rb_native_cond_destroy(rb_nativethread_cond_t *cond); -RUBY_SYMBOL_EXPORT_END +/** + * Destroys the passed condition variable. + * + * @param[out] cond A condition variable to kill. + * @post `cond` is no longer eligible for other functions. + */ +void rb_native_cond_destroy(rb_nativethread_cond_t *cond); +RBIMPL_SYMBOL_EXPORT_END() #endif diff --git a/include/ruby/util.h b/include/ruby/util.h index 660f91de8e..12e69c4b80 100644 --- a/include/ruby/util.h +++ b/include/ruby/util.h @@ -9,46 +9,230 @@ * 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 DO NOT ADD RANDOM GARBAGES IN THIS FILE! Contents of this file + * reside here for historical reasons. Find a right place for your + * API! */ #include "ruby/internal/config.h" + +#ifdef STDC_HEADERS +# include <stddef.h> /* size_t */ +#endif + +#ifdef HAVE_SYS_TYPES_H +# include <sys/types.h> /* ssize_t */ +#endif + +#include "ruby/internal/attr/noalias.h" +#include "ruby/internal/attr/nodiscard.h" +#include "ruby/internal/attr/nonnull.h" +#include "ruby/internal/attr/restrict.h" +#include "ruby/internal/attr/returns_nonnull.h" #include "ruby/internal/dllexport.h" #include "ruby/defines.h" RBIMPL_SYMBOL_EXPORT_BEGIN() +/** an approximation of ceil(n * log10(2)), up to 1,048,576 (1<<20) + * without overflow within 32-bit calculation + */ #define DECIMAL_SIZE_OF_BITS(n) (((n) * 3010 + 9998) / 9999) -/* an approximation of ceil(n * log10(2)), up to 65536 at least */ +/** an approximation of decimal representation size for n-bytes */ +#define DECIMAL_SIZE_OF_BYTES(n) DECIMAL_SIZE_OF_BITS((n) * CHAR_BIT) + +/** + * An approximation of decimal representation size. `expr` may be a + * type name + */ +#define DECIMAL_SIZE_OF(expr) DECIMAL_SIZE_OF_BYTES(sizeof(expr)) + +/** + * Character to number mapping like `'a'` -> `10`, `'b'` -> `11` etc. For + * punctuation etc., the value is -1. "36" terminology comes from the fact + * that this is the table behind `str.to_i(36)`. + */ RUBY_EXTERN const signed char ruby_digit36_to_number_table[]; + +/** + * Characters that Ruby accepts as hexadecimal digits. This is `/\h/` expanded + * into an array. + */ RUBY_EXTERN const char ruby_hexdigits[]; +/** + * Scans the passed string, assuming the string is a textual representation of + * an integer. Stops when encountering something non-digit for the passed + * base. + * + * @note This does not understand minus sign. + * @note This does not understand e.g. `0x` prefix. + * @note It is a failure to pass `0` to `base`, unlike ruby_strtoul(). + * @param[in] str Target string of digits to interpret. + * @param[in] len Number of bytes of `str`, or -1 to detect `NUL`. + * @param[in] base Base, `2` to `36` inclusive. + * @param[out] retlen Return value buffer. + * @param[out] overflow Return value buffer. + * @return Interpreted numeric representation of `str`. + * @post `retlen` is the number of bytes scanned so far. + * @post `overflow` is set to true if the string represents something + * bigger than `ULONG_MAX`. Something meaningful still returns; + * which is the designed belabour of C's unsigned arithmetic. + */ unsigned long ruby_scan_digits(const char *str, ssize_t len, int base, size_t *retlen, int *overflow); + +/** @old{ruby_scan_oct} */ #define scan_oct(s,l,e) ((int)ruby_scan_oct((s),(l),(e))) -unsigned long ruby_scan_oct(const char *, size_t, size_t *); + +RBIMPL_ATTR_NOALIAS() +RBIMPL_ATTR_NONNULL(()) +/** + * Interprets the passed string as an octal unsigned integer. Stops when + * encounters something not understood. + * + * @param[in] str C string to scan. + * @param[in] len Length of `str`. + * @param[out] consumed Return value buffer. + * @return Parsed integer. + * @post `ret` is the number of characters read. + * + * @internal + * + * No consideration is made for integer overflows. As the return value is + * unsigned this function has fully defined behaviour, but you cannot know if + * there was an integer wrap-around or not. + */ +unsigned long ruby_scan_oct(const char *str, size_t len, size_t *consumed); + +/** @old{ruby_scan_hex} */ #define scan_hex(s,l,e) ((int)ruby_scan_hex((s),(l),(e))) -unsigned long ruby_scan_hex(const char *, size_t, size_t *); +RBIMPL_ATTR_NONNULL(()) +/** + * Interprets the passed string a hexadecimal unsigned integer. Stops when + * encounters something not understood. + * + * @param[in] str C string to scan. + * @param[in] len Length of `str`. + * @param[out] ret Return value buffer. + * @return Parsed integer. + * @post `ret` is the number of characters read. + * + * @internal + * + * No consideration is made for integer overflows. As the return value is + * unsigned this function has fully defined behaviour, but you cannot know if + * there was an integer wrap-around or not. + */ +unsigned long ruby_scan_hex(const char *str, size_t len, size_t *ret); + +/** + * Reentrant implementation of quick sort. If your system provides something + * (like C11 qsort_s), this is a thin wrapper of that routine. Otherwise + * resorts to our own version. + */ #ifdef HAVE_GNU_QSORT_R # define ruby_qsort qsort_r #else void ruby_qsort(void *, const size_t, const size_t, - int (*)(const void *, const void *, void *), void *); + int (*)(const void *, const void *, void *), void *); #endif -void ruby_setenv(const char *, const char *); -void ruby_unsetenv(const char *); +RBIMPL_ATTR_NONNULL((1)) +/** + * Sets an environment variable. In case of POSIX this is a wrapper of + * `setenv(3)`. But there are systems which lack one. We try hard emulating. + * + * @param[in] key An environment variable. + * @param[in] val A value to be associated with `key`, or 0. + * @exception rb_eSystemCallError `setenv(3)` failed for some reason. + * @post Environment variable `key` is created if necessary. Its value + * is updated to be `val`. + */ +void ruby_setenv(const char *key, const char *val); + +RBIMPL_ATTR_NONNULL(()) +/** + * Deletes the passed environment variable, if any. + * + * @param[in] key An environment variable. + * @exception rb_eSystemCallError `unsetenv(3)` failed for some reason. + * @post Environment variable `key` does not exist. + */ +void ruby_unsetenv(const char *key); + +RBIMPL_ATTR_NODISCARD() +RBIMPL_ATTR_RESTRICT() +RBIMPL_ATTR_RETURNS_NONNULL() +RBIMPL_ATTR_NONNULL(()) +/** + * This is our own version of `strdup(3)` that uses ruby_xmalloc() instead of + * system malloc (benefits our GC). + * + * @param[in] str Target C string to duplicate. + * @return An allocated C string holding the identical contents. + * @note Return value must be discarded using ruby_xfree(). + */ +char *ruby_strdup(const char *str); -char *ruby_strdup(const char *); #undef strdup +/** + * @alias{ruby_strdup} + * + * @internal + * + * @shyouhei doesn't think it is a wise idea. ruby_strdup()'s return value + * must be passed to ruby_xfree(), but this macro makes it almost impossible. + */ #define strdup(s) ruby_strdup(s) +RBIMPL_ATTR_NODISCARD() +RBIMPL_ATTR_RESTRICT() +RBIMPL_ATTR_RETURNS_NONNULL() +/** + * This is our own version of `getcwd(3)` that uses ruby_xmalloc() instead of + * system malloc (benefits our GC). + * + * @return An allocated C string holding the process working directory. + * @note Return value must be discarded using ruby_xfree(). + */ char *ruby_getcwd(void); -double ruby_strtod(const char *, char **); +RBIMPL_ATTR_NONNULL((1)) +/** + * Our own locale-insensitive version of `strtod(3)`. The conversion is done + * as if the current locale is set to the "C" locale, no matter actual runtime + * locale settings. + * + * @param[in] str Decimal or hexadecimal representation of a floating + * point number. + * @param[out] endptr NULL, or an arbitrary pointer (overwritten on return). + * @return Converted number. + * @post If `endptr` is not NULL, it is updated to point the first such + * byte where conversion failed. + * @note This function sets `errno` on failure. + * - `ERANGE`: Converted integer is out of range of `double`. + * @see William D. Clinger, "How to Read Floating Point Numbers + * Accurately" in Proc. ACM SIGPLAN '90, pp. 92-101. + * https://doi.org/10.1145/93542.93557 + */ +double ruby_strtod(const char *str, char **endptr); + #undef strtod +/** @alias{ruby_strtod} */ #define strtod(s,e) ruby_strtod((s),(e)) -void ruby_each_words(const char *, void (*)(const char*, int, void*), void *); +RBIMPL_ATTR_NONNULL((2)) +/** + * Scans the passed string, with calling the callback function every time it + * encounters a "word". A word here is a series of characters separated by + * either a space (of IEEE 1003.1 section 7.3.1.1), or a `','`. + * + * @param[in] str Target string to split into each words. + * @param[in] func Callback function. + * @param[in,out] argv Passed as-is to `func`. + */ +void ruby_each_words(const char *str, void (*func)(const char *word, int len, void *argv), void *argv); RBIMPL_SYMBOL_EXPORT_END() diff --git a/include/ruby/version.h b/include/ruby/version.h index d25008fad9..5bb381cea2 100644 --- a/include/ruby/version.h +++ b/include/ruby/version.h @@ -20,40 +20,139 @@ * check the features with mkmf.rb instead. */ -/* The origin. */ +/** + * @name The origin. + * + * These information never change. Just written here to remember. + * + * @{ + */ + +/** Author of this project. */ #define RUBY_AUTHOR "Yukihiro Matsumoto" + +/** Ruby's birth year. */ #define RUBY_BIRTH_YEAR 1993 + +/** Ruby's birth month. */ #define RUBY_BIRTH_MONTH 2 + +/** Ruby's birth day. */ #define RUBY_BIRTH_DAY 24 -/* API version */ -#define RUBY_API_VERSION_MAJOR 3 +/** @} */ + +/** + * @name The API version. + * + * API version is different from binary version. These numbers are for API + * stability. When you have distinct API versions x and y, you cannot expect + * codes targeted to x also works for y. + * + * However let us repeat here that it's a BAD idea to check + * #RUBY_API_VERSION_CODE form extension libraries. Different API versions are + * just different. There is no such thing like upper compatibility. + * + * @{ + */ + +/** + * Major version. This digit changes sometimes for various reasons, but that + * doesn't mean a total rewrite. Practically when it comes to API versioning, + * major and minor version changes are equally catastrophic. + */ +#define RUBY_API_VERSION_MAJOR 4 + +/** + * Minor version. As of writing this version changes annually. Greater + * version doesn't mean "better"; they just mean years passed. + */ #define RUBY_API_VERSION_MINOR 1 + +/** + * Teeny version. This digit is kind of reserved these days. Kept 0 for the + * entire 2.x era. Waiting for future uses. + */ #define RUBY_API_VERSION_TEENY 0 + +/** + * This macro is API versions encoded into a C integer. + * + * @note Use mkmf. + * @note Don't rely on it. + */ #define RUBY_API_VERSION_CODE (RUBY_API_VERSION_MAJOR*10000+RUBY_API_VERSION_MINOR*100+RUBY_API_VERSION_TEENY) +/** @} */ + #ifdef RUBY_EXTERN /* Internal note: this file could be included from verconf.mk _before_ * generating config.h, on Windows. The #ifdef above is to trick such * situation. */ RBIMPL_SYMBOL_EXPORT_BEGIN() -/* - * Interfaces from extension libraries. +/** + * @name Interfaces from extension libraries. * * Before using these infos, think thrice whether they are really * necessary or not, and if the answer was yes, think twice a week * later again. + * + * @{ */ + +/** API versions, in { major, minor, teeny } order. */ RUBY_EXTERN const int ruby_api_version[3]; + +/** + * Stringised version. + * + * @note This is the runtime version, not the API version. For instance it + * was `"2.5.9"` when ::ruby_api_version was `{ 2, 5, 0 }`. + */ RUBY_EXTERN const char ruby_version[]; + +/** Date of release, in a C string. */ RUBY_EXTERN const char ruby_release_date[]; + +/** + * Target platform identifier, in a C string. + * + * @note Seasoned UNIX programmers should beware that this "platform + * identifier" is our invention; not always identical to so-called + * target triplets that GNU systems use. For instance on @shyouhei's + * machine, ::ruby_platform is `"x64_64-linux"` while its target triplet + * is `x86_64-pc-linux-gnu`. + * @note Note also that we support Windows. + */ RUBY_EXTERN const char ruby_platform[]; + +/** + * This is a monotonic increasing integer that describes specific "patch" + * level. You can know the exact changeset your binary is running by this info + * (and ::ruby_version), unless this is -1. -1 means there is no release yet + * for the version; ruby is actively developed. 0 means the initial GA version. + */ RUBY_EXTERN const int ruby_patchlevel; + +/** + * This is what `ruby -v` prints to the standard error. Something like: + * `"ruby 2.5.9p229 (2021-04-05 revision 67829) [x86_64-linux]"`. This doesn't + * include runtime options like a JIT being enabled. + */ RUBY_EXTERN const char ruby_description[]; + +/** Copyright notice. */ RUBY_EXTERN const char ruby_copyright[]; + +/** + * This is just `"ruby"` for us. But different implementations can have + * different strings here. + */ RUBY_EXTERN const char ruby_engine[]; +/** @} */ + RBIMPL_SYMBOL_EXPORT_END() #endif diff --git a/include/ruby/vm.h b/include/ruby/vm.h index 7bdd567453..8779780952 100644 --- a/include/ruby/vm.h +++ b/include/ruby/vm.h @@ -9,21 +9,26 @@ * 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. + * + * We planned to have multiple VMs run side-by-side. The API here was a + * preparation of that feature. The topic branch was eventually abandoned, and + * we now have Ractor. This file is kind of obsolescent. */ #include "ruby/internal/dllexport.h" RBIMPL_SYMBOL_EXPORT_BEGIN() -/* Place holder. - * - * We will prepare VM creation/control APIs on 1.9.2 or later. - * +/** + * The opaque struct to hold VM internals. Its fields are intentionally hidden + * from extension libraries because it changes drastically time to time. */ - -/* VM type declaration */ typedef struct rb_vm_struct ruby_vm_t; -/* core API */ +/** + * Destructs the passed VM. You don't have to call this API directly now, + * because there is no way to create one. There is only one VM at one time. + * ruby_stop() should just suffice. + */ int ruby_vm_destruct(ruby_vm_t *vm); /** @@ -44,6 +49,13 @@ int ruby_vm_destruct(ruby_vm_t *vm); */ void ruby_vm_at_exit(void(*func)(ruby_vm_t *)); +/** + * Returns whether the Ruby VM will free all memory at shutdown. + * + * @return true if free-at-exit is enabled, false otherwise. + */ +bool ruby_free_at_exit_p(void); + RBIMPL_SYMBOL_EXPORT_END() #endif /* RUBY_VM_H */ diff --git a/include/ruby/win32.h b/include/ruby/win32.h index c8ae599f2f..ae11a61481 100644 --- a/include/ruby/win32.h +++ b/include/ruby/win32.h @@ -19,11 +19,6 @@ RUBY_SYMBOL_EXPORT_BEGIN */ /* - * Definitions for NT port of Perl - */ - - -/* * Ok now we can include the normal include files. */ @@ -35,14 +30,10 @@ extern "C++" { /* template without extern "C++" */ #if !defined(_WIN64) && !defined(WIN32) #define WIN32 #endif -#if defined(_MSC_VER) && _MSC_VER <= 1200 -#include <windows.h> -#endif #include <winsock2.h> #include <ws2tcpip.h> -#if !defined(_MSC_VER) || _MSC_VER >= 1400 +#include <mswsock.h> #include <iphlpapi.h> -#endif #if defined(__cplusplus) && defined(_MSC_VER) } #endif @@ -63,13 +54,7 @@ extern "C++" { /* template without extern "C++" */ #include <direct.h> #include <process.h> #include <time.h> -#if defined(__cplusplus) && defined(_MSC_VER) && _MSC_VER == 1200 -extern "C++" { /* template without extern "C++" */ -#endif #include <math.h> -#if defined(__cplusplus) && defined(_MSC_VER) && _MSC_VER == 1200 -} -#endif #include <signal.h> #include <sys/stat.h> #include <sys/types.h> @@ -130,8 +115,30 @@ typedef unsigned int uintptr_t; #define O_SHARE_DELETE 0x20000000 /* for rb_w32_open(), rb_w32_wopen() */ typedef int clockid_t; -#define CLOCK_REALTIME 0 -#define CLOCK_MONOTONIC 1 + +/* + * Since we use our versions in win32/win32.c, not to depend on yet + * another DLL, prefix our versions not to conflict with inline + * versions provided in time.h. + */ +#define clock_gettime rb_w32_clock_gettime +#define clock_getres rb_w32_clock_getres + +#ifndef CLOCK_REALTIME +# define CLOCK_REALTIME 0 +#endif +#ifndef CLOCK_MONOTONIC +# define CLOCK_MONOTONIC 1 +#endif +#ifndef CLOCK_PROCESS_CPUTIME_ID +# define CLOCK_PROCESS_CPUTIME_ID 2 +#endif +#ifndef CLOCK_THREAD_CPUTIME_ID +# define CLOCK_THREAD_CPUTIME_ID 3 +#endif +#ifndef CLOCK_REALTIME_COARSE +# define CLOCK_REALTIME_COARSE 4 +#endif #undef utime #undef lseek @@ -152,13 +159,19 @@ typedef int clockid_t; #define open rb_w32_uopen #define close(h) rb_w32_close(h) #define fclose(f) rb_w32_fclose(f) -#define read(f, b, s) rb_w32_read(f, b, s) -#define write(f, b, s) rb_w32_write(f, b, s) +#define read(f, b, s) rb_w32_read(f, b, s) +#define write(f, b, s) rb_w32_write(f, b, s) +#define pread(f, b, s, o) rb_w32_pread(f, b, s, o) +#define pwrite(f, b, s, o) rb_w32_pwrite(f, b, s, o) #define getpid() rb_w32_getpid() +#undef HAVE_GETPPID +#define HAVE_GETPPID 1 #define getppid() rb_w32_getppid() #define sleep(x) rb_w32_Sleep((x)*1000) #define Sleep(msec) (void)rb_w32_Sleep(msec) +#undef HAVE_EXECV +#define HAVE_EXECV 1 #undef execv #define execv(path,argv) rb_w32_uaspawn(P_OVERLAY,path,argv) #undef isatty @@ -191,7 +204,6 @@ struct stati128 { long st_ctimensec; }; -#define off_t __int64 #define stat stati128 #undef SIZEOF_STRUCT_STAT_ST_INO #define SIZEOF_STRUCT_STAT_ST_INO sizeof(unsigned __int64) @@ -250,7 +262,6 @@ struct ifaddrs { #endif extern void rb_w32_sysinit(int *, char ***); -extern DWORD rb_w32_osid(void); extern int flock(int fd, int oper); extern int rb_w32_io_cancelable_p(int); extern int rb_w32_is_socket(int); @@ -294,12 +305,15 @@ extern void rb_w32_free_environ(char **); extern int rb_w32_map_errno(DWORD); extern const char *WSAAPI rb_w32_inet_ntop(int,const void *,char *,size_t); extern int WSAAPI rb_w32_inet_pton(int,const char *,void *); -extern DWORD rb_w32_osver(void); + +RBIMPL_ATTR_DEPRECATED(("as Windows 9x is not supported already")) +static inline DWORD rb_w32_osid(void) {return VER_PLATFORM_WIN32_NT;} +RBIMPL_ATTR_DEPRECATED(("by Windows Version Helper APIs")) +extern DWORD rb_w32_osver(void); extern int rb_w32_uchown(const char *, int, int); extern int rb_w32_ulink(const char *, const char *); extern ssize_t rb_w32_ureadlink(const char *, char *, size_t); -extern ssize_t rb_w32_wreadlink(const WCHAR *, WCHAR *, size_t); extern int rb_w32_usymlink(const char *src, const char *link); extern int gettimeofday(struct timeval *, struct timezone *); extern int clock_gettime(clockid_t, struct timespec *); @@ -309,7 +323,9 @@ extern rb_pid_t wait(int *); extern rb_pid_t rb_w32_uspawn(int, const char *, const char*); extern rb_pid_t rb_w32_uaspawn(int, const char *, char *const *); extern rb_pid_t rb_w32_uaspawn_flags(int, const char *, char *const *, DWORD); -extern int kill(int, int); +#undef HAVE_KILL +#define HAVE_KILL 1 +extern int kill(rb_pid_t, int); extern int fcntl(int, int, ...); extern int rb_w32_set_nonblock(int); extern rb_pid_t rb_w32_getpid(void); @@ -329,7 +345,7 @@ extern int rb_w32_dup2(int, int); #include <float.h> -#if defined _MSC_VER && _MSC_VER >= 1800 && defined INFINITY +#if defined _MSC_VER && defined INFINITY #pragma warning(push) #pragma warning(disable:4756) static inline float @@ -388,6 +404,7 @@ scalb(double a, long b) #endif #define S_IFLNK 0xa000 +#define S_IFSOCK 0xc000 /* * define this so we can do inplace editing @@ -395,9 +412,9 @@ scalb(double a, long b) #define SUFFIX -extern int rb_w32_ftruncate(int fd, off_t length); -extern int rb_w32_truncate(const char *path, off_t length); -extern int rb_w32_utruncate(const char *path, off_t length); +extern int rb_w32_ftruncate(int fd, rb_off_t length); +extern int rb_w32_truncate(const char *path, rb_off_t length); +extern int rb_w32_utruncate(const char *path, rb_off_t length); #undef HAVE_FTRUNCATE #define HAVE_FTRUNCATE 1 @@ -411,11 +428,6 @@ extern int rb_w32_utruncate(const char *path, off_t length); #define HAVE_TRUNCATE 1 #define truncate rb_w32_utruncate -#if defined(_MSC_VER) && _MSC_VER >= 1400 && _MSC_VER < 1800 -#define strtoll _strtoi64 -#define strtoull _strtoui64 -#endif - /* * stubs */ @@ -647,6 +659,8 @@ extern char *rb_w32_strerror(int); #undef setsockopt #define setsockopt(s, v, n, o, l) rb_w32_setsockopt(s, v, n, o, l) +#undef HAVE_SHUTDOWN +#define HAVE_SHUTDOWN 1 #undef shutdown #define shutdown(s, h) rb_w32_shutdown(s, h) @@ -694,10 +708,10 @@ extern char *rb_w32_strerror(int); #endif struct tms { - long tms_utime; - long tms_stime; - long tms_cutime; - long tms_cstime; + long tms_utime; + long tms_stime; + long tms_cutime; + long tms_cstime; }; int rb_w32_times(struct tms *); @@ -714,7 +728,9 @@ int rb_w32_fclose(FILE*); int rb_w32_pipe(int[2]); ssize_t rb_w32_read(int, void *, size_t); ssize_t rb_w32_write(int, const void *, size_t); -off_t rb_w32_lseek(int, off_t, int); +ssize_t rb_w32_pread(int, void *, size_t, rb_off_t offset); +ssize_t rb_w32_pwrite(int, const void *, size_t, rb_off_t offset); +rb_off_t rb_w32_lseek(int, rb_off_t, int); int rb_w32_uutime(const char *, const struct utimbuf *); int rb_w32_uutimes(const char *, const struct timeval *); int rb_w32_uutimensat(int /* must be AT_FDCWD */, const char *, const struct timespec *, int /* must be 0 */); @@ -796,6 +812,25 @@ double rb_w32_pow(double x, double y); #define pow rb_w32_pow #endif +// mmap tiny emulation +#define MAP_FAILED ((void *)-1) + +#define PROT_READ 0x01 +#define PROT_WRITE 0x02 +#define PROT_EXEC 0x04 + +#define MAP_PRIVATE 0x0002 +#define MAP_ANON 0x1000 +#define MAP_ANONYMOUS MAP_ANON + +extern void *rb_w32_mmap(void *, size_t, int, int, int, rb_off_t); +extern int rb_w32_munmap(void *, size_t); +extern int rb_w32_mprotect(void *, size_t, int); + +#define mmap(a, l, p, f, d, o) rb_w32_mmap(a, l, p, f, d, o) +#define munmap(a, l) rb_w32_munmap(a, l) +#define mprotect(a, l, prot) rb_w32_mprotect(a, l, prot) + #if defined(__cplusplus) #if 0 { /* satisfy cc-mode */ |