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

\subsection{nxo\_instance}
\label{nxo_instance}
\index{nxo_instance@\classname{nxo\_instance}{}}

The \classname{nxo\_instance} class is a subclass of the \classname{nxo}
class.

\subsubsection{API}
\begin{capi}
\label{cw_nxo_instance_ref_iter_t}
\index{cw_nxo_instance_ref_iter_t@\cfunc{cw\_nxo\_instance\_ref\_iter\_t}{}}
\citem{\cfunc[cw\_nxoe\_t *]{cw\_nxo\_instance\_ref\_iter\_t}{void *a\_opaque,
bool a\_reset}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_opaque: ]
			Opaque data pointer.
		\item[a\_reset: ]
			\begin{description}\item[]
			\item[false: ]
				At least one iteration has already occurred.
			\item[true: ]
				First iteration.
			\end{description}
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[non-NULL: ]
				Pointer to an \classname{nxoe}.
			\item[NULL: ]
				No more references.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Reference iterator function typedef.
	\end{capilist}
\label{cw_nxo_instance_delete_t}
\index{cw_nxo_instance_delete_t@\cfunc{cw\_nxo\_instance\_delete\_t}{}}
\citem{\cfunc[bool]{cw\_nxo\_instance\_delete\_t}{void *a\_opaque,
uint32\_t a\_iter}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_opaque: ]
			Opaque data pointer.
		\item[a\_iter: ]
			Garbage collector sweep iteration count (starts at 0).
			This value can be used to impose ordering of dependent
			object deletions.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			\begin{description}\item[]
			\item[false: ] Success.
			\item[true: ] Defer deletion until a later garbage
			collector sweep iteration.
			\end{description}
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Destructor function typedef.
	\end{capilist}
\label{nxo_instance_new}
\index{nxo_instance_new@\cfunc{nxo\_instance\_new}{}}
\citem{\cfunc[void]{nxo\_instance\_new}{cw\_nxo\_t *a\_nxo, void *a\_opaque,
cw\_nxo\_instance\_ref\_iter\_t *a\_ref\_iter\_f, cw\_nxo\_instance\_delete\_t
*a\_delete\_f}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to an instance \classname{nxo}.
		\item[a\_opaque: ]
			Opaque data pointer to be passed to \cvar{a\_eval\_f},
			\cvar{a\_ref\_iter\_f}, and \cvar{a\_delete\_f}.
		\item[a\_ref\_iter\_f: ]
			Pointer to a reference iterator function.
		\item[a\_delete\_f: ]
			Pointer to a destructor function.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Constructor.
	\end{capilist}
\label{nxo_instance_isa_get}
\index{nxo_instance_isa_get@\cfunc{nxo\_instance\_isa\_get}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_instance\_isa\_get}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to an instance \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the isa object associated with \cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the isa object associated with
		\cvar{a\_nxo}.  This object pointer can safely be used for
		modifying the isa object.
	\end{capilist}
\label{nxo_instance_data_get}
\index{nxo_instance_data_get@\cfunc{nxo\_instance\_data\_get}{}}
\citem{\cfunc[cw\_nxo\_t *]{nxo\_instance\_data\_get}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to an instance \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the data object associated with
			\cvar{a\_nxo}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the data object associated with
		\cvar{a\_nxo}.  This object pointer can safely be used for
		modifying the data object.
	\end{capilist}
\label{nxo_instance_opaque_get}
\index{nxo_instance_opaque_get@\cfunc{nxo\_instance\_opaque\_get}{}}
\citem{\cfunc[void *]{nxo\_instance\_opaque\_get}{const cw\_nxo\_t *a\_nxo}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to an instance \classname{nxo}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Opaque data pointer.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the opaque data pointer associated with \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_instance_opaque_set}
\index{nxo_instance_opaque_set@\cfunc{nxo\_instance\_opaque\_set}{}}
\citem{\cfunc[void]{nxo\_instance\_opaque\_set}{cw\_nxo\_t *a\_nxo, void
*a\_opaque}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to an instance \classname{nxo}.
		\item[a\_opaque: ]
			Opaque data pointer.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Set the opaque data pointer associated with \cvar{a\_nxo}.
	\end{capilist}
\label{nxo_instance_eval}
\index{nxo_instance_eval@\cfunc{nxo\_instance\_eval}{}}
\citem{\cfunc[void]{nxo\_instance\_eval}{cw\_nxo\_t *a\_nxo, cw\_nxo\_t
*a\_thread}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nxo: ]
			Pointer to an instance \classname{nxo}.
		\item[a\_thread: ]
			Pointer to a thread \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] Instance-specific.
	\item[Description: ]
		Evaluate the \cvar{a\_nxo}.  If there is no evaluation function
		associated with \cvar{a\_nxo}, it is pushed onto ostack.
	\end{capilist}
\end{capi}
