flight/libraries/PyMite/vm/heap.h

   1 /*
   2 # This file is Copyright 2003, 2006, 2007, 2009, 2010 Dean Hall.
   3 #
   4 # This file is part of the PyMite VM.
   5 # The PyMite VM is free software: you can redistribute it and/or modify
   6 # it under the terms of the GNU GENERAL PUBLIC LICENSE Version 2.
   7 #
   8 # The PyMite VM is distributed in the hope that it will be useful,
   9 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  10 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  11 # A copy of the GNU GENERAL PUBLIC LICENSE Version 2
  12 # is seen in the file COPYING in this directory.
  13 */
  14
  15
  16 #ifndef __HEAP_H__
  17 #define __HEAP_H__
  18
  19
  20 /**
  21  * \file
  22  * \brief VM Heap
  23  *
  24  * VM heap header.
  25  */
  26
  27
  28 /**
  29  * The threshold of heap.avail under which the interpreter will run the GC
  30  * just before starting a native session.
  31  */
  32 #define HEAP_GC_NF_THRESHOLD (512)
  33
  34
  35 #ifdef __DEBUG__
  36 #define DEBUG_PRINT_HEAP_AVAIL(s) \
  37     do { uint16_t n; heap_getAvail(&n); printf(s "heap avail = %d\n", n); } \
  38     while (0)
  39 #else
  40 #define DEBUG_PRINT_HEAP_AVAIL(s)
  41 #endif
  42
  43
  44 /**
  45  * Initializes the heap for use.
  46  *
  47  * @return  nothing.
  48  */
  49 PmReturn_t heap_init(void);
  50
  51 /**
  52  * Returns a free chunk from the heap.
  53  *
  54  * The chunk will be at least the requested size.
  55  * The actual size can be found in the return chunk's od.od_size.
  56  *
  57  * @param   requestedsize Requested size of the chunk in bytes.
  58  * @param   r_pchunk Addr of ptr to chunk (return).
  59  * @return  Return code
  60  */
  61 PmReturn_t heap_getChunk(uint16_t requestedsize, uint8_t **r_pchunk);
  62
  63 /**
  64  * Places the chunk back in the heap.
  65  *
  66  * @param   ptr Pointer to object to free.
  67  */
  68 PmReturn_t heap_freeChunk(pPmObj_t ptr);
  69
  70 /** @return  Return number of bytes available in the heap */
  71 #if PM_HEAP_SIZE > 65535
  72 uint32_t
  73 #else
  74 uint16_t
  75 #endif
  76   heap_getAvail(void);
  77
  78 #ifdef HAVE_GC
  79 /**
  80  * Runs the mark-sweep garbage collector
  81  *
  82  * @return  Return code
  83  */
  84 PmReturn_t heap_gcRun(void);
  85
  86 /**
  87  * Enables (if true) or disables automatic garbage collection
  88  *
  89  * @param   bool Value to enable or disable auto GC
  90  * @return  Return code
  91  */
  92 PmReturn_t heap_gcSetAuto(uint8_t auto_gc);
  93
  94 #endif /* HAVE_GC */
  95
  96 /**
  97  * Pushes an object onto the temporary roots stack if there is room
  98  * to protect the objects from a potential garbage collection
  99  *
 100  * @param pobj Object to push onto the roots stack
 101  * @param r_objid By reference; ID to use when popping the object from the stack
 102  */
 103 void heap_gcPushTempRoot(pPmObj_t pobj, uint8_t *r_objid);
 104
 105 /**
 106  * Pops from the temporary roots stack all objects upto and including the one
 107  * denoted by the given ID
 108  *
 109  * @param objid ID of object to pop
 110  */
 111 void heap_gcPopTempRoot(uint8_t objid);
 112
 113 #endif /* __HEAP_H__ */