Ruby: include/ruby/internal/xmalloc.h File Reference

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

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.

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] | nelems | Number of elements.
  [in] | elemsiz | Size of an element.

Exceptions

  rb_eNoMemError | No 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] | ptr | Either 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] | size | Requested amount of memory.

Exceptions

  rb_eNoMemError | No 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] | nelems | Number of elements.
  [in] | elemsiz | Size of an element.

Exceptions

  rb_eNoMemError | No 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] | ptr | A valid pointer to a storage instance that was previously returned from either ruby_xmalloc(), ruby_xmalloc2(), ruby_xcalloc(), ruby_xrealloc(), or ruby_xrealloc2().
  [in] | newsiz | Requested new amount of memory.

Exceptions

  rb_eNoMemError | No space left for `newsiz` bytes allocation.

Return values

  ptr | In 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.
  otherwise | A 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] | ptr | A valid pointer to a storage instance that was previously returned from either ruby_xmalloc(), ruby_xmalloc2(), ruby_xcalloc(), ruby_xrealloc(), or ruby_xrealloc2().
  [in] | newelems | Requested new number of elements.
  [in] | newsiz | Requested new size of each element.

Exceptions

  rb_eNoMemError | No space left for allocation.
  rb_eArgError | `newelems` * `newsiz` would overflow.

Return values

  ptr | In 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.
  otherwise | A 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().