#$@%#$%!

Ngiler SH3LL 360
: / opt / alt / ruby31 / include / ruby / internal / core /

Information Server
MySQL : OFF Perl : OFF CURL : ON WGET : OFF PKEXEC : OFF

Directive	Local Value
IP Address	162.0.209.101
System	Linux premium169.web-hosting.com 4.18.0-553.50.1.lve.el8.x86_64 #1 SMP Thu Apr 17 19:10:24 UTC 2025 x86_64
User	luxeelil
PHP Version	8.0.30
Software	LiteSpeed
Doc root	Writable

Edit File : rarray.h \| Size : 17.95 KB
#ifndef RBIMPL_RARRAY_H /--C++--vi:se ft=cpp:/ #define RBIMPL_RARRAY_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 struct ::RArray. / #include "ruby/internal/arithmetic/long.h" #include "ruby/internal/attr/artificial.h" #include "ruby/internal/attr/constexpr.h" #include "ruby/internal/attr/maybe_unused.h" #include "ruby/internal/attr/pure.h" #include "ruby/internal/cast.h" #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/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. * @return The passed object casted to ::RArray. / #define RARRAY(obj) RBIMPL_CAST((struct RArray )(obj)) /** @cond INTERNAL_MACRO / #define RARRAY_EMBED_FLAG RARRAY_EMBED_FLAG #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) \|\| \ defined(__FCC__) \|\| defined(__FCC_VERSION) / workaround for old version of Fujitsu C Compiler (fcc) / # define FIX_CONST_VALUE_PTR(x) ((const VALUE )(x)) #else # define FIX_CONST_VALUE_PTR(x) (x) #endif #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 / /* * @private * * Bits that you can set to ::RBasic::flags. * * @warning These enums are not the only bits we use for arrays. * * @internal * * Unlike strings, flag usages for arrays are scattered across the entire * source codes. @shyouhei doesn't know the complete list. But what is listed * here is at least incomplete. / enum ruby_rarray_flags { /* * 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 * struct ::RArray for storing its contents. 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 * SEGV. Also, internal structures of an array change * dynamically and transparently throughout of its lifetime. * Don't assume it being persistent. * * @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_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 * ::RArray::ary. * * @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_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 }; /* * This is an enum because GDB wants it (rather than a macro). People need not * bother. / 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) }; /* Ruby's array. / struct RArray { /* Basic part, including flags and class. / struct RBasic basic; /* Array's specific fields. / union { /* * Arrays that use separated memory region for elements use this * pattern. / struct { /* Number of elements of the array. / long len; /* Auxiliary info. / union { /* * Capacity of `ptr`. A continuous memory region of at least `capa` elements is expected to exist at `ptr`. This can be bigger than `len`. / long capa; /* * Parent of the array. Nowadays arrays can share their * backend memory regions each other, constructing gigantic * nest of objects. This situation is called "shared", and * this is the field to control such properties. / #if defined(__clang__) / <- clang++ is sane / \|\| \ !defined(__cplusplus) / <- C99 is sane / \|\| \ (__cplusplus > 199711L) / <- C++11 is sane / const #endif VALUE shared_root; } aux; /* * Pointer to the C array that holds the elements of the array. In * the old days each array had dedicated memory regions. That is * no longer true today, but there still are arrays of such * properties. This field could be used to point such things. / const VALUE ptr; } heap; /** * Embedded elements. When an array is short enough, it uses this area * to store its elements. In this case the length is encoded into the * flags. / const VALUE ary[RARRAY_EMBED_LEN_MAX]; } as; }; RBIMPL_SYMBOL_EXPORT_BEGIN() /* * @private * * Declares a section of code where raw pointers are used. This is an * implementation detail of #RARRAY_PTR_USE. People don't use it directly. * * @param[in] ary An object of ::RArray. * @return `ary`'s backend C array. / VALUE rb_ary_ptr_use_start(VALUE ary); /** * @private * * Declares an end of a section formerly started by rb_ary_ptr_use_start(). * This is an implementation detail of #RARRAY_PTR_USE. People don't use it * directly. * * @param[in] a An object of ::RArray. / 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() RBIMPL_ATTR_ARTIFICIAL() /* * Queries the length of the array. * * @param[in] ary Array in question. * @return Its number of elements. * @pre `ary` must be an instance of ::RArray, and must has its * ::RARRAY_EMBED_FLAG flag set. * * @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 RARRAY_EMBED_LEN(VALUE ary) { RBIMPL_ASSERT_TYPE(ary, RUBY_T_ARRAY); RBIMPL_ASSERT_OR_ASSUME(RB_FL_ANY_RAW(ary, RARRAY_EMBED_FLAG)); VALUE f = RBASIC(ary)->flags; f &= RARRAY_EMBED_LEN_MASK; f >>= RARRAY_EMBED_LEN_SHIFT; return RBIMPL_CAST((long)f); } RBIMPL_ATTR_PURE_UNLESS_DEBUG() /* * Queries the length of the array. * * @param[in] a Array in question. * @return Its number of elements. * @pre `a` must be an instance of ::RArray. / static inline long rb_array_len(VALUE a) { RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY); if (RB_FL_ANY_RAW(a, RARRAY_EMBED_FLAG)) { return RARRAY_EMBED_LEN(a); } else { return RARRAY(a)->as.heap.len; } } RBIMPL_ATTR_ARTIFICIAL() /* * Identical to rb_array_len(), except it differs for the return type. * * @param[in] ary Array in question. * @exception rb_eRangeError Too long. * @return Its number of elements. * @pre `ary` must be an instance of ::RArray. * * @internal * * This API seems redundant but has actual usages. / static inline int RARRAY_LENINT(VALUE ary) { return rb_long2int(RARRAY_LEN(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 * * 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. / static inline const VALUE rb_array_const_ptr_transient(VALUE a) { RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY); if (RB_FL_ANY_RAW(a, RARRAY_EMBED_FLAG)) { return FIX_CONST_VALUE_PTR(RARRAY(a)->as.ary); } else { return FIX_CONST_VALUE_PTR(RARRAY(a)->as.heap.ptr); } } #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 { \ RBIMPL_ASSERT_TYPE((ary), RUBY_T_ARRAY); \ const VALUE rbimpl_ary = (ary); \ VALUE var = rb_array_ptr_use_start(rbimpl_ary, (flag)); \ expr; \ rb_array_ptr_use_end(rbimpl_ary, (flag)); \ } 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. * * ```CXX * const auto ary = rb_eval_string("[...]"); * const auto len = RARRAY_LENINT(ary); * const auto symwrite = rb_intern("write"); * * RARRAY_PTR_USE(ary, ptr, { * rb_funcallv(rb_stdout, symwrite, len, ptr); * }); * ``` * * @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`. * * @internal * * For historical reasons use of this macro is not enforced. There are * extension libraries in the wild which call RARRAY_PTR() without it. We want * 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) /* * Wild use of a C pointer. This function accesses the backend storage * directly. This is slower than #RARRAY_PTR_USE_TRANSIENT. It exercises * extra manoeuvres to protect our generational GC. Use of this function is * considered archaic. Use a modern way instead. * * @param[in] ary An object of ::RArray. * @return The backend C array. * * @internal * * That said... there are extension libraries in the wild who uses it. We * cannot but continue supporting. / static inline VALUE RARRAY_PTR(VALUE ary) { RBIMPL_ASSERT_TYPE(ary, RUBY_T_ARRAY); VALUE tmp = RB_OBJ_WB_UNPROTECT_FOR(ARRAY, ary); return RBIMPL_CAST((VALUE )RARRAY_CONST_PTR(tmp)); } /* * Assigns an object in an array. * * @param[out] ary Destination array object. * @param[in] i Index of `ary`. * @param[in] v Arbitrary ruby object. * @pre `ary` must be an instance of ::RArray. * @pre `ary`'s length must be longer than or equal to `i`. * @pre `i` must be greater than or equal to zero. * @post `ary`'s `i`th element is set to `v`. / static inline void RARRAY_ASET(VALUE ary, long i, VALUE v) { RARRAY_PTR_USE_TRANSIENT(ary, ptr, RB_OBJ_WRITE(ary, &ptr[i], v)); } /* * @deprecated * * :FIXME: we want to convert RARRAY_AREF into an inline function (to add rooms * for more sanity checks). However there were situations where the address of * this macro is taken i.e. &RARRAY_AREF(...). They cannot be possible if this * is not a macro. Such usages are abuse, and we eliminated them internally. * However we are afraid of similar things to remain in the wild. This macro * 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] #endif / RBIMPL_RARRAY_H */ Back

Edit File : rarray.h | Size : 17.95 KB

#ifndef RBIMPL_RARRAY_H                              /*-*-C++-*-vi:se ft=cpp:*/
#define RBIMPL_RARRAY_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 struct ::RArray.
 */
#include "ruby/internal/arithmetic/long.h"
#include "ruby/internal/attr/artificial.h"
#include "ruby/internal/attr/constexpr.h"
#include "ruby/internal/attr/maybe_unused.h"
#include "ruby/internal/attr/pure.h"
#include "ruby/internal/cast.h"
#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/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.
 * @return  The passed object casted to ::RArray.
 */
#define RARRAY(obj)            RBIMPL_CAST((struct RArray *)(obj))
/** @cond INTERNAL_MACRO */
#define RARRAY_EMBED_FLAG      RARRAY_EMBED_FLAG
#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) || \
    defined(__FCC__) || defined(__FCC_VERSION)
/* workaround for old version of Fujitsu C Compiler (fcc) */
# define FIX_CONST_VALUE_PTR(x) ((const VALUE *)(x))
#else
# define FIX_CONST_VALUE_PTR(x) (x)
#endif

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

/**
 * @private
 *
 * Bits that you can set to ::RBasic::flags.
 *
 * @warning  These enums are not the only bits we use for arrays.
 *
 * @internal
 *
 * Unlike  strings, flag  usages for  arrays  are scattered  across the  entire
 * source codes.  @shyouhei doesn't know the complete list.  But what is listed
 * here is at least incomplete.
 */
enum ruby_rarray_flags {
    /**
     * 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
     * struct  ::RArray  for storing  its  contents.   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
     *           SEGV.    Also,  internal   structures  of   an  array   change
     *           dynamically  and  transparently  throughout of  its  lifetime.
     *           Don't assume it being persistent.
     *
     * @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_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
     * ::RArray::ary.
     *
     * @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_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
};

/**
 * This is an enum because GDB wants it (rather than a macro).  People need not
 * bother.
 */
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)
};

/** Ruby's array. */
struct RArray {

/** Basic part, including flags and class. */
    struct RBasic basic;

/** Array's specific fields. */
    union {

/**
         * Arrays  that  use separated  memory  region  for elements  use  this
         * pattern.
         */
        struct {

/** Number of elements of the array. */
            long len;

/** Auxiliary info. */
            union {

/**
                 * Capacity of `*ptr`.  A continuous  memory region of at least
                 * `capa` elements is expected to exist at `*ptr`.  This can be
                 * bigger than `len`.
                 */
                long capa;

/**
                 * Parent  of  the  array.   Nowadays arrays  can  share  their
                 * backend  memory regions  each  other, constructing  gigantic
                 * nest  of objects.   This situation  is called  "shared", and
                 * this is the field to control such properties.
                 */
#if defined(__clang__)      /* <- clang++ is sane */ || \
    !defined(__cplusplus)   /* <- C99 is sane */     || \
    (__cplusplus > 199711L) /* <- C++11 is sane */
                const
#endif
                VALUE shared_root;
            } aux;

/**
             * Pointer to the C array that holds the elements of the array.  In
             * the old days  each array had dedicated memory  regions.  That is
             * no  longer  true today,  but  there  still  are arrays  of  such
             * properties.  This field could be used to point such things.
             */
            const VALUE *ptr;
        } heap;

/**
         * Embedded elements.  When an array is short enough, it uses this area
         * to store its elements.  In this  case the length is encoded into the
         * flags.
         */
        const VALUE ary[RARRAY_EMBED_LEN_MAX];
    } as;
};

RBIMPL_SYMBOL_EXPORT_BEGIN()
/**
 * @private
 *
 * Declares  a  section of  code  where  raw pointers  are  used.   This is  an
 * implementation detail of #RARRAY_PTR_USE.  People don't use it directly.
 *
 * @param[in]  ary  An object of ::RArray.
 * @return     `ary`'s backend C array.
 */
VALUE *rb_ary_ptr_use_start(VALUE ary);

/**
 * @private
 *
 * Declares an  end of  a section  formerly started  by rb_ary_ptr_use_start().
 * This is  an implementation detail  of #RARRAY_PTR_USE.  People don't  use it
 * directly.
 *
 * @param[in]  a  An object of ::RArray.
 */
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()
RBIMPL_ATTR_ARTIFICIAL()
/**
 * Queries the length of the array.
 *
 * @param[in]  ary  Array in question.
 * @return     Its number of elements.
 * @pre        `ary`  must  be  an  instance  of ::RArray,  and  must  has  its
 *             ::RARRAY_EMBED_FLAG flag set.
 *
 * @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
RARRAY_EMBED_LEN(VALUE ary)
{
    RBIMPL_ASSERT_TYPE(ary, RUBY_T_ARRAY);
    RBIMPL_ASSERT_OR_ASSUME(RB_FL_ANY_RAW(ary, RARRAY_EMBED_FLAG));

VALUE f = RBASIC(ary)->flags;
    f &= RARRAY_EMBED_LEN_MASK;
    f >>= RARRAY_EMBED_LEN_SHIFT;
    return RBIMPL_CAST((long)f);
}

RBIMPL_ATTR_PURE_UNLESS_DEBUG()
/**
 * Queries the length of the array.
 *
 * @param[in]  a  Array in question.
 * @return     Its number of elements.
 * @pre        `a` must be an instance of ::RArray.
 */
static inline long
rb_array_len(VALUE a)
{
    RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY);

if (RB_FL_ANY_RAW(a, RARRAY_EMBED_FLAG)) {
        return RARRAY_EMBED_LEN(a);
    }
    else {
        return RARRAY(a)->as.heap.len;
    }
}

RBIMPL_ATTR_ARTIFICIAL()
/**
 * Identical to rb_array_len(), except it differs for the return type.
 *
 * @param[in]  ary             Array in question.
 * @exception  rb_eRangeError  Too long.
 * @return     Its number of elements.
 * @pre        `ary` must be an instance of ::RArray.
 *
 * @internal
 *
 * This API seems redundant but has actual usages.
 */
static inline int
RARRAY_LENINT(VALUE ary)
{
    return rb_long2int(RARRAY_LEN(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
 *
 * 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.
 */
static inline const VALUE *
rb_array_const_ptr_transient(VALUE a)
{
    RBIMPL_ASSERT_TYPE(a, RUBY_T_ARRAY);

if (RB_FL_ANY_RAW(a, RARRAY_EMBED_FLAG)) {
        return FIX_CONST_VALUE_PTR(RARRAY(a)->as.ary);
    }
    else {
        return FIX_CONST_VALUE_PTR(RARRAY(a)->as.heap.ptr);
    }
}

#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 {        \
    RBIMPL_ASSERT_TYPE((ary), RUBY_T_ARRAY);                 \
    const VALUE rbimpl_ary = (ary);                          \
    VALUE *var = rb_array_ptr_use_start(rbimpl_ary, (flag)); \
    expr;                                                   \
    rb_array_ptr_use_end(rbimpl_ary, (flag));                \
} 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.
 *
 * ```CXX
 * const auto ary = rb_eval_string("[...]");
 * const auto len = RARRAY_LENINT(ary);
 * const auto symwrite = rb_intern("write");
 *
 * RARRAY_PTR_USE(ary, ptr, {
 *     rb_funcallv(rb_stdout, symwrite, len, ptr);
 * });
 * ```
 *
 * @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`.
 *
 * @internal
 *
 * For  historical reasons  use  of  this macro  is  not  enforced.  There  are
 * extension libraries in the wild which call RARRAY_PTR() without it.  We want
 * 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)

/**
 * Wild  use of  a  C  pointer.  This  function  accesses  the backend  storage
 * directly.   This is  slower  than  #RARRAY_PTR_USE_TRANSIENT.  It  exercises
 * extra manoeuvres  to protect our generational  GC.  Use of this  function is
 * considered archaic.  Use a modern way instead.
 *
 * @param[in]  ary  An object of ::RArray.
 * @return     The backend C array.
 *
 * @internal
 *
 * That said...  there are  extension libraries  in the wild  who uses  it.  We
 * cannot but continue supporting.
 */
static inline VALUE *
RARRAY_PTR(VALUE ary)
{
    RBIMPL_ASSERT_TYPE(ary, RUBY_T_ARRAY);

VALUE tmp = RB_OBJ_WB_UNPROTECT_FOR(ARRAY, ary);
    return RBIMPL_CAST((VALUE *)RARRAY_CONST_PTR(tmp));
}

/**
 * Assigns an object in an array.
 *
 * @param[out]  ary  Destination array object.
 * @param[in]   i    Index of `ary`.
 * @param[in]   v    Arbitrary ruby object.
 * @pre         `ary` must be an instance of ::RArray.
 * @pre         `ary`'s length must be longer than or equal to `i`.
 * @pre         `i` must be greater than or equal to zero.
 * @post        `ary`'s `i`th element is set to `v`.
 */
static inline void
RARRAY_ASET(VALUE ary, long i, VALUE v)
{
    RARRAY_PTR_USE_TRANSIENT(ary, ptr,
        RB_OBJ_WRITE(ary, &ptr[i], v));
}

/**
 * @deprecated
 *
 * :FIXME: we want to convert RARRAY_AREF into an inline function (to add rooms
 * for more sanity checks).  However there were situations where the address of
 * this macro is taken i.e. &RARRAY_AREF(...).  They cannot be possible if this
 * is not a  macro.  Such usages are abuse, and  we eliminated them internally.
 * However we are afraid  of similar things to remain in  the wild.  This macro
 * 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]

#endif /* RBIMPL_RARRAY_H */

Back