% $OpenXM: OpenXM/doc/issac2000/session-management.tex,v 1.6 2000/01/15 00:20:46 takayama Exp $

\section{Session Management}
\label{secsession}
%MEMO: key words:
%Security (ssh PAM), initial negotiation of byte order,
%mathcap, interruption, debugging window, etc.
 
In this section we show the realization of control integration in
OpenXM.  In OpenXM it is assumed that various clients and servers
establish connections dynamically and communicate to each
other. Therefore it is necessary to unify the communication interface
and the method of communication establishment.  Besides, interruption
of an execution and debugging are common operations when we use
programming systems. OpenXM provides a method to realize them for
distributed computation.

\subsection{Interface of servers}

A server has additional I/O streams for exchanging data between
a client and itself other than ones for diagnostic
messages. As the streams are for binary data,
the byte order conversion is necessary when a
client and a server have different byte orders. It is determined by
exchanging the preferable byte order of each peer. If the preference
does not coincides with each other,
then the network byte order is used.
This implies that all servers and clients should be able to
handle the network byte
order. Nevertheless it is necessary to negotiate the byte order to
skip the byte order conversion because its cost is often dominant over
fast networks.

\subsection{Invocation of servers}
\label{launcher}

In general it is complicated to establish a connection over TCP/IP.
On the other hand a server itself does not have any function to
make a connection. In order to fill this gap an application called
{\bf launcher} is provided. A connection is established by using
the launcher as follows.

\begin{enumerate}
\item A launcher is invoked from a client or by hand.
When the launcher is invoked, a port number for TCP/IP connection
and the name of a server should be informed.
\item The launcher and the client establish a connection with the
specified port number.
\item The launcher create a process and execute the server after
setting the binary I/O channels appropriately.
\end{enumerate}

Though the above is all the task as a launcher, the launcher process
acts as a control server and controls the server process created by
itself. As for a control server see Section \ref{control}.

\subsection{Control server}
\label{control}
When we use a mathematical software, an execution time or necessary
storage is often unknown in advance. Therefore it is desirable
to be able to abort an execution and to start another execution.
On OpenXM we adopted the following simple and robust method.

An OpenXM server has logically two I/O channels: one for exchanging
data for computations and the other for controlling computations. The
control channel is used to send commands to control execution on the
server. The launcher introduced in Section \ref{launcher}
is used as a control process. We call such a process a {\bf
control server}. In contrast, we call a server for computation an {\bf
engine}. In this case the control server and the engine runs on the
same machine and it is easy to manipulate the engine, especially to
send a signal from the control server. A control server is also an
OpenXM stackmachine and it accepts {\tt SM\_control\_*} commands
to send signals to a server or to terminate a server.

\subsection{Resetting a connection}

By using the control channel a client can send a signal to an engine
at any time. However, I/O operations are usually buffered and several
additional operations on buffers after sending a signal is necessary
to reset connections safely. Here a safe resetting means the
following:

\begin{enumerate}
\item A sending of an {\tt OX} message must be completed.

As an {\tt OX} message is sent as a combination of several {\tt CMO}
data, a global exit without sending all the data confuses the
subsequent communication.

\item After restarting a server, a request from a client 
must correctly corresponds to the response from the server.

An incorrect correspondence occurs if some data remain on the stream
after restarting a server.
\end{enumerate}

{\tt SM\_control\_reset\_connection} is an {\tt SM} command to
initiate a safe resetting of a connection. We show the action of 
a server and a client from the initiation to the completion of
a resetting.

\centerline{\fbox{client}}

\begin{enumerate}
\item The client sends {\tt SM\_control\_reset\_connection} to the
control server.
\item The client enters the resetting state. it skips all {\tt
OX} messages from the engine until it receives {\tt OX\_SYNC\_BALL}.
\item After receiving {\tt OX\_SYNC\_BALL} the client sends 
{\tt OX\_SYNC\_BALL} to the engine and returns to the usual state.
\end{enumerate}

\centerline{\fbox{engine}}

\begin{enumerate}
\item After receiving {\tt SIGUSR1} from the control server,
the engine enters the resetting state.
\item If an {\tt OX} message is being sent or received, then
the engine completes it. This does not block because
the client reads and skips {\tt OX} messages soon after sending
{\tt SM\_control\_reset\_connection}.
\item The engine sends {\tt OX\_SYNC\_BALL} to the client.
\item The engine skips all {\tt OX} messages from the engine until it
receives {\tt OX\_SYNC\_BALL}.
\item After receiving {\tt OX\_SYNC\_BALL} the engine returns to the
usual state.
\end{enumerate}

{\tt OX\_SYNC\_BALL} means an end mark of the data remaining in the
I/O streams. After reading it it is assured that the stream is empty
and that a request from a client correctly corresponds to the response
from the server. We note that we don't have to associate 
{\tt OX\_SYNC\_BALL} with
any special action to be executed by the server because it is
assured that the peer is in the resetting state when one receives
{\tt OX\_SYNC\_BALL}.

\subsection{Debugging supports}
To help debugging on the server, various supports are possible. If
servers are executed on X window system, then the control server can
attach an {\tt xterm} to the standard outputs of the engine to display
diagnostic messages from the engine.
Furthermore, if the engine provides an interface to input commands,
then debugging of user defined programs will be
possible. For example {\tt ox\_asir}, which is
the OpenXM server of {\tt Risa/Asir}, can pop up a window to input
debug commands and the debugging similar to that on usual terminals is possible.
One can also send {\tt SIGINT} by using {\tt SM\_control\_intr}
and it provides a similar functionality to entering the debugging
mode from a keyboard interruption.