1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
#ifndef RBIMPL_NEWOBJ_H /*-*-C++-*-vi:se ft=cpp:*/
#define RBIMPL_NEWOBJ_H
/**
* @file
* @author Ruby developers <ruby-core@ruby-lang.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.
* @brief Defines #NEWOBJ.
*/
#include "ruby/internal/attr/deprecated.h"
#include "ruby/internal/cast.h"
#include "ruby/internal/core/rbasic.h"
#include "ruby/internal/dllexport.h"
#include "ruby/internal/fl_type.h"
#include "ruby/internal/special_consts.h"
#include "ruby/internal/value.h"
#include "ruby/assert.h"
/**
* Declares, allocates, then assigns a new object to the given variable.
*
* @param obj Variable name.
* @param type Variable type.
* @exception rb_eNoMemError No space left.
* @return An allocated object, not initialised.
* @note Modern programs tend to use #NEWOBJ_OF instead.
*
* @internal
*
* :FIXME: Should we deprecate it?
*/
#define RB_NEWOBJ(obj,type) type *(obj) = RBIMPL_CAST((type *)rb_newobj())
/**
* Identical to #RB_NEWOBJ, except it also accepts the allocating object's
* class and flags.
*
* @param obj Variable name.
* @param type Variable type.
* @param klass Object's class.
* @param flags Object's flags.
* @exception rb_eNoMemError No space left.
* @return An allocated object, filled with the arguments.
*/
#define RB_NEWOBJ_OF(obj,type,klass,flags) type *(obj) = RBIMPL_CAST((type *)rb_newobj_of(klass, flags))
#define NEWOBJ RB_NEWOBJ /**< @old{RB_NEWOBJ} */
#define NEWOBJ_OF RB_NEWOBJ_OF /**< @old{RB_NEWOBJ_OF} */
#define OBJSETUP rb_obj_setup /**< @old{rb_obj_setup} */
#define CLONESETUP rb_clone_setup /**< @old{rb_clone_setup} */
#define DUPSETUP rb_dup_setup /**< @old{rb_dup_setup} */
RBIMPL_SYMBOL_EXPORT_BEGIN()
/**
* This is the implementation detail of #RB_NEWOBJ.
*
* @exception rb_eNoMemError No space left.
* @return An allocated object, not initialised.
*/
VALUE rb_newobj(void);
/**
* This is the implementation detail of #RB_NEWOBJ_OF.
*
* @param klass Object's class.
* @param flags Object's flags.
* @exception rb_eNoMemError No space left.
* @return An allocated object, filled with the arguments.
*/
VALUE rb_newobj_of(VALUE klass, VALUE flags);
/**
* Fills common fields in the object.
*
* @note Prefer rb_newobj_of() to this function.
* @param[in,out] obj A Ruby object to be set up.
* @param[in] klass `obj` will belong to this class.
* @param[in] type One of ::ruby_value_type.
* @return The passed object.
*
* @internal
*
* Historically, authors of Ruby has described the `type` argument as "one of
* ::ruby_value_type". In reality it accepts either ::ruby_value_type,
* ::ruby_fl_type, or any combinations of the two. For instance
* `RUBY_T_STRING | RUBY_FL_FREEZE` is a valid value that this function takes,
* and means this is a frozen string.
*
* 3rd party extension libraries rarely need to allocate Strings this way.
* They normally only concern ::RUBY_T_DATA. This argument is mainly used for
* specifying flags, @shyouhei suspects.
*/
VALUE rb_obj_setup(VALUE obj, VALUE klass, VALUE type);
/**
* Queries the class of an object. This is not always identical to
* `RBASIC_CLASS(obj)`. It searches for the nearest ancestor skipping
* singleton classes or included modules.
*
* @param[in] obj Object in question.
* @return The object's class, in a normal sense.
*/
VALUE rb_obj_class(VALUE obj);
/**
* Clones a singleton class. An object can have its own singleton class. OK.
* Then what happens when a program clones such object? The singleton class
* that is attached to the source object must also be cloned. Otherwise a
* singleton object gets shared with two objects, which breaks "singleton"-ness
* of such class.
*
* This is basically an implementation detail of rb_clone_setup(). People
* need not be aware of this working behind-the-scene.
*
* @param[in] obj The object that has its own singleton class.
* @return Cloned singleton class.
*/
VALUE rb_singleton_class_clone(VALUE obj);
/**
* Attaches a singleton class to its corresponding object.
*
* This is basically an implementation detail of rb_clone_setup(). People
* need not be aware of this working behind-the-scene.
*
* @param[in] klass The singleton class.
* @param[out] obj The object to attach a class.
* @pre The passed two objects must agree with each other that `klass`
* becomes a singleton class of `obj`.
* @post `klass` becomes the singleton class of `obj`.
*/
void rb_singleton_class_attached(VALUE klass, VALUE obj);
/**
* Copies the list of instance variables. 3rd parties need not know, but there
* are several ways to store an object's instance variables, depending on its
* internal structure. This function makes sense when either of the passed
* objects are using so-called "generic" backend storage. This distinction is
* purely an implementation detail of rb_clone_setup(). People need not be
* aware of this working behind-the-scenes.
*
* @param[out] clone The destination object.
* @param[in] obj The source object.
*/
void rb_copy_generic_ivar(VALUE clone, VALUE obj);
RBIMPL_SYMBOL_EXPORT_END()
RBIMPL_ATTR_DEPRECATED(("This is no longer how Object#clone works."))
/**
* @deprecated Not sure exactly when but at some time, the implementation of
* `Object#clone` stopped using this function. It remained
* untouched for a while, and then @shyouhei realised that they
* are no longer doing the same thing. It seems nobody seriously
* uses this function any longer. Let's just abandon it.
*
* @param[out] clone The destination object.
* @param[in] obj The source object.
*/
static inline void
rb_clone_setup(VALUE clone, VALUE obj)
{
return;
}
RBIMPL_ATTR_DEPRECATED(("This is no longer how Object#dup works."))
/**
* @deprecated Not sure exactly when but at some time, the implementation of
* `Object#dup` stopped using this function. It remained
* untouched for a while, and then @shyouhei realised that they
* are no longer the same thing. It seems nobody seriously uses
* this function any longer. Let's just abandon it.
*
* @param[out] dup The destination object.
* @param[in] obj The source object.
*/
static inline void
rb_dup_setup(VALUE dup, VALUE obj)
{
return;
}
#endif /* RBIMPL_NEWOBJ_H */
|
