Return to control.tex CVS log

Up to [local] / OpenXM / doc / OpenXM-specs

A draft of the specification of a notification protocol
(OX_NOTIFY).  It will be discussed soon at the committer
meeting at Kanazawa.

%% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.7 2000/11/17 02:50:04 takayama Exp $
\section{Session Management}

\subsection{Control server}
/*&jp
OpenXM では, 次に述べるような単純かつロバストなサーバの制御方法
を採用している. 

OpenXM サーバは論理的に 2 つの I/O channel をもつ: 一方は計算データ
用であり, 他方は計算制御用である. 制御 channel はサーバを制御する
ためのコマンドを送るために使われる. 
サンプルサーバ ({\tt oxmain.c}) では, そのようなコントロールメッセージ
は別のプロセスが行っている. 以下, そのプロセスをコントロールサーバ
と呼ぶ. これに対して, 計算用サーバをエンジンと呼ぶ. 
コントロールサーバとエンジンは同一のマシン上で動作する. 
このため, コントロールサーバからエンジンに signal を送ることは容易である. 
コントロールサーバ自体も OX スタックマシンであり
{\tt SM\_control\_*} コマンドを受け取る. それらはエンジンへの
signal 送信, engine process の終了などの request のためのコマンドである. 
*/

/*&eg
In OpenXM we adopted the following simple and robust method to 
control servers.

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
nserver. The sample server ({\tt oxmain.c}) processes such control
messages on another process. We call such a process a {\it
control server}. In contrast, we call a server for computation an {\it
engine}. As the control server and the engine runs on the
same machine, it is easy to send a signal from the control server. 
A control server is also an
OpenXM stack machine and it accepts {\tt SM\_control\_*} commands
to send signals to a server or to terminate a server.
*/

\subsection{New specification for OpenXM control servers}

/*&jp

我々は新しいコントロールサーバを提案する。そのサンプル実装として oxc が
提供される。新しいコントロールサーバは以下の点で従来のものと異なる。
\begin{enumerate}
\item コントロールサーバは OpenXM スタックマシンであり、
CMObject/Primitive をサポートする。
\item 計算サーバの起動はスタックマシンコマンドを介して行う。
\item 一つのコントロールサーバから複数の計算サーバを起動できる。
\end{enumerate}

oxc の導入により、いままでのサーバの起動手順はコントロールサーバの起動と
計算サーバの起動に分離される。コントロールサーバを起動するには次の手順を
取る。まず、適当なオプション(後述)をつけて、コントロールサーバを起動する
と、コントロールサーバはソケットを作成し、connect する。クライアントは、
listen, accept する。接続後、バイトオーダを決定する。バイトオーダの決定
については???を見よ。その後、コントロールサーバは待機状態にはいる。コン
トロールサーバは OpenXM スタックマシンであるから、mathcap の交換などの手
続きに入ってもよい。

計算サーバの起動は、oxc のローカル関数 oxc\_open による。oxc\_open は少
なくとも 4 個の引数を持つ。すなわち、
\begin{verbatim}
oxc_open(計算サーバ名, ホスト名, ポート番号, モード, ...)
\end{verbatim}
という形式である。ここで、「計算サーバ名」、「ホスト名」は CMO\_STRING 
型のオブジェクト、「ポート番号」、「モード」は CMO\_INT32型
のオブジェクトである。ホスト名というのはOpenXMクライアントのホ
スト名のことである。ローカル関数の実行は SM\_executeFunction による。す
なわち各引数を順にスタックに積み、最後にSM\_executeFunction を実行する。
SM\_executeStringByLocalParser は利用できないので注意する。

oxc\_open は、計算サーバの起動に成功したら (CMO\_INT32, サーバID) を、失
敗したらエラーオブジェクトをスタックに積む。例えば計算サーバが発見できな
かった場合にはエラーオブジェクトを積むことになる。コントロールサーバは 
access(2) を用いて PATH から計算サーバを探す。もし見つからなければ、fork 
をせずに、エラーオブジェクトをスタックに積む。

コントロールサーバの実行形式は以下のオプションを許す。
\begin{verbatim}
     --pass
     --host
     --port
\end{verbatim}
*/



\subsection{OpenXM reset protocol}

/*&jp
クライアントはコントロールサーバ経由でいつでもエンジンに signal を
送ることができる. しかし, I/O 操作は通常バッファリングされている
ため, トラブルが生ずる場合がある. エンジンを安全にリセットするため
次が必要である. 

\begin{enumerate}
\item 全ての OX メッセージは Java の意味で synchronized object である. 

\item エンジンのリセット後に送られるクライアントからの計算要求メッセージと
エンジンからの返答が正しく対応していなければならない. 
\end{enumerate}

{\tt SM\_control\_reset\_connection} は, エンジンの安全なリセットを
行う一連の手続きを開始するための SM コマンドである. 
クライアントから {\tt SM\_control\_reset\_connection} がコントロール
サーバに送られると, コントロールサーバは {\tt SIGUSR1} をエンジンに
送る. 以後の手続きは次の通りである. 

\vskip 2mm
\noindent
{\it クライアント側} 
\begin{enumerate}
\item {\tt SM\_control\_reset\_connection} をコントロールサーバに
送った後, クライアントはリセット状態に入る. リセット状態では, 
{\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす. 
\item {\tt OX\_SYNC\_BALL} を受け取ったあと, クライアントは
{\tt OX\_SYNC\_BALL} をエンジンに送り, 通常状態に戻る. 
\end{enumerate}

\noindent
{\it エンジン側}
\begin{enumerate}
\item 
{\tt SIGUSR1} をコントロールサーバから受け取ったら, エンジンは
リセット状態に入る. {\tt OX\_SYNC\_BALL} をクライアントに送る. 
この時点でクライアントは既にリセット状態にあるので, この送信が
ブロックされることはない. 
\item エンジンは
{\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす. 
{\tt OX\_SYNC\_BALL} を受け取ったら通常状態に戻る. 
\end{enumerate}
*/
/*&eg
A client can send a signal to an engine by using the control channel 
at any time. However, I/O operations are usually buffered,
which may cause troubles.
To reset an engine safely the following are required.

\begin{enumerate}
\item Any OX message must be a synchronized object in the sense of Java.

\item After restarting an engine, a request from a client 
must correctly corresponds to the response from the engine.
\end{enumerate}

{\tt SM\_control\_reset\_connection} is a stack machine command to
initiate a safe resetting of an engine.
The control server sends {\tt SIGUSR1} to the engine if it receives
{\tt SM\_control\_reset\_connection} from the client.
Under the OpenXM reset protocol, an engine and a client act as follows.

\vskip 2mm
\noindent
{\it Client side} 
\begin{enumerate}
\item After sending {\tt SM\_control\_reset\_connection} to the
control server, the client enters the resetting state. It discards 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}

\noindent
{\it Engine side}
\begin{enumerate}
\item 
After receiving {\tt SIGUSR1} from the control server,
the engine enters the resetting state.
The engine sends {\tt OX\_SYNC\_BALL} to the client.
The operation does not block because
the client is now in the resetting state.
\item The engine discards all OX messages from the engine until it
receives {\tt OX\_SYNC\_BALL}. After receiving {\tt OX\_SYNC\_BALL} 
the engine returns to the usual state.
\end{enumerate}
*/

/*&eg
Figure \ref{reset} illustrates the flow of data.
{\tt OX\_SYNC\_BALL} is a special OX message and
is used to mark the end of data remaining in the
I/O streams. After reading it, it is assured that each stream is empty
and that the subsequent request from a client correctly 
corresponds to the response from the engine.
*/
/*&jp
図 \ref{reset} はデータの流れを示す. 
{\tt OX\_SYNC\_BALL} は特殊な OX メッセージであり, 
I/O stream に残るデータの終りを示す. 
{\tt OX\_SYNC\_BALL} を読んだ後, それぞれの stream は空であり, 
後に続くクライアントからのリクエストと, エンジンからの返答が
正しく対応する. 
*/
\begin{figure}[htbp]
\epsfxsize=10cm
\begin{center}
\epsffile{reset.eps}
\end{center}
\caption{OpenXM reset procedure}
\label{reset}
\end{figure}

\subsection{Control message (SMObject/TCPIP/Control)}

\begin{enumerate}
\item 
\begin{verbatim}
SM_control_reset_connection 
\end{verbatim}
/*&jp
コントロールサーバに, {\tt SIGUSR1} をエンジンに送るよう要求する. 
*/
/*&eg
It requests a control server to send {\tt SIGUSR1} to the engine.
The control server should immediately reply an acknowledgment to
the client.
*/
Request:
\begin{tabular}{|c|c|}  \hline
{\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection}  \\
\hline 
\end{tabular}
Result:  
\begin{tabular}{|c|c|}  \hline
{\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\
\hline 
\end{tabular}

\item
\begin{verbatim}
SM_control_kill
\end{verbatim}
/*&jp
サーバはこのメッセージを受信したら
%ただちに返答をおくり, 
すべてのファイルをクローズして終了する.
*/
/*&eg
It requests a control server to terminate the engine and the control server
itself. 
%The control server should immediately reply an acknowledgment to
%the client.
All files and streams should be closed before the termination of servers.
*/
Request:
\begin{tabular}{|c|c|}  \hline
{\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill}  \\
\hline 
\end{tabular}\\
Result: none.
\end{enumerate}

\medbreak
\noindent
//&jp {\bf 例}: (シリアル番号は省略してある.) 
//&eg {\bf Example}: (serial numbers are omitted.)
\begin{verbatim}
0  0 2 01 (OX_COMMAND) 
0  0 4 06 (SM_control_reset_connection)
\end{verbatim}

//&jp Reset に対する返事.
//&eg Reply to the reset request
\begin{verbatim}
0  0 2 02 (OX_DATA)
0  0 0  2 (CMO_INT32)
0  0 0  0 (  0   )
\end{verbatim}


//&jp 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が取られる.
//&eg {\tt OX\_SYNC\_BALL} are exchanged on the data channel for synchronization.

\begin{verbatim}
0   0   2   03   (OX_SYNC_BALL)
\end{verbatim}

\subsection{Notification from servers}

/*&jp
OpenXM サーバは, 可能であるかぎり寡黙である.
たとえばエラーをおこしても, エラーはサーバのエンジンスタックにつまれる
だけであり, サーバはクライアントが {\tt pop\_cmo} メッセージをおくらない
かぎり何も送信しない.
*/
/*&eg
OpenXM servers try to be quiet as far as possible.
For example, engine errors of a server are only put on the engine stack and
the engine does not send error packets unless the client sends the message
{\tt pop\_cmo}.
*/

/*&jp
OpenXM はこの原則をやぶる例外的な方法を一つ用意している.
コントロールサーバは,
{\tt OX\_NOTIFY} ヘッダおよびそれにつづく {\tt OX\_DATA} パケットを送る
ことができる.
この機能は mathcap で禁止することも可能である.
*/
/*&eg
OpenXM provides a method to break this principle.
Control server may send {\tt OX\_NOTIFY} header and an {\tt OX\_DATA} packet.
This transmission can be prohibited by mathcap.
*/

/*&jp
この機能をどのように使うか例をあげて説明しよう.
{\tt Asir} の {\tt ox\_plot} サーバは, quit ボタンをもっている.
quit ボタンがおされると canvas が消滅するが, エンジン自体は存在を
つづける.  この状態で描画命令がくると,
エンジンスタックに, ``canvas does not exist'' というエラーがつまれる.
エンジンがこのエラーが生じたことを緊急に知らせたいときに
{\tt OX\_NOTIFY} を用いる.
*/
/*&eg
Let us explain how to use {\tt OX\_NOTIFY}.
The {\tt ox\_plot} server of {\tt asir} has a quit button.
If the quit button is pressed, the canvas dissappears, but the engine
does not terminate.
If the client sends drawing messages without the canvas, 
then the engine pushes
error packets ``canvas does not exist'' on the engine stack.
If the engine wants to notify the error to the client immediately,
the {\tt OX\_NOTIFY} message should be used.
*/

/*&jp
ここで, {\tt OX\_NOTIFY} をおくるのは, コントロールプロセスで
あることに注意しよう.
したがってエンジンはなんらかの方法で, コントロールサーバに
{\tt OX\_NOTIFY} をおくることを依頼しないといけない.
OpenXM の規格では,
ファイル {\tt /tmp/.ox\_notify.pid} に touch することでこれの
一つの実現方法を与えている.
ここで {\tt pid} はエンジンのプロセス番号である.
コントロールサーバはファイル {\tt /tmp/.ox\_notify.pid} が
touch されたことを検出したら, クライアントに
{\tt OX\_NOTIFY} パケットおよび {\tt OX\_DATA} で {\tt cmo\_null} を送る.
エンジンはファイルを用いてコントロールサーバに急を知らせる以外に,
共有メモリやシグナルを用いてしらせてもよい.
*/
/*&eg
Let us note that it is the control process that sends {\tt OX\_NOTIFY}.
Therefore, the engine must ask the control server to send
{\tt OX\_NOTIFY}.
In the OpenXM, if the engine touches the file
{\tt /tmp/.ox\_notify.pid}, then the control server sends
the {\tt OX\_NOTIFY} header and the {\tt OX\_DATA} packet 
of {\tt cmo\_null}.
Here, {\tt pid} is the process id of the engine.
Engines and control processes may use a shared memory or a signal
instead of the file {\tt /tmp.ox\_notify.pid}.
*/