%-*-mode:latex-*-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (C) 1996-2004 Jason Evans <jasone@canonware.com>.
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions
% are met:
% 1. Redistributions of source code must retain the above copyright
%    notice(s), this list of conditions and the following disclaimer
%    unmodified other than the allowable addition of one or more
%    copyright notices.
% 2. Redistributions in binary form must reproduce the above copyright
%    notice(s), this list of conditions and the following disclaimer in
%    the documentation and/or other materials provided with the
%    distribution.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
% EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
% PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
% BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
% WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
% OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
% EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Version: Onyx 5.1.1
%
% mem portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{mem}
\label{mem}
\index{mem@\classname{mem}{}}

The \classname{mem} class implements a memory allocation (malloc) wrapper.  For
the debug version of \libname{libonyx}, extra information is hashed for each
memory allocation that allows tracking of the following:

\begin{itemize}
\item{File/line number of allocation.}
\item{Double allocation/deallocation of the same address.}
\item{Memory leaks (memory left allocated at mem destruction time).}
\end{itemize}

If any memory leaks are detected, diagnostic output is printed to
\cvar{stderr}.

Also, the debug version of \libname{libonyx} sets all newly allocated bytes to
{\tt 0xa5}, and all deallocated bytes to {\tt 0x5a} (except in the case of
\cfunc{mem\_calloc}{}).  This tends to cause things to break sooner when
uninitialized or deallocated memory is referenced.

In general, the \classname{mem} class doesn't need to be used directly.
Instead, there are several preprocessor macros that can be used:
\cppmacro{cw\_malloc}{}, \cppmacro{cw\_calloc}{},
\cppmacro{cw\_realloc}{}, and \cppmacro{cw\_free}{}.

\label{mema}
The \classname{mema} class encapsulates a set of pointers to allocation
functions.  It is used by the \htmlref{\classname{ch}}{ch} and
\htmlref{\classname{dch}}{dch} classes.

\subsubsection{API}
\begin{capi}
\label{mema_new}
\index{mema_new@\cfunc{mema\_new}{}}
\citem{\cfunc[cw\_mema\_t *]{mema\_new}{cw\_mema\_t *a\_mema,
cw\_opaque\_alloc\_t *a\_alloc, cw\_opaque\_calloc\_t *a\_calloc,
cw\_opaque\_realloc\_t *a\_realloc, cw\_opaque\_dealloc\_t *a\_dealloc, void
*a\_arg}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mema: ]
			Pointer to space for a \classname{mema}, or NULL.
		\item[a\_alloc: ]
			Pointer to an allocation function.
		\item[a\_alloc: ]
			Pointer to a zero-ing allocation function.
		\item[a\_alloc: ]
			Pointer to a reallocation function.
		\item[a\_dealloc: ]
			Pointer to a deallocation function.
		\item[a\_arg: ]
			Opaque pointer to pass to \cfunc{a\_alloc}{},
			\cfunc{a\_calloc}{}, \cfunc{a\_realloc}{}, and
			\cfunc{a\_dealloc}{}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a \classname{mema}.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Constructor.
	\end{capilist}
\label{mema_delete}
\index{mema_delete@\cfunc{mema\_delete}{}}
\citem{\cfunc[void]{mema\_delete}{cw\_mema\_t *a\_mema}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mema: ]
			Pointer to a \classname{mema}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Destructor.
	\end{capilist}
\label{mema_alloc_get}
\index{mema_alloc_get@\cfunc{mema\_alloc\_get}{}}
\citem{\cfunc[cw\_opaque\_alloc\_t *]{mema\_alloc\_get}{cw\_mema\_t *a\_mema}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mema: ]
			Pointer to a \classname{mema}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to an allocation function.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to an allocation function.
	\end{capilist}
\label{mema_calloc_get}
\index{mema_calloc_get@\cfunc{mema\_calloc\_get}{}}
\citem{\cfunc[cw\_opaque\_calloc\_t *]{mema\_calloc\_get}{cw\_mema\_t *a\_mema}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mema: ]
			Pointer to a \classname{mema}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a zero-ing allocation function.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to a zero-ing allocation function.
	\end{capilist}
\label{mema_realloc_get}
\index{mema_realloc_get@\cfunc{mema\_realloc\_get}{}}
\citem{\cfunc[cw\_opaque\_realloc\_t *]{mema\_realloc\_get}{cw\_mema\_t
*a\_mema}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mema: ]
			Pointer to a \classname{mema}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a reallocation function.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to a reallocation function.
	\end{capilist}
\label{mema_dealloc_get}
\index{mema_dealloc_get@\cfunc{mema\_dealloc\_get}{}}
\citem{\cfunc[cw\_opaque\_dealloc\_t *]{mema\_dealloc\_get}{cw\_mema\_t
*a\_mema}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mema: ]
			Pointer to a \classname{mema}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a deallocation function.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to a deallocation function.
	\end{capilist}
\label{mema_arg_get}
\index{mema_arg_get@\cfunc{mema\_arg\_get}{}}
\citem{\cfunc[cw\_opaque\_arg\_t *]{mema\_arg\_get}{cw\_mema\_t *a\_mema}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mema: ]
			Pointer to a \classname{mema}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Opaque pointer to pass to \cfunc{a\_alloc}{},
			\cfunc{a\_calloc}{}, \cfunc{a\_realloc}{}, and
			\cfunc{a\_dealloc}{}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return an opaque pointer to pass to the allocation functions
		returned by \cfunc{mema\_alloc\_get}{\cvar{a\_mema}},
		\cfunc{mema\_calloc\_get}{\cvar{a\_mema}},
		\cfunc{mema\_realloc\_get}{\cvar{a\_mema}}, and
		\cfunc{mema\_dealloc\_get}{\cvar{a\_mema}}.
	\end{capilist}
\label{mem_malloc_e}
\index{mem_malloc_e@\cfunc{mem\_malloc\_e}{}}
\citem{\cfunc[void *]{mem\_malloc\_e}{cw\_mem\_t *a\_mem, size\_t a\_size, const
char *a\_filename, uint32\_t a\_line\_num}}
\label{mem_malloc}
\index{mem_malloc@\cfunc{mem\_malloc}{}}
\citem{\cfunc[void *]{mem\_malloc}{cw\_mem\_t *a\_mem, size\_t a\_size}}
\label{cw_malloc}
\index{cw_malloc@\cppmacro{cw\_malloc}{}}
\citem{\cppmacro[void *]{cw\_malloc}{size\_t a\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mem: ]
			Pointer to a \classname{mem}, or NULL.
		\item[a\_size: ]
			Size of memory range to allocate.
		\item[a\_filename: ]
			Should be \_\_FILE\_\_.
		\item[a\_line\_num: ]
			Should be \_\_LINE\_\_.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a memory range.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		\cfunc{malloc}{} wrapper.
	\end{capilist}
\label{mem_calloc_e}
\index{mem_calloc_e@\cfunc{mem\_calloc\_e}{}}
\citem{\cfunc[void *]{mem\_calloc\_e}{cw\_mem\_t *a\_mem, size\_t a\_number,
size\_t a\_size, const char *a\_filename, uint32\_t a\_line\_num}}
\label{mem_calloc}
\index{mem_calloc@\cfunc{mem\_calloc}{}}
\citem{\cfunc[void *]{mem\_calloc}{cw\_mem\_t *a\_mem, size\_t a\_number,
size\_t a\_size}}
\label{cw_calloc}
\index{cw_calloc@\cppmacro{cw\_calloc}{}}
\citem{\cppmacro[void *]{cw\_calloc}{size\_t a\_number, size\_t a\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mem: ]
			Pointer to a \classname{mem}, or NULL.
		\item[a\_number: ]
			Number of elements to allocate.
		\item[a\_size: ]
			Size of each element to allocate.
		\item[a\_filename: ]
			Should be \_\_FILE\_\_.
		\item[a\_line\_num: ]
			Should be \_\_LINE\_\_.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a zeroed memory range.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		\cfunc{calloc}{} wrapper.
	\end{capilist}
\label{mem_realloc_e}
\index{mem_realloc_e@\cfunc{mem\_realloc\_e}{}}
\citem{\cfunc[void *]{mem\_realloc\_e}{cw\_mem\_t *a\_mem, void *a\_ptr, size\_t
a\_size, size\_t a\_old\_size, const char *a\_filename, uint32\_t
a\_line\_num}}
\label{mem_realloc}
\index{mem_realloc@\cfunc{mem\_realloc}{}}
\citem{\cfunc[void *]{mem\_realloc}{cw\_mem\_t *a\_mem, void *a\_ptr, size\_t
a\_size}}
\label{cw_realloc}
\index{cw_realloc@\cppmacro{cw\_realloc}{}}
\citem{\cppmacro[void *]{cw\_realloc}{void *a\_ptr, size\_t a\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mem: ]
			Pointer to a \classname{mem}, or NULL.
		\item[a\_ptr: ]
			Pointer to memory range to be reallocated.
		\item[a\_size: ]
			Size of memory range to allocate.
		\item[a\_old\_size: ]
			Size of memory range previously pointed to by
			\cvar{a\_ptr}.
		\item[a\_filename: ]
			Should be \_\_FILE\_\_.
		\item[a\_line\_num: ]
			Should be \_\_LINE\_\_.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to a memory range.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		\cfunc{realloc}{} wrapper.
	\end{capilist}
\label{mem_free_e}
\index{mem_free_e@\cfunc{mem\_free\_e}{}}
\citem{\cfunc[void]{mem\_free\_e}{cw\_mem\_t *a\_mem, void *a\_ptr, size\_t
a\_size, const char *a\_filename, uint32\_t a\_line\_num}}
\label{mem_free}
\index{mem_free@\cfunc{mem\_free}{}}
\citem{\cfunc[void]{mem\_free}{cw\_mem\_t *a\_mem, void *a\_ptr, size\_t
a\_size}}
\label{cw_free}
\index{cw_free@\cppmacro{cw\_free}{}}
\citem{\cppmacro[void]{cw\_free}{void *a\_ptr}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_mem: ]
			Pointer to a \classname{mem}, or NULL.
		\item[a\_ptr: ]
			Pointer to to memory range to be freed.
		\item[a\_size: ]
			Sizef of memory range pointed to by \cvar{a\_ptr}.
		\item[a\_filename: ]
			Should be \_\_FILE\_\_.
		\item[a\_line\_num: ]
			Should be \_\_LINE\_\_.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		\cfunc{free}{} wrapper.
	\end{capilist}
\end{capi}
