/* CURRENT API
 *
 * (Look at the example below for usage of functions not documented here!)
*/


void tar_init(int atomic_heap_size,
              int heap_size,
              int max_mem_size,
              int audio_priority_setting,
              float time_between_full_snapshot);

tar_heap_t *tar_create_heap(void);
void tar_delete_heap(tar_heap_t *heap,bool audio_is_running);

/* 'tar_alloc' returns a memory block which can be used for storing
 * any kind of data.
 *
 * The returned memory only contains zeros.
 */
void *tar_alloc(tar_heap_t *heap,size_t size);

/* 'tar_alloc_atomic' returns a memory block which can be used for storing
 * any kind of data, except pointers to other memory blocks allocated by either
 * 'tar_alloc' or 'tar_alloc_atomic'.
 * 
 * It's a huge optimization to use 'tar_alloc_atomic' instead of
 * 'tar_alloc' whenever possible.
 *
 * The returned memory only contains zeros. (Unlike the atomic function
 * in BDW-GC!)
 */
void *tar_alloc_atomic(tar_heap_t *heap,size_t size);

size_t tar_get_used_mem(tar_heap_t *heap);

size_t tar_get_used_atomic_mem(tar_heap_t *heap);

void tar_init_block(float duration);

void tar_before_using_heap(tar_heap_t *heap);
bool tar_after_using_heap(tar_heap_t *heap);

void tar_add_root(tar_heap_t *heap,void *start,void *end);
void tar_add_root_concurrently(tar_heap_t *heap,void *start,void *end);

void tar_start_gc(tar_heap_t *heap);

/* If having a global variable in a dynamic library pointed to by 'pointer',
 * 'tar_get_dynamic_roots_for' will find the range of global variables in that library.
 *
 * Afterwards, it makes sense to use those values
 * with the function 'tar_add_root_concurrenty'.
 *
 * The function returns 0 if the dynamic root could not be found.
 *
 * (This function is implemented using code from BDW-GC)
 */
int tar_get_dynamic_roots_for(char *pointer,char **start,char **end);

/* EXAMPLE OF USAGE */

#include <rollendurchmesserzeitsammler.h>

tar_heap_t *heap;

int audio_thread(int blocksize){

  int i;
  static void *root[50];


  /* 'tar_init_block' must be called before using any heap in the current block.        
   *
   * The function takes as argument the time (in seconds) since last call to tar_init_block.
   * Note that this number is only used to calculate when to do the next full snapshot,
   * so it should usually be more than good enough just to return the average time between each
   * call to 'tar_init_block'.
   */
  tar_init_block((float)blocksize/44100.0f);


  /* 'tar_before_using_heap' must be called before using a specific heap in the current block.
   *
   *  (In case a snapshot of the heap was scheduled to start at the end of the previous
   *  block, 'tar_before_using_heap' waits until the snapshot is finished.)
   */
  tar_before_using_heap(heap);


  /* Allocate and use memory */
  for(i=0;i<blocksize;i++){
    root[x]=tar_alloc(heap,20);
  }


  /* 'tar_after_using_heap' must be called when the heap is no longer used
   * in the current block.
   *
   * If 'tar_after_using_heap' returns true, roots must be added before calling 'tar_run_gc':
   */
  if(tar_after_using_heap(heap)){

     /* Roots must be added before calling tar_run_gc
      *
      * We can use the concurrent function ('tar_add_root_concurrently') since the 'root' variable
      * is static and can't disappear after calling 'tar_add_root_concurrently'. (at least
      * as long as the C compiler is not doing anything really weird, but it should be safe to assume
      * that it doesn't.)
      *
      * The advantage of using the concurrent function is that the values
      * will be scheduled to be copied in a parallel thread, similarly
      * to how snapshots are performed.
      */
    tar_add_root_concurrently(heap,&root[0],&root[50]); /* [2] */

     /* Any value stored in CPU registers or stack are likely
      * to disappear though, so for such variables, the function 'tar_add_root'
      * must be used instead [1]: (Look at the file 'stalinwrapper.c' for a simple example
      * on how to get hold of stack and register values, and BDW-GC for a more thorough
      * way to get hold of stack and register values.)
      */
    tar_add_root(heap,registers_start,registers_end); /* [2] */
    tar_add_root(heap,stack_start,stack_end);

     /* After all roots have been added, 'tar_run_gc' must be called:
      */
    tar_run_gc(heap);
  }


  return 0;
}


int main(){
   tar_init(10*1024*1024, /* Size of the atomic memory heap. (Can be large). All heaps share the same atomic memory heap. */
            1024*1024,    /* Size of non-atomic memory heap per garbage collector heap (Should be as small as possible)  */
            1024*64       /* Maximum size of memory block to allocate. (Should be as small as possible)                  */
            audio_prior   /* Priority of the audio thread. Using jack, this would be jack_client_real_time_priority(client) */
            1.0f          /* Time (in seconds) between doing full snapshots. 1 second should work fine.                  */
    );
    heap=tar_create_heap(); /* Creates a new heap contaning non-atomic memory. */
    start_audio_thread(audio_thread);
    wait_forever();
    tar_delete(heap);
    return 0;
}

/*
[1] Adding registers and stack to the roots is unnecessary in this example. It is just
    to point out that it can be done, infact it is very often necessary.
    But in this specific example, there can't be pointers we need in the registers or stack
    since this function is exited after calling tar_run_gc() and all data stored
    in the registers and stack are lost anyway.

[2] The order of the two last arguments for tar_add_root_concurrently and tar_add_root does not matter.
*/