---

MeMemory.h

Go to the documentation of this file.

#ifndef _MEMEMORY_H
#define _MEMEMORY_H
/*
  Copyright MathEngine PLC 2000

  MathEngine memory manager API

  $Name: t-release-0-0-5-msvcrt $

  $Id: MeMemory.h,v 1.17 2000/07/27 15:53:12 jamesg Exp $
*/

/** @file
 * The memory manager API.
 *
 * This API allows a library to use an external memory manager, via a
 * a set of function pointers with predefined semantics.
 *
 * It also allows a library to give hints as to what kind of memory
 * management it prefers; the memory manager may or may not heed such
 * advice.
 *
 * It is expected that the debug version of the memory managers will
 * perform extensive checks, like verifying redzones around each block.
 */

#include <stddef.h>

#ifdef __cplusplus
  extern "C" {
#endif

/* All these options are strictly advisory. Default for all is '0',
   which means that the allocator chooses something general.

   Suppose instead that one knows in advance that one needs only blocks
   of sizes 8 to 12 aligned on 4 byte boundaries, and 64 aligned on 16
   bytes boundaries (e.g. 2-3 floats and 16 floats), and one needs
   exactly 400 of one and at least 850 of the other, and one likes an
   array based algorithm, then one can write:

   struct MeMemoryOptionsSize sizes[] =
   {
     { 2,       10,12,   400,400},
     { 4,       64,64,   850,0  }
   };
   struct MeMemoryOptions options;

   options.allocation = MeMemoryArrays;
   options.reclamation = MeMemoryManual;

   options.arenaAtLeast = 0;
   options.arenaAtMost = 0;

   options.blockFixed = 2;
   options.block.sizes = sizes;

   (*MeMemoryAPI.setOptions)(&options);
   (*MeMemoryAPI.setup)();

   and similarly for other policies. */

/**
 * Type of memory allocation implementation.
 */
enum MeMemoryAllocation
{
  MeMemoryAny = 0,         /**< Choose any. (default, must be 0) */
  MeMemorySegment,         /**< Growing area, like UNIX data segment */
  MeMemoryBIBOP,           /**< Big bag of pages */
  MeMemoryBTag,            /**< Boundary tag */
  MeMemoryBitmap,          /**< Flat bitmap */
  MeMemoryBuddy,           /**< Buddy system */
  MeMemoryArrays,          /**< Contiguous fixed size arrays */
  MeMemoryPools            /**< Contiguous flexible size arrays */
};

/**
 * Type of memory reclamation policy.
 */
enum MeMemoryReclamation
{
  MeMemoryManual = 0,      /**< Manual/explicit. (default, must be 0) */
  MeMemoryNone,            /**< No memory reclamation */
  MeMemoryStack,           /**< Like Pascal Mark/Release */
  MeMemoryRefCount,        /**< Reference counting */
  MeMemoryGC,              /**< Vanilla conservative GC */
  MeMemoryGCCompacting,    /**< Compacting GC */
  MeMemoryGCCopying,       /**< Baker style copying GC */
  MeMemoryGCAged           /**< Hewitt style generational GC */
};

/**
 * Memory manager initialisation options.
 *
 * The following is pretty obvious, except for the presence of 'minSize'
 * and 'maxSize' for fixed size blocks. Well, the blocks are actually
 * 'maxSize' large (plus alignment padding), but if smaller size pools
 * are used up, a block smaller than 'maxSize' may be allocated in a
 * 'maxSize' pool, if it is at least 'minSize' large.
 */
struct MeMemoryOptions
{
  /** Allocation implementation */
  enum MeMemoryAllocation  allocation;

  /** Reclamation policy */
  enum MeMemoryReclamation reclamation;

  /** suggested min size of an arena */
  size_t                minArena;
  /** suggested max size of an arena */
  size_t                maxArena;

  /** # of fixed block sizes, 0: flex */
  unsigned              blockFixed;
  union
  {
    /**
     * Options specific to flexible block size managers.
     */
    struct MeMemoryOptionsFlex
    {
      unsigned          align2Addr;     /**< lg2 of address alignment */
      unsigned          align2Size;     /**< lg2 of size alignment */
      size_t            minSize;        /**< min size of block */
      size_t            maxSize;        /**< max size of block */
      size_t            minTotal;       /**< min amount of memory */
      size_t            maxTotal;       /**< max amount of memory */
    }
                        flex;           /**< if 'blockFixed' is 0 */

    /**
     * Options specific to fixed block size managers.
     */
    struct MeMemoryOptionsFixed
    {
      unsigned          align2Addr;     /**< lg2 of address alignment */
      size_t            minSize;        /**< minimum block size */
      size_t            defSize;        /**< default block size */

      /** min # of blocks in size range */
      long unsigned     minCount;
      /** max # of blocks in size range */
      long unsigned     maxCount;
    }
                        *fixed;         /**< if 'blockFixed' is > 0 */
  }
                        block;          /**< Manager specific options */
};

/**
 * Memory manager statistics.
 */
struct MeMemoryStats
{
  long unsigned         createCounter;  /**< # of create calls */
  long unsigned         resizeCounter;  /**< # of resize calls */
  long unsigned         incRefCounter;  /**< # of incRef calls */
  long unsigned         decRefCounter;  /**< # of decRef calls */
  long unsigned         destroyCounter; /**< # of destroy calls */

  /** min size of an arena so far */
  size_t                minArena;
  /** max size of an arena so far */
  size_t                maxArena;

  /** # of fixed block sizes, 0: flex */
  unsigned              blockFixed;
  union
  {
    /**
     * Options specific to flexible block size managers.
     */
    struct MeMemoryStatsFlex
    {
      size_t            minSize;        /**< min requested size */
      size_t            maxSize;        /**< max requested size */
      long unsigned     currentCount;   /**< current # of blocks busy */
      long unsigned     maxCount;       /**< max # of blocks busy */

      /** total memory currently busy */
      size_t            currentTotal;
      /** total memory highest ever busy */
      size_t            maxTotal;
    }
                        flex;           /**< if 'blockFixed' is 0 */

    /**
     * Options specific to Fixed block size managers.
     */
    struct MeMemoryStatsFixed
    {
      size_t            minSize;        /**< minimum block size */
      size_t            defSize;        /**< default block size */

      /** # of allocations size < defSize */
      long unsigned     minCounter;
      /** # of allocations size == defSize*/

      long unsigned     defCounter;

      long unsigned     currentCount;   /**< current # of blocks busy */
      long unsigned     maxCount;       /**< max # of blocks busy */
    }
                        *fixed;         /**< if 'blockFixed' is > 0 */
  }
                        block;          /**< manager specific options */
};

/**
 * Table of pointers to memory manager functions.
 *
 * Each memory manager usable via this API will come with a set of API
 * compliant wrapper functions, that will be packaged in a 'struct'
 * similar to this one. At program startup copy that into the canonical
 * one called 'MeMemoryAPI' to initialise it.
 */
struct MeMemoryAPI
{
  /**
   * Set memory manager API options.
   *
   * Use this to setup the memory manager API with hints as to what
   * kind of memory manager and policy it should select.
   */
  void                  (*setOptions)(const struct MeMemoryOptions
                                      *const options);
  /**
   * Get memory manager API options.
   *
   * Returns the memory manager options that have been set.
   */
  void                  (*getOptions)(struct MeMemoryOptions
                                      *const options);

  /**
   * Initialize the memory manager.
   *
   * Allows memory manager initialisation. You should first call
   * setOptions to inform the API what kind of memory manager is
   * desirable, and getStats to see what kind of memory arena size the
   * API thinks that requires.
   *
   * Then, if necessary, allocate that size (or something else) and pass
   * it the allocate arena to this function.
   */
  void                  (*init)(void *const arena,const size_t bytes,...);

  /**
   * Allocate a block of at least that given size.
   *
   * If there are any options (form example for placement) then these
   * can be specified after the size, but this will be highly unportable.
   *
   * The in-use count of the newly created block will be one.
   */
  void                  *(*create)(size_t bytes,...);
  /**
   * Change the size of a block, possibly moving it.
   *
   * If there are any options (form example for placement) then these
   * can be specified after the size, but this will be highly
   * unportable.
   *
   * This function may fail as it may be unavailable under some memory
   * managers, or the specific resizing may be impossible or
   * unsupported.  In particular resizing to a smaller size may be
   * forbidden, or resizing to a larger one may not be feasible.
   */
  void                  *(*resize)(void *block,size_t bytes,...);
  /**
   * Increment the in-use count of a block.
   *
   * This function may actually do nothing.
   */
  void                  (*incRef)(const void *const block);
  /**
   * Decrement the in-use count of a block.
   *
   * This function may actually do nothing.
   */
  void                  (*decRef)(const void *const block);
  /**
   * Reduce the in-use count of a block to zero.
   *
   * This function may actually do nothing, for example when the
   * memory manager does automatic reclamation via garbage collection.
   */
  void                  (*destroy)(void *const block,...);

  /**
   * Obtain a copy of the usage statistics of the memory manager API.
   *
   * The statistics returned may be incomplete, depending on how many
   * are supported by the memory manager itself. It can be called after
   * setOptions and before init to
   */
  void                  (*getStats)(struct MeMemoryStats *const stats);
  /**
   * Terminate memory manager API operation.
   *
   * Invoking this will often be needed in order to collect some types
   * of statistics. It also will often check that usage of the API has
   * been correct, e.g. that the number of calls to incRef and to decRef
   * has been the same.
   */
  void                  (*term)();
};

/* The table of memory manager API functions */

extern struct MeMemoryAPI  MeMemoryAPI;

/* Enable or disable tracing and statistics, if compiled in */

extern unsigned         MeMemoryDoTrace;
extern unsigned         MeMemoryDoStats;

#if (__GNUC__)
# define MeMemoryALLOCA(n) __builtin_alloca(n)
# define MeMemoryFREEA(b)  ((void) 0)
#else
#ifdef IRIX
# include <alloca.h>
# define MeMemoryALLOCA(n) alloca(n)
# define MeMemoryFREEA(b)  ((void) 0)
#endif
#endif

#if (_MSC_VER)
# include <malloc.h>
# define MeMemoryALLOCA(n) _alloca(n)
# define MeMemoryFREEA(b)  ((void) 0)
#endif

  
#if (!defined MeMemoryALLOCA)
  /**
   * Stack allocation.
   *
   * If the compiler supports stack allocation (GNU C or MS C)
   * then the relevant compiler intrinsics are used. Otherwise
   * it uses heap allocation, which is why a FREEA function is
   * needed too, and you must use it.
   */
# define MeMemoryALLOCA(n) ((*MeMemoryAPI.create)(n))
  /**
   * Stack deallocation.
   *
   * If the compiler supports stack allocation (GNU C or MS C)
   * then this does nothing. Otherwise heap allocation has been used
   * and this just destroys the heap allocated block.
   */
# define MeMemoryFREEA(b)  ((*MeMemoryAPI.destroy)(b))
#endif


#define MeMemoryQUADALIGNED(n)    assert((((long unsigned) (n)) % 16) == 0)

#define MeMemoryQUADALIGN(a) \
    ((void *) ((((long unsigned) (void *) (a)) + 15) &~ 15))


#ifdef MeMemoryALLOCA
# define MeMemoryQUADALIGNEDALLOCA(name, type, n) \
        void *name##Addr = \
            MeMemoryALLOCA(((n) * sizeof (type)) + 16); \
        type *name = (type *) MeMemoryQUADALIGN(name##Addr);

# define MeMemoryQUADALIGNEDFREEA(name) \
        MeMemoryFREEA(name##Addr)
#endif

/* These functions can be used to print an options or statistics
   record returned from 'getOptions' or 'getStats'. */

void                    MeMemoryPrintOptions(const struct MeMemoryOptions
                          *const options);
void                    MeMemoryPrintStats(const struct MeMemoryStats
                          *const stats);

/* This sets the options to some defaults values. */
void                    MeMemorySetDefaults(struct MeMemoryOptions
                          *const opts);

/**
 * This flag allows testing whether the API is being used
 */
#define MeMemoryAVAILABLE  1

#ifdef __cplusplus
  }
#endif

#endif

---