%-*-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
%
% nxa portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

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

The \classname{nxa} class implements garbage collection.  The garbage collector
runs a separate thread that is controlled via an asynchronous message queue.

\subsubsection{API}
\begin{capi}
\label{nxa_malloc_e}
\index{nxa_malloc_e@\cfunc{nxa\_malloc\_e}{}}
\citem{\cfunc[void *]{nxa\_malloc\_e}{void *a\_arg, size\_t a\_size, const
char *a\_filename, uint32\_t a\_line\_num}}
\label{nxa_malloc}
\index{nxa_malloc@\cfunc{nxa\_malloc}{}}
\citem{\cfunc[void *]{nxa\_malloc}{size\_t a\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_arg: ]
			Unused.
		\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{nxa_calloc_e}
\index{nxa_calloc_e@\cfunc{nxa\_calloc\_e}{}}
\citem{\cfunc[void *]{nxa\_calloc\_e}{void *a\_arg, size\_t a\_number,
size\_t a\_size, const char *a\_filename, uint32\_t a\_line\_num}}
\label{nxa_calloc}
\index{nxa_calloc@\cfunc{nxa\_calloc}{}}
\citem{\cfunc[void *]{nxa\_calloc}{size\_t a\_number, size\_t a\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_arg: ]
			Unused.
		\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{nxa_realloc_e}
\index{nxa_realloc_e@\cfunc{nxa\_realloc\_e}{}}
\citem{\cfunc[void *]{nxa\_realloc\_e}{void *a\_arg, void *a\_ptr, size\_t
a\_size, size\_t a\_old\_size, const char *a\_filename, uint32\_t
a\_line\_num}}
\label{nxa_realloc}
\index{nxa_realloc@\cfunc{nxa\_realloc}{}}
\citem{\cfunc[void *]{nxa\_realloc}{void *a\_ptr, size\_t a\_size, size\_t
a\_old\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_arg: ]
			Unused.
		\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{nxa_free_e}
\index{nxa_free_e@\cfunc{nxa\_free\_e}{}}
\citem{\cfunc[void *]{nxa\_free\_e}{void *a\_arg, void *a\_ptr, size\_t a\_size,
const char *a\_filename, uint32\_t a\_line\_num}}
\label{nxa_free}
\index{nxa_free@\cfunc{nxa\_free}{}}
\citem{\cfunc[void *]{nxa\_free}{void *a\_ptr, size\_t a\_size}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_arg: ]
			Unused.
		\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}
\label{nxa_collect}
\index{nxa_collect@\cfunc{nxa\_collect}{}}
\citem{\cfunc[void]{nxa\_collect}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Force an asynchronous garbage collection.
	\end{capilist}
\label{nxa_active_get}
\index{nxa_active_get@\cfunc{nxa\_active\_get}{}}
\citem{\cfunc[bool]{nxa\_active\_get}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ]
				Garbage collector deactivated.
			\item[true: ]
				Garbage collector active.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return whether the garbage collector is active (runnable).
	\end{capilist}
\label{nxa_active_set}
\index{nxa_active_set@\cfunc{nxa\_active\_set}{}}
\citem{\cfunc[void]{nxa\_active\_set}{bool a\_active}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_active: ]
			\begin{description}\item[]
			\item[false: ]
				Deactivate garbage collector.
			\item[true: ]
				Activate garbage collector.
			\end{description}
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Send a message to the garbage collector to activate or
		deactivate.  The asynchronous nature of the message means that
		it is possible for the garbage collector to run after this
		function returns, even if a deactivation message has been sent.
	\end{capilist}
\label{nxa_period_get}
\index{nxa_period_get@\cfunc{nxa\_period\_get}{}}
\citem{\cfunc[cw\_nxoi\_t]{nxa\_period\_get}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Current inactivity period in seconds that the garbage
			collector waits before doing a collection.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the current inactivity period in seconds that the garbage
		collector waits before doing a collection.
	\end{capilist}
\label{nxa_period_set}
\index{nxa_period_set@\cfunc{nxa\_period\_set}{}}
\citem{\cfunc[void]{nxa\_period\_set}{cw\_nxoi\_t a\_period}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_period: ]
			Inactivity period in seconds that the garbage collector
			should wait before doing a collection.  If 0, the
			garbage collector will never run due to inactivity.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Set the inactivity period in seconds that the garbage collector
		should wait before doing a collection.
	\end{capilist}
\label{nxa_threshold_get}
\index{nxa_threshold_get@\cfunc{nxa\_threshold\_get}{}}
\citem{\cfunc[cw\_nxoi\_t]{nxa\_threshold\_get}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Number of bytes of memory allocated since the last
			garbage collection that will trigger the garbage
			collector to run.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the number of bytes of memory allocated since the last
		garbage collection that will trigger the garbage collector to
		run.
	\end{capilist}
\label{nxa_threshold_set}
\index{nxa_threshold_set@\cfunc{nxa\_threshold\_set}{}}
\citem{\cfunc[void]{nxa\_threshold\_set}{cw\_nxoi\_t a\_threshold}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_threshold: ]
			The number of bytes of memory allocated since the last
			garbage collection that will trigger the garbage
			collector to run.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Set the number of bytes of memory allocated since the last
		garbage collection that will trigger the garbage collector to
		run.
	\end{capilist}
\label{nxa_stats_get}
\index{nxa_stats_get@\cfunc{nxa\_stats\_get}{}}
\citem{\cfunc[void]{nxa\_stats\_get}{cw\_nxoi\_t *r\_collections, cw\_nxoi\_t
*r\_count, cw\_nxoi\_t *r\_ccount, cw\_nxoi\_t *r\_cmark, cw\_nxoi\_t
*r\_mcount, cw\_nxoi\_t *r\_mmark, cw\_nxoi\_t *r\_scount, cw\_nxoi\_t
*r\_smark}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[r\_collections: ]
			Pointer to an integer.
		\item[r\_count: ]
			Pointer to an integer.
		\item[r\_ccount: ]
			Pointer to an integer.
		\item[r\_cmark: ]
			Pointer to an integer.
		\item[r\_mcount: ]
			Pointer to an integer.
		\item[r\_mmark: ]
			Pointer to an integer.
		\item[r\_scount: ]
			Pointer to an integer.
		\item[r\_smark: ]
			Pointer to an integer.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[*r\_collections: ]
			Number of times the garbage collector has run.
		\item[*r\_count: ]
			Current number of bytes of memory allocated.
		\item[*r\_ccount: ]
			Number of bytes of memory allocated as of the end of the
			most recent garbage collection.
		\item[*r\_cmark: ]
			Number of microseconds spent in the mark phase of the
			most recent garbage collection.
		\item[*r\_mcount: ]
			Largest number of bytes of memory ever allocated at any
			point in time.
		\item[*r\_mmark: ]
			Largest number of microseconds ever spent in the mark
			phase of a garbage collection.
		\item[*r\_scount: ]
			Total number of bytes of memory ever allocated.
		\item[*r\_smark: ]
			Total number of microseconds spent in the mark phase of
			all garbage collections.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return garbage collector statistics.
	\end{capilist}
\end{capi}
