Ruby 3.4.1p0 (2024-12-25 revision 48d4efcb85000e1ebae42004e963b5d0cedddcf2)
|
Memory management stuff. More...
#include "ruby/internal/config.h"
#include "ruby/internal/attr/alloc_size.h"
#include "ruby/internal/attr/const.h"
#include "ruby/internal/attr/constexpr.h"
#include "ruby/internal/attr/noalias.h"
#include "ruby/internal/attr/nonnull.h"
#include "ruby/internal/attr/noreturn.h"
#include "ruby/internal/attr/restrict.h"
#include "ruby/internal/attr/returns_nonnull.h"
#include "ruby/internal/cast.h"
#include "ruby/internal/dllexport.h"
#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"
Go to the source code of this file.
Macros | |
#define | RUBY_ALLOCV_LIMIT 1024 |
Maximum possible number of bytes that RB_ALLOCV can allocate using alloca . | |
#define | RB_GC_GUARD(v) |
Prevents premature destruction of local objects. | |
#define | RB_ALLOC_N(type, n) |
Convenient macro that allocates an array of n elements. | |
#define | RB_ALLOC(type) |
Shorthand of RB_ALLOC_N with n=1 . | |
#define | RB_ZALLOC_N(type, n) |
Identical to RB_ALLOC_N() but also nullifies the allocated region before returning. | |
#define | RB_ZALLOC(type) |
Shorthand of RB_ZALLOC_N with n=1 . | |
#define | RB_REALLOC_N(var, type, n) |
Convenient macro that reallocates an array with a new size. | |
#define | ALLOCA_N(type, n) |
#define | RB_ALLOCV(v, n) |
Identical to RB_ALLOCV_N(), except that it allocates a number of bytes and returns a void* . | |
#define | RB_ALLOCV_N(type, v, n) |
Allocates a memory region, possibly on stack. | |
#define | RB_ALLOCV_END(v) |
Polite way to declare that the given array is not used any longer. | |
#define | MEMZERO(p, type, n) |
Handy macro to erase a region of memory. | |
#define | MEMCPY(p1, p2, type, n) |
Handy macro to call memcpy. | |
#define | MEMMOVE(p1, p2, type, n) |
Handy macro to call memmove. | |
#define | MEMCMP(p1, p2, type, n) |
Handy macro to call memcmp. | |
#define | ALLOC_N RB_ALLOC_N |
Old name of RB_ALLOC_N. | |
#define | ALLOC RB_ALLOC |
Old name of RB_ALLOC. | |
#define | ZALLOC_N RB_ZALLOC_N |
Old name of RB_ZALLOC_N. | |
#define | ZALLOC RB_ZALLOC |
Old name of RB_ZALLOC. | |
#define | REALLOC_N RB_REALLOC_N |
Old name of RB_REALLOC_N. | |
#define | ALLOCV RB_ALLOCV |
Old name of RB_ALLOCV. | |
#define | ALLOCV_N RB_ALLOCV_N |
Old name of RB_ALLOCV_N. | |
#define | ALLOCV_END RB_ALLOCV_END |
Old name of RB_ALLOCV_END. | |
Functions | |
static int | rb_mul_size_overflow (size_t a, size_t b, size_t max, size_t *c) |
static void * | rb_alloc_tmp_buffer2 (volatile VALUE *store, long count, size_t elsize) |
This is an implementation detail of RB_ALLOCV_N(). | |
static void * | ruby_nonempty_memcpy (void *dest, const void *src, size_t n) |
Memory management stuff.
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. __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 memory.h.
#define ALLOCA_N | ( | type, | |
n ) |
type | Type of array elements. |
n | Length of the array. |
Definition at line 292 of file memory.h.
Referenced by rb_apply(), rb_funcall(), rb_str_buf_cat_ascii(), rb_str_concat(), and rb_yield_values().
#define MEMCMP | ( | p1, | |
p2, | |||
type, | |||
n ) |
Handy macro to call memcmp.
p1 | Target LHS. |
p2 | Target RHS. |
type | Type of p1[0] |
n | Length of p1 . |
<0 | p1 is "less" than p2 . |
0 | p1 is equal to p2 . |
>0 | p1 is "greater" than p2 . |
Definition at line 397 of file memory.h.
Referenced by rb_big_eq(), and rb_big_eql().
#define MEMCPY | ( | p1, | |
p2, | |||
type, | |||
n ) |
Handy macro to call memcpy.
p1 | Destination pointer. |
p2 | Source pointer. |
type | Type of p2[0] |
n | Length of p2 . |
p1
. n
elements of p2
are copied into p1
. Definition at line 372 of file memory.h.
Referenced by rb_apply(), rb_ary_resize(), rb_big_clone(), rb_econv_set_replacement(), rb_integer_unpack(), and rb_str_resize().
#define MEMMOVE | ( | p1, | |
p2, | |||
type, | |||
n ) |
Handy macro to call memmove.
p1 | Destination pointer. |
p2 | Source pointer. |
type | Type of p2[0] |
n | Length of p2 . |
p1
. n
elements of p2
are copied into p1
. Definition at line 384 of file memory.h.
Referenced by rb_ary_delete_at(), rb_econv_insert_output(), and rb_io_ungetc().
#define MEMZERO | ( | p, | |
type, | |||
n ) |
#define RB_ALLOC | ( | type | ) |
Shorthand of RB_ALLOC_N with n=1
.
type | Type of allocation. |
rb_eNoMemError | No space left for allocation. |
type
object. #define RB_ALLOC_N | ( | type, | |
n ) |
Convenient macro that allocates an array of n elements.
type | Type of array elements. |
n | Length of the array. |
rb_eNoMemError | No space left for allocation. |
rb_eArgError | Integer overflow trying to calculate the length of continuous memory region of n elements of type . |
n
elements of type type
. n
is zero. #define RB_ALLOCV | ( | v, | |
n ) |
Identical to RB_ALLOCV_N(), except that it allocates a number of bytes and returns a void* .
v | A variable to hold the just-in-case opaque Ruby object. |
n | Size of allocation, in bytes. |
n
bytes storage. n
may be evaluated twice. #define RB_ALLOCV_END | ( | v | ) |
Polite way to declare that the given array is not used any longer.
Calling this not mandatory. Our GC can baby-sit you. However it is not a very bad idea to use it when possible. Doing so could reduce memory footprint.
v | A variable previously passed to either RB_ALLOCV/RB_ALLOCV_N. |
#define RB_ALLOCV_N | ( | type, | |
v, | |||
n ) |
Allocates a memory region, possibly on stack.
If the given size exceeds RUBY_ALLOCV_LIMIT, it allocates a dedicated opaque ruby object instead and let our GC sweep that region after use. Either way you can fire-and-forget.
If you want to be super-duper polite you can also explicitly state the end of use of such memory region by calling RB_ALLOCV_END().
type | The type of array elements. |
v | A variable to hold the just-in-case opaque Ruby object. |
n | Number of elements requested to allocate. |
n
elements of type
. n
may be evaluated twice. #define RB_GC_GUARD | ( | v | ) |
Prevents premature destruction of local objects.
Ruby's garbage collector is conservative; it scans the C level machine stack as well. Possible in- use Ruby objects must remain visible on stack, to be properly marked as such. However contemporary C compilers do not interface well with this. Consider the following example:
Here, without the RB_GC_GUARD, the last use of s
is before the last use of sptr
. Compilers could thus think s
and t
are allowed to overlap. That would eliminate s
from the stack, while sptr
is still in use. If our GC ran at that very moment, s
gets swept out, which also destroys sptr
. Boom! You got a SEGV.
In order to prevent this scenario RB_GC_GUARD must be placed after the last use of sptr
. Placing RB_GC_GUARD before dereferencing sptr
would be of no use.
RB_GC_GUARD would not be necessary at all in the above example if non- inlined function calls are made on the s
variable after sptr
is dereferenced. Thus, in the above example, calling any un-inlined function on s
such as rb_str_modify(s);
will ensure s
stays on the stack or register to prevent a GC invocation from prematurely freeing it.
Using the RB_GC_GUARD macro is preferable to using the volatile
keyword in C. RB_GC_GUARD has the following advantages:
volatile
generates some extra code every time the variable is used, hurting optimisation.volatile
implementations may be buggy/inconsistent in some compilers and architectures. RB_GC_GUARD is customisable for broken systems/compilers without negatively affecting other systems.volatile
. If you write your extension library in that language there is no escape but to use this macro.v | A variable of VALUE type. |
v
is still alive. Definition at line 167 of file memory.h.
Referenced by rb_apply(), rb_autoload_load(), rb_big_and(), rb_big_or(), rb_big_xor(), rb_define_hooked_variable(), rb_econv_substr_append(), rb_env_clear(), rb_f_exec(), rb_find_file(), rb_find_file_ext(), rb_gc_register_address(), rb_integer_pack(), rb_path_to_class(), rb_proc_call_kw(), rb_proc_call_with_block_kw(), rb_reg_prepare_re(), rb_str_buf_append(), rb_str_format(), rb_str_plus(), rb_str_subpos(), rb_struct_initialize(), rb_yield_splat(), and rb_yield_splat_kw().
#define RB_REALLOC_N | ( | var, | |
type, | |||
n ) |
Convenient macro that reallocates an array with a new size.
var | A variable of type , which points to a storage instance that was previously returned from either
|
type | Type of allocation. |
n | Requested new size of each element. |
rb_eNoMemError | No space left for allocation. |
rb_eArgError | Integer overflow trying to calculate the length of continuous memory region of n elements of type . |
n
elements of type type
. n
is zero. #define RB_ZALLOC | ( | type | ) |
Shorthand of RB_ZALLOC_N with n=1
.
type | Type of allocation. |
rb_eNoMemError | No space left for allocation. |
type
object. #define RB_ZALLOC_N | ( | type, | |
n ) |
Identical to RB_ALLOC_N() but also nullifies the allocated region before returning.
type | Type of array elements. |
n | Length of the array. |
rb_eNoMemError | No space left for allocation. |
rb_eArgError | Integer overflow trying to calculate the length of continuous memory region of n elements of type . |
n
elements of type type
. n
is zero. #define RUBY_ALLOCV_LIMIT 1024 |
|
inlinestatic |
This is an implementation detail of RB_ALLOCV_N().
People don't use this directly.
[out] | store | Pointer to a variable. |
[in] | count | Number of elements in an array. |
[in] | elsize | Size of each elements. |
count
* elsize
bytes. store
holds the corresponding tmp buffer object.
|
inlinestatic |
[in] | a | Arbitrary value. |
[in] | b | Arbitrary value. |
[in] | max | Possible maximum value. |
[out] | c | A pointer to return the computation result. |
1 | c is insane. |
0 | c is sane. |
c
holds a
* b
, but could be overflowed.