/*
 * heap
 *
 * A heap system in a flex block
 *
 * © 1993-1998 Straylight
 */

/*----- Licensing note ----------------------------------------------------*
 *
 * This file is part of Straylight's Steel library.
 *
 * Steel is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2, or (at your option)
 * any later version.
 *
 * Steel is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Steel.  If not, write to the Free Software Foundation,
 * 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
 */

#ifndef __heap_h
#define __heap_h

#ifndef __size_t
#define __size_t 1
typedef unsigned int size_t;   /* from <stddef.h> */
#endif

typedef struct heap_infostr
{
  int size;                                   /* Size of the whole heap    */
  int free;                                   /* Heap space currently free */
  int largest;                                /* Size of the largest block */
}
heap_infostr;

/*
 * void heap_init(void)
 *
 * Use
 * Initialises the heap system for use.  This must be called before
 *  flex_alloc to ensure that the system gets the first block and so it
 *  doesn't move around.  heap doesn't mind this, but your data probably will
 *  (if it doen't, why don't you use flex?).
 */

void heap_init(void);

/*
 * heap_infostr heap_info(void)
 *
 * Use
 *  Describes the heap's current status.
 *
 * Returns
 *  Structure type described above.
 */

heap_infostr heap_info(void);

/*
 * void *heap_alloc(size_t size)
 *
 * Use
 *  Allocates a block of at least a given size from a heap.  If the heap is
 *  not big enough, more is claimed from the operating system.  A NULL
 *  pointer is returned if a block of suitable size could not be found.
 *
 * Parameters
 *  size_t size == size of block required
 *
 * Returns
 *  Pointer to block
 */

void *heap_alloc(size_t size);

/*
 * void heap_free(void *block)
 *
 * Use
 *  Frees a block allocated using heap_alloc.  It tries to shrink the heap
 *  as much as possible and to coagulate adjacent free blocks together.
 *
 * Parameters
 *  void *block == pointer to the block to free
 */

void heap_free(void *block);

/*
 * void *heap_realloc(void *block,int newSize)
 *
 * Use
 *  Changes the size of a heap block.  If possible, the block's position is
 *  is unchanged, but this may not always be the case.
 *
 *  Note that changing a block's size to 0 is permitted.  Passing a NULL
 *  pointer will probably result in severe heap death.
 *
 * Parameters
 *  void *block == pointer to the block to change
 *  int newSize == the new size to make the block
 *
 * Returns
 *   Pointer to where the block has been moved to, or a NULL pointer if the
 *   allocation failed.
 */

void *heap_realloc(void *block,int newSize);

#endif