Ruby: include/ruby/internal/core/rtypeddata.h File Reference

Ruby 3.2.5p208 (2024-07-26 revision 31d0f1a2e7dbfb60731d1f05b868e1d578cda493)

Data Structures | Macros | Typedefs | Functions
rtypeddata.h File Reference

Defines struct RTypedData. More...

`#include "ruby/internal/config.h"`
`#include "ruby/internal/assume.h"`
`#include "ruby/internal/attr/artificial.h"`
`#include "ruby/internal/attr/flag_enum.h"`
`#include "ruby/internal/attr/nonnull.h"`
`#include "ruby/internal/attr/pure.h"`
`#include "ruby/internal/cast.h"`
`#include "ruby/internal/core/rbasic.h"`
`#include "ruby/internal/core/rdata.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/error.h"`
`#include "ruby/internal/fl_type.h"`
`#include "ruby/internal/stdbool.h"`
`#include "ruby/internal/value_type.h"`

Go to the source code of this file.

## Data Structures
struct | rb_data_type_struct
| This is the struct that holds necessary info for a struct. More...
struct | RTypedData
| "Typed" user data. More...

## Macros
#define | HAVE_TYPE_RB_DATA_TYPE_T 1
#define | HAVE_RB_DATA_TYPE_T_FUNCTION 1
#define | HAVE_RB_DATA_TYPE_T_PARENT 1
#define | RUBY_TYPED_DEFAULT_FREE RUBY_DEFAULT_FREE
| This is a value you can set to rb_data_type_struct::dfree.
#define | RUBY_TYPED_NEVER_FREE RUBY_NEVER_FREE
| This is a value you can set to rb_data_type_struct::dfree.
#define | RTYPEDDATA(obj)
| Convenient casting macro.
#define | RTYPEDDATA_DATA(v)
| Convenient getter macro.
#define | Check_TypedStruct(v, t)
| Old name of rb_check_typeddata.
#define | TypedData_Wrap_Struct(klass, data_type, sval)
| Converts sval, a pointer to your struct, into a Ruby object.
#define | TypedData_Make_Struct0(result, klass, type, size, data_type, sval)
| This is an implementation detail of TypedData_Make_Struct.
#define | TypedData_Make_Struct(klass, type, data_type, sval)
| Identical to TypedData_Wrap_Struct, except it allocates a new data region internally instead of taking an existing one.
#define | TypedData_Get_Struct(obj, type, data_type, sval)
| Obtains a C struct from inside of a wrapper Ruby object.

## Typedefs
typedef struct rb_data_type_struct | rb_data_type_t
| This is the struct that holds necessary info for a struct.

## Functions
VALUE | rb_data_typed_object_wrap (VALUE klass, void *datap, const rb_data_type_t *type)
| This is the primitive way to wrap an existing C struct into RTypedData.
VALUE | rb_data_typed_object_zalloc (VALUE klass, size_t size, const rb_data_type_t *type)
| Identical to rb_data_typed_object_wrap(), except it allocates a new data region internally instead of taking an existing one.
int | rb_typeddata_inherited_p (const rb_data_type_t *child, const rb_data_type_t *parent)
| Checks for the domestic relationship between the two.
int | rb_typeddata_is_kind_of (VALUE obj, const rb_data_type_t *data_type)
| Checks if the given object is of given kind.
void * | rb_check_typeddata (VALUE obj, const rb_data_type_t *data_type)
| Identical to rb_typeddata_is_kind_of(), except it raises exceptions instead of returning false.
static bool | RTYPEDDATA_P (VALUE obj)
| Checks whether the passed object is RTypedData or RData.
static const struct rb_data_type_struct * | RTYPEDDATA_TYPE (VALUE obj)
| Queries for the type of given object.
static VALUE | rb_data_typed_object_make (VALUE klass, const rb_data_type_t *type, void **datap, size_t size)
| While we don't stop you from using this function, it seems to be an implementation detail of TypedData_Make_Struct, which is preferred over this one.
static VALUE | rb_data_typed_object_alloc (VALUE klass, void *datap, const rb_data_type_t *type)

## Detailed Description

Defines struct RTypedData.

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

## Macro Definition Documentation

## ◆ HAVE_RB_DATA_TYPE_T_FUNCTION

#define HAVE_RB_DATA_TYPE_T_FUNCTION 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 59 of file rtypeddata.h.

## ◆ HAVE_RB_DATA_TYPE_T_PARENT

#define HAVE_RB_DATA_TYPE_T_PARENT 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 68 of file rtypeddata.h.

## ◆ HAVE_TYPE_RB_DATA_TYPE_T

#define HAVE_TYPE_RB_DATA_TYPE_T 1

Deprecated
  This macro once was a thing in the old days, but makes no sense any longer today. Exists here for backwards compatibility only. You can safely forget about it.

Definition at line 50 of file rtypeddata.h.

## ◆ RTYPEDDATA

#define RTYPEDDATA | ( |  | obj | ) |

Value:
RBIMPL_CAST((struct RTypedData *)(obj))
RTypedData
"Typed" user data.
Definition rtypeddata.h:340

Convenient casting macro.

Parameters

  obj | An object, which is in fact an RTypedData.

Returns
  The passed object casted to RTypedData.

Definition at line 94 of file rtypeddata.h.

Referenced by RTYPEDDATA_TYPE().

## ◆ RTYPEDDATA_DATA

#define RTYPEDDATA_DATA | ( |  | v | ) |

Value:
(RTYPEDDATA(v)->data)
RTYPEDDATA
#define RTYPEDDATA(obj)
Convenient casting macro.
Definition rtypeddata.h:94

Convenient getter macro.

Parameters

  v | An object, which is in fact an RTypedData.

Returns
  The passed object's RTypedData::data field.

Definition at line 102 of file rtypeddata.h.

## ◆ RUBY_TYPED_DEFAULT_FREE

#define RUBY_TYPED_DEFAULT_FREE RUBY_DEFAULT_FREE

This is a value you can set to rb_data_type_struct::dfree.

Setting this means the data was allocated using ruby_xmalloc() (or variants), and shall be freed using ruby_xfree().

Warning
  Do not use this if you want to use system malloc, because the system and Ruby might or might not share the same malloc implementation.

Definition at line 79 of file rtypeddata.h.

## ◆ RUBY_TYPED_NEVER_FREE

#define RUBY_TYPED_NEVER_FREE RUBY_NEVER_FREE

This is a value you can set to rb_data_type_struct::dfree.

Setting this means the data is managed by someone else, like, statically allocated. Of course you are on your own then.

Definition at line 86 of file rtypeddata.h.

## ◆ TypedData_Get_Struct

#define TypedData_Get_Struct | ( |  | obj,
|  |  | type,
|  |  | data_type,
|  |  | sval )

Value:
((sval) = RBIMPL_CAST((type *)rb_check_typeddata((obj), (data_type))))
rb_check_typeddata
void * rb_check_typeddata(VALUE obj, const rb_data_type_t *data_type)
Identical to rb_typeddata_is_kind_of(), except it raises exceptions instead of returning false.
Definition error.c:1058

Obtains a C struct from inside of a wrapper Ruby object.

Parameters

  obj | An instance of RTypedData.
  type | Type name of the C struct.
  data_type | The data type describing `type`.
  sval | Variable name of obtained C struct.

Exceptions

  rb_eTypeError | `obj` is not a kind of `data_type`.

Returns
  Unwrapped C struct that `obj` holds.

Definition at line 507 of file rtypeddata.h.

Referenced by rb_method_call_with_block_kw().

## ◆ TypedData_Make_Struct

#define TypedData_Make_Struct | ( |  | klass,
|  |  | type,
|  |  | data_type,
|  |  | sval )

Value:
rb_data_typed_object_make( \
(klass), \
(data_type), \
RBIMPL_CAST((void **)&(sval)), \
sizeof(type))
rb_data_typed_object_make
static VALUE rb_data_typed_object_make(VALUE klass, const rb_data_type_t *type, void **datap, size_t size)
While we don't stop you from using this function, it seems to be an implementation detail of TypedDat...
Definition rtypeddata.h:590

Identical to TypedData_Wrap_Struct, except it allocates a new data region internally instead of taking an existing one.

The allocation is done using ruby_calloc(). Hence it makes no sense for `data_type->function.dfree` to be anything other than RUBY_TYPED_DEFAULT_FREE.

Parameters

  klass | Ruby level class of the object.
  type | Type name of the C struct.
  data_type | The data type describing `type`.
  sval | Variable name of created C struct.

Exceptions

  rb_eTypeError | `klass` is not a class.
  rb_eNoMemError | Out of memory.

Returns
  A created Ruby object.

Definition at line 489 of file rtypeddata.h.

## ◆ TypedData_Make_Struct0

#define TypedData_Make_Struct0 | ( |  | result,
|  |  | klass,
|  |  | type,
|  |  | size,
|  |  | data_type,
|  |  | sval )

Value:
VALUE result = rb_data_typed_object_zalloc(klass, size, data_type); \
(sval) = RBIMPL_CAST((type *)RTYPEDDATA_DATA(result)); \
RBIMPL_CAST(/*suppress unused variable warnings*/(void)(sval))
RTYPEDDATA_DATA
#define RTYPEDDATA_DATA(v)
Convenient getter macro.
Definition rtypeddata.h:102
rb_data_typed_object_zalloc
VALUE rb_data_typed_object_zalloc(VALUE klass, size_t size, const rb_data_type_t *type)
Identical to rb_data_typed_object_wrap(), except it allocates a new data region internally instead of...
Definition gc.c:3140
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

This is an implementation detail of TypedData_Make_Struct.

People don't use it directly.

Parameters

  result | Variable name of created Ruby object.
  klass | Ruby level class of the object.
  type | Type name of the C struct.
  size | Size of the C struct.
  data_type | The data type describing `type`.
  sval | Variable name of created C struct.

Definition at line 457 of file rtypeddata.h.

Referenced by rb_data_typed_object_make().

## ◆ TypedData_Wrap_Struct

#define TypedData_Wrap_Struct | ( |  | klass,
|  |  | data_type,
|  |  | sval )

Value:
rb_data_typed_object_wrap((klass),(sval),(data_type))
rb_data_typed_object_wrap
VALUE rb_data_typed_object_wrap(VALUE klass, void *datap, const rb_data_type_t *type)
This is the primitive way to wrap an existing C struct into RTypedData.
Definition gc.c:3132

Converts sval, a pointer to your struct, into a Ruby object.

Parameters

  klass | A ruby level class.
  data_type | The type of `sval`.
  sval | A pointer to your struct.

Exceptions

  rb_eTypeError | `klass` is not a class.
  rb_eNoMemError | Out of memory.

Returns
  A created Ruby object.

Definition at line 441 of file rtypeddata.h.

Referenced by rb_memory_view_register().

## Typedef Documentation

## ◆ rb_data_type_t

typedef struct rb_data_type_struct rb_data_type_t

This is the struct that holds necessary info for a struct.

It roughly resembles a Ruby level class; multiple objects can share a rb_data_type_t instance.

Definition at line 187 of file rtypeddata.h.

## Function Documentation

## ◆ rb_data_typed_object_alloc()

static VALUE rb_data_typed_object_alloc | ( | VALUE | klass,
|  | void * | datap,
|  | const rb_data_type_t * | type )
| inlinestatic

Deprecated
  This function was renamed to rb_data_typed_object_wrap().

Definition at line 599 of file rtypeddata.h.

## ◆ rb_data_typed_object_make()

static VALUE rb_data_typed_object_make | ( | VALUE | klass,
|  | const rb_data_type_t * | type,
|  | void ** | datap,
|  | size_t | size )
| inlinestatic

While we don't stop you from using this function, it seems to be an implementation detail of TypedData_Make_Struct, which is preferred over this one.

Parameters

  [in] | klass | Ruby level class of the returning object.
  [in] | type | The data type
  [out] | datap | Return pointer.
  [in] | size | Size of the C struct.

Exceptions

  rb_eTypeError | `klass` is not a class.
  rb_eNoMemError | Out of memory.

Returns
  A created Ruby object.

Postcondition
  `*datap` points to the C struct wrapped by the returned object.

Definition at line 590 of file rtypeddata.h.

## ◆ rb_data_typed_object_wrap()

VALUE rb_data_typed_object_wrap | ( | VALUE | klass,
|  | void * | datap,
|  | const rb_data_type_t * | type )

This is the primitive way to wrap an existing C struct into RTypedData.

Parameters

  [in] | klass | Ruby level class of the returning object.
  [in] | datap | Pointer to the target C struct.
  [in] | type | The characteristics of the passed data.

Exceptions

  rb_eTypeError | `klass` is not a class.
  rb_eNoMemError | Out of memory.

Returns
  An allocated object that wraps `datap`.

Definition at line 3132 of file gc.c.

Referenced by rb_data_typed_object_alloc().

## ◆ rb_data_typed_object_zalloc()

VALUE rb_data_typed_object_zalloc | ( | VALUE | klass,
|  | size_t | size,
|  | const rb_data_type_t * | type )

Identical to rb_data_typed_object_wrap(), except it allocates a new data region internally instead of taking an existing one.

The allocation is done using ruby_calloc(). Hence it makes no sense for `type->function.dfree` to be anything other than RUBY_TYPED_DEFAULT_FREE.

Parameters

  [in] | klass | Ruby level class of the returning object.
  [in] | size | Requested size of memory to allocate.
  [in] | type | The characteristics of the passed data.

Exceptions

  rb_eTypeError | `klass` is not a class.
  rb_eNoMemError | Out of memory.

Returns
  An allocated object that wraps a new `size` byte region.

Definition at line 3140 of file gc.c.

## ◆ RTYPEDDATA_P()

static bool RTYPEDDATA_P | ( | VALUE | obj | ) |
| inlinestatic

Checks whether the passed object is RTypedData or RData.

Parameters

  [in] | obj | Object in question

Return values

  true | `obj` is an instance of RTypedData.
  false | `obj` is an instance of RData.

Precondition
  `obj` must be a Ruby object of RUBY_T_DATA.

Definition at line 540 of file rtypeddata.h.

Referenced by rb_check_typeddata(), rb_rand_if(), rb_typeddata_is_kind_of(), and RTYPEDDATA_TYPE().

## ◆ RTYPEDDATA_TYPE()

static const struct rb_data_type_struct * RTYPEDDATA_TYPE | ( | VALUE | obj | ) |
| inlinestatic

Queries for the type of given object.

Parameters

  [in] | obj | Object in question

Returns
  Data type struct that corresponds to `obj`.

Precondition
  `obj` must be an instance of RTypedData.

Definition at line 563 of file rtypeddata.h.

Referenced by rb_check_typeddata(), rb_rand_if(), and rb_typeddata_is_kind_of().