Ruby: include/ruby/internal/core/rtypeddata.h Source File

Ruby 3.3.5p100 (2024-09-03 revision ef084cc8f4958c1b6e4ead99136631bef6d8ddba)

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"
30#include "ruby/internal/attr/artificial.h"
31#include "ruby/internal/attr/flag_enum.h"
32#include "ruby/internal/attr/nonnull.h"
33#include "ruby/internal/attr/pure.h"
34#include "ruby/internal/cast.h"
35#include "ruby/internal/core/rbasic.h"
36#include "ruby/internal/core/rdata.h"
37#include "ruby/internal/dllexport.h"
38#include "ruby/internal/error.h"
39#include "ruby/internal/fl_type.h"
40#include "ruby/internal/stdbool.h"
41#include "ruby/internal/value_type.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
124enum
125 RBIMPL_ATTR_FLAG_ENUM()
126rbimpl_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
200 struct rb_data_type_struct {
201
207 const char *wrap_struct_name;
208
210 struct {
211
221 RUBY_DATA_FUNC dmark;
222
230 RUBY_DATA_FUNC dfree;
231
240 size_t (*dsize)(const void *);
241
251 RUBY_DATA_FUNC dcompact;
252
257 void *reserved[1]; /* For future extension.
258 This array *must* be filled with ZERO. */
259 } function;
260
290 const rb_data_type_t *parent;
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
367 const VALUE typed_flag;
368
370 void *data;
371};
372
373 RBIMPL_SYMBOL_EXPORT_BEGIN()
374 RBIMPL_ATTR_NONNULL((3))
385 VALUE rb_data_typed_object_wrap(VALUE klass, void *datap, const rb_data_type_t *type);
386
400 VALUE rb_data_typed_object_zalloc(VALUE klass, size_t size, const rb_data_type_t *type);
401
414int rb_typeddata_inherited_p(const rb_data_type_t *child, const rb_data_type_t *parent);
415
424int rb_typeddata_is_kind_of(VALUE obj, const rb_data_type_t *data_type);
425
436void *rb_check_typeddata(VALUE obj, const rb_data_type_t *data_type);
437 RBIMPL_SYMBOL_EXPORT_END()
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
518static inline bool
519RTYPEDDATA_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);
524 RBIMPL_UNREACHABLE_RETURN(false);
525 }
526#endif
527
528 return RTYPEDDATA(obj)->typed_flag & TYPED_DATA_EMBEDDED;
529}
530
531static inline void *
532RTYPEDDATA_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);
537 RBIMPL_UNREACHABLE_RETURN(false);
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
548 RBIMPL_ATTR_PURE()
549 RBIMPL_ATTR_ARTIFICIAL()
561static inline bool
562rbimpl_rtypeddata_p(VALUE obj)
563{
564 VALUE typed_flag = RTYPEDDATA(obj)->typed_flag;
565 return typed_flag != 0 && typed_flag <= 3;
566}
567
568 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
569 RBIMPL_ATTR_ARTIFICIAL()
578static inline bool
579RTYPEDDATA_P(VALUE obj)
580{
581#if RUBY_DEBUG
582 if (RB_UNLIKELY(! RB_TYPE_P(obj, RUBY_T_DATA))) {
583 Check_Type(obj, RUBY_T_DATA);
584 RBIMPL_UNREACHABLE_RETURN(false);
585 }
586#endif
587
588 return rbimpl_rtypeddata_p(obj);
589}
590
591 RBIMPL_ATTR_PURE_UNLESS_DEBUG()
592 RBIMPL_ATTR_ARTIFICIAL()
593/* :TODO: can this function be __attribute__((returns_nonnull)) or not? */
601static inline const struct rb_data_type_struct *
602RTYPEDDATA_TYPE(VALUE obj)
603{
604#if RUBY_DEBUG
605 if (RB_UNLIKELY(! RTYPEDDATA_P(obj))) {
606 rb_unexpected_type(obj, RUBY_T_DATA);
607 RBIMPL_UNREACHABLE_RETURN(NULL);
608 }
609#endif
610
611 return RTYPEDDATA(obj)->type;
612}
613
628static inline VALUE
629rb_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"))
637static inline VALUE
638rb_data_typed_object_alloc(VALUE klass, void *datap, const rb_data_type_t *type)
639{
640 return rb_data_typed_object_wrap(klass, datap, type);
641}
642
643#endif /* RBIMPL_RTYPEDDATA_H */
artificial.h
Defines RBIMPL_ATTR_ARTIFICIAL.
RBIMPL_ATTR_ARTIFICIAL
#define RBIMPL_ATTR_ARTIFICIAL()
Wraps (or simulates) __attribute__((artificial))
Definition artificial.h:43
RBIMPL_ATTR_DEPRECATED
#define RBIMPL_ATTR_DEPRECATED(msg)
Wraps (or simulates) [[deprecated]]
Definition deprecated.h:64
dllexport.h
Tweaking visibility of C variables/functions.
RBIMPL_SYMBOL_EXPORT_END
#define RBIMPL_SYMBOL_EXPORT_END()
Counterpart of RBIMPL_SYMBOL_EXPORT_BEGIN.
Definition dllexport.h:74
RBIMPL_SYMBOL_EXPORT_BEGIN
#define RBIMPL_SYMBOL_EXPORT_BEGIN()
Shortcut macro equivalent to RUBY_SYMBOL_EXPORT_BEGIN extern "C" {.
Definition dllexport.h:65
fl_type.h
Defines enum ruby_fl_type.
RUBY_FL_WB_PROTECTED
@ RUBY_FL_WB_PROTECTED
Definition fl_type.h:199
RUBY_FL_UNUSED6
@ RUBY_FL_UNUSED6
This flag is no longer in use.
Definition fl_type.h:225
RUBY_FL_USER2
@ RUBY_FL_USER2
User-defined flag.
Definition fl_type.h:330
RUBY_FL_SHAREABLE
@ RUBY_FL_SHAREABLE
This flag has something to do with Ractor.
Definition fl_type.h:266
flag_enum.h
Defines RBIMPL_ATTR_FLAG_ENUM.
RBIMPL_ATTR_FLAG_ENUM
#define RBIMPL_ATTR_FLAG_ENUM()
Wraps (or simulates) __attribute__((flag_enum)
Definition flag_enum.h:30
rb_typeddata_inherited_p
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:1284
rb_typeddata_is_kind_of
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:1294
rb_check_typeddata
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:1311
rb_unexpected_type
void rb_unexpected_type(VALUE x, int t)
Fails with the given object's type incompatibility to the type.
Definition error.c:1274
error.h
Declares rb_raise().
assume.h
Defines RBIMPL_ASSUME / RBIMPL_UNREACHABLE.
RBIMPL_UNREACHABLE_RETURN
#define RBIMPL_UNREACHABLE_RETURN(_)
Wraps (or simulates) __builtin_unreachable.
Definition assume.h:48
nonnull.h
Defines RBIMPL_ATTR_NONNULL.
RBIMPL_ATTR_NONNULL
#define RBIMPL_ATTR_NONNULL(list)
Wraps (or simulates) __attribute__((nonnull))
Definition nonnull.h:30
inline
#define inline
Old Visual Studio versions do not support the inline keyword, so we need to define it to be __inline.
Definition defines.h:66
pure.h
Defines RBIMPL_ATTR_PURE.
RBIMPL_ATTR_PURE
#define RBIMPL_ATTR_PURE()
Wraps (or simulates) __attribute__((pure))
Definition pure.h:33
RBIMPL_ATTR_PURE_UNLESS_DEBUG
#define RBIMPL_ATTR_PURE_UNLESS_DEBUG()
Enables RBIMPL_ATTR_PURE if and only if.
Definition pure.h:38
rbasic.h
Defines struct RBasic.
rdata.h
Defines struct RData.
RUBY_DATA_FUNC
void(* RUBY_DATA_FUNC)(void *)
This is the type of callbacks registered to RData.
Definition rdata.h:108
RTYPEDDATA_P
static bool RTYPEDDATA_P(VALUE obj)
Checks whether the passed object is RTypedData or RData.
Definition rtypeddata.h:579
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.
Definition gc.c:3160
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...
Definition gc.c:3170
TypedData_Make_Struct0
#define TypedData_Make_Struct0(result, klass, type, size, data_type, sval)
This is an implementation detail of TypedData_Make_Struct.
Definition rtypeddata.h:465
RTYPEDDATA
#define RTYPEDDATA(obj)
Convenient casting macro.
Definition rtypeddata.h:94
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)
While we don't stop you from using this function, it seems to be an implementation detail of TypedDat...
Definition rtypeddata.h:629
RTYPEDDATA_TYPE
static const struct rb_data_type_struct * RTYPEDDATA_TYPE(VALUE obj)
Queries for the type of given object.
Definition rtypeddata.h:602
stdbool.h
C99 shim for <stdbool.h>
RBasic
Ruby's object's, base components.
Definition rbasic.h:64
RBasic::klass
const VALUE klass
Class of an object.
Definition rbasic.h:88
RTypedData
"Typed" user data.
Definition rtypeddata.h:350
RTypedData::data
void * data
Pointer to the actual C level struct that you want to wrap.
Definition rtypeddata.h:370
RTypedData::typed_flag
const VALUE typed_flag
This has to be always 1.
Definition rtypeddata.h:367
RTypedData::basic
struct RBasic basic
The part that all ruby objects have in common.
Definition rtypeddata.h:353
RTypedData::type
const rb_data_type_t *const type
This field stores various information about how Ruby should handle a data.
Definition rtypeddata.h:360
rb_data_type_struct
This is the struct that holds necessary info for a struct.
Definition rtypeddata.h:200
rb_data_type_struct::dsize
size_t(* dsize)(const void *)
This function is to query the size of the underlying memory regions.
Definition rtypeddata.h:240
rb_data_type_struct::parent
const rb_data_type_t * parent
Parent of this class.
Definition rtypeddata.h:290
rb_data_type_struct::dfree
RUBY_DATA_FUNC dfree
This function is called when the object is no longer used.
Definition rtypeddata.h:230
rb_data_type_struct::reserved
void * reserved[1]
This field is reserved for future extension.
Definition rtypeddata.h:257
rb_data_type_struct::dcompact
RUBY_DATA_FUNC dcompact
This function is called when the object is relocated.
Definition rtypeddata.h:251
rb_data_type_struct::function
struct rb_data_type_struct::@54 function
Function pointers.
rb_data_type_struct::wrap_struct_name
const char * wrap_struct_name
Name of structs of this kind.
Definition rtypeddata.h:207
rb_data_type_struct::dmark
RUBY_DATA_FUNC dmark
This function is called when the object is experiencing GC marks.
Definition rtypeddata.h:221
rb_data_type_struct::data
void * data
Type-specific static data.
Definition rtypeddata.h:296
rb_data_type_struct::flags
VALUE flags
Type-specific behavioural characteristics.
Definition rtypeddata.h:309
VALUE
uintptr_t VALUE
Type that represents a Ruby object.
Definition value.h:40
value_type.h
Defines enum ruby_value_type.
Check_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:432
RUBY_T_DATA
@ RUBY_T_DATA
Definition value_type.h:126