[BACK]Return to control.tex CVS log [TXT][DIR] Up to [local] / OpenXM / doc / OpenXM-specs

Diff for /OpenXM/doc/OpenXM-specs/control.tex between version 1.1.1.1 and 1.7

version 1.1.1.1, 2000/01/20 08:52:46 version 1.7, 2000/11/17 02:50:04
Line 1 
Line 1 
 %% $OpenXM$  %% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.6 2000/07/27 09:51:04 ohara Exp $
 //&jp \section{コントロールメッセージ (SMObject/TCPIP/Control)}  \section{Session Management}
 //&eg \section{Control message (SMObject/TCPIP/Control)} (This section has not been translated.)  
   
   \subsection{Control server}
 /*&jp  /*&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}  \begin{enumerate}
 \item  \item コントロールサーバは OpenXM スタックマシンであり、
 サーバは {\tt SM\_control\_reset\_connection}  CMObject/Primitive をサポートする。
 メッセージを受信したら, 現在の計算を中断する.  \item 計算サーバの起動はスタックマシンコマンドを介して行う。
 中断操作は細心の注意をもって行なわないといけない.  \item 一つのコントロールサーバから複数の計算サーバを起動できる。
 サンプルサーバ ({\tt oxmain.c})では, コントロールメッセージの  \end{enumerate}
 処理は別のプロセスがおこなっており, SIGUSR1 割り込みをスタックマシンへ  
 かける.  oxc の導入により、いままでのサーバの起動手順はコントロールサーバの起動と
 もしサーバがメッセージの通信中であれば, このコントロールメッセージ  計算サーバの起動に分離される。コントロールサーバを起動するには次の手順を
 をすぐには実行せず, メッセージ通信を終了するのを待つ.  取る。まず、適当なオプション(後述)をつけて、コントロールサーバを起動する
 当然, メッセージを発信中に, このメッセージを送信してもいけない.  と、コントロールサーバはソケットを作成し、connect する。クライアントは、
 (Java 風にいえば, すべての メッセージは synchronized object である.)  listen, accept する。接続後、バイトオーダを決定する。バイトオーダの決定
 また, たとえば file IO なども, 中断をうけてはならない, synchronized な  については???を見よ。その後、コントロールサーバは待機状態にはいる。コン
 操作であろう.  トロールサーバは OpenXM スタックマシンであるから、mathcap の交換などの手
 クライアントがサーバに controlResetConnection コントロールメッセージを  続きに入ってもよい。
 おくったら, サーバは, 現在の受信バッファをすべてクリアし,  
 クライアントへ  計算サーバの起動は、oxc のローカル関数 oxc\_open による。oxc\_open は少
 {\tt OX\_SYNC\_BALL}  なくとも 4 個の引数を持つ。すなわち、
 を送る.  \begin{verbatim}
 クライアントは, コントロールメッセージをおくったあと,  oxc_open(計算サーバ名, ホスト名, ポート番号, モード, ...)
 待機モードに入り, {\tt OX\_SYNC\_BALL}  \end{verbatim}
 をうけとるまですべてのメッセージを読み飛ばす.  という形式である。ここで、「計算サーバ名」、「ホスト名」は CMO\_STRING
 クライアントは {\tt OX\_SYNC\_BALL} をうけとったら,  型のオブジェクト、「ポート番号」、「モード」は CMO\_INT32型
 サーバに {\tt OX\_SYNC\_BALL} を送る.  のオブジェクトである。ホスト名というのはOpenXMクライアントのホ
 サーバは, 最初の {\tt OX\_SYNC\_BALL} を投げたあと,  スト名のことである。ローカル関数の実行は SM\_executeFunction による。す
 待機モードに入り,  なわち各引数を順にスタックに積み、最後にSM\_executeFunction を実行する。
 {\tt OX\_SYNC\_BALL}  SM\_executeStringByLocalParser は利用できないので注意する。
 をうけとるまですべてのメッセージを読み飛ばす.  
 %% 最後に,  サーバ  oxc\_open は、計算サーバの起動に成功したら (CMO\_INT32, サーバID) を、失
 %% はすべての操作が終了したことを通知するため,  敗したらエラーオブジェクトをスタックに積む。例えば計算サーバが発見できな
 %% クライアントに  かった場合にはエラーオブジェクトを積むことになる。コントロールサーバは
 %% {\tt OX\_SYNC\_BALL} を投げる.  access(2) を用いて PATH から計算サーバを探す。もし見つからなければ、fork
 \\ Request:  をせずに、エラーオブジェクトをスタックに積む。
   
   コントロールサーバの実行形式は以下のオプションを許す。
   \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  \begin{tabular}{|c|c|}  \hline
 {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection}  \\  {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection}  \\
 \hline  \hline
 \end{tabular}  \end{tabular}
 \\ Result:  Result:
 \begin{tabular}{|c|c|}  \hline  \begin{tabular}{|c|c|}  \hline
 {\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\  {\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\
 \hline  \hline
 \end{tabular}  \end{tabular}
   
 @@@  
   
 \item  \item
 サーバはこのメッセージを受信したらただちにコントロールメッセージへの  \begin{verbatim}
 返答をおくり, すべてのファイルをクローズして終了する.  SM_control_kill
 \\ Request:  \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  \begin{tabular}{|c|c|}  \hline
 {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill}  \\  {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill}  \\
 \hline  \hline
 \end{tabular}  \end{tabular}\\
 \\ Result:  Result: none.
 Empty \\  
   
   
 \end{enumerate}  \end{enumerate}
   
 \medbreak  \medbreak
 \noindent  \noindent
 {\bf 例}: (シリアル番号は省略してある.)\  //&jp {\bf 例}: (シリアル番号は省略してある.)
   //&eg {\bf Example}: (serial numbers are omitted.)
 \begin{verbatim}  \begin{verbatim}
 0  0 2 01 (OX_COMMAND)  0  0 2 01 (OX_COMMAND)
 0  0 4 06 (SM_control_reset_connection)  0  0 4 06 (SM_control_reset_connection)
 \end{verbatim}  \end{verbatim}
   
 Reset に対する返事.  //&jp Reset に対する返事.
   //&eg Reply to the reset request
 \begin{verbatim}  \begin{verbatim}
 0  0 2 02 (OX_DATA)  0  0 2 02 (OX_DATA)
 0  0 0  2 (CMO_INT32)  0  0 0  2 (CMO_INT32)
Line 78  Reset に対する返事.
Line 269  Reset に対する返事.
 \end{verbatim}  \end{verbatim}
   
   
 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が  //&jp 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が取られる.
 取られる.  //&eg {\tt OX\_SYNC\_BALL} are exchanged on the data channel for synchronization.
   
 \begin{verbatim}  \begin{verbatim}
 0   0   2   03   (OX_SYNC_BALL)  0   0   2   03   (OX_SYNC_BALL)
 \end{verbatim}  \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}.
   */
Legend:
Removed from v.1.1.1.1  
changed lines
  Added in v.1.7
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>