Zen API

- Home
- Help Topics
- Types by Category
- All Types
- Files

All Classes Files Functions Variables Typedefs Macros Groups Pages
kObject.h
Go to the documentation of this file.
1 /**
2 * @file kObject.h
3 * @brief Declares the kObject class.
4 *
5 * @internal
6 * Copyright (C) 2005-2014 by LMI Technologies Inc.
7 * Licensed under the MIT License.
8 * Redistributed files must retain the above copyright notice.
9 */
10 #include <kApi/kApiDef.h> //--inclusion order controlled by kApiDef
11
12 #ifndef K_API_OBJECT_H
13 #define K_API_OBJECT_H
14
15 kBeginHeader()
16
17 /**
18 * @class kObject
19 * @ingroup kApi
20 * @brief Root of all class types in the Zen type system.
21 *
22 * All Zen classes inherit directly or indirectly from kObject. Accordingly, kObject methods can be used
23 * on any Zen object:
24 *
25 * @code
26 * kArrayList list = kNULL;
27 *
28 * kArrayList_Construct(&list, kTypeOf(k32s), 0, kNULL);
29 * //...
30 * kObject_Destroy(list);
31 * @endcode
32 */
33 //typedef kPointer kObject; --forward-declared in kApiDef.x.h
34
35 /**
36 * Constructs a new object by copying an existing object, including any aggregated child elements.
37 *
38 * If the source object is an object collection (e.g. kArrayList<kString>), any aggregated child objects
39 * are also cloned. In this case, the kObject_Dispose method can be used to free the cloned collection and
40 * its associated elements.
41 *
42 * This method will fail if the source object (or an aggregated child element) does not support cloning.
43 *
44 * @public @memberof kObject
45 * @param object Receives the constructed object.
46 * @param source Source object.
47 * @param allocator Memory allocator (or kNULL for default).
48 * @return Operation status.
49 * @see kObject_Dispose
50 */
51 kFx(kStatus) kObject_Clone(kObject* object, kObject source, kAlloc allocator);
52
53 /**
54 * Increments the reference count associated with this object.
55 *
56 * This method is thread-safe.
57 *
58 * @public @memberof kObject
59 * @param object Object.
60 * @return Operation status.
61 * @see reference-counting
62 */
63 kFx(kStatus) kObject_Share(kObject object);
64
65 /**
66 * Sets the object pool associated with this object.
67 *
68 * Object pools can be used to implement custom lifecycle management. If an object has an assigned pool,
69 * then the kObjectPool_Reclaim method will be called just prior to destruction, to provide an opportunity
70 * for the object to be reclaimed.
71 *
72 * @public @memberof kObject
73 * @param object Object.
74 * @param pool Pool object (or kNULL to clear the pool assignment).
75 * @return Operation status.
76 */
77 kFx(kStatus) kObject_SetPool(kObject object, kObjectPool pool);
78
79 /**
80 * Destroys the object.
81 *
82 * The kObject_Destroy method destroys the object itself and any resources that are owned by the object.
83 * See @ref destruction for more information.
84 *
85 * When an object is destroyed (or disposed), its reference count is decremented. The object is only truly
86 * destroyed when the reference count reaches zero. See @ref reference-counting for more information.
87 *
88 * @public @memberof kObject
89 * @param object Object (or kNULL).
90 * @return Operation status.
91 * @see @ref destruction, @ref reference-counting
92 */
93 kFx(kStatus) kObject_Destroy(kObject object);
94
95 /**
96 * Destroys the object and any aggregated child elements.
97 *
98 * The kObject_Dispose method destroys the object itself, any resources that are owned by the object, and
99 * if the object represents a collection of objects, any child objects in the collection. See @ref destruction
100 * for more information.
101 *
102 * When an object is destroyed (or disposed), its reference count is decremented. The object is only truly
103 * destroyed when the reference count reaches zero. See @ref reference-counting for more information.
104 *
105 * @public @memberof kObject
106 * @param object Object (or kNULL).
107 * @return Operation status.
108 * @see @ref destruction, @ref reference-counting
109 */
110 kFx(kStatus) kObject_Dispose(kObject object);
111
112 /**
113 * Returns the type of the object.
114 *
115 * Each object is an instance of a specific class type. The type handle returned by this function can be
116 * used to learn about the class.
117 *
118 * @public @memberof kObject
119 * @param object Object.
120 * @return Type.
121 * @see kType, kObject_Type_
122 */
123 kFx(kType) kObject_Type(kObject object);
124
125 /**
126 * Determines whether this object is an instance of the specified type.
127 *
128 * This function compares the type of this object with the given type. An object is considered to be an
129 * instance of a given type if a) the type represents a class and this object inherits from (or instantiates)
130 * that class, or b) the type represents an interface and this object implements the interface.
131 *
132 * @public @memberof kObject
133 * @param object Object.
134 * @param type Type.
135 * @return kTRUE if the object is of the specified type; otherwise kFALSE.
136 * @see kObject_Is_, kType_Is
137 */
138 kFx(kBool) kObject_Is(kObject object, kType type);
139
140 /**
141 * Determines whether the object is equal to another object.
142 *
143 * By default, objects are compared by reference; objects are considered equal if the given handles refer to
144 * the same object instance. However, some classes override the Equals method to provide a more meaningful
145 * comparison (e.g. kString).
146 *
147 * @public @memberof kObject
148 * @param object Object.
149 * @param other Object for comparison.
150 * @return kTRUE if the objects are equal.
151 */
152 kFx(kBool) kObject_Equals(kObject object, kObject other);
153
154 /**
155 * Gets a hash code representing the state of this object.
156 *
157 * By default, objects return a hash code based on the object handle value. However, some classes override
158 * the HashCode method to provide a more useful hash (e.g. kString).
159 *
160 * @public @memberof kObject
161 * @param object Object.
162 * @return Hash code.
163 */
164 kFx(kSize) kObject_HashCode(kObject object);
165
166 /**
167 * Gets the memory allocator associated with this object.
168 *
169 * Most objects are constructed with an allocator, which is used to allocate the memory required by the
170 * object. Objects retain a reference to this allocator to enable further allocations and to free memory when
171 * the object is destroyed.
172 *
173 * @public @memberof kObject
174 * @param object Object.
175 * @return Memory allocator.
176 * @see kAlloc, kObject_Alloc_
177 */
178 kFx(kAlloc) kObject_Alloc(kObject object);
179
180 /**
181 * Estimates the memory consumed by this object, including any aggregated child elements.
182 *
183 * This method can be optionally overridden by kObject-derived classes to report the amount of memory consumed
184 * by an object. The default implementation reports only the size of the class instance (additional allocations
185 * performed by the class are excluded).
186 *
187 * @public @memberof kObject
188 * @param object Object.
189 * @return Object size, in bytes.
190 */
191 kFx(kSize) kObject_Size(kObject object);
192
193 /**
194 * Reports whether the object is currently shared (reference count greater than one).
195 *
196 * Objects are initialized with a reference count of one. The kObject_Share method can be used to increment
197 * the reference count. The kObject_Destroy and kObject_Dispose methods decrease the reference count, and
198 * when the reference count reaches zero, the object is actually destroyed/disposed.
199 *
200 * This method can be used to determine if the reference count of an object is currently greater than one.
201 *
202 * This method is thread-safe.
203 *
204 * @public @memberof kObject
205 * @param object Object.
206 * @return kTRUE if the object is shared; kFALSE otherwise.
207 * @see @ref reference-counting, kObject_Share
208 */
209 kFx(kBool) kObject_IsShared(kObject object);
210
211 #define kObject_Type_(OBJ) kxObject_Type_(OBJ) ///< Macro version of kObject_Type.
212 #define kObject_Is_(OBJ, TYPE) kxObject_Is_(OBJ, TYPE) ///< Macro version of kObject_Is.
213 #define kObject_Alloc_(OBJ) kxObject_Allocator_(OBJ) ///< Macro version of kObject_Alloc.
214
215 kEndHeader()
216
217 #include <kApi/kObject.x.h>
218
219 #endif
kObject::kObject_Size
kSize kObject_Size(kObject object)
Estimates the memory consumed by this object, including any aggregated child elements.
kObject::kObject_Alloc
kAlloc kObject_Alloc(kObject object)
Gets the memory allocator associated with this object.
kObject::kObject_Share
kStatus kObject_Share(kObject object)
Increments the reference count associated with this object.
kObject::kObject_Is
kBool kObject_Is(kObject object, kType type)
Determines whether this object is an instance of the specified type.
kSize
Represents an unsigned integer that can store a pointer address.
kAlloc
Abstract base class for memory allocator types.
kObject::kObject_Equals
kBool kObject_Equals(kObject object, kObject other)
Determines whether the object is equal to another object.
kObject::kObject_Type
kType kObject_Type(kObject object)
Returns the type of the object.
kObject::kObject_SetPool
kStatus kObject_SetPool(kObject object, kObjectPool pool)
Sets the object pool associated with this object.
kObject::kObject_HashCode
kSize kObject_HashCode(kObject object)
Gets a hash code representing the state of this object.
kObjectPool
Supports reclaiming objects upon destruction.
kApiDef.h
Essential API declarations.
kObject::kObject_IsShared
kBool kObject_IsShared(kObject object)
Reports whether the object is currently shared (reference count greater than one).
kObject::kObject_Clone
kStatus kObject_Clone(kObject *object, kObject source, kAlloc allocator)
Constructs a new object by copying an existing object, including any aggregated child elements...
kType
Represents metadata about a type (class, interface, or value).
kObject
Root of all class types in the Zen type system.
kStatus
Represents an enumeration of error codes.
kObject::kObject_Destroy
kStatus kObject_Destroy(kObject object)
Destroys the object.
kBool
Represents a boolean value.
kObject::kObject_Dispose
kStatus kObject_Dispose(kObject object)
Destroys the object and any aggregated child elements.