Ruby: rb_data_type_struct Struct Reference

Ruby 3.4.1p0 (2024-12-25 revision 48d4efcb85000e1ebae42004e963b5d0cedddcf2)

Data Fields
rb_data_type_struct Struct Reference

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

`#include <rtypeddata.h>`

## Data Fields
const char * | wrap_struct_name
| Name of structs of this kind.
struct { |
RUBY_DATA_FUNC dmark |
| This function is called when the object is experiencing GC marks. More...
RUBY_DATA_FUNC dfree |
| This function is called when the object is no longer used. More...
size_t(* dsize )(const void *) |
| This function is to query the size of the underlying memory regions. More...
RUBY_DATA_FUNC dcompact |
| This function is called when the object is relocated. More...
void * reserved [1] |
| This field is reserved for future extension. More...
} | function |
| Function pointers.
const rb_data_type_t * | parent
| Parent of this class.
void * | data
| Type-specific static data.
VALUE | flags
| Type-specific behavioural characteristics.

## Detailed Description

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

## Field Documentation

## ◆ data

void* rb_data_type_struct::data

Type-specific static data.

This area can be used for any purpose by a programmer who define the type. Ruby does not manage this at all.

Definition at line 296 of file rtypeddata.h.

## ◆ dcompact

RUBY_DATA_FUNC rb_data_type_struct::dcompact

This function is called when the object is relocated.

Like rb_data_type_struct::dmark, you need to update references to Ruby objects inside of your structs.

See also
  rb_gc_location()

Warning
  This is called during GC runs. Object allocations are impossible at that moment (that is why GC runs).

Definition at line 251 of file rtypeddata.h.

## ◆ dfree

RUBY_DATA_FUNC rb_data_type_struct::dfree

This function is called when the object is no longer used.

You need to do whatever necessary to avoid memory leaks.

Warning
  This is called during GC runs. Object allocations are impossible at that moment (that is why GC runs).

Definition at line 230 of file rtypeddata.h.

## ◆ dmark

RUBY_DATA_FUNC rb_data_type_struct::dmark

This function is called when the object is experiencing GC marks.

If it contains references to other Ruby objects, you need to mark them also. Otherwise GC will smash your data.

See also
  rb_gc_mark()

Warning
  This is called during GC runs. Object allocations are impossible at that moment (that is why GC runs).

Definition at line 221 of file rtypeddata.h.

## ◆ dsize

size_t(* rb_data_type_struct::dsize) (const void *)

This function is to query the size of the underlying memory regions.

Definition at line 240 of file rtypeddata.h.

## ◆ flags

VALUE rb_data_type_struct::flags

Type-specific behavioural characteristics.

This is a bitfield. It is an EXTREMELY WISE IDEA to leave this field blank. It is designed so that setting zero is the safest thing to do. If you risk to set any bits on, you have to know exactly what you are doing.

Definition at line 309 of file rtypeddata.h.

## ◆ [struct]

struct { ... } rb_data_type_struct::function

Function pointers.

Resembles C++ `vtbl`.

## ◆ parent

const rb_data_type_t* rb_data_type_struct::parent

Parent of this class.

Sometimes C structs have inheritance-like relationships. An example is `struct sockaddr` and its family. If you design such things, make rb_data_type_t for each of them and connect using this field. Ruby can then transparently cast your data back and forth when you call TypedData_Get_Struct().

struct parent { };
static inline const rb_data_type_t parent_type = {
.wrap_struct_name = "parent",
};
struct child: public parent { };
static inline const rb_data_type_t child_type = {
.wrap_struct_name = "child",
.parent = &parent_type,
};
// This function can take both parent_class and child_class.
static inline struct parent *
get_parent(VALUE v)
{
struct parent *p;
TypedData_Get_Struct(v, parent_type, struct parent, p);
return p;
}
TypedData_Get_Struct
#define TypedData_Get_Struct(obj, type, data_type, sval)
Obtains a C struct from inside of a wrapper Ruby object.
Definition rtypeddata.h:515
rb_data_type_t
struct rb_data_type_struct rb_data_type_t
This is the struct that holds necessary info for a struct.
Definition rtypeddata.h:197
rb_data_type_struct::parent
const rb_data_type_t * parent
Parent of this class.
Definition rtypeddata.h:290
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

Definition at line 290 of file rtypeddata.h.

Referenced by rb_typeddata_inherited_p().

## ◆ reserved

void* rb_data_type_struct::reserved[1]

This field is reserved for future extension.

For now, it must be filled with zeros.

Definition at line 257 of file rtypeddata.h.

## ◆ wrap_struct_name

const char* rb_data_type_struct::wrap_struct_name

Name of structs of this kind.

This is used for diagnostic purposes. This has to be unique in the process, but doesn't has to be a valid C/Ruby identifier.

Definition at line 207 of file rtypeddata.h.

Referenced by rb_check_typeddata().

The documentation for this struct was generated from the following file:

- include/ruby/internal/core/rtypeddata.h