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

Ruby 3.4.9p82 (2026-03-11 revision 76cca827ab52ab1d346a728f068d5b8da3e2952b)

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 | TYPED_DATA_EMBEDDED 2
#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_EMBEDDED_P (VALUE obj)
static void * | RTYPEDDATA_GET_DATA (VALUE obj)
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:350

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.

## ◆ TYPED_DATA_EMBEDDED

#define TYPED_DATA_EMBEDDED 2

Definition at line 117 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:1397

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 515 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:629

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 497 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) = (type *)RTYPEDDATA_GET_DATA(result); \
RBIMPL_CAST(/*suppress unused variable warnings*/(void)(sval))
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 465 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))

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 449 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 197 of file rtypeddata.h.

## Function Documentation

## ◆ rb_data_typed_object_alloc()

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 638 of file rtypeddata.h.

## ◆ rb_data_typed_object_make()

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 629 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 1087 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 1097 of file gc.c.

## ◆ RTYPEDDATA_EMBEDDED_P()

bool RTYPEDDATA_EMBEDDED_P | ( | VALUE | obj | ) |
| inlinestatic

Definition at line 519 of file rtypeddata.h.

## ◆ RTYPEDDATA_GET_DATA()

void * RTYPEDDATA_GET_DATA | ( | VALUE | obj | ) |
| inlinestatic

Definition at line 532 of file rtypeddata.h.

## ◆ RTYPEDDATA_P()

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 579 of file rtypeddata.h.

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

## ◆ RTYPEDDATA_TYPE()

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 602 of file rtypeddata.h.

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