%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  gmm.tex        LiDIA documentation
%%  
%%  This file contains the documentation of the class gmm
%%  
%%  Copyright (c) 1995 by the LiDIA Group
%%  
%%  Authors: Thomas Papanikolaou
%%  

\begin{lidia_man}
\markright{\BF{gmm}}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
\BF{gmm}    \DOTFILL       general          memory        manager 

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
\BF{gmm}  is  the  memory  management  interface  of  \LiDIA.  It 
provides  standardized  calls  to  the  underlying memory manager
(which  can  be either the system's manager or a user implemented
one).  \BF{gmm}  assumes an uncooperative environment. This means that no
special class support is needed in order to add memory management
to the class.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
\BF{gmm} is implemented as a class providing a small set of
functions for allocation, memory resizing and deallocation. Using
this functions overloads the \TT{new} and \TT{delete} operators.
A user class is registered to \BF{gmm} by simple inheritance, i.e.

\begin{verbatim}
 #include <LiDIA/gmm.h>

 class user_class: public gmm { ...  };
\end{verbatim}

A variable of the class \TT{user\_class} can then be allocated
by simply typing


\begin{verbatim}
    user_class *a = new user_class;
\end{verbatim}

or equivalently


\begin{verbatim}
    user_class *a = new (NoGC) user_class;
\end{verbatim}

The additional argument after the \TT{new} keyword denotes the
method to be used for the allocation of \MATH{a}. In order to support
garbage collecting and non-garbage collecting memory managers
\BF{gmm} provides three modes

\begin{enumerate}
\item \TT{NoGC}\\
allocates an uncollectable item.
\item \TT{AtGC}\\
allocates a collectable atomic item, i.e.
an object containing no pointers in it.
\item \TT{GC}\\
allocates a collectable item.
\end{enumerate}

Now, if \BF{gmm} is implemented by \TT{malloc()}, then these three
modes are equal (allocate always an uncollectable object).
However, if a garbage-collector is used like \cite{boehm},
then these three modes are different.

A note on the philosophy of this approach. Garbage collection
is expensive in execution resources. Although in some examples it
does as well as by-hand collection (i.e. the user is responsible
to free allocated memory, for example be using \TT{delete}). In
general it is 10\% to 20\% slower (most of the time even
worse than that). Therefore, \LiDIA\ functions and classes are
written using by-hand collection (so that there is no memory leak
if a non-collecting manager is used). It is clear that avoiding the
use of automatic collection implies more work. However, we do not
want to lose this factor of more than 10\%.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\BASIC
\fcode{{static void *}}{allocate}{size\_t NMEMB\k size\_t SIZE}
{
allocates memory for an array of \MATH{NMEMB} 
elements of \MATH{SIZE} bytes each and returns a pointer to the allocated
memory. The memory is set to zero.
For \TT{allocate(NMEMB, SIZE)}, the value returned is a pointer to 
the allocated memory, which is suitably aligned for any kind
of variable or NULL if the request fails.}


\fcode{{static void *}}{allocate}{size\_t SIZE}
{
allocates \MATH{SIZE} bytes and returns a pointer to
the allocated memory. The memory ist not cleared.
For \TT{allocate(SIZE)}, the value returned is a pointer to the
allocated memory, which is suitably aligned for any kind
of variable or NULL if the request fails.}



\fcode{{static void *}}{allocate\_uncollectable}{size\_t SIZE}
{
allocates \MATH{SIZE} bytes and returns
a pointer to the allocated memory. The memory ist not cleared and 
will not be collected by the implemented memory manager.
For \TT{allocate\_uncollectable(SIZE)}, the value returned is a
pointer to the allocated memory, which is suitably aligned for 
any kind of variable or NULL if the request fails.}



\fcode{{static void *}}{allocate\_atomic}{size\_t SIZE}
{
allocates \MATH{SIZE} bytes and returns a
pointer to the allocated memory. \TT{allocate\_atomic(SIZE)}
assumes that there are no relevant pointers in the object.
The memory ist not cleared.
For \TT{allocate\_atomic(SIZE)}, the value returned is a pointer to
the allocated memory, which is suitably aligned for any
kind of variable or NULL if the request fails.}


\fcode{{static void *}}{resize}{void *PTR\k size\_t NSIZE\k size\_t OSIZE}
{
changes the size of the memory block 
pointed to by \MATH{PTR} to \MATH{NSIZE} bytes. The contents will be unchanged to
the minimum of the \MATH{OSIZE} and \MATH{NSIZE} sizes. Newly allocated
memory will be uninitialized. If \MATH{PTR} is NULL, the call is
equivalent to \TT{allocate(SIZE)}. If \MATH{NSIZE} is equal to zero,
the call is equivalent to \TT{release(PTR)}. Unless \MATH{PTR} is
NULL, it must have been returned by an earlier call of
\TT{allocate(SIZE)} or \TT{resize(PTR,NSIZE,OSIZE)}.
\TT{resize(PTR,NSIZE,OSIZE)} returns a pointer to the newly allocated 
memory, which is suitably aligned for any kind of variable and may
be different from \MATH{PTR} or NULL if the request fails or if
\MATH{NSIZE} was equal to 0.}



\fcode{{static void}}{release}{void *PTR}
{
frees the memory space pointed to by \MATH{PTR}, which
must have been returned by a previous call of \TT{allocate(SIZE)}.
If \MATH{PTR} is NULL, no operation is performed.}



\fcode{{static void}}{collect}{}
{
initiates a garbage collection if the
implemented memory manager supports garbage collection.}



\fcode{{void *}}{operator new}{size\_t SIZE}
{
operator new overloading. Calls \TT{allocate(SIZE)}.}



\fcode{{void *}}{operator new}{size\_t SIZE\k memory\_manager\_mode MODE}
{
operator new overloading with a predefined MODE. Mode can be one of \TT{NoGC}
(the default), \TT{AtGC} or \TT{GC}.}



\fcode{{void *}}{operator delete}{void *PTR}
{
operator delete overloading. Class \TT{release(PTR)}.}

If the compiler allows the overloading of the \TT{new} and \TT{delete} operators for
arrays, the following functions are also available:



\fcode{{void *}}{operator new[]}{size\_t SIZE}{}
\fcode{{void *}}{operator new[]}{size\_t SIZE\k memory\_manager\_mode MODE}{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
UNIX manual page malloc.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Thomas Papanikolaou

\end{lidia_man}
