Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
Data Structures | Macros | Typedefs | Functions
rdata.h File Reference

(348a53415339076afc4a02fcd09f3ae36e9c4c61)

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"
Include dependency graph for rdata.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  RData
 

Macros

#define RDATA(obj)   RBIMPL_CAST((struct RData *)(obj))
 Convenient casting macro. More...
 
#define DATA_PTR(obj)   RDATA(obj)->data
 Convenient getter macro. More...
 
#define RUBY_DEFAULT_FREE   RBIMPL_DATA_FUNC(-1)
 This is a value you can set to RData::dfree. More...
 
#define RUBY_NEVER_FREE   RBIMPL_DATA_FUNC(0)
 This is a value you can set to RData::dfree. More...
 
#define RUBY_UNTYPED_DATA_FUNC(f)   f RBIMPL_ATTRSET_UNTYPED_DATA_FUNC()
 
#define Data_Wrap_Struct(klass, mark, free, sval)
 Converts sval, a pointer to your struct, into a Ruby object. More...
 
#define Data_Make_Struct0(result, klass, type, size, mark, free, sval)
 This is an implementation detail of Data_Make_Struct. More...
 
#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. More...
 
#define Data_Get_Struct(obj, type, sval)    ((sval) = RBIMPL_CAST((type*)rb_data_object_get(obj)))
 Obtains a C struct from inside of a wrapper Ruby object. More...
 

Typedefs

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

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. More...
 
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. More...
 
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. More...
 
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
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 
)     ((sval) = RBIMPL_CAST((type*)rb_data_object_get(obj)))

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

Parameters
objAn instance of RData.
typeType name of the C struct.
svalVariable name of obtained C struct.
Returns
Unwrapped C struct that obj holds.

Definition at line 274 of file rdata.h.

◆ Data_Make_Struct

#define Data_Make_Struct (   klass,
  type,
  mark,
  free,
  sval 
)
Value:
(klass), \
RBIMPL_DATA_FUNC(mark), \
RBIMPL_DATA_FUNC(free), \
RBIMPL_CAST((void **)&(sval)), \
sizeof(type))
VALUE type(ANYARGS)
ANYARGS-ed function type.
Definition: cxxanyargs.hpp:56
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:345

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
klassRuby level class of the returning object.
typeType name of the C struct.
markMark function.
freeFree function.
svalVariable name of created C struct.
Exceptions
rb_eTypeErrorklass is not a class.
rb_eNoMemErrorOut of memory.
Returns
A created Ruby object.

Definition at line 257 of file rdata.h.

◆ Data_Make_Struct0

#define Data_Make_Struct0 (   result,
  klass,
  type,
  size,
  mark,
  free,
  sval 
)
Value:
(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))
#define DATA_PTR(obj)
Convenient getter macro.
Definition: rdata.h:67
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:954
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
resultVariable name of created Ruby object.
klassRuby level class of the object.
typeType name of the C struct.
sizeSize of the C struct.
markMark function.
freeFree function.
svalVariable name of created C struct.

Definition at line 219 of file rdata.h.

◆ DATA_PTR

#define DATA_PTR (   obj)    RDATA(obj)->data

Convenient getter macro.

Parameters
objAn object, which is in fact an RData.
Returns
The passed object's RData::data field.

Definition at line 67 of file rdata.h.

◆ Data_Wrap_Struct

#define Data_Wrap_Struct (   klass,
  mark,
  free,
  sval 
)
Value:
(klass), \
(sval), \
RBIMPL_DATA_FUNC(mark), \
RBIMPL_DATA_FUNC(free))
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:946

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

Parameters
klassA ruby level class.
markMark function.
freeFree function.
svalA pointer to your struct.
Exceptions
rb_eTypeErrorklass is not a class.
rb_eNoMemErrorOut of memory.
Returns
A created Ruby object.

Definition at line 198 of file rdata.h.

◆ RDATA

#define RDATA (   obj)    RBIMPL_CAST((struct RData *)(obj))

Convenient casting macro.

Parameters
objAn object, which is in fact an RData.
Returns
The passed object casted to RData.

Definition at line 59 of file rdata.h.

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

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

◆ RUBY_UNTYPED_DATA_FUNC

#define RUBY_UNTYPED_DATA_FUNC (   f)    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 94 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 104 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 354 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]klassRuby level class of the returning object.
[in]mark_funcMark function.
[in]free_funcFree function.
[in]datapVariable of created C struct.
[in]sizeRequested size of allocation.
Exceptions
rb_eTypeErrorklass is not a class.
rb_eNoMemErrorOut of memory.
Returns
A created Ruby object.
Postcondition
*datap holds the created C struct.

Definition at line 345 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]klassRuby level class of the returning object.
[in]datapPointer to the target C struct.
[in]dmarkMark function.
[in]dfreeFree function.
Exceptions
rb_eTypeErrorklass is not a class.
rb_eNoMemErrorOut of memory.
Returns
An allocated object that wraps datap.

Definition at line 946 of file gc.c.

Referenced by rb_data_object_zalloc().

◆ 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]klassRuby level class of the returning object.
[in]sizeRequested size of memory to allocate.
[in]dmarkMark function.
[in]dfreeFree function.
Exceptions
rb_eTypeErrorklass is not a class.
rb_eNoMemErrorOut of memory.
Returns
An allocated object that wraps a new size byte region.

Definition at line 954 of file gc.c.