(892c46283a5ea4179500d951c9d4866c0051f27b)

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"

Include dependency graph for rtypeddata.h:

This graph shows which files directly or indirectly include this file:

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. More...

#define	RUBY_TYPED_NEVER_FREE RUBY_NEVER_FREE
	This is a value you can set to rb_data_type_struct::dfree. More...

#define	RTYPEDDATA(obj) RBIMPL_CAST((struct RTypedData *)(obj))
	Convenient casting macro. More...

#define	RTYPEDDATA_DATA(v) (RTYPEDDATA(v)->data)
	Convenient getter macro. More...

#define	Check_TypedStruct(v, t) rb_check_typeddata(RBIMPL_CAST((VALUE)(v)), (t))
	Old name of rb_check_typeddata. More...

#define	TYPED_DATA_EMBEDDED 2

#define	TypedData_Wrap_Struct(klass, data_type, sval) rb_data_typed_object_wrap((klass),(sval),(data_type))
	Converts sval, a pointer to your struct, into a Ruby object. More...

#define	TypedData_Make_Struct0(result, klass, type, size, data_type, sval)
	This is an implementation detail of TypedData_Make_Struct. More...

#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. More...

#define	TypedData_Get_Struct(obj, type, data_type, sval) ((sval) = RBIMPL_CAST((type *)rb_check_typeddata((obj), (data_type))))
	Obtains a C struct from inside of a wrapper Ruby object. More...

Typedefs
typedef struct rb_data_type_struct	rb_data_type_t
	This is the struct that holds necessary info for a struct. More...

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. More...

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. More...

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. More...

int	rb_typeddata_is_kind_of (VALUE obj, const rb_data_type_t *data_type)
	Checks if the given object is of given kind. More...

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. More...

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. More...

static const struct rb_data_type_struct *	RTYPEDDATA_TYPE (VALUE obj)
	Queries for the type of given object. More...

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. More...

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 ) RBIMPL_CAST((struct RTypedData *)(obj))

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.

◆ RTYPEDDATA_DATA

#define RTYPEDDATA_DATA ( v ) (RTYPEDDATA(v)->data)

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.

◆ TypedData_Get_Struct

#define TypedData_Get_Struct	(	obj,
		type,
		data_type,
		sval
	)	((sval) = RBIMPL_CAST((type *)rb_check_typeddata((obj), (data_type))))

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.

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

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

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.

◆ TypedData_Wrap_Struct

#define TypedData_Wrap_Struct	(	klass,
		data_type,
		sval
	)	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.

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

Function Documentation

◆ rb_data_typed_object_alloc()

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

static 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 1058 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 1068 of file gc.c.

◆ RTYPEDDATA_P()

static 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_rand_if(), rb_typeddata_is_kind_of(), and RTYPEDDATA_TYPE().

◆ RTYPEDDATA_TYPE()

static 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_rand_if(), and rb_typeddata_is_kind_of().

(892c46283a5ea4179500d951c9d4866c0051f27b)

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ HAVE_RB_DATA_TYPE_T_FUNCTION

◆ HAVE_RB_DATA_TYPE_T_PARENT

◆ HAVE_TYPE_RB_DATA_TYPE_T

◆ RTYPEDDATA

◆ RTYPEDDATA_DATA

◆ RUBY_TYPED_DEFAULT_FREE

◆ RUBY_TYPED_NEVER_FREE

◆ TypedData_Get_Struct

◆ TypedData_Make_Struct

◆ TypedData_Make_Struct0

◆ TypedData_Wrap_Struct

Typedef Documentation

◆ rb_data_type_t

Function Documentation

◆ rb_data_typed_object_alloc()

◆ rb_data_typed_object_make()

◆ rb_data_typed_object_wrap()

◆ rb_data_typed_object_zalloc()

◆ RTYPEDDATA_P()

◆ RTYPEDDATA_TYPE()