2 * Heap header definition and assorted macros, including ref counting.
3 * Access all fields through the accessor macros.
6 #ifndef DUK_HEAPHDR_H_INCLUDED
7 #define DUK_HEAPHDR_H_INCLUDED
12 * All heap objects share the same flags and refcount fields. Objects other
13 * than strings also need to have a single or double linked list pointers
14 * for insertion into the "heap allocated" list. Strings are held in the
15 * heap-wide string table so they don't need link pointers.
17 * Technically, 'h_refcount' must be wide enough to guarantee that it cannot
18 * wrap (otherwise objects might be freed incorrectly after wrapping). This
19 * means essentially that the refcount field must be as wide as data pointers.
20 * On 64-bit platforms this means that the refcount needs to be 64 bits even
21 * if an 'int' is 32 bits. This is a bit unfortunate, and compromising on
22 * this might be reasonable in the future.
24 * Heap header size on 32-bit platforms: 8 bytes without reference counting,
25 * 16 bytes with reference counting.
31 #if defined(DUK_USE_REFERENCE_COUNTING)
32 #if defined(DUK_USE_REFCOUNT16)
33 duk_uint16_t h_refcount16
;
35 duk_size_t h_refcount
;
39 #if defined(DUK_USE_HEAPPTR16)
40 duk_uint16_t h_next16
;
45 #if defined(DUK_USE_DOUBLE_LINKED_HEAP)
46 /* refcounting requires direct heap frees, which in turn requires a dual linked heap */
47 #if defined(DUK_USE_HEAPPTR16)
48 duk_uint16_t h_prev16
;
54 /* When DUK_USE_HEAPPTR16 (and DUK_USE_REFCOUNT16) is in use, the
55 * struct won't align nicely to 4 bytes. This 16-bit extra field
56 * is added to make the alignment clean; the field can be used by
57 * heap objects when 16-bit packing is used. This field is now
58 * conditional to DUK_USE_HEAPPTR16 only, but it is intended to be
59 * used with DUK_USE_REFCOUNT16 and DUK_USE_DOUBLE_LINKED_HEAP;
60 * this only matter to low memory environments anyway.
62 #if defined(DUK_USE_HEAPPTR16)
63 duk_uint16_t h_extra16
;
67 struct duk_heaphdr_string
{
68 /* 16 bits would be enough for shared heaphdr flags and duk_hstring
69 * flags. The initial parts of duk_heaphdr_string and duk_heaphdr
70 * must match so changing the flags field size here would be quite
71 * awkward. However, to minimize struct size, we can pack at least
72 * 16 bits of duk_hstring data into the flags field.
76 #if defined(DUK_USE_REFERENCE_COUNTING)
77 #if defined(DUK_USE_REFCOUNT16)
78 duk_uint16_t h_refcount16
;
80 duk_size_t h_refcount
;
85 #define DUK_HEAPHDR_FLAGS_TYPE_MASK 0x00000003UL
86 #define DUK_HEAPHDR_FLAGS_FLAG_MASK (~DUK_HEAPHDR_FLAGS_TYPE_MASK)
88 /* 2 bits for heap type */
89 #define DUK_HEAPHDR_FLAGS_HEAP_START 2 /* 4 heap flags */
90 #define DUK_HEAPHDR_FLAGS_USER_START 6 /* 26 user flags */
92 #define DUK_HEAPHDR_HEAP_FLAG_NUMBER(n) (DUK_HEAPHDR_FLAGS_HEAP_START + (n))
93 #define DUK_HEAPHDR_USER_FLAG_NUMBER(n) (DUK_HEAPHDR_FLAGS_USER_START + (n))
94 #define DUK_HEAPHDR_HEAP_FLAG(n) (1UL << (DUK_HEAPHDR_FLAGS_HEAP_START + (n)))
95 #define DUK_HEAPHDR_USER_FLAG(n) (1UL << (DUK_HEAPHDR_FLAGS_USER_START + (n)))
97 #define DUK_HEAPHDR_FLAG_REACHABLE DUK_HEAPHDR_HEAP_FLAG(0) /* mark-and-sweep: reachable */
98 #define DUK_HEAPHDR_FLAG_TEMPROOT DUK_HEAPHDR_HEAP_FLAG(1) /* mark-and-sweep: children not processed */
99 #define DUK_HEAPHDR_FLAG_FINALIZABLE DUK_HEAPHDR_HEAP_FLAG(2) /* mark-and-sweep: finalizable (on current pass) */
100 #define DUK_HEAPHDR_FLAG_FINALIZED DUK_HEAPHDR_HEAP_FLAG(3) /* mark-and-sweep: finalized (on previous pass) */
102 #define DUK_HTYPE_MIN 1
103 #define DUK_HTYPE_STRING 1
104 #define DUK_HTYPE_OBJECT 2
105 #define DUK_HTYPE_BUFFER 3
106 #define DUK_HTYPE_MAX 3
108 #if defined(DUK_USE_HEAPPTR16)
109 #define DUK_HEAPHDR_GET_NEXT(heap,h) \
110 ((duk_heaphdr *) DUK_USE_HEAPPTR_DEC16((heap)->heap_udata, (h)->h_next16))
111 #define DUK_HEAPHDR_SET_NEXT(heap,h,val) do { \
112 (h)->h_next16 = DUK_USE_HEAPPTR_ENC16((heap)->heap_udata, (void *) val); \
115 #define DUK_HEAPHDR_GET_NEXT(heap,h) ((h)->h_next)
116 #define DUK_HEAPHDR_SET_NEXT(heap,h,val) do { \
117 (h)->h_next = (val); \
121 #if defined(DUK_USE_DOUBLE_LINKED_HEAP)
122 #if defined(DUK_USE_HEAPPTR16)
123 #define DUK_HEAPHDR_GET_PREV(heap,h) \
124 ((duk_heaphdr *) DUK_USE_HEAPPTR_DEC16((heap)->heap_udata, (h)->h_prev16))
125 #define DUK_HEAPHDR_SET_PREV(heap,h,val) do { \
126 (h)->h_prev16 = DUK_USE_HEAPPTR_ENC16((heap)->heap_udata, (void *) (val)); \
129 #define DUK_HEAPHDR_GET_PREV(heap,h) ((h)->h_prev)
130 #define DUK_HEAPHDR_SET_PREV(heap,h,val) do { \
131 (h)->h_prev = (val); \
136 #if defined(DUK_USE_REFERENCE_COUNTING)
137 #if defined(DUK_USE_REFCOUNT16)
138 #define DUK_HEAPHDR_GET_REFCOUNT(h) ((h)->h_refcount16)
139 #define DUK_HEAPHDR_SET_REFCOUNT(h,val) do { \
140 (h)->h_refcount16 = (val); \
142 #define DUK_HEAPHDR_PREINC_REFCOUNT(h) (++(h)->h_refcount16) /* result: updated refcount */
143 #define DUK_HEAPHDR_PREDEC_REFCOUNT(h) (--(h)->h_refcount16) /* result: updated refcount */
145 #define DUK_HEAPHDR_GET_REFCOUNT(h) ((h)->h_refcount)
146 #define DUK_HEAPHDR_SET_REFCOUNT(h,val) do { \
147 (h)->h_refcount = (val); \
149 #define DUK_HEAPHDR_PREINC_REFCOUNT(h) (++(h)->h_refcount) /* result: updated refcount */
150 #define DUK_HEAPHDR_PREDEC_REFCOUNT(h) (--(h)->h_refcount) /* result: updated refcount */
153 /* refcount macros not defined without refcounting, caller must #ifdef now */
154 #endif /* DUK_USE_REFERENCE_COUNTING */
157 * Note: type is treated as a field separate from flags, so some masking is
158 * involved in the macros below.
161 #define DUK_HEAPHDR_GET_FLAGS_RAW(h) ((h)->h_flags)
163 #define DUK_HEAPHDR_GET_FLAGS(h) ((h)->h_flags & DUK_HEAPHDR_FLAGS_FLAG_MASK)
164 #define DUK_HEAPHDR_SET_FLAGS(h,val) do { \
165 (h)->h_flags = ((h)->h_flags & ~(DUK_HEAPHDR_FLAGS_FLAG_MASK)) | (val); \
168 #define DUK_HEAPHDR_GET_TYPE(h) ((h)->h_flags & DUK_HEAPHDR_FLAGS_TYPE_MASK)
169 #define DUK_HEAPHDR_SET_TYPE(h,val) do { \
170 (h)->h_flags = ((h)->h_flags & ~(DUK_HEAPHDR_FLAGS_TYPE_MASK)) | (val); \
173 #define DUK_HEAPHDR_HTYPE_VALID(h) ( \
174 DUK_HEAPHDR_GET_TYPE((h)) >= DUK_HTYPE_MIN && \
175 DUK_HEAPHDR_GET_TYPE((h)) <= DUK_HTYPE_MAX \
178 #define DUK_HEAPHDR_SET_TYPE_AND_FLAGS(h,tval,fval) do { \
179 (h)->h_flags = ((tval) & DUK_HEAPHDR_FLAGS_TYPE_MASK) | \
180 ((fval) & DUK_HEAPHDR_FLAGS_FLAG_MASK); \
183 #define DUK_HEAPHDR_SET_FLAG_BITS(h,bits) do { \
184 DUK_ASSERT(((bits) & ~(DUK_HEAPHDR_FLAGS_FLAG_MASK)) == 0); \
185 (h)->h_flags |= (bits); \
188 #define DUK_HEAPHDR_CLEAR_FLAG_BITS(h,bits) do { \
189 DUK_ASSERT(((bits) & ~(DUK_HEAPHDR_FLAGS_FLAG_MASK)) == 0); \
190 (h)->h_flags &= ~((bits)); \
193 #define DUK_HEAPHDR_CHECK_FLAG_BITS(h,bits) (((h)->h_flags & (bits)) != 0)
195 #define DUK_HEAPHDR_SET_REACHABLE(h) DUK_HEAPHDR_SET_FLAG_BITS((h),DUK_HEAPHDR_FLAG_REACHABLE)
196 #define DUK_HEAPHDR_CLEAR_REACHABLE(h) DUK_HEAPHDR_CLEAR_FLAG_BITS((h),DUK_HEAPHDR_FLAG_REACHABLE)
197 #define DUK_HEAPHDR_HAS_REACHABLE(h) DUK_HEAPHDR_CHECK_FLAG_BITS((h),DUK_HEAPHDR_FLAG_REACHABLE)
199 #define DUK_HEAPHDR_SET_TEMPROOT(h) DUK_HEAPHDR_SET_FLAG_BITS((h),DUK_HEAPHDR_FLAG_TEMPROOT)
200 #define DUK_HEAPHDR_CLEAR_TEMPROOT(h) DUK_HEAPHDR_CLEAR_FLAG_BITS((h),DUK_HEAPHDR_FLAG_TEMPROOT)
201 #define DUK_HEAPHDR_HAS_TEMPROOT(h) DUK_HEAPHDR_CHECK_FLAG_BITS((h),DUK_HEAPHDR_FLAG_TEMPROOT)
203 #define DUK_HEAPHDR_SET_FINALIZABLE(h) DUK_HEAPHDR_SET_FLAG_BITS((h),DUK_HEAPHDR_FLAG_FINALIZABLE)
204 #define DUK_HEAPHDR_CLEAR_FINALIZABLE(h) DUK_HEAPHDR_CLEAR_FLAG_BITS((h),DUK_HEAPHDR_FLAG_FINALIZABLE)
205 #define DUK_HEAPHDR_HAS_FINALIZABLE(h) DUK_HEAPHDR_CHECK_FLAG_BITS((h),DUK_HEAPHDR_FLAG_FINALIZABLE)
207 #define DUK_HEAPHDR_SET_FINALIZED(h) DUK_HEAPHDR_SET_FLAG_BITS((h),DUK_HEAPHDR_FLAG_FINALIZED)
208 #define DUK_HEAPHDR_CLEAR_FINALIZED(h) DUK_HEAPHDR_CLEAR_FLAG_BITS((h),DUK_HEAPHDR_FLAG_FINALIZED)
209 #define DUK_HEAPHDR_HAS_FINALIZED(h) DUK_HEAPHDR_CHECK_FLAG_BITS((h),DUK_HEAPHDR_FLAG_FINALIZED)
211 /* get or set a range of flags; m=first bit number, n=number of bits */
212 #define DUK_HEAPHDR_GET_FLAG_RANGE(h,m,n) (((h)->h_flags >> (m)) & ((1UL << (n)) - 1UL))
214 #define DUK_HEAPHDR_SET_FLAG_RANGE(h,m,n,v) do { \
216 ((h)->h_flags & (~(((1 << (n)) - 1) << (m)))) \
220 /* init pointer fields to null */
221 #if defined(DUK_USE_DOUBLE_LINKED_HEAP)
222 #define DUK_HEAPHDR_INIT_NULLS(h) do { \
223 DUK_HEAPHDR_SET_NEXT((h), (void *) NULL); \
224 DUK_HEAPHDR_SET_PREV((h), (void *) NULL); \
227 #define DUK_HEAPHDR_INIT_NULLS(h) do { \
228 DUK_HEAPHDR_SET_NEXT((h), (void *) NULL); \
232 #define DUK_HEAPHDR_STRING_INIT_NULLS(h) /* currently nop */
235 * Reference counting helper macros. The macros take a thread argument
236 * and must thus always be executed in a specific thread context. The
237 * thread argument is needed for features like finalization. Currently
238 * it is not required for INCREF, but it is included just in case.
240 * Note that 'raw' macros such as DUK_HEAPHDR_GET_REFCOUNT() are not
241 * defined without DUK_USE_REFERENCE_COUNTING, so caller must #ifdef
245 #if defined(DUK_USE_REFERENCE_COUNTING)
247 /* Fast variants, inline refcount operations except for refzero handling.
248 * Can be used explicitly when speed is always more important than size.
249 * For a good compiler and a single file build, these are basically the
250 * same as a forced inline.
252 #define DUK_TVAL_INCREF_FAST(thr,tv) do { \
253 duk_tval *duk__tv = (tv); \
254 DUK_ASSERT(duk__tv != NULL); \
255 if (DUK_TVAL_IS_HEAP_ALLOCATED(duk__tv)) { \
256 duk_heaphdr *duk__h = DUK_TVAL_GET_HEAPHDR(duk__tv); \
257 DUK_ASSERT(duk__h != NULL); \
258 DUK_ASSERT(DUK_HEAPHDR_HTYPE_VALID(duk__h)); \
259 DUK_HEAPHDR_PREINC_REFCOUNT(duk__h); \
262 #define DUK_TVAL_DECREF_FAST(thr,tv) do { \
263 duk_tval *duk__tv = (tv); \
264 DUK_ASSERT(duk__tv != NULL); \
265 if (DUK_TVAL_IS_HEAP_ALLOCATED(duk__tv)) { \
266 duk_heaphdr *duk__h = DUK_TVAL_GET_HEAPHDR(duk__tv); \
267 DUK_ASSERT(duk__h != NULL); \
268 DUK_ASSERT(DUK_HEAPHDR_HTYPE_VALID(duk__h)); \
269 DUK_ASSERT(DUK_HEAPHDR_GET_REFCOUNT(duk__h) > 0); \
270 if (DUK_HEAPHDR_PREDEC_REFCOUNT(duk__h) == 0) { \
271 duk_heaphdr_refzero((thr), duk__h); \
275 #define DUK_HEAPHDR_INCREF_FAST(thr,h) do { \
276 duk_heaphdr *duk__h = (duk_heaphdr *) (h); \
277 DUK_ASSERT(duk__h != NULL); \
278 DUK_ASSERT(DUK_HEAPHDR_HTYPE_VALID(duk__h)); \
279 DUK_HEAPHDR_PREINC_REFCOUNT(duk__h); \
281 #define DUK_HEAPHDR_DECREF_FAST(thr,h) do { \
282 duk_heaphdr *duk__h = (duk_heaphdr *) (h); \
283 DUK_ASSERT(duk__h != NULL); \
284 DUK_ASSERT(DUK_HEAPHDR_HTYPE_VALID(duk__h)); \
285 DUK_ASSERT(DUK_HEAPHDR_GET_REFCOUNT(duk__h) > 0); \
286 if (DUK_HEAPHDR_PREDEC_REFCOUNT(duk__h) == 0) { \
287 duk_heaphdr_refzero((thr), duk__h); \
291 /* Slow variants, call to a helper to reduce code size.
292 * Can be used explicitly when size is always more important than speed.
294 #define DUK_TVAL_INCREF_SLOW(thr,tv) do { \
295 duk_tval_incref((tv)); \
297 #define DUK_TVAL_DECREF_SLOW(thr,tv) do { \
298 duk_tval_decref((thr), (tv)); \
300 #define DUK_HEAPHDR_INCREF_SLOW(thr,h) do { \
301 duk_heaphdr_incref((duk_heaphdr *) (h)); \
303 #define DUK_HEAPHDR_DECREF_SLOW(thr,h) do { \
304 duk_heaphdr_decref((thr), (duk_heaphdr *) (h)); \
307 /* Default variants. Selection depends on speed/size preference.
308 * Concretely: with gcc 4.8.1 -Os x64 the difference in final binary
309 * is about +1kB for _FAST variants.
311 #if defined(DUK_USE_FAST_REFCOUNT_DEFAULT)
312 #define DUK_TVAL_INCREF(thr,tv) DUK_TVAL_INCREF_FAST((thr),(tv))
313 #define DUK_TVAL_DECREF(thr,tv) DUK_TVAL_DECREF_FAST((thr),(tv))
314 #define DUK_HEAPHDR_INCREF(thr,h) DUK_HEAPHDR_INCREF_FAST((thr),(h))
315 #define DUK_HEAPHDR_DECREF(thr,h) DUK_HEAPHDR_DECREF_FAST((thr),(h))
317 #define DUK_TVAL_INCREF(thr,tv) DUK_TVAL_INCREF_SLOW((thr),(tv))
318 #define DUK_TVAL_DECREF(thr,tv) DUK_TVAL_DECREF_SLOW((thr),(tv))
319 #define DUK_HEAPHDR_INCREF(thr,h) DUK_HEAPHDR_INCREF_SLOW((thr),(h))
320 #define DUK_HEAPHDR_DECREF(thr,h) DUK_HEAPHDR_DECREF_SLOW((thr),(h))
323 /* Casting convenience. */
324 #define DUK_HSTRING_INCREF(thr,h) DUK_HEAPHDR_INCREF((thr),(duk_heaphdr *) (h))
325 #define DUK_HSTRING_DECREF(thr,h) DUK_HEAPHDR_DECREF((thr),(duk_heaphdr *) (h))
326 #define DUK_HOBJECT_INCREF(thr,h) DUK_HEAPHDR_INCREF((thr),(duk_heaphdr *) (h))
327 #define DUK_HOBJECT_DECREF(thr,h) DUK_HEAPHDR_DECREF((thr),(duk_heaphdr *) (h))
328 #define DUK_HBUFFER_INCREF(thr,h) DUK_HEAPHDR_INCREF((thr),(duk_heaphdr *) (h))
329 #define DUK_HBUFFER_DECREF(thr,h) DUK_HEAPHDR_DECREF((thr),(duk_heaphdr *) (h))
330 #define DUK_HCOMPILEDFUNCTION_INCREF(thr,h) DUK_HEAPHDR_INCREF((thr),(duk_heaphdr *) &(h)->obj)
331 #define DUK_HCOMPILEDFUNCTION_DECREF(thr,h) DUK_HEAPHDR_DECREF((thr),(duk_heaphdr *) &(h)->obj)
332 #define DUK_HNATIVEFUNCTION_INCREF(thr,h) DUK_HEAPHDR_INCREF((thr),(duk_heaphdr *) &(h)->obj)
333 #define DUK_HNATIVEFUNCTION_DECREF(thr,h) DUK_HEAPHDR_DECREF((thr),(duk_heaphdr *) &(h)->obj)
334 #define DUK_HBUFFEROBJECT_INCREF(thr,h) DUK_HEAPHDR_INCREF((thr),(duk_heaphdr *) &(h)->obj)
335 #define DUK_HBUFFEROBJECT_DECREF(thr,h) DUK_HEAPHDR_DECREF((thr),(duk_heaphdr *) &(h)->obj)
336 #define DUK_HTHREAD_INCREF(thr,h) DUK_HEAPHDR_INCREF((thr),(duk_heaphdr *) &(h)->obj)
337 #define DUK_HTHREAD_DECREF(thr,h) DUK_HEAPHDR_DECREF((thr),(duk_heaphdr *) &(h)->obj)
339 /* Convenience for some situations; the above macros don't allow NULLs
340 * for performance reasons.
342 #define DUK_HOBJECT_INCREF_ALLOWNULL(thr,h) do { \
344 DUK_HEAPHDR_INCREF((thr), (duk_heaphdr *) (h)); \
347 #define DUK_HOBJECT_DECREF_ALLOWNULL(thr,h) do { \
349 DUK_HEAPHDR_DECREF((thr), (duk_heaphdr *) (h)); \
353 #else /* DUK_USE_REFERENCE_COUNTING */
355 #define DUK_TVAL_INCREF_FAST(thr,v) do {} while (0) /* nop */
356 #define DUK_TVAL_DECREF_FAST(thr,v) do {} while (0) /* nop */
357 #define DUK_TVAL_INCREF_SLOW(thr,v) do {} while (0) /* nop */
358 #define DUK_TVAL_DECREF_SLOW(thr,v) do {} while (0) /* nop */
359 #define DUK_TVAL_INCREF(thr,v) do {} while (0) /* nop */
360 #define DUK_TVAL_DECREF(thr,v) do {} while (0) /* nop */
361 #define DUK_HEAPHDR_INCREF_FAST(thr,h) do {} while (0) /* nop */
362 #define DUK_HEAPHDR_DECREF_FAST(thr,h) do {} while (0) /* nop */
363 #define DUK_HEAPHDR_INCREF_SLOW(thr,h) do {} while (0) /* nop */
364 #define DUK_HEAPHDR_DECREF_SLOW(thr,h) do {} while (0) /* nop */
365 #define DUK_HEAPHDR_INCREF(thr,h) do {} while (0) /* nop */
366 #define DUK_HEAPHDR_DECREF(thr,h) do {} while (0) /* nop */
367 #define DUK_HSTRING_INCREF(thr,h) do {} while (0) /* nop */
368 #define DUK_HSTRING_DECREF(thr,h) do {} while (0) /* nop */
369 #define DUK_HOBJECT_INCREF(thr,h) do {} while (0) /* nop */
370 #define DUK_HOBJECT_DECREF(thr,h) do {} while (0) /* nop */
371 #define DUK_HBUFFER_INCREF(thr,h) do {} while (0) /* nop */
372 #define DUK_HBUFFER_DECREF(thr,h) do {} while (0) /* nop */
373 #define DUK_HCOMPILEDFUNCTION_INCREF(thr,h) do {} while (0) /* nop */
374 #define DUK_HCOMPILEDFUNCTION_DECREF(thr,h) do {} while (0) /* nop */
375 #define DUK_HNATIVEFUNCTION_INCREF(thr,h) do {} while (0) /* nop */
376 #define DUK_HNATIVEFUNCTION_DECREF(thr,h) do {} while (0) /* nop */
377 #define DUK_HBUFFEROBJECT_INCREF(thr,h) do {} while (0) /* nop */
378 #define DUK_HBUFFEROBJECT_DECREF(thr,h) do {} while (0) /* nop */
379 #define DUK_HTHREAD_INCREF(thr,h) do {} while (0) /* nop */
380 #define DUK_HTHREAD_DECREF(thr,h) do {} while (0) /* nop */
381 #define DUK_HOBJECT_INCREF_ALLOWNULL(thr,h) do {} while (0) /* nop */
382 #define DUK_HOBJECT_DECREF_ALLOWNULL(thr,h) do {} while (0) /* nop */
384 #endif /* DUK_USE_REFERENCE_COUNTING */
386 #endif /* DUK_HEAPHDR_H_INCLUDED */