638
edits
GC API: Difference between revisions
steal bsmedberg's flags, gc_free()
(steal bsmedberg's flags, gc_free()) |
|||
| Line 47: | Line 47: | ||
All allocations are <code>malloc</code>-aligned (that is, alignment is such that the pointer can be cast to any reasonable C/C++ type and used). | All allocations are <code>malloc</code>-aligned (that is, alignment is such that the pointer can be cast to any reasonable C/C++ type and used). | ||
void * '''gc_alloc_no_pointers'''(GCHeap heap, size_t size); | typedef enum GCAllocFlags { | ||
'''GC_HAS_FINALIZER''' | |||
} '''GCAllocFlags'''; | |||
The ''flags'' parameter to the allocation functions is a bitwise OR of <code>GCAllocFlags</code> constants. Currently we only have one: <code>GC_HAS_FINALIZER</code> indicates that the allocation starts with a C++ object of a type that has a virtual destructor. The GC will call the destructor at some point after the object becomes unreachable and before its memory is reused or the heap is destroyed. | |||
void * '''gc_alloc_no_pointers'''( | |||
GCHeap heap, size_t size, int flags); | |||
Allocate ''size'' bytes of memory, not necessarily zeroed. The GC will assume the memory never contains pointers to other GC allocations. | Allocate ''size'' bytes of memory, not necessarily zeroed. The GC will assume the memory never contains pointers to other GC allocations. | ||
void * '''gc_alloc_conservative'''(GCHeap heap, size_t size); | void * '''gc_alloc_conservative'''( | ||
GCHeap heap, size_t size, int flags); | |||
Allocate and zero out ''size'' bytes of memory. The GC will conservatively scan the memory for pointers. | Allocate and zero out ''size'' bytes of memory. The GC will conservatively scan the memory for pointers. | ||
void * '''gc_alloc_onion'''(GCHeap, size_t rawSize, size_t ptrsSize); | void * '''gc_alloc_onion'''( | ||
GCHeap heap, size_t rawSize, size_t ptrsSize, int flags); | |||
Allocate ''rawSize'' + ''ptrsSize'' bytes of memory. Both sizes must be pointer-size-aligned. The first ''rawSize'' bytes are not necessarily zeroed. They GC will assume that they never contain pointers. The next ''ptrsSize'' bytes are treated as an array of "possible pointers" (<code>jsval</code>, really; see below). | Allocate ''rawSize'' + ''ptrsSize'' bytes of memory. Both sizes must be pointer-size-aligned. The first ''rawSize'' bytes are not necessarily zeroed. They GC will assume that they never contain pointers. The next ''ptrsSize'' bytes are treated as an array of "possible pointers" (<code>jsval</code>, really; see below). | ||
''flags'' must not contain <code>GC_HAS_FINALIZER</code>. | |||
Returns a pointer to the first byte of the pointers region, so the non-pointer-containing words are at negative offsets and the pointer-containing words are at positive offsets. | Returns a pointer to the first byte of the pointers region, so the non-pointer-containing words are at negative offsets and the pointer-containing words are at positive offsets. | ||
void * '''gc_alloc_with_layout'''(GCHeap heap, GCLayout layout); | void * '''gc_alloc_with_layout'''( | ||
GCHeap heap, GCLayout layout, int flags); | |||
Allocate and zero out memory for an object. The ''layout'' specifies the size of the allocation and which words of it may contain pointers. Layout is described in more detail below. | Allocate and zero out memory for an object. The ''layout'' specifies the size of the allocation and which words of it may contain pointers. Layout is described in more detail below. | ||
| Line 69: | Line 81: | ||
GCLayout headerLayout, | GCLayout headerLayout, | ||
GCLayout elementLayout, | GCLayout elementLayout, | ||
size_t count); | size_t count, | ||
int flags); | |||
Allocate and zero out memory for an array. The layout of the array consists of an optional header described by ''headerLayout'', followed by ''count'' array elements, each described by ''elementLayout''. Returns a pointer to the beginning of the allocation (the header). | Allocate and zero out memory for an array. The layout of the array consists of an optional header described by ''headerLayout'', followed by ''count'' array elements, each described by ''elementLayout''. Returns a pointer to the beginning of the allocation (the header). | ||
| Line 78: | Line 91: | ||
'''Open issue:''' Weak references. | '''Open issue:''' Weak references. | ||
== Explicit deallocation == | |||
void '''gc_free'''(GCHeap heap, void *ptr); | |||
Frees the allocation at ''ptr'', which must be a pointer returned by an allocation function. The region of memory at ''ptr'' must be live, but the caller must also ensure that no live, exactly-scanned words point to it. (Conservatively scanned words, including C/C++ temporaries and local variables, may point to it.) | |||
This may be a no-op. | |||
== Layout == | == Layout == | ||
| Line 137: | Line 158: | ||
This is a description of the private API that the allocator needs to provide to the GC engine which runs atop it. (The allocator also provides all the Allocation and Layout APIs, which are user-visible.) | This is a description of the private API that the allocator needs to provide to the GC engine which runs atop it. (The allocator also provides all the Allocation and Layout APIs, which are user-visible.) | ||
/* APIs for marking */ | /* APIs for marking */ | ||