(11ce3778c6eacc10897729314e5ab3bed7830971)

Defines struct RTypedData. More...

#include "ruby/internal/config.h"
#include "ruby/assert.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/static_assert.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.

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

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

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

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

#define	RUBY_TYPED_FREE_IMMEDIATELY RUBY_TYPED_FREE_IMMEDIATELY
	Macros to see if each corresponding flag is defined.

#define	RUBY_TYPED_THREAD_SAFE_FREE RUBY_TYPED_THREAD_SAFE_FREE

#define	RUBY_TYPED_FROZEN_SHAREABLE RUBY_TYPED_FROZEN_SHAREABLE

#define	RUBY_TYPED_WB_PROTECTED RUBY_TYPED_WB_PROTECTED

#define	RUBY_TYPED_EMBEDDABLE RUBY_TYPED_EMBEDDABLE

#define	RUBY_TYPED_PROMOTED1 RUBY_TYPED_PROMOTED1

#define	RDATA(obj) RTYPEDDATA(obj)
	Convenient casting macro for backward compatibility.

#define	DATA_PTR(obj) RTYPEDDATA_DATA(obj)
	Convenient casting macro for backward compatibility.

#define	RBIMPL_TYPEDDATA_PRECONDITION(obj, unreachable) RBIMPL_ASSERT_NOTHING

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

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

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

#define	rb_typeddata_inherited_p rbimpl_typeddata_inherited_p_inline

#define	rb_typeddata_is_kind_of rbimpl_typeddata_is_kind_of_inline

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

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

Functions
static VALUE	rbimpl_check_external_typeddata (VALUE obj)
	This is an implementation detail of RTYPEDDATA_DATA().

	RBIMPL_STATIC_ASSERT (fields_obj_in_rdata, offsetof(struct RData, fields_obj)==offsetof(struct RTypedData, fields_obj))

	RBIMPL_STATIC_ASSERT (data_in_rtypeddata, offsetof(struct RData, data)==offsetof(struct RTypedData, data))

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.

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.

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.

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

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.

static bool	rbimpl_typeddata_embedded_p (VALUE obj)

static bool	RTYPEDDATA_EMBEDDED_P (VALUE obj)

static void *	rbimpl_typeddata_get_data (VALUE obj)

static void *	RTYPEDDATA_GET_DATA (VALUE obj)

static bool	RTYPEDDATA_P (VALUE obj)
	Checks whether the passed object is RTypedData.

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

static bool	rbimpl_typeddata_inherited_p_inline (const rb_data_type_t child, const rb_data_type_t parent)

static bool	rbimpl_typeddata_is_kind_of_inline (VALUE obj, const rb_data_type_t *data_type)

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.

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

◆ DATA_PTR

#define DATA_PTR ( obj ) RTYPEDDATA_DATA(obj)

Convenient casting macro for backward compatibility.

Parameters

obj	An object, which is in fact an RData.

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

Definition at line 435 of file rtypeddata.h.

◆ 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 61 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 70 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 52 of file rtypeddata.h.

◆ rb_typeddata_inherited_p

#define rb_typeddata_inherited_p rbimpl_typeddata_inherited_p_inline

Definition at line 712 of file rtypeddata.h.

◆ rb_typeddata_is_kind_of

#define rb_typeddata_is_kind_of rbimpl_typeddata_is_kind_of_inline

Definition at line 722 of file rtypeddata.h.

◆ RBIMPL_TYPEDDATA_PRECONDITION

#define RBIMPL_TYPEDDATA_PRECONDITION	(	obj,
		unreachable
	)	RBIMPL_ASSERT_NOTHING

Definition at line 543 of file rtypeddata.h.

◆ RDATA

#define RDATA ( obj ) RTYPEDDATA(obj)

Convenient casting macro for backward compatibility.

Parameters

obj	An object, which is in fact an RData.

Returns: The passed object casted to RData.

Definition at line 427 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 96 of file rtypeddata.h.

◆ RTYPEDDATA_DATA

#define RTYPEDDATA_DATA ( v ) (RTYPEDDATA(rbimpl_check_external_typeddata(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 106 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 81 of file rtypeddata.h.

◆ RUBY_TYPED_EMBEDDABLE

#define RUBY_TYPED_EMBEDDABLE RUBY_TYPED_EMBEDDABLE

Definition at line 126 of file rtypeddata.h.

◆ RUBY_TYPED_FREE_IMMEDIATELY

#define RUBY_TYPED_FREE_IMMEDIATELY RUBY_TYPED_FREE_IMMEDIATELY

Macros to see if each corresponding flag is defined.

Definition at line 122 of file rtypeddata.h.

◆ RUBY_TYPED_FROZEN_SHAREABLE

#define RUBY_TYPED_FROZEN_SHAREABLE RUBY_TYPED_FROZEN_SHAREABLE

Definition at line 124 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 88 of file rtypeddata.h.

◆ RUBY_TYPED_PROMOTED1

#define RUBY_TYPED_PROMOTED1 RUBY_TYPED_PROMOTED1

Definition at line 127 of file rtypeddata.h.

◆ RUBY_TYPED_THREAD_SAFE_FREE

#define RUBY_TYPED_THREAD_SAFE_FREE RUBY_TYPED_THREAD_SAFE_FREE

Definition at line 123 of file rtypeddata.h.

◆ RUBY_TYPED_WB_PROTECTED

#define RUBY_TYPED_WB_PROTECTED RUBY_TYPED_WB_PROTECTED

Definition at line 125 of file rtypeddata.h.

◆ TypedData_Get_Struct

#define TypedData_Get_Struct	(	obj,
		type,
		data_type,
		sval
	)	((sval) = RBIMPL_CAST((type *)rbimpl_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 773 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().

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 604 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) = RBIMPL_CAST((type *)rbimpl_typeddata_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 573 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 557 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 235 of file rtypeddata.h.

Function Documentation

◆ 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 792 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 1339 of file gc.c.

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

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

◆ rbimpl_check_external_typeddata()

static VALUE rbimpl_check_external_typeddata ( VALUE obj )

inlinestatic

This is an implementation detail of RTYPEDDATA_DATA().

Don't use it directly.

Definition at line 756 of file rtypeddata.h.

◆ rbimpl_typeddata_embedded_p()

static bool rbimpl_typeddata_embedded_p ( VALUE obj )

inlinestatic

Definition at line 613 of file rtypeddata.h.

◆ rbimpl_typeddata_get_data()

static void * rbimpl_typeddata_get_data ( VALUE obj )

inlinestatic

Definition at line 628 of file rtypeddata.h.

◆ rbimpl_typeddata_inherited_p_inline()

static bool rbimpl_typeddata_inherited_p_inline	(	const rb_data_type_t *	child,
		const rb_data_type_t *	parent
	)

inlinestatic

Definition at line 705 of file rtypeddata.h.

◆ rbimpl_typeddata_is_kind_of_inline()

static bool rbimpl_typeddata_is_kind_of_inline	(	VALUE	obj,
		const rb_data_type_t *	data_type
	)

inlinestatic

Definition at line 717 of file rtypeddata.h.

◆ RTYPEDDATA_EMBEDDED_P()

static bool RTYPEDDATA_EMBEDDED_P ( VALUE obj )

inlinestatic

Definition at line 620 of file rtypeddata.h.

◆ RTYPEDDATA_GET_DATA()

static void * RTYPEDDATA_GET_DATA ( VALUE obj )

inlinestatic

Definition at line 637 of file rtypeddata.h.

◆ RTYPEDDATA_P()

static bool RTYPEDDATA_P ( VALUE obj )

inlinestatic

Checks whether the passed object is RTypedData.

Parameters

[in] obj Object in question

Return values

true

Precondition: obj must be a Ruby object of RUBY_T_DATA.

Definition at line 674 of file rtypeddata.h.

◆ RTYPEDDATA_TYPE()

static const rb_data_type_t * 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 692 of file rtypeddata.h.

Referenced by rb_rand_if().

(11ce3778c6eacc10897729314e5ab3bed7830971)

Data Structures

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ DATA_PTR

◆ HAVE_RB_DATA_TYPE_T_FUNCTION

◆ HAVE_RB_DATA_TYPE_T_PARENT

◆ HAVE_TYPE_RB_DATA_TYPE_T

◆ rb_typeddata_inherited_p

◆ rb_typeddata_is_kind_of

◆ RBIMPL_TYPEDDATA_PRECONDITION

◆ RDATA

◆ RTYPEDDATA

◆ RTYPEDDATA_DATA

◆ RUBY_TYPED_DEFAULT_FREE

◆ RUBY_TYPED_EMBEDDABLE

◆ RUBY_TYPED_FREE_IMMEDIATELY

◆ RUBY_TYPED_FROZEN_SHAREABLE

◆ RUBY_TYPED_NEVER_FREE

◆ RUBY_TYPED_PROMOTED1

◆ RUBY_TYPED_THREAD_SAFE_FREE

◆ RUBY_TYPED_WB_PROTECTED

◆ TypedData_Get_Struct

◆ TypedData_Make_Struct

◆ TypedData_Make_Struct0

◆ TypedData_Wrap_Struct

Typedef Documentation

◆ rb_data_type_t

Function Documentation

◆ rb_data_typed_object_make()

◆ rb_data_typed_object_wrap()

◆ rb_data_typed_object_zalloc()

◆ rbimpl_check_external_typeddata()

◆ rbimpl_typeddata_embedded_p()

◆ rbimpl_typeddata_get_data()

◆ rbimpl_typeddata_inherited_p_inline()

◆ rbimpl_typeddata_is_kind_of_inline()

◆ RTYPEDDATA_EMBEDDED_P()

◆ RTYPEDDATA_GET_DATA()

◆ RTYPEDDATA_P()

◆ RTYPEDDATA_TYPE()