/*
 * mem
 *  Store handling for Steel
 *
 * version 1.00 6 September 1991
 *
 * © 1991-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 __mem_h
#define __mem_h

#ifndef __size_t
#define __size_t
typedef unsigned int size_t;
#endif

typedef void *(*mem_allocProc)(size_t size);
typedef void (*mem_freeProc)(void *ptr);

/*
 * void mem_flexdInit(void)
 *
 * Use
 *  Initialises flex system.  If flex is already initialised, nothing
 *  happens.  This call should be used in preference to flex_init().
 */

void mem_flexdInit(const char *name, long max);
#define mem_flexInit(x) mem_flexdInit(0, 0)

/*
 * void mem_heapInit(void)
 *
 * Use
 *  Initialises heap system.  If heap is already initialised, nothing
 *  happens.  If flex is not initialised, it is initialised for you.  This
 *  call should be used in preference to heap_init().  Note that unlike
 *  earlier versioms, this call will NOT set up ArmenLib to use heap by
 *  default.  This would be duplicating the functionality of mem_useHeap().
 */

void mem_heapInit(void);

/*
 * void mem_useMalloc(void)
 *
 * Use
 *  Makes ArmenLib use malloc() etc. for memory allocation.
 */

void mem_useMalloc(void);

/*
 * void mem_useHeap(void)
 *
 * Use
 *  Makes ArmenLib use heap_alloc() etc. for memory allocation.  It is
 *  initialised if necessary.
 */

void mem_useHeap(void);

/*
 * void mem_useUser(mem_allocProc alloc,mem_freeProc free)
 *
 * Use
 *  Makes ArmenLib use your own user-defined memory allocation procedures.
 *
 * Parameters
 *  mem_allocProc alloc == a routine to allocate a block of memory.  If a
 *    block of sufficient size cannot be allocated, return 0.  Problems
 *    about allocating blocks of 0 size are handled before your routine is
 *    called.
 *  mem_freeProc free == a routine to free a block of memory.  A valid
 *    pointer will be passed to your routine.
 */

void mem_useUser(mem_allocProc alloc,mem_freeProc free);

/*
 * void mem_useRMA(void)
 *
 * Use
 *  Makes ArmenLib use the RMA for memory allocation.
 */

void mem_useRMA(void);

/*
 * void *mem_RMAalloc(size_t size)
 *
 * Use
 *  Allocates a block of memory from the relocatable module area.
 *
 * Parameters
 *  size_t size == the size of the block
 *
 * Returns
 *  A pointer to the block (or 0)
 */

void *mem_RMAalloc(size_t size);

/*
 * void mem_RMAfree(void *ptr)
 *
 * Use
 *  Frees a block allocated using RMAalloc.
 *
 * Parameters
 *  void *ptr == a pointer to the block.
 */

void mem_RMAfree(void *ptr);

/*
 * void *mem_alloc(size_t size)
 *
 * Use
 *  Allocates a block of memory using malloc (or heap if initialised).  If
 *  size is zero, or allocation fails then a NULL pointer is returned.
 *
 * Parameters
 *  size_t size == how big you want the block.
 *
 * Returns
 *  A pointer to the block allocated.
 */

void *mem_alloc(size_t size);

/*
 * void mem_free(void *ptr)
 *
 * Purpose
 *  Frees a block of memory.  It must have been allocated using mem_alloc().
 *  If ptr is NULL, then mem_free() does nothing.
 *
 * Parameters
 *  void *ptr == the pointer returned by mem_alloc()
 */

void mem_free(void *ptr);

/*
 * size_t mem_sizeOfBlock(void *ptr)
 *
 * Use
 *  Returns the allocated size of the block.
 *
 * Parameters
 *  void *ptr == the pointer to the block
 *
 * Returns
 *  The size of the block.
 */

size_t mem_sizeOfBlock(void *ptr);

/*
 * void *mem_reAlloc(void *ptr,size_t newSize)
 *
 * Use
 *  Alters the size of the block given.  If the block could not be resized,
 *  its contents are unchanged.  Note that the block may move as a result of
 *  this call.
 *
 * Parameters
 *  void *ptr == a pointer to the block.  This may be NULL, in which case,
 *    this call behaves exactly like mem_alloc().
 *  size_t newSize == the new size to make the block.  This may be zero, in
 *    which case the block is freed.
 *
 * Returns
 *  A pointer to the block.
 */

void *mem_reAlloc(void *ptr,size_t newSize);

/*
 * void mem_allowFlexBudge(BOOL allow)
 *
 * Use
 *  A slightly more sensible way to allow flex store to be shunted around.
 *
 * Parameters
 *  BOOL allow == whether you want flex store to be shifted around willy-
 *    nilly.
 */

void mem_allowFlexBudge(BOOL allow);

#endif