Ruby 3.0.5p211 (2022-11-24 revision ba5cf0f7c52d4d35cc6a173c89eda98ceffa2dcf)
Macros | Functions
xmalloc.h File Reference

Declares ruby_xmalloc(). More...

#include "ruby/internal/config.h"
#include "ruby/internal/attr/alloc_size.h"
#include "ruby/internal/attr/nodiscard.h"
#include "ruby/internal/attr/noexcept.h"
#include "ruby/internal/attr/restrict.h"
#include "ruby/internal/attr/returns_nonnull.h"
#include "ruby/internal/dllexport.h"

Go to the source code of this file.

Macros

#define USE_GC_MALLOC_OBJ_INFO_DETAILS   0
 
#define xmalloc   ruby_xmalloc
 
#define xmalloc2   ruby_xmalloc2
 
#define xcalloc   ruby_xcalloc
 
#define xrealloc   ruby_xrealloc
 
#define xrealloc2   ruby_xrealloc2
 
#define xfree   ruby_xfree
 

Functions

void * ruby_xmalloc (size_t size)
 Allocates a storage instance. More...
 
void * ruby_xmalloc2 (size_t nelems, size_t elemsiz)
 Identical to ruby_xmalloc(), except it allocates nelems * elemsiz bytes. More...
 
void * ruby_xcalloc (size_t nelems, size_t elemsiz)
 Identical to ruby_xmalloc2(), except it zero-fills the region before it returns. More...
 
void * ruby_xrealloc (void *ptr, size_t newsiz)
 Resize the storage instance. More...
 
void * ruby_xrealloc2 (void *ptr, size_t newelems, size_t newsiz)
 Identical to ruby_xrealloc(), except it resizes the given storage instance to newelems * newsiz bytes. More...
 
void ruby_xfree (void *ptr)
 Deallocates a storage instance. More...
 

Detailed Description

Declares ruby_xmalloc().

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 xmalloc.h.

Macro Definition Documentation

◆ USE_GC_MALLOC_OBJ_INFO_DETAILS

#define USE_GC_MALLOC_OBJ_INFO_DETAILS   0

Definition at line 41 of file xmalloc.h.

◆ xcalloc

#define xcalloc   ruby_xcalloc

Definition at line 46 of file xmalloc.h.

◆ xfree

#define xfree   ruby_xfree

Definition at line 49 of file xmalloc.h.

◆ xmalloc

#define xmalloc   ruby_xmalloc

Definition at line 44 of file xmalloc.h.

◆ xmalloc2

#define xmalloc2   ruby_xmalloc2

Definition at line 45 of file xmalloc.h.

◆ xrealloc

#define xrealloc   ruby_xrealloc

Definition at line 47 of file xmalloc.h.

◆ xrealloc2

#define xrealloc2   ruby_xrealloc2

Definition at line 48 of file xmalloc.h.

Function Documentation

◆ ruby_xcalloc()

void * ruby_xcalloc ( size_t  nelems,
size_t  elemsiz 
)

Identical to ruby_xmalloc2(), except it zero-fills the region before it returns.

This could also be seen as a routine identical to ruby_xmalloc(), except it calls calloc() instead of malloc() internally.

Parameters
[in]nelemsNumber of elements.
[in]elemsizSize of an element.
Exceptions
rb_eNoMemErrorNo space left for allocation.
rb_eArgError`nelems` * `elemsiz` would overflow.
Returns
A valid pointer to an allocated storage instance; which has at least nelems * elemsiz bytes width, with appropriate alignment detected by the underlying calloc() routine.
Note
It doesn't return NULL.
Unlike some calloc() implementations, it allocates something and returns a meaningful value even when nelems or elemsiz or both are zero.
Warning
The return value shall be invalidated exactly once by either ruby_xfree(), ruby_xrealloc(), or ruby_xrealloc2(). It is a failure to pass it to system free(), because the system and Ruby might or might not share the same malloc() implementation.

Definition at line 12815 of file gc.c.

References ruby_xcalloc_body().

Referenced by getifaddrs(), rb_iseq_defined_string(), and rb_xcalloc_mul_add_mul().

◆ ruby_xfree()

void ruby_xfree ( void *  ptr)

Deallocates a storage instance.

Parameters
[out]ptrEither NULL, or a valid pointer previously returned from one of ruby_xmalloc(), ruby_xmalloc2(), ruby_xcalloc(), ruby_xrealloc(), or ruby_xrealloc2().
Warning
Every single storage instance that was previously allocated by either ruby_xmalloc(), ruby_xmalloc2(), ruby_xcalloc(), ruby_xrealloc(), or ruby_xrealloc2() shall be invalidated exactly once by either passing it to ruby_xfree(), or passing it to either ruby_xrealloc(), ruby_xrealloc2() then check the return value for invalidation.
Do not pass anything other than pointers described above. For instance pointers returned from malloc() or mmap() shall not be passed to this function, because the underlying memory management mechanism could differ.
Do not pass any invalid pointers to this function e.g. by calling it twice with a same argument.

Definition at line 10914 of file gc.c.

References ruby_sized_xfree.

Referenced by freeifaddrs(), getifaddrs(), Init_fiddle(), rb_fiddle_free(), rb_free_tmp_buffer(), rb_iseq_free(), rb_iseq_insns_info_encode_positions(), rb_ractor_finish_marking(), and rb_str_resize().

◆ ruby_xmalloc()

void * ruby_xmalloc ( size_t  size)

Allocates a storage instance.

It is largely the same as system malloc(), except:

  • It raises Ruby exceptions instead of returning NULL, and
  • In case of ENOMEM it tries to GC to make some room.
Parameters
[in]sizeRequested amount of memory.
Exceptions
rb_eNoMemErrorNo space left for `size` bytes allocation.
Returns
A valid pointer to an allocated storage instance; which has at least size bytes width, with appropriate alignment detected by the underlying malloc() routine.
Note
It doesn't return NULL.
Unlike some malloc() implementations, it allocates something and returns a meaningful value even when size is equal to zero.
Warning
The return value shall be invalidated exactly once by either ruby_xfree(), ruby_xrealloc(), or ruby_xrealloc2(). It is a failure to pass it to system free(), because the system and Ruby might or might not share the same malloc() implementation.

Definition at line 12795 of file gc.c.

References ruby_xmalloc_body().

Referenced by getifaddrs(), rb_xmalloc_mul_add(), and rb_xmalloc_mul_add_mul().

◆ ruby_xmalloc2()

void * ruby_xmalloc2 ( size_t  nelems,
size_t  elemsiz 
)

Identical to ruby_xmalloc(), except it allocates nelems * elemsiz bytes.

This is needed because the multiplication could integer overflow. On such situations Ruby does not try to allocate at all but raises Ruby level exceptions instead. If there is no integer overflow the behaviour is exactly the same as ruby_xmalloc(nelems*elemsiz).

Parameters
[in]nelemsNumber of elements.
[in]elemsizSize of an element.
Exceptions
rb_eNoMemErrorNo space left for allocation.
rb_eArgError`nelems` * `elemsiz` would overflow.
Returns
A valid pointer to an allocated storage instance; which has at least nelems * elemsiz bytes width, with appropriate alignment detected by the underlying malloc() routine.
Note
It doesn't return NULL.
Unlike some malloc() implementations, it allocates something and returns a meaningful value even when nelems or elemsiz or both are zero.
Warning
The return value shall be invalidated exactly once by either ruby_xfree(), ruby_xrealloc(), or ruby_xrealloc2(). It is a failure to pass it to system free(), because the system and Ruby might or might not share the same malloc() implementation.

Definition at line 12805 of file gc.c.

References ruby_xmalloc2_body().

◆ ruby_xrealloc()

void * ruby_xrealloc ( void *  ptr,
size_t  newsiz 
)

Resize the storage instance.

Parameters
[in]ptrA valid pointer to a storage instance that was previously returned from either ruby_xmalloc(), ruby_xmalloc2(), ruby_xcalloc(), ruby_xrealloc(), or ruby_xrealloc2().
[in]newsizRequested new amount of memory.
Exceptions
rb_eNoMemErrorNo space left for `newsiz` bytes allocation.
Return values
ptrIn case the function returns the passed pointer as-is, the storage instance that the pointer holds is either grown or shrunken to have at least newsiz bytes.
otherwiseA valid pointer to a newly allocated storage instance which has at least newsiz bytes width, and holds previous contents of ptr. In this case ptr is invalidated as if it was passed to ruby_xfree().
Note
It doesn't return NULL.
Warning
Unlike some realloc() implementations, passing zero to elemsiz is not the same as calling ruby_xfree(), because this function never returns NULL. Something meaningful still returns then.
It is a failure not to check the return value. Do not assume anything on it. It could be either identical to, or distinct form the passed argument.
Do not assume anything on the alignment of the return value. There is no guarantee that it inherits the passed argument's one.
The return value shall be invalidated exactly once by either ruby_xfree(), ruby_xrealloc(), or ruby_xrealloc2(). It is a failure to pass it to system free(), because the system and Ruby might or might not share the same malloc() implementation.

Definition at line 12825 of file gc.c.

References ptr, and ruby_xrealloc_body().

Referenced by rb_xrealloc_mul_add().

◆ ruby_xrealloc2()

void * ruby_xrealloc2 ( void *  ptr,
size_t  newelems,
size_t  newsiz 
)

Identical to ruby_xrealloc(), except it resizes the given storage instance to newelems * newsiz bytes.

This is needed because the multiplication could integer overflow. On such situations Ruby does not try to touch the contents of argument pointer at all but raises Ruby level exceptions instead. If there is no integer overflow the behaviour is exactly the same as ruby_xrealloc(ptr,nelems*elemsiz).

This is roughly the same as reallocarray() function that OpenBSD etc. provides, but also interacts with our GC.

Parameters
[in]ptrA valid pointer to a storage instance that was previously returned from either ruby_xmalloc(), ruby_xmalloc2(), ruby_xcalloc(), ruby_xrealloc(), or ruby_xrealloc2().
[in]newelemsRequested new number of elements.
[in]newsizRequested new size of each element.
Exceptions
rb_eNoMemErrorNo space left for allocation.
rb_eArgError`newelems` * `newsiz` would overflow.
Return values
ptrIn case the function returns the passed pointer as-is, the storage instance that the pointer holds is either grown or shrunken to have at least newelems * newsiz bytes.
otherwiseA valid pointer to a newly allocated storage instance which has at least newelems * newsiz bytes width, and holds previous contents of ptr. In this case ptr is invalidated as if it was passed to ruby_xfree().
Note
It doesn't return NULL.
Warning
Unlike some realloc() implementations, passing zero to either newelems or elemsiz are not the same as calling ruby_xfree(), because this function never returns NULL. Something meaningful still returns then.
It is a failure not to check the return value. Do not assume anything on it. It could be either identical to, or distinct form the passed argument.
Do not assume anything on the alignment of the return value. There is no guarantee that it inherits the passed argument's one.
The return value shall be invalidated exactly once by either ruby_xfree(), ruby_xrealloc(), or ruby_xrealloc2(). It is a failure to pass it to system free(), because the system and Ruby might or might not share the same malloc() implementation.

Definition at line 12835 of file gc.c.

References ptr, and ruby_xrealloc2_body().