Ruby  3.4.0dev (2024-11-05 revision 348a53415339076afc4a02fcd09f3ae36e9c4c61)
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 
29 #include "ruby/internal/assume.h"
34 #include "ruby/internal/cast.h"
38 #include "ruby/internal/error.h"
39 #include "ruby/internal/fl_type.h"
40 #include "ruby/internal/stdbool.h"
42 
50 #define HAVE_TYPE_RB_DATA_TYPE_T 1
51 
59 #define HAVE_RB_DATA_TYPE_T_FUNCTION 1
60 
68 #define HAVE_RB_DATA_TYPE_T_PARENT 1
69 
79 #define RUBY_TYPED_DEFAULT_FREE RUBY_DEFAULT_FREE
80 
86 #define RUBY_TYPED_NEVER_FREE RUBY_NEVER_FREE
87 
94 #define RTYPEDDATA(obj) RBIMPL_CAST((struct RTypedData *)(obj))
95 
102 #define RTYPEDDATA_DATA(v) (RTYPEDDATA(v)->data)
103 
105 #define Check_TypedStruct(v, t) \
106  rb_check_typeddata(RBIMPL_CAST((VALUE)(v)), (t))
107 
109 #define RTYPEDDATA_P RTYPEDDATA_P
110 #define RTYPEDDATA_TYPE RTYPEDDATA_TYPE
111 #define RUBY_TYPED_FREE_IMMEDIATELY RUBY_TYPED_FREE_IMMEDIATELY
112 #define RUBY_TYPED_FROZEN_SHAREABLE RUBY_TYPED_FROZEN_SHAREABLE
113 #define RUBY_TYPED_WB_PROTECTED RUBY_TYPED_WB_PROTECTED
114 #define RUBY_TYPED_PROMOTED1 RUBY_TYPED_PROMOTED1
117 #define TYPED_DATA_EMBEDDED 2
118 
124 enum
126 rbimpl_typeddata_flags {
140  RUBY_TYPED_FREE_IMMEDIATELY = 1,
141 
142  RUBY_TYPED_EMBEDDABLE = 2,
143 
156  RUBY_TYPED_FROZEN_SHAREABLE = RUBY_FL_SHAREABLE,
157 
177  RUBY_TYPED_WB_PROTECTED = RUBY_FL_WB_PROTECTED, /* THIS FLAG DEPENDS ON Ruby version */
178 
182  RUBY_TYPED_UNUSED = RUBY_FL_UNUSED6,
183 
189  RUBY_TYPED_DECL_MARKING = RUBY_FL_USER2
190 };
191 
197 typedef struct rb_data_type_struct rb_data_type_t;
198 
201 
207  const char *wrap_struct_name;
208 
210  struct {
211 
222 
231 
240  size_t (*dsize)(const void *);
241 
252 
257  void *reserved[1]; /* For future extension.
258  This array *must* be filled with ZERO. */
259  } function;
260 
291 
296  void *data; /* This area can be used for any purpose
297  by a programmer who define the type. */
298 
309  VALUE flags; /* RUBY_FL_WB_PROTECTED */
310 };
311 
350 struct RTypedData {
351 
353  struct RBasic basic;
354 
360  const rb_data_type_t *const type;
361 
368 
370  void *data;
371 };
372 
386 
401 
414 int rb_typeddata_inherited_p(const rb_data_type_t *child, const rb_data_type_t *parent);
415 
424 int rb_typeddata_is_kind_of(VALUE obj, const rb_data_type_t *data_type);
425 
436 void *rb_check_typeddata(VALUE obj, const rb_data_type_t *data_type);
438 
449 #define TypedData_Wrap_Struct(klass,data_type,sval)\
450  rb_data_typed_object_wrap((klass),(sval),(data_type))
451 
465 #define TypedData_Make_Struct0(result, klass, type, size, data_type, sval) \
466  VALUE result = rb_data_typed_object_zalloc(klass, size, data_type); \
467  (sval) = (type *)RTYPEDDATA_GET_DATA(result); \
468  RBIMPL_CAST(/*suppress unused variable warnings*/(void)(sval))
469 
484 #ifdef HAVE_STMT_AND_DECL_IN_EXPR
485 #define TypedData_Make_Struct(klass, type, data_type, sval) \
486  RB_GNUC_EXTENSION({ \
487  TypedData_Make_Struct0( \
488  data_struct_obj, \
489  klass, \
490  type, \
491  sizeof(type), \
492  data_type, \
493  sval); \
494  data_struct_obj; \
495  })
496 #else
497 #define TypedData_Make_Struct(klass, type, data_type, sval) \
498  rb_data_typed_object_make( \
499  (klass), \
500  (data_type), \
501  RBIMPL_CAST((void **)&(sval)), \
502  sizeof(type))
503 #endif
504 
515 #define TypedData_Get_Struct(obj,type,data_type,sval) \
516  ((sval) = RBIMPL_CAST((type *)rb_check_typeddata((obj), (data_type))))
517 
518 static inline bool
519 RTYPEDDATA_EMBEDDED_P(VALUE obj)
520 {
521 #if RUBY_DEBUG
522  if (RB_UNLIKELY(!RB_TYPE_P(obj, RUBY_T_DATA))) {
523  Check_Type(obj, RUBY_T_DATA);
525  }
526 #endif
527 
528  return RTYPEDDATA(obj)->typed_flag & TYPED_DATA_EMBEDDED;
529 }
530 
531 static inline void *
532 RTYPEDDATA_GET_DATA(VALUE obj)
533 {
534 #if RUBY_DEBUG
535  if (RB_UNLIKELY(!RB_TYPE_P(obj, RUBY_T_DATA))) {
536  Check_Type(obj, RUBY_T_DATA);
538  }
539 #endif
540 
541  /* We reuse the data pointer in embedded TypedData. We can't use offsetof
542  * since RTypedData a non-POD type in C++. */
543  const size_t embedded_typed_data_size = sizeof(struct RTypedData) - sizeof(void *);
544 
545  return RTYPEDDATA_EMBEDDED_P(obj) ? (char *)obj + embedded_typed_data_size : RTYPEDDATA(obj)->data;
546 }
547 
561 static inline bool
562 rbimpl_rtypeddata_p(VALUE obj)
563 {
564  VALUE typed_flag = RTYPEDDATA(obj)->typed_flag;
565  return typed_flag != 0 && typed_flag <= 3;
566 }
567 
578 static inline bool
580 {
581 #if RUBY_DEBUG
582  if (RB_UNLIKELY(! RB_TYPE_P(obj, RUBY_T_DATA))) {
583  Check_Type(obj, RUBY_T_DATA);
585  }
586 #endif
587 
588  return rbimpl_rtypeddata_p(obj);
589 }
590 
593 /* :TODO: can this function be __attribute__((returns_nonnull)) or not? */
601 static inline const struct rb_data_type_struct *
603 {
604 #if RUBY_DEBUG
605  if (RB_UNLIKELY(! RTYPEDDATA_P(obj))) {
608  }
609 #endif
610 
611  return RTYPEDDATA(obj)->type;
612 }
613 
628 static inline VALUE
629 rb_data_typed_object_make(VALUE klass, const rb_data_type_t *type, void **datap, size_t size)
630 {
631  TypedData_Make_Struct0(result, klass, void, size, type, *datap);
632  return result;
633 }
634 
635 RBIMPL_ATTR_DEPRECATED(("by: rb_data_typed_object_wrap"))
637 static inline VALUE
639 {
640  return rb_data_typed_object_wrap(klass, datap, type);
641 }
642 
643 #endif /* RBIMPL_RTYPEDDATA_H */
Defines RBIMPL_ATTR_ARTIFICIAL.
#define RBIMPL_ATTR_ARTIFICIAL()
Wraps (or simulates) __attribute__((artificial))
Definition: artificial.h:41
#define RB_UNLIKELY(x)
Asserts that the given Boolean expression likely doesn't hold.
Definition: assume.h:50
#define RBIMPL_ATTR_DEPRECATED(msg)
Wraps (or simulates) [[deprecated]]
Definition: deprecated.h:36
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:199
@ RUBY_FL_UNUSED6
This flag is no longer in use.
Definition: fl_type.h:225
@ RUBY_FL_USER2
User-defined flag.
Definition: fl_type.h:330
@ RUBY_FL_SHAREABLE
This flag has something to do with Ractor.
Definition: fl_type.h:266
Defines RBIMPL_ATTR_FLAG_ENUM.
#define RBIMPL_ATTR_FLAG_ENUM()
Wraps (or simulates) __attribute__((flag_enum)
Definition: flag_enum.h:28
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:1370
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:1343
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:1353
void rb_unexpected_type(VALUE x, int t)
Fails with the given object's type incompatibility to the type.
Definition: error.c:1333
Declares rb_raise().
RBIMPL_ATTR_PURE() int rb_io_read_pending(rb_io_t *fptr)
Queries if the passed IO has any pending reads.
Defines RBIMPL_ASSUME / RBIMPL_UNREACHABLE.
#define RBIMPL_UNREACHABLE_RETURN(_)
Wraps (or simulates) __builtin_unreachable.
Definition: assume.h:42
VALUE type(ANYARGS)
ANYARGS-ed function type.
Definition: cxxanyargs.hpp:56
Defines RBIMPL_ATTR_NONNULL.
#define RBIMPL_ATTR_NONNULL(list)
Wraps (or simulates) __attribute__((nonnull))
Definition: nonnull.h:27
#define inline
Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
Definition: defines.h:88
Defines RBIMPL_ATTR_PURE.
#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:579
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:971
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:981
#define TypedData_Make_Struct0(result, klass, type, size, data_type, sval)
This is an implementation detail of TypedData_Make_Struct.
Definition: rtypeddata.h:465
static VALUE rb_data_typed_object_alloc(VALUE klass, void *datap, const rb_data_type_t *type)
Definition: rtypeddata.h:638
#define RTYPEDDATA(obj)
Convenient casting macro.
Definition: rtypeddata.h:94
static const struct rb_data_type_struct * RTYPEDDATA_TYPE(VALUE obj)
Queries for the type of given object.
Definition: rtypeddata.h:602
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:629
C99 shim for <stdbool.h>
Ruby object's base components.
Definition: rbasic.h:63
const VALUE klass
Class of an object.
Definition: rbasic.h:86
"Typed" user data.
Definition: rtypeddata.h:350
void * data
Pointer to the actual C level struct that you want to wrap.
Definition: rtypeddata.h:370
const VALUE typed_flag
This has to be always 1.
Definition: rtypeddata.h:367
struct RBasic basic
The part that all ruby objects have in common.
Definition: rtypeddata.h:353
const rb_data_type_t *const type
This field stores various information about how Ruby should handle a data.
Definition: rtypeddata.h:360
This is the struct that holds necessary info for a struct.
Definition: rtypeddata.h:200
size_t(* dsize)(const void *)
This function is to query the size of the underlying memory regions.
Definition: rtypeddata.h:240
const rb_data_type_t * parent
Parent of this class.
Definition: rtypeddata.h:290
RUBY_DATA_FUNC dfree
This function is called when the object is no longer used.
Definition: rtypeddata.h:230
void * reserved[1]
This field is reserved for future extension.
Definition: rtypeddata.h:257
RUBY_DATA_FUNC dcompact
This function is called when the object is relocated.
Definition: rtypeddata.h:251
const char * wrap_struct_name
Name of structs of this kind.
Definition: rtypeddata.h:207
RUBY_DATA_FUNC dmark
This function is called when the object is experiencing GC marks.
Definition: rtypeddata.h:221
void * data
Type-specific static data.
Definition: rtypeddata.h:296
VALUE flags
Type-specific behavioural characteristics.
Definition: rtypeddata.h:309
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