Ruby 3.5.0dev (2025-09-16 revision 7dd9c76ad46af63f76e0df243f76a1720f54d50d)
rtypeddata.h
Go to the documentation of this file.
1#ifndef RBIMPL_RTYPEDDATA_H /*-*-C++-*-vi:se ft=cpp:*/
2#define RBIMPL_RTYPEDDATA_H
23#include "ruby/internal/config.h"
24
25#ifdef STDC_HEADERS
26# include <stddef.h>
27#endif
28
34#include "ruby/internal/cast.h"
38#include "ruby/internal/error.h"
43
51#define HAVE_TYPE_RB_DATA_TYPE_T 1
52
60#define HAVE_RB_DATA_TYPE_T_FUNCTION 1
61
69#define HAVE_RB_DATA_TYPE_T_PARENT 1
70
80#define RUBY_TYPED_DEFAULT_FREE RUBY_DEFAULT_FREE
81
87#define RUBY_TYPED_NEVER_FREE RUBY_NEVER_FREE
88
95#define RTYPEDDATA(obj) RBIMPL_CAST((struct RTypedData *)(obj))
96
103#define RTYPEDDATA_DATA(v) (RTYPEDDATA(v)->data)
104
106#define Check_TypedStruct(v, t) \
107 rb_check_typeddata(RBIMPL_CAST((VALUE)(v)), (t))
108
110#define RTYPEDDATA_P RTYPEDDATA_P
111#define RTYPEDDATA_TYPE RTYPEDDATA_TYPE
112#define RUBY_TYPED_FREE_IMMEDIATELY RUBY_TYPED_FREE_IMMEDIATELY
113#define RUBY_TYPED_FROZEN_SHAREABLE RUBY_TYPED_FROZEN_SHAREABLE
114#define RUBY_TYPED_WB_PROTECTED RUBY_TYPED_WB_PROTECTED
115#define RUBY_TYPED_PROMOTED1 RUBY_TYPED_PROMOTED1
118#define TYPED_DATA_EMBEDDED ((VALUE)1)
119#define TYPED_DATA_PTR_MASK (~(TYPED_DATA_EMBEDDED))
120
126enum
128rbimpl_typeddata_flags {
142 RUBY_TYPED_FREE_IMMEDIATELY = 1,
143
144 RUBY_TYPED_EMBEDDABLE = 2,
145
158 RUBY_TYPED_FROZEN_SHAREABLE = RUBY_FL_SHAREABLE,
159
179 RUBY_TYPED_WB_PROTECTED = RUBY_FL_WB_PROTECTED, /* THIS FLAG DEPENDS ON Ruby version */
180
184 RUBY_TYPED_FL_IS_TYPED_DATA = RUBY_FL_USERPRIV0,
185
191 RUBY_TYPED_DECL_MARKING = RUBY_FL_USER2
192};
193
200
203
209 const char *wrap_struct_name;
210
212 struct {
213
224
233
242 size_t (*dsize)(const void *);
243
254
259 void *reserved[1]; /* For future extension.
260 This array *must* be filled with ZERO. */
262
293
298 void *data; /* This area can be used for any purpose
299 by a programmer who define the type. */
300
311 VALUE flags; /* RUBY_FL_WB_PROTECTED */
312};
313
353
355 struct RBasic basic;
356
359
370 const VALUE type;
371
373 void *data;
374};
375
376#if !defined(__cplusplus) || __cplusplus >= 201103L
377RBIMPL_STATIC_ASSERT(data_in_rtypeddata, offsetof(struct RData, data) == offsetof(struct RTypedData, data));
378#endif
379
392VALUE rb_data_typed_object_wrap(VALUE klass, void *datap, const rb_data_type_t *type);
393
408
421int rb_typeddata_inherited_p(const rb_data_type_t *child, const rb_data_type_t *parent);
422
431int rb_typeddata_is_kind_of(VALUE obj, const rb_data_type_t *data_type);
432
443void *rb_check_typeddata(VALUE obj, const rb_data_type_t *data_type);
445
456#define TypedData_Wrap_Struct(klass,data_type,sval)\
457 rb_data_typed_object_wrap((klass),(sval),(data_type))
458
472#define TypedData_Make_Struct0(result, klass, type, size, data_type, sval) \
473 VALUE result = rb_data_typed_object_zalloc(klass, size, data_type); \
474 (sval) = (type *)RTYPEDDATA_GET_DATA(result); \
475 RBIMPL_CAST(/*suppress unused variable warnings*/(void)(sval))
476
490#ifdef HAVE_STMT_AND_DECL_IN_EXPR
491#define TypedData_Make_Struct(klass, type, data_type, sval) \
492 RB_GNUC_EXTENSION({ \
493 TypedData_Make_Struct0( \
494 data_struct_obj, \
495 klass, \
496 type, \
497 sizeof(type), \
498 data_type, \
499 sval); \
500 data_struct_obj; \
501 })
502#else
503#define TypedData_Make_Struct(klass, type, data_type, sval) \
504 rb_data_typed_object_make( \
505 (klass), \
506 (data_type), \
507 RBIMPL_CAST((void **)&(sval)), \
508 sizeof(type))
509#endif
510
521#define TypedData_Get_Struct(obj,type,data_type,sval) \
522 ((sval) = RBIMPL_CAST((type *)rb_check_typeddata((obj), (data_type))))
523
524static inline bool
525RTYPEDDATA_EMBEDDED_P(VALUE obj)
526{
527#if RUBY_DEBUG
528 if (RB_UNLIKELY(!RB_TYPE_P(obj, RUBY_T_DATA))) {
531 }
532#endif
533
534 return (RTYPEDDATA(obj)->type) & TYPED_DATA_EMBEDDED;
535}
536
537static inline void *
538RTYPEDDATA_GET_DATA(VALUE obj)
539{
540#if RUBY_DEBUG
541 if (RB_UNLIKELY(!RB_TYPE_P(obj, RUBY_T_DATA))) {
544 }
545#endif
546
547 /* We reuse the data pointer in embedded TypedData. We can't use offsetof
548 * since RTypedData a non-POD type in C++. */
549 const size_t embedded_typed_data_size = sizeof(struct RTypedData) - sizeof(void *);
550
551 return RTYPEDDATA_EMBEDDED_P(obj) ? (char *)obj + embedded_typed_data_size : RTYPEDDATA(obj)->data;
552}
553
567static inline bool
568rbimpl_rtypeddata_p(VALUE obj)
569{
570 return FL_TEST_RAW(obj, RUBY_TYPED_FL_IS_TYPED_DATA);
571}
572
583static inline bool
585{
586#if RUBY_DEBUG
587 if (RB_UNLIKELY(! RB_TYPE_P(obj, RUBY_T_DATA))) {
590 }
591#endif
592
593 return rbimpl_rtypeddata_p(obj);
594}
595
598/* :TODO: can this function be __attribute__((returns_nonnull)) or not? */
606static inline const struct rb_data_type_struct *
608{
609#if RUBY_DEBUG
610 if (RB_UNLIKELY(! RTYPEDDATA_P(obj))) {
613 }
614#endif
615
616 return (const struct rb_data_type_struct *)(RTYPEDDATA(obj)->type & TYPED_DATA_PTR_MASK);
617}
618
633static inline VALUE
634rb_data_typed_object_make(VALUE klass, const rb_data_type_t *type, void **datap, size_t size)
635{
636 TypedData_Make_Struct0(result, klass, void, size, type, *datap);
637 return result;
638}
639
640RBIMPL_ATTR_DEPRECATED(("by: rb_data_typed_object_wrap"))
642static inline VALUE
643rb_data_typed_object_alloc(VALUE klass, void *datap, const rb_data_type_t *type)
644{
645 return rb_data_typed_object_wrap(klass, datap, type);
646}
647
648#endif /* RBIMPL_RTYPEDDATA_H */
Defines RBIMPL_ATTR_ARTIFICIAL.
#define RBIMPL_ATTR_ARTIFICIAL()
Wraps (or simulates) __attribute__((artificial))
Definition artificial.h:43
#define RBIMPL_ATTR_DEPRECATED(msg)
Wraps (or simulates) [[deprecated]]
Definition deprecated.h:64
Tweaking visibility of C variables/functions.
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
Defines enum ruby_fl_type.
@ RUBY_FL_WB_PROTECTED
Definition fl_type.h:198
@ RUBY_FL_USER2
User-defined flag.
Definition fl_type.h:326
@ RUBY_FL_USERPRIV0
This flag meaning is type dependent, currently only used by T_DATA.
Definition fl_type.h:224
@ RUBY_FL_SHAREABLE
This flag has something to do with Ractor.
Definition fl_type.h:280
Defines RBIMPL_ATTR_FLAG_ENUM.
#define RBIMPL_ATTR_FLAG_ENUM()
Wraps (or simulates) __attribute__((flag_enum)
Definition flag_enum.h:30
#define FL_TEST_RAW
Old name of RB_FL_TEST_RAW.
Definition fl_type.h:131
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.
Definition error.c:1370
int rb_typeddata_is_kind_of(VALUE obj, const rb_data_type_t *data_type)
Checks if the given object is of given kind.
Definition error.c:1380
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.
Definition error.c:1397
void rb_unexpected_type(VALUE x, int t)
Fails with the given object's type incompatibility to the type.
Definition error.c:1360
Declares rb_raise().
Defines RBIMPL_STATIC_ASSERT.
#define RBIMPL_STATIC_ASSERT
Wraps (or simulates) static_assert
Defines RBIMPL_ASSUME / RBIMPL_UNREACHABLE.
#define RBIMPL_UNREACHABLE_RETURN(_)
Wraps (or simulates) __builtin_unreachable.
Definition assume.h:48
Defines RBIMPL_ATTR_NONNULL.
#define RBIMPL_ATTR_NONNULL(list)
Wraps (or simulates) __attribute__((nonnull))
Definition nonnull.h:30
#define inline
Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
Definition defines.h:91
Defines RBIMPL_ATTR_PURE.
#define RBIMPL_ATTR_PURE()
Wraps (or simulates) __attribute__((pure))
Definition pure.h:33
#define RBIMPL_ATTR_PURE_UNLESS_DEBUG()
Enables RBIMPL_ATTR_PURE if and only if.
Definition pure.h:38
Defines struct RBasic.
Defines struct RData.
void(* RUBY_DATA_FUNC)(void *)
This is the type of callbacks registered to RData.
Definition rdata.h:104
static bool RTYPEDDATA_P(VALUE obj)
Checks whether the passed object is RTypedData or RData.
Definition rtypeddata.h:584
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.
Definition gc.c:1081
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...
Definition gc.c:1091
#define TypedData_Make_Struct0(result, klass, type, size, data_type, sval)
This is an implementation detail of TypedData_Make_Struct.
Definition rtypeddata.h:472
#define RTYPEDDATA(obj)
Convenient casting macro.
Definition rtypeddata.h:95
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 TypedDat...
Definition rtypeddata.h:634
static const struct rb_data_type_struct * RTYPEDDATA_TYPE(VALUE obj)
Queries for the type of given object.
Definition rtypeddata.h:607
C99 shim for <stdbool.h>
Ruby object's base components.
Definition rbasic.h:69
const VALUE klass
Class of an object.
Definition rbasic.h:92
Definition rdata.h:120
"Typed" user data.
Definition rtypeddata.h:352
void * data
Pointer to the actual C level struct that you want to wrap.
Definition rtypeddata.h:373
const VALUE type
This is a const rb_data_type_t *const value, with the low bits set:
Definition rtypeddata.h:370
VALUE fields_obj
Direct reference to the slots that holds instance variables, if any.
Definition rtypeddata.h:358
struct RBasic basic
The part that all ruby objects have in common.
Definition rtypeddata.h:355
This is the struct that holds necessary info for a struct.
Definition rtypeddata.h:202
size_t(* dsize)(const void *)
This function is to query the size of the underlying memory regions.
Definition rtypeddata.h:242
const rb_data_type_t * parent
Parent of this class.
Definition rtypeddata.h:292
RUBY_DATA_FUNC dfree
This function is called when the object is no longer used.
Definition rtypeddata.h:232
void * reserved[1]
This field is reserved for future extension.
Definition rtypeddata.h:259
RUBY_DATA_FUNC dcompact
This function is called when the object is relocated.
Definition rtypeddata.h:253
struct rb_data_type_struct::@54 function
Function pointers.
const char * wrap_struct_name
Name of structs of this kind.
Definition rtypeddata.h:209
RUBY_DATA_FUNC dmark
This function is called when the object is experiencing GC marks.
Definition rtypeddata.h:223
void * data
Type-specific static data.
Definition rtypeddata.h:298
VALUE flags
Type-specific behavioural characteristics.
Definition rtypeddata.h:311
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40
Defines enum ruby_value_type.
static void Check_Type(VALUE v, enum ruby_value_type t)
Identical to RB_TYPE_P(), except it raises exceptions on predication failure.
Definition value_type.h:433
static bool RB_TYPE_P(VALUE obj, enum ruby_value_type t)
Queries if the given object is of given type.
Definition value_type.h:376
@ RUBY_T_DATA
Definition value_type.h:127