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

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

The \classname{nx} class encapsulates an Onyx interpreter instance.  It contains
a number of interpreter-global objects.  The garbage collector is shared among
all \classname{nx} instances, so when an \classname{nx} is destroyed, only the
objects which no other \classname{nx} references are destroyed.

\subsubsection{API}
\begin{capi}
\label{cw_thread_start_t}
\index{cw_thread_start_t@\cfunc{cw\_thread\_start\_t}{}}
\citem{\cfunc[void]{cw\_thread\_start\_t}{cw\_nxo\_t *a\_thread, cw\_op\_t
*a\_start}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_thread: ]
			Pointer to a thread \classname{nxo}.
		\item[a\_start: ]
			Pointer to a start function.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] Application dependent.
	\item[Description: ]
		Type definition for a callback function that is called by
		\cfunc{nxo\_thread\_start}{}.  This function must call
		\cvar{a\_start}, which is the actual start function.

		The main use for a start callback function is to create a top
		level \classname{xep} exception handling context for each
		thread.
	\end{capilist}
\label{nx_new}
\index{nx_new@\cfunc{nx\_new}{}}
\citem{\cfunc[cw\_nx\_t *]{nx\_new}{cw\_nx\_t *a\_nx, cw\_op\_t
*a\_thread\_init, cw\_thread\_start\_t *a\_thread\_start}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to space for an \classname{nx}, or NULL.
		\item[a\_thread\_init: ]
			Pointer to an initialization function to be called
			during thread initialization, or NULL.
		\item[a\_thread\_start: ]
			Pointer to a thread start callback function to be called
			by \cfunc{nxo\_thread\_start}{}, or NULL.  See the
			\ctype{cw\_thread\_start\_t} documentation for details.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[\htmlref{CW\_ONYXX\_OOM}{CW_ONYXX_OOM}.]
		\end{description}
	\item[Description: ]
		Constructor.
	\end{capilist}
\label{nx_delete}
\index{nx_delete@\cfunc{nx\_delete}{}}
\citem{\cfunc[void]{nx\_delete}{cw\_nx\_t *a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Destructor.
	\end{capilist}
\label{nx_maxestack_get}
\index{nx_maxestack_get@\cfunc{nx\_maxestack\_get}{}}
\citem{\cfunc[cw\_nxoi\_t]{nx\_\htmlref{maxestack}{systemdict:gmaxestack}\_get}{cw\_nx\_t
*a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Default maximum estack depth.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the default maximum allowable estack depth.  This value
		is used when creating new threads.
	\end{capilist}
\label{nx_maxestack_set}
\index{nx_maxestack_set@\cfunc{nx\_maxestack\_set}{}}
\citem{\cfunc[void]{nx\_\htmlref{maxestack}{systemdict:setgmaxestack}\_set}{cw\_nx\_t
*a\_nx, cw\_nxoi\_t a\_maxestack}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\item[a\_maxestack: ]
			Default maximum estack depth.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Set \cvar{a\_nx}'s default maximum allowable estack depth to
		\cvar{a\_maxestack}.
	\end{capilist}
\label{nx_tailopt_get}
\index{nx_tailopt_get@\cfunc{nx\_tailopt\_get}{}}
\citem{\cfunc[bool]{nx\_\htmlref{tailopt}{systemdict:gtailopt}\_get}{cw\_nx\_t
*a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Default tail optimization setting.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the default tail optimization setting.  This value is
		used when creating new threads.
	\end{capilist}
\label{nx_tailopt_set}
\index{nx_tailopt_set@\cfunc{nx\_tailopt\_set}{}}
\citem{\cfunc[void]{nx\_\htmlref{tailopt}{systemdict:setgtailopt}\_set}{cw\_nx\_t
*a\_nx, bool a\_tailopt}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\item[a\_tailopt: ]
			Default tail optimization setting.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Set \cvar{a\_nx}'s default tail optimization setting to
		\cvar{a\_tailopt}.
	\end{capilist}
\label{nx_systemdict_get}
\index{nx_systemdict_get@\cfunc{nx\_systemdict\_get}{}}
\citem{\cfunc[cw\_nxo\_t
*]{nx\_\htmlref{systemdict}{sec:systemdict}\_get}{cw\_nx\_t *a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the \classname{nxo} corresponding to
			\onyxop{systemdict}{}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the \classname{nxo} corresponding to
		\onyxop{systemdict}{}.
	\end{capilist}
\label{nx_globaldict_get}
\index{nx_globaldict_get@\cfunc{nx\_globaldict\_get}{}}
\citem{\cfunc[cw\_nxo\_t
*]{nx\_\htmlref{globaldict}{sec:globaldict}\_get}{cw\_nx\_t *a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the \classname{nxo} corresponding to
			\onyxop{globaldict}{}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the \classname{nxo} corresponding to
		\onyxop{globaldict}{}.
	\end{capilist}
\label{nx_stdin_get}
\index{nx_stdin_get@\cfunc{nx\_stdin\_get}{}}
\citem{\cfunc[cw\_nxo\_t
*]{nx\_\htmlref{stdin}{systemdict:gstdin}\_get}{cw\_nx\_t *a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the \classname{nxo} corresponding to
			\onyxop{stdin}{}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the \classname{nxo} corresponding to
		\onyxop{stdin}{}.
	\end{capilist}
\label{nx_stdin_set}
\index{nx_stdin_set@\cfunc{nx\_stdin\_set}{}}
\citem{\cfunc[void]{nx\_\htmlref{stdin}{systemdict:setgstdin}\_set}{cw\_nx\_t
*a\_nx, cw\_nxo\_t *a\_stdin}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\item[a\_stdin: ]
			Pointer to a file \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Set \cvar{a\_nx}'s stdin to \cvar{a\_stdin}.
	\end{capilist}
\label{nx_stdout_get}
\index{nx_stdout_get@\cfunc{nx\_stdout\_get}{}}
\citem{\cfunc[cw\_nxo\_t
*]{nx\_\htmlref{stdout}{systemdict:gstdout}\_get}{cw\_nx\_t *a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the \classname{nxo} corresponding to
			\onyxop{stdout}{}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the \classname{nxo} corresponding to
		\onyxop{stdout}{}.
	\end{capilist}
\label{nx_stdout_set}
\index{nx_stdout_set@\cfunc{nx\_stdout\_set}{}}
\citem{\cfunc[void]{nx\_\htmlref{stdout}{systemdict:setgstdout}\_set}{cw\_nx\_t
*a\_nx, cw\_nxo\_t *a\_stdout}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\item[a\_stdout: ]
			Pointer to a file \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Set \cvar{a\_nx}'s stdout to \cvar{a\_stdout}.
	\end{capilist}
\label{nx_stderr_get}
\index{nx_stderr_get@\cfunc{nx\_stderr\_get}{}}
\citem{\cfunc[cw\_nxo\_t
*]{nx\_\htmlref{stderr}{systemdict:gstderr}\_get}{cw\_nx\_t *a\_nx}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\end{description}
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Pointer to the \classname{nxo} corresponding to
			\onyxop{stderr}{}.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return a pointer to the \classname{nxo} corresponding to
		\onyxop{stderr}{}.
	\end{capilist}
\label{nx_stderr_set}
\index{nx_stderr_set@\cfunc{nx\_stderr\_set}{}}
\citem{\cfunc[void]{nx\_\htmlref{stderr}{systemdict:setgstderr}\_set}{cw\_nx\_t
*a\_nx, cw\_nxo\_t *a\_stderr}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_nx: ]
			Pointer to an \classname{nx}.
		\item[a\_stderr: ]
			Pointer to a file \classname{nxo}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Set \cvar{a\_nx}'s stderr to \cvar{a\_stderr}.
	\end{capilist}
\end{capi}
