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

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

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

Defines struct RData. More...

`#include "ruby/internal/config.h"`
`#include "ruby/internal/attr/deprecated.h"`
`#include "ruby/internal/attr/warning.h"`
`#include "ruby/internal/cast.h"`
`#include "ruby/internal/core/rbasic.h"`
`#include "ruby/internal/dllexport.h"`
`#include "ruby/internal/fl_type.h"`
`#include "ruby/internal/value.h"`
`#include "ruby/internal/value_type.h"`
`#include "ruby/defines.h"`

Go to the source code of this file.

## Data Structures
struct | RData

## Macros
#define | RDATA(obj)
| Convenient casting macro.
#define | DATA_PTR(obj)
| Convenient getter macro.
#define | RUBY_DEFAULT_FREE RBIMPL_DATA_FUNC(-1)
| This is a value you can set to RData::dfree.
#define | RUBY_NEVER_FREE RBIMPL_DATA_FUNC(0)
| This is a value you can set to RData::dfree.
#define | RUBY_UNTYPED_DATA_FUNC(f)
#define | Data_Wrap_Struct(klass, mark, free, sval)
| Converts sval, a pointer to your struct, into a Ruby object.
#define | Data_Make_Struct0(result, klass, type, size, mark, free, sval)
| This is an implementation detail of Data_Make_Struct.
#define | Data_Make_Struct(klass, type, mark, free, sval)
| Identical to Data_Wrap_Struct, except it allocates a new data region internally instead of taking an existing one.
#define | Data_Get_Struct(obj, type, sval)
| Obtains a C struct from inside of a wrapper Ruby object.

## Typedefs
typedef void(* | RUBY_DATA_FUNC) (void *)
| This is the type of callbacks registered to RData.

## Functions
VALUE | rb_data_object_wrap (VALUE klass, void *datap, RUBY_DATA_FUNC dmark, RUBY_DATA_FUNC dfree)
| This is the primitive way to wrap an existing C struct into RData.
VALUE | rb_data_object_zalloc (VALUE klass, size_t size, RUBY_DATA_FUNC dmark, RUBY_DATA_FUNC dfree)
| Identical to rb_data_object_wrap(), except it allocates a new data region internally instead of taking an existing one.
static VALUE | rb_data_object_make (VALUE klass, RUBY_DATA_FUNC mark_func, RUBY_DATA_FUNC free_func, void **datap, size_t size)
| This is an implementation detail of Data_Make_Struct.
static VALUE | rb_data_object_alloc (VALUE klass, void *data, RUBY_DATA_FUNC dmark, RUBY_DATA_FUNC dfree)

## Detailed Description

Defines struct RData.

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

## Macro Definition Documentation

## ◆ Data_Get_Struct

#define Data_Get_Struct | ( |  | obj,
|  |  | type,
|  |  | sval )

Value:
((sval) = RBIMPL_CAST((type*)rb_data_object_get(obj)))

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

Parameters

  obj | An instance of RData.
  type | Type name of the C struct.
  sval | Variable name of obtained C struct.

Returns
  Unwrapped C struct that `obj` holds.

Definition at line 278 of file rdata.h.

## ◆ Data_Make_Struct

#define Data_Make_Struct | ( |  | klass,
|  |  | type,
|  |  | mark,
|  |  | free,
|  |  | sval )

Value:
rb_data_object_make( \
(klass), \
RBIMPL_DATA_FUNC(mark), \
RBIMPL_DATA_FUNC(free), \
RBIMPL_CAST((void **)&(sval)), \
sizeof(type))
rb_data_object_make
static VALUE rb_data_object_make(VALUE klass, RUBY_DATA_FUNC mark_func, RUBY_DATA_FUNC free_func, void **datap, size_t size)
This is an implementation detail of Data_Make_Struct.
Definition rdata.h:358

Identical to Data_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 to pass anything other than RUBY_DEFAULT_FREE to the `free` argument.

Parameters

  klass | Ruby level class of the returning object.
  type | Type name of the C struct.
  mark | Mark function.
  free | Free function.
  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 261 of file rdata.h.

## ◆ Data_Make_Struct0

#define Data_Make_Struct0 | ( |  | result,
|  |  | klass,
|  |  | type,
|  |  | size,
|  |  | mark,
|  |  | free,
|  |  | sval )

Value:
VALUE result = rb_data_object_zalloc( \
(klass), \
(size), \
RBIMPL_DATA_FUNC(mark), \
RBIMPL_DATA_FUNC(free)); \
(sval) = RBIMPL_CAST((type *)DATA_PTR(result)); \
RBIMPL_CAST(/*suppress unused variable warnings*/(void)(sval))
DATA_PTR
#define DATA_PTR(obj)
Convenient getter macro.
Definition rdata.h:71
rb_data_object_zalloc
VALUE rb_data_object_zalloc(VALUE klass, size_t size, RUBY_DATA_FUNC dmark, RUBY_DATA_FUNC dfree)
Identical to rb_data_object_wrap(), except it allocates a new data region internally instead of takin...
Definition gc.c:3124
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40

This is an implementation detail of Data_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.
  mark | Mark function.
  free | Free function.
  sval | Variable name of created C struct.

Definition at line 223 of file rdata.h.

Referenced by rb_data_object_make().

## ◆ DATA_PTR

#define DATA_PTR | ( |  | obj | ) |

Value:
RDATA(obj)->data
RDATA
#define RDATA(obj)
Convenient casting macro.
Definition rdata.h:63

Convenient getter macro.

Parameters

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

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

Definition at line 71 of file rdata.h.

Referenced by rb_check_typeddata(), rb_data_object_zalloc(), rb_data_typed_object_zalloc(), and ruby_getcwd().

## ◆ Data_Wrap_Struct

#define Data_Wrap_Struct | ( |  | klass,
|  |  | mark,
|  |  | free,
|  |  | sval )

Value:
rb_data_object_wrap( \
(klass), \
(sval), \
RBIMPL_DATA_FUNC(mark), \
RBIMPL_DATA_FUNC(free))
rb_data_object_wrap
VALUE rb_data_object_wrap(VALUE klass, void *datap, RUBY_DATA_FUNC dmark, RUBY_DATA_FUNC dfree)
This is the primitive way to wrap an existing C struct into RData.
Definition gc.c:3116

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

Parameters

  klass | A ruby level class.
  mark | Mark function.
  free | Free function.
  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 202 of file rdata.h.

Referenced by ruby_getcwd().

## ◆ RDATA

#define RDATA | ( |  | obj | ) |

Value:
RBIMPL_CAST((struct RData *)(obj))
RData
Definition rdata.h:124

Convenient casting macro.

Parameters

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

Returns
  The passed object casted to RData.

Definition at line 63 of file rdata.h.

Referenced by rb_find_encoding(), and rb_to_encoding().

## ◆ RUBY_DEFAULT_FREE

#define RUBY_DEFAULT_FREE RBIMPL_DATA_FUNC(-1)

This is a value you can set to RData::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 82 of file rdata.h.

Referenced by ruby_getcwd().

## ◆ RUBY_NEVER_FREE

#define RUBY_NEVER_FREE RBIMPL_DATA_FUNC(0)

This is a value you can set to RData::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 89 of file rdata.h.

## ◆ RUBY_UNTYPED_DATA_FUNC

#define RUBY_UNTYPED_DATA_FUNC | ( |  | f | ) |

Value:
f RBIMPL_ATTRSET_UNTYPED_DATA_FUNC()

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 98 of file rdata.h.

## Typedef Documentation

## ◆ RUBY_DATA_FUNC

typedef void(* RUBY_DATA_FUNC) (void *)

This is the type of callbacks registered to RData.

The argument is the `data` field.

Definition at line 108 of file rdata.h.

## Function Documentation

## ◆ rb_data_object_alloc()

static VALUE rb_data_object_alloc | ( | VALUE | klass,
|  | void * | data,
|  | RUBY_DATA_FUNC | dmark,
|  | RUBY_DATA_FUNC | dfree )
| inlinestatic

Deprecated
  This function was renamed to rb_data_object_wrap().

Definition at line 367 of file rdata.h.

## ◆ rb_data_object_make()

static VALUE rb_data_object_make | ( | VALUE | klass,
|  | RUBY_DATA_FUNC | mark_func,
|  | RUBY_DATA_FUNC | free_func,
|  | void ** | datap,
|  | size_t | size )
| inlinestatic

This is an implementation detail of Data_Make_Struct.

People don't use it directly.

Parameters

  [in] | klass | Ruby level class of the returning object.
  [in] | mark_func | Mark function.
  [in] | free_func | Free function.
  [in] | datap | Variable of created C struct.
  [in] | size | Requested size of allocation.

Exceptions

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

Returns
  A created Ruby object.

Postcondition
  `*datap` holds the created C struct.

Definition at line 358 of file rdata.h.

## ◆ rb_data_object_wrap()

VALUE rb_data_object_wrap | ( | VALUE | klass,
|  | void * | datap,
|  | RUBY_DATA_FUNC | dmark,
|  | RUBY_DATA_FUNC | dfree )

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

Parameters

  [in] | klass | Ruby level class of the returning object.
  [in] | datap | Pointer to the target C struct.
  [in] | dmark | Mark function.
  [in] | dfree | Free function.

Exceptions

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

Returns
  An allocated object that wraps `datap`.

Definition at line 3116 of file gc.c.

Referenced by rb_data_object_alloc().

## ◆ rb_data_object_zalloc()

VALUE rb_data_object_zalloc | ( | VALUE | klass,
|  | size_t | size,
|  | RUBY_DATA_FUNC | dmark,
|  | RUBY_DATA_FUNC | dfree )

Identical to rb_data_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 to pass anything other than RUBY_DEFAULT_FREE to the last argument.

Parameters

  [in] | klass | Ruby level class of the returning object.
  [in] | size | Requested size of memory to allocate.
  [in] | dmark | Mark function.
  [in] | dfree | Free function.

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 3124 of file gc.c.