Ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e0ba6b95ab71a441357ed5484e33498)
Data Structures | Macros | Enumerations | Functions
rarray.h File Reference

Defines struct RArray. More...

#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"

Go to the source code of this file.

Data Structures

struct  RArray
 Ruby's array. More...
 

Macros

#define USE_TRANSIENT_HEAP   1
 
#define RARRAY(obj)   RBIMPL_CAST((struct RArray *)(obj))
 Convenient casting macro. More...
 
#define RARRAY_LEN   rb_array_len
 Just another name of rb_array_len. More...
 
#define RARRAY_CONST_PTR   rb_array_const_ptr
 Just another name of rb_array_const_ptr. More...
 
#define RARRAY_CONST_PTR_TRANSIENT   rb_array_const_ptr_transient
 Just another name of rb_array_const_ptr_transient. More...
 
#define RBIMPL_RARRAY_STMT(flag, ary, var, expr)
 This is an implementation detail of RARRAY_PTR_USE. More...
 
#define RARRAY_PTR_USE_START(a)   rb_array_ptr_use_start(a, 0)
 This is an implementation detail of RARRAY_PTR_USE. More...
 
#define RARRAY_PTR_USE_END(a)   rb_array_ptr_use_end(a, 0)
 This is an implementation detail of RARRAY_PTR_USE. More...
 
#define RARRAY_PTR_USE(ary, ptr_name, expr)    RBIMPL_RARRAY_STMT(0, ary, ptr_name, expr)
 Declares a section of code where raw pointers are used. More...
 
#define RARRAY_PTR_USE_START_TRANSIENT(a)   rb_array_ptr_use_start(a, 1)
 This is an implementation detail of RARRAY_PTR_USE_TRANSIENT. More...
 
#define RARRAY_PTR_USE_END_TRANSIENT(a)   rb_array_ptr_use_end(a, 1)
 This is an implementation detail of RARRAY_PTR_USE_TRANSIENT. More...
 
#define RARRAY_PTR_USE_TRANSIENT(ary, ptr_name, expr)    RBIMPL_RARRAY_STMT(1, ary, ptr_name, expr)
 Identical to RARRAY_PTR_USE, except the pointer can be a transient one. More...
 
#define RARRAY_AREF(a, i)   RARRAY_CONST_PTR_TRANSIENT(a)[i]
 

Enumerations

enum  ruby_rarray_consts { RARRAY_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 3 , RARRAY_EMBED_LEN_MAX = ((int)(sizeof(VALUE[3]) / (sizeof(VALUE)))) , RARRAY_EMBED_LEN_SHIFT = RUBY_FL_USHIFT + 3 , RARRAY_EMBED_LEN_MAX = RBIMPL_EMBED_LEN_MAX_OF(VALUE) }
 This is an enum because GDB wants it (rather than a macro). More...
 

Functions

void rb_ary_detransient (VALUE a)
 Destructively converts an array of transient backend into ordinal one. More...
 
static long RARRAY_EMBED_LEN (VALUE ary)
 Queries the length of the array. More...
 
static long rb_array_len (VALUE a)
 Queries the length of the array. More...
 
static int RARRAY_LENINT (VALUE ary)
 Identical to rb_array_len(), except it differs for the return type. More...
 
static bool RARRAY_TRANSIENT_P (VALUE ary)
 Queries if the array is a transient array. More...
 
static VALUERARRAY_PTR (VALUE ary)
 Wild use of a C pointer. More...
 
static void RARRAY_ASET (VALUE ary, long i, VALUE v)
 Assigns an object in an array. More...
 

Detailed Description

Defines struct RArray.

Author
Ruby developers ruby-.nosp@m.core.nosp@m.@ruby.nosp@m.-lan.nosp@m.g.org
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.

Definition in file rarray.h.

Macro Definition Documentation

◆ RARRAY

#define RARRAY (   obj)    RBIMPL_CAST((struct RArray *)(obj))

Convenient casting macro.

Parameters
objAn object, which is in fact an RArray.
Returns
The passed object casted to RArray.

Definition at line 56 of file rarray.h.

◆ RARRAY_AREF

#define RARRAY_AREF (   a,
 
)    RARRAY_CONST_PTR_TRANSIENT(a)[i]
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.

Definition at line 588 of file rarray.h.

◆ RARRAY_CONST_PTR

#define RARRAY_CONST_PTR   rb_array_const_ptr

Just another name of rb_array_const_ptr.

Definition at line 69 of file rarray.h.

◆ RARRAY_CONST_PTR_TRANSIENT

#define RARRAY_CONST_PTR_TRANSIENT   rb_array_const_ptr_transient

Just another name of rb_array_const_ptr_transient.

Definition at line 70 of file rarray.h.

◆ RARRAY_LEN

#define RARRAY_LEN   rb_array_len

Just another name of rb_array_len.

Definition at line 68 of file rarray.h.

◆ RARRAY_PTR_USE

#define RARRAY_PTR_USE (   ary,
  ptr_name,
  expr 
)     RBIMPL_RARRAY_STMT(0, ary, ptr_name, expr)

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.

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);
});
VALUE rb_stdout
STDOUT constant.
Definition: io.c:198
VALUE rb_funcallv(VALUE recv, ID mid, int argc, const VALUE *argv)
Identical to rb_funcall(), except it takes the method arguments as a C array.
Definition: vm_eval.c:1061
VALUE rb_eval_string(const char *str)
Evaluates the given string in an isolated binding.
Definition: vm_eval.c:1835
ID rb_intern(const char *name)
Finds or creates a symbol of the given name.
Definition: symbol.c:782
static int RARRAY_LENINT(VALUE ary)
Identical to rb_array_len(), except it differs for the return type.
Definition: rarray.h:324
#define RARRAY_PTR_USE(ary, ptr_name, expr)
Declares a section of code where raw pointers are used.
Definition: rarray.h:507
Parameters
aryAn object of RArray.
ptr_nameA variable name which points the C array in expr.
exprThe expression that touches ptr_name.

Definition at line 507 of file rarray.h.

◆ RARRAY_PTR_USE_END

#define RARRAY_PTR_USE_END (   a)    rb_array_ptr_use_end(a, 0)

This is an implementation detail of RARRAY_PTR_USE.

People do not use it directly.

Definition at line 480 of file rarray.h.

◆ RARRAY_PTR_USE_END_TRANSIENT

#define RARRAY_PTR_USE_END_TRANSIENT (   a)    rb_array_ptr_use_end(a, 1)

This is an implementation detail of RARRAY_PTR_USE_TRANSIENT.

People do not use it directly.

Definition at line 524 of file rarray.h.

◆ RARRAY_PTR_USE_START

#define RARRAY_PTR_USE_START (   a)    rb_array_ptr_use_start(a, 0)

This is an implementation detail of RARRAY_PTR_USE.

People do not use it directly.

Definition at line 472 of file rarray.h.

◆ RARRAY_PTR_USE_START_TRANSIENT

#define RARRAY_PTR_USE_START_TRANSIENT (   a)    rb_array_ptr_use_start(a, 1)

This is an implementation detail of RARRAY_PTR_USE_TRANSIENT.

People do not use it directly.

Definition at line 516 of file rarray.h.

◆ RARRAY_PTR_USE_TRANSIENT

#define RARRAY_PTR_USE_TRANSIENT (   ary,
  ptr_name,
  expr 
)     RBIMPL_RARRAY_STMT(1, ary, ptr_name, expr)

Identical to RARRAY_PTR_USE, except the pointer can be a transient one.

Parameters
aryAn object of RArray.
ptr_nameA variable name which points the C array in expr.
exprThe expression that touches ptr_name.

Definition at line 533 of file rarray.h.

◆ RBIMPL_RARRAY_STMT

#define RBIMPL_RARRAY_STMT (   flag,
  ary,
  var,
  expr 
)
Value:
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)
@ RUBY_T_ARRAY
Definition: value_type.h:121

This is an implementation detail of RARRAY_PTR_USE.

People do not use it directly.

Definition at line 458 of file rarray.h.

◆ USE_TRANSIENT_HEAP

#define USE_TRANSIENT_HEAP   1
Warning
Do not touch this macro.
It is an implementation detail.
The value of this macro must match for ruby itself and all extension libraries, otherwise serious memory corruption shall occur.

Definition at line 47 of file rarray.h.

Enumeration Type Documentation

◆ ruby_rarray_consts

enum ruby_rarray_consts

This is an enum because GDB wants it (rather than a macro).

People need not bother.

Enumerator
RARRAY_EMBED_LEN_SHIFT 

Where ::RARRAY_EMBED_LEN_MASK resides.

RARRAY_EMBED_LEN_MAX 

Max possible number elements that can be embedded.

Definition at line 157 of file rarray.h.

Function Documentation

◆ RARRAY_ASET()

static void RARRAY_ASET ( VALUE  ary,
long  i,
VALUE  v 
)
inlinestatic

Assigns an object in an array.

Parameters
[out]aryDestination array object.
[in]iIndex of ary.
[in]vArbitrary ruby object.
Precondition
ary must be an instance of RArray.
ary's length must be longer than or equal to i.
i must be greater than or equal to zero.
Postcondition
ary's ith element is set to v.

Definition at line 571 of file rarray.h.

◆ RARRAY_EMBED_LEN()

static long RARRAY_EMBED_LEN ( VALUE  ary)
inlinestatic

Queries the length of the array.

Parameters
[in]aryArray in question.
Returns
Its number of elements.
Precondition
ary must be an instance of RArray, and must has its ::RARRAY_EMBED_FLAG flag set.

Definition at line 278 of file rarray.h.

◆ RARRAY_LENINT()

static int RARRAY_LENINT ( VALUE  ary)
inlinestatic

Identical to rb_array_len(), except it differs for the return type.

Parameters
[in]aryArray in question.
Exceptions
rb_eRangeErrorToo long.
Returns
Its number of elements.
Precondition
ary must be an instance of RArray.

Definition at line 324 of file rarray.h.

Referenced by rb_apply(), rb_eval_cmd_kw(), and rb_struct_initialize().

◆ RARRAY_PTR()

static VALUE * RARRAY_PTR ( VALUE  ary)
inlinestatic

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.

Parameters
[in]aryAn object of RArray.
Returns
The backend C array.

Definition at line 551 of file rarray.h.

Referenced by rb_struct_new().

◆ RARRAY_TRANSIENT_P()

static bool RARRAY_TRANSIENT_P ( VALUE  ary)
inlinestatic

Queries if the array is a transient array.

Parameters
[in]aryArray in question.
Return values
trueYes it is.
falseNo it isn't.
Precondition
ary must be an instance of RArray.

Definition at line 345 of file rarray.h.

Referenced by rb_ary_detransient(), and rb_ary_free().

◆ rb_array_len()

static long rb_array_len ( VALUE  a)
inlinestatic

Queries the length of the array.

Parameters
[in]aArray in question.
Returns
Its number of elements.
Precondition
a must be an instance of RArray.

Definition at line 298 of file rarray.h.

◆ rb_ary_detransient()

void rb_ary_detransient ( VALUE  a)

Destructively converts an array of transient backend into ordinal one.

Parameters
[out]aAn object of RArray.
Precondition
a must be a transient array.
Postcondition
a gets out of transient heap, destructively.

Definition at line 429 of file array.c.