/*
Copyright (c) 1993 Xerox Corporation.  All rights reserved.
*/
/*
$Id$

$Date$
 *
 * PCR Memory Management public interface
 */
/* Chauser, October 28, 1993 4:22 pm PDT */

#ifndef __PCR_MM_h
#define __PCR_MM_h 1

#include <config/PCR_StdTypes.h>
#include <stddef.h>

/*
 * A simple replace-able memory manager interface
 *
 * This is not *really* object oriented,
 *   since the procs in an object must share state covertly.
 *
 * Implementations are expected to use the POSIX system-provided
 *   malloc/calloc to allocate their own heap space.
 *
 * Clients (wizards excepted) are expected *never* to use 
 *   malloc/calloc/realloc/free directly.
 */


typedef void * ((PCR_MM_AllocProc)(
        size_t size, PCR_Bool ptrFree, PCR_Bool clear ));
/*
    Allocate memory.
    The ptrFree flag is a hint that says it's okay for a GC
      to not trace through the object.
    The clear argument causes the allocated area to be initialized to zeroes.
*/

typedef void * ((PCR_MM_ReallocProc)(void *p, size_t size));
/*
    Grow / shrink object p, as in the standard C library routine.
    The ptrFree property is preserved.
*/

typedef void ((PCR_MM_FreeProc)(void *p));
/*
    Explicit free.
*/


typedef PCR_ERes ((PCR_MM_EnumerateProc)(
    PCR_Bool ptrFree,
    PCR_ERes (*proc)(void *p, size_t size, PCR_Any data),
    PCR_Any data
));
/*
    Enumerate all currently allocated pointer-containing
      (if ptrFree is false) or pointer-free (if ptrFree is true)
      objects.
    The ptrFree characterization is just a hint -- a conservative
      system is free to ignore it and treat all objects as
      pointer-containing.
    Enumeration is terminated if proc returns error.
    
*/



typedef void ((PCR_MM_ShutdownProc)(void));
/*
    Terminate any currently running daemons (e.g GC).
    Calls to allocate/free and enumeration procs are still legitimate
      but will not restart any daemons or cause garbage collections.
    This is called automatically by PCR_MM_Install() below.
*/


extern unsigned long PCR_MM_defaultMagic;

struct PCR_MM_ProcsRep {
    unsigned long mmp_magic;
    PCR_MM_AllocProc *mmp_alloc;
    PCR_MM_ReallocProc *mmp_realloc;
    PCR_MM_FreeProc *mmp_free;
    PCR_MM_FreeProc *mmp_unsafeFree;
    PCR_MM_EnumerateProc *mmp_enumerate;
    PCR_MM_ShutdownProc *mmp_shutdown;
};

typedef struct PCR_MM_ProcsRep PCR_MM_Procs;


extern PCR_MM_Procs * volatile PCR_MM_installedProcs;

extern void
PCR_MM_Install(PCR_MM_Procs *self, PCR_MM_Procs **prev);
/*
    Atomically
      call shutdown proc of previous implementation,
      store previous implementation into *prev
      install self
    No calls to new implementation are performed until
      previous one has been shut down and copied to *prev. 
*/

/*
 * C clients may use the following sugared names:
 *
 * For allocation:
 *   (*(PCR_MM_installedProcs->mmp_alloc))(sz, ptrFree, clear)
 *   PCR_MM_Alloc(sz, ptrFree, clear)
 *
 *   malloc(sz) -- renamed in posix hdr file
 *   PCR_malloc(sz)
 *   PCR_MM_Malloc(sz)
 *
 * etc.
 */


extern void * (PCR_MM_Alloc(size_t size, PCR_Bool ptrFree, PCR_Bool clear));
#   define PCR_MM_Alloc(sz,pf,cl) \
	(*(PCR_MM_installedProcs->mmp_alloc))((sz), (pf), (cl))


extern void * (PCR_MM_New(size_t size));
#   define PCR_MM_New(sz) \
	(*(PCR_MM_installedProcs->mmp_alloc))( \
		(sz), PCR_Bool_false, PCR_Bool_true )


extern void * (PCR_MM_Malloc(size_t size));
#   define PCR_MM_Malloc(sz) \
	(*(PCR_MM_installedProcs->mmp_alloc))( \
		(sz), PCR_Bool_false, PCR_Bool_false )


extern void * (PCR_MM_Realloc(void *p, size_t size));
#   define PCR_MM_Realloc(p,sz) \
	(*(PCR_MM_installedProcs->mmp_realloc))((p), (sz))


extern void (PCR_MM_Free(void *p));
#   define PCR_MM_Free(p) \
	(*(PCR_MM_installedProcs->mmp_free))(p)


extern void (PCR_MM_UnsafeFree(void *p));
#   define PCR_MM_UnsafeFree(p) \
	(*(PCR_MM_installedProcs->mmp_unsafeFree))(p)


extern PCR_ERes (PCR_MM_Enumerate(
    PCR_Bool ptrFree,
    PCR_ERes (*proc)(void *p, size_t size, PCR_Any data),
    PCR_Any data
));
#   define PCR_MM_Enumerate(pf,proc,data) \
	(*(PCR_MM_installedProcs->mmp_enumerate))((pf), (proc), (data))


#endif /* ! __PCR_MM_h */
/*
$Log$
*/