1 /* gc_heap.h -- heap packing, run-time image generation */ 2 /* Copyright (c) 2016 Chris Walsh. All rights reserved. */ 3 /* BSD-style license: http://synthcode.com/license.txt */ 4 5 #ifndef SEXP_GC_HEAP_H 6 #define SEXP_GC_HEAP_H 7 8 #include "chibi/sexp.h" 9 10 #if SEXP_USE_IMAGE_LOADING 11 12 #ifdef __cplusplus 13 extern "C" { 14 #endif 15 16 /* Iterate the heap associated with the context argument 'ctx', 17 calling user provided callbacks for the individual heap elements. 18 19 For each heap found, heap_callback is called. 20 For each free segment found, free_callback is called. 21 For each valid sexp found, sexp_callback is called. 22 23 Callbacks are skipped if the associated function 24 pointer argument is NULL. 25 26 A callback return value of SEXP_TRUE allows the heap walk to 27 continue normally. Any other value terminates the heap walk 28 with the callback result being returned. 29 30 The sexp_gc_heap_walk return value of SEXP_TRUE indicates all 31 elements of the heap were walked normally. Any other return 32 value indicates an abnormal return condition. 33 */ 34 SEXP_API sexp sexp_gc_heap_walk( 35 sexp ctx, /* a possibly incomplete context */ 36 sexp_heap h, /* normally set to sexp_context_heap(ctx) */ 37 sexp *types, /* normally set to sexp_context_types(ctx) */ 38 size_t types_cnt, /* normally set to sexp_context_num_types(ctx) */ 39 void *user, /* arbitrary data passed to callbacks */ 40 sexp (*heap_callback)(sexp ctx, sexp_heap h, void *user), 41 sexp (*free_callback)(sexp ctx, sexp_free_list f, void *user), 42 sexp (*sexp_callback)(sexp ctx, sexp s, void *user)); 43 44 45 /* Returns a new context which contains a single, packed heap. 46 47 The original ctx or heap are not altered, leaving two copies 48 of all sexps. For runtime use where you are packing the heap 49 to make accesses more efficient, the old heap and context should 50 be discarded after a sucessful call to heap pack; finalizers do 51 not need to be called since all active objects are in the new heap. 52 53 The input heap_size specifies the amount of free space to allocate 54 at the end of the packed heap. A heap_size of zero will produce a 55 single packed heap just large enough to hold all sexps from the 56 original heap. 57 */ 58 SEXP_API sexp sexp_gc_heap_pack(sexp ctx, sexp_uint_t heap_free_size); 59 60 61 /* Creates a new packed heap from the provided context, and saves 62 the contents of the packed heap to the file named filename. 63 64 If sucessful, SEXP_TRUE is returned. If a problem was encountered 65 in either creating the packed heap or saving to a file, then either 66 SEXP_FALSE or an exception is returned. Because of shared code with 67 sexp_load_image, sexp_load_image_err() can also be used to return the 68 error condition. 69 70 In all cases, upon completion the temporary packed context is deleted 71 and the context provided as an argument is not changed. 72 */ 73 SEXP_API sexp sexp_save_image (sexp ctx, const char* filename); 74 75 76 /* Loads a previously saved image, and returns the context associated with 77 that image. If the context could not be loaded, either NULL or an exception 78 are returned instead. 79 80 A new context is created with the contents of filename loaded into the 81 heap. The heap_free_size parameter specifies the size of the heap to be 82 created in addition to the heap image on disk. A size of zero will 83 result in an initial heap exactly the size of the disk image which will 84 be expanded with an additional heap when the system requests storage space. 85 86 The return value is either the context of the loaded image, or NULL. In 87 the case of a NULL context, the function sexp_load_image_err() can be called 88 to provide a description of the error encountered. An sexp exception cannot be 89 returned because there is not a valid context in which to put the exception. 90 */ 91 SEXP_API sexp sexp_load_image (const char* filename, off_t offset, sexp_uint_t heap_free_size, sexp_uint_t heap_max_size); 92 93 94 /* In the case that sexp_load_image() returns NULL, this function will return 95 a string containing a description of the error condition. 96 */ 97 SEXP_API char* sexp_load_image_err(); 98 99 #ifdef __cplusplus 100 } 101 #endif 102 103 #endif /* SEXP_USE_IMAGE_LOADING */ 104 105 #endif /* ! SEXP_GC_HEAP_H */ 106