heap.h

00001 /*
00002 # This file is Copyright 2003, 2006, 2007, 2009 Dean Hall.
00003 #
00004 # This file is part of the PyMite VM.
00005 # The PyMite VM is free software: you can redistribute it and/or modify
00006 # it under the terms of the GNU GENERAL PUBLIC LICENSE Version 2.
00007 #
00008 # The PyMite VM is distributed in the hope that it will be useful,
00009 # but WITHOUT ANY WARRANTY; without even the implied warranty of
00010 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
00011 # A copy of the GNU GENERAL PUBLIC LICENSE Version 2
00012 # is seen in the file COPYING in this directory.
00013 */
00014 
00015 
00016 #ifndef __HEAP_H__
00017 #define __HEAP_H__
00018 
00019 
00020 /**
00021  * \file
00022  * \brief VM Heap
00023  *
00024  * VM heap header.
00025  */
00026 
00027 
00028 /**
00029  * The threshold of heap.avail under which the interpreter will run the GC
00030  * just before starting a native session.
00031  */
00032 #define HEAP_GC_NF_THRESHOLD (512)
00033 
00034 
00035 #ifdef __DEBUG__
00036 #define DEBUG_PRINT_HEAP_AVAIL(s) \
00037     do { uint16_t n; heap_getAvail(&n); printf(s "heap avail = %d\n", n); } \
00038     while (0)
00039 #else
00040 #define DEBUG_PRINT_HEAP_AVAIL(s)
00041 #endif
00042 
00043 
00044 /**
00045  * Initializes the heap for use.
00046  *
00047  * @return  nothing.
00048  */
00049 PmReturn_t heap_init(void);
00050 
00051 /**
00052  * Returns a free chunk from the heap.
00053  *
00054  * The chunk will be at least the requested size.
00055  * The actual size can be found in the return chunk's od.od_size.
00056  *
00057  * @param   requestedsize Requested size of the chunk in bytes.
00058  * @param   r_pchunk Addr of ptr to chunk (return).
00059  * @return  Return code
00060  */
00061 PmReturn_t heap_getChunk(uint16_t requestedsize, uint8_t **r_pchunk);
00062 
00063 /**
00064  * Places the chunk back in the heap.
00065  *
00066  * @param   ptr Pointer to object to free.
00067  */
00068 PmReturn_t heap_freeChunk(pPmObj_t ptr);
00069 
00070 /** @return  Return number of bytes available in the heap */
00071 #if PM_HEAP_SIZE > 65535
00072 uint32_t
00073 #else
00074 uint16_t
00075 #endif
00076   heap_getAvail (void);
00077 
00078 #ifdef HAVE_GC
00079 /**
00080  * Runs the mark-sweep garbage collector
00081  *
00082  * @return  Return code
00083  */
00084 PmReturn_t heap_gcRun(void);
00085 
00086 /**
00087  * Enables (if true) or disables automatic garbage collection
00088  *
00089  * @param   bool Value to enable or disable auto GC
00090  * @return  Return code
00091  */
00092 PmReturn_t heap_gcSetAuto(uint8_t auto_gc);
00093 #endif /* HAVE_GC */
00094 
00095 #endif /* __HEAP_H__ */