/* gc_heap.h -- heap packing, run-time image generation    */
/* Copyright (c) 2016 Chris Walsh.  All rights reserved.   */
/* BSD-style license: http://synthcode.com/license.txt     */

#ifndef SEXP_GC_HEAP_H
#define SEXP_GC_HEAP_H

#include "chibi/sexp.h"

#if SEXP_USE_IMAGE_LOADING

#ifdef __cplusplus
extern "C" {
#endif

/* Iterate the heap associated with the context argument 'ctx',
   calling user provided callbacks for the individual heap elements.
   
   For each heap found, heap_callback is called.
   For each free segment found, free_callback is called.
   For each valid sexp found, sexp_callback is called.
     
   Callbacks are skipped if the associated function
   pointer argument is NULL.

   A callback return value of SEXP_TRUE allows the heap walk to 
   continue normally.  Any other value terminates the heap walk
   with the callback result being returned.
 
   The sexp_gc_heap_walk return value of SEXP_TRUE indicates all
   elements of the heap were walked normally.  Any other return 
   value indicates an abnormal return condition.
*/
SEXP_API sexp sexp_gc_heap_walk(
  sexp ctx,         /* a possibly incomplete context */
  sexp_heap h,      /* normally set to sexp_context_heap(ctx) */
  sexp *types,      /* normally set to sexp_context_types(ctx) */
  size_t types_cnt, /* normally set to sexp_context_num_types(ctx) */
  void *user,   /* arbitrary data passed to callbacks */
  sexp (*heap_callback)(sexp ctx, sexp_heap h, void *user),
  sexp (*free_callback)(sexp ctx, sexp_free_list f, void *user),
  sexp (*sexp_callback)(sexp ctx, sexp s, void *user));


/* Returns a new context which contains a single, packed heap.
   
   The original ctx or heap are not altered, leaving two copies
   of all sexps.  For runtime use where you are packing the heap
   to make accesses more efficient, the old heap and context should
   be discarded after a sucessful call to heap pack; finalizers do
   not need to be called since all active objects are in the new heap.
 
   The input heap_size specifies the amount of free space to allocate
   at the end of the packed heap.  A heap_size of zero will produce a
   single packed heap just large enough to hold all sexps from the
   original heap.
*/
SEXP_API sexp sexp_gc_heap_pack(sexp ctx, sexp_uint_t heap_free_size);


/* Creates a new packed heap from the provided context, and saves
   the contents of the packed heap to the file named filename.

   If sucessful, SEXP_TRUE is returned.  If a problem was encountered
   in either creating the packed heap or saving to a file, then either
   SEXP_FALSE or an exception is returned.  Because of shared code with
   sexp_load_image, sexp_load_image_err() can also be used to return the
   error condition.

   In all cases, upon completion the temporary packed context is deleted 
   and the context provided as an argument is not changed.
*/
SEXP_API sexp sexp_save_image (sexp ctx, const char* filename);


/* Loads a previously saved image, and returns the context associated with
   that image.  If the context could not be loaded, either NULL or an exception
   are returned instead.

   A new context is created with the contents of filename loaded into the
   heap.  The heap_free_size parameter specifies the size of the heap to be
   created in addition to the heap image on disk.  A size of zero will
   result in an initial heap exactly the size of the disk image which will
   be expanded with an additional heap when the system requests storage space.
 
   The return value is either the context of the loaded image, or NULL.  In
   the case of a NULL context, the function sexp_load_image_err() can be called
   to provide a description of the error encountered.  An sexp exception cannot be
   returned because there is not a valid context in which to put the exception.
*/
SEXP_API sexp sexp_load_image (const char* filename, off_t offset, sexp_uint_t heap_free_size, sexp_uint_t heap_max_size);


/* In the case that sexp_load_image() returns NULL, this function will return
   a string containing a description of the error condition.
*/
SEXP_API char* sexp_load_image_err();

#ifdef __cplusplus
}
#endif

#endif  /* SEXP_USE_IMAGE_LOADING */

#endif  /* ! SEXP_GC_HEAP_H */