(892c46283a5ea4179500d951c9d4866c0051f27b)

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

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
	)	((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 274 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))

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 257 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))

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

◆ DATA_PTR

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

Convenient getter macro.

Parameters

obj	An 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:

    rb_data_object_wrap(                          \
        (klass),                                  \
        (sval),                                   \
        RBIMPL_DATA_FUNC(mark),                    \
        RBIMPL_DATA_FUNC(free))

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

◆ RDATA

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

Convenient casting macro.

Parameters

obj	An 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]	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 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]	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 1033 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]	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 1041 of file gc.c.

(892c46283a5ea4179500d951c9d4866c0051f27b)

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ Data_Get_Struct

◆ Data_Make_Struct

◆ Data_Make_Struct0

◆ DATA_PTR

◆ Data_Wrap_Struct

◆ RDATA

◆ RUBY_DEFAULT_FREE

◆ RUBY_NEVER_FREE

◆ RUBY_UNTYPED_DATA_FUNC

Typedef Documentation

◆ RUBY_DATA_FUNC

Function Documentation

◆ rb_data_object_alloc()

◆ rb_data_object_make()

◆ rb_data_object_wrap()

◆ rb_data_object_zalloc()