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

Annotation of OpenXM/doc/OpenXM-specs/control.tex, Revision 1.13

1.13    ! takayama    1: %% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.12 2016/08/27 02:11:01 takayama Exp $
1.2       noro        2: \section{Session Management}
1.1       noro        3:
1.2       noro        4: \subsection{Control server}
1.1       noro        5: /*&jp
1.13    ! takayama    6: OpenXM では, 次に述べるような単純かつロバストなサーバの制御方法
        !             7: を採用している.
1.2       noro        8:
1.13    ! takayama    9: OpenXM サーバは論理的に 2 つの I/O channel をもつ: 一方は計算データ
        !            10: 用であり, 他方は計算制御用である. 制御 channel はサーバを制御する
        !            11: ためのコマンドを送るために使われる.
        !            12: サンプルサーバ ({\tt oxmain.c}) では, そのようなコントロールメッセージ
        !            13: は別のプロセスが行っている. 以下, そのプロセスをコントロールサーバ
        !            14: と呼ぶ. これに対して, 計算用サーバをエンジンと呼ぶ.
        !            15: コントロールサーバとエンジンは同一のマシン上で動作する.
        !            16: このため, コントロールサーバからエンジンに signal を送ることは容易である.
        !            17: コントロールサーバ自体も OX スタックマシンであり
        !            18: {\tt SM\_control\_*} コマンドを受け取る. それらはエンジンへの
        !            19: signal 送信, engine process の終了などの request のためのコマンドである.
1.2       noro       20: */
                     21:
                     22: /*&eg
                     23: In OpenXM we adopted the following simple and robust method to
                     24: control servers.
                     25:
                     26: An OpenXM server has logically two I/O channels: one for exchanging
                     27: data for computations and the other for controlling computations. The
                     28: control channel is used to send commands to control execution on the
1.7       takayama   29: nserver. The sample server ({\tt oxmain.c}) processes such control
1.2       noro       30: messages on another process. We call such a process a {\it
                     31: control server}. In contrast, we call a server for computation an {\it
                     32: engine}. As the control server and the engine runs on the
                     33: same machine, it is easy to send a signal from the control server.
                     34: A control server is also an
                     35: OpenXM stack machine and it accepts {\tt SM\_control\_*} commands
                     36: to send signals to a server or to terminate a server.
                     37: */
1.6       ohara      38:
1.8       takayama   39: \subsection{New OpenXM control servers}
1.6       ohara      40: /*&jp
1.13    ! takayama   41: OpenXM RFC 101 Draft を見よ
1.8       takayama   42: \htmladdnormallink{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}.
                     43: */
                     44: /*&eg
                     45: See OpenXM RFC 101 Draft.
                     46: \htmladdnormallink{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}.
1.6       ohara      47: */
1.2       noro       48:
                     49: \subsection{OpenXM reset protocol}
                     50:
                     51: /*&jp
1.13    ! takayama   52: クライアントはコントロールサーバ経由でいつでもエンジンに signal を
        !            53: 送ることができる. しかし, I/O 操作は通常バッファリングされている
        !            54: ため, トラブルが生ずる場合がある. エンジンを安全にリセットするため
        !            55: 次が必要である.
1.2       noro       56:
1.1       noro       57: \begin{enumerate}
1.13    ! takayama   58: \item 全ての OX メッセージは Java の意味で synchronized object である.
1.2       noro       59:
1.13    ! takayama   60: \item エンジンのリセット後に送られるクライアントからの計算要求メッセージと
        !            61: エンジンからの返答が正しく対応していなければならない.
1.2       noro       62: \end{enumerate}
                     63:
1.13    ! takayama   64: {\tt SM\_control\_reset\_connection} は, エンジンの安全なリセットを
        !            65: 行う一連の手続きを開始するための SM コマンドである.
        !            66: クライアントから {\tt SM\_control\_reset\_connection} がコントロール
        !            67: サーバに送られると, コントロールサーバは {\tt SIGUSR1} をエンジンに
        !            68: 送る. 以後の手続きは次の通りである.
1.2       noro       69:
                     70: \vskip 2mm
                     71: \noindent
1.13    ! takayama   72: {\it クライアント側}
1.2       noro       73: \begin{enumerate}
1.13    ! takayama   74: \item {\tt SM\_control\_reset\_connection} をコントロールサーバに
        !            75: 送った後, クライアントはリセット状態に入る. リセット状態では,
        !            76: {\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす.
        !            77: \item {\tt OX\_SYNC\_BALL} を受け取ったあと, クライアントは
        !            78: {\tt OX\_SYNC\_BALL} をエンジンに送り, 通常状態に戻る.
1.2       noro       79: \end{enumerate}
                     80:
                     81: \noindent
1.13    ! takayama   82: {\it エンジン側}
1.2       noro       83: \begin{enumerate}
                     84: \item
1.13    ! takayama   85: {\tt SIGUSR1} をコントロールサーバから受け取ったら, エンジンは
        !            86: リセット状態に入る. {\tt OX\_SYNC\_BALL} をクライアントに送る.
        !            87: この時点でクライアントは既にリセット状態にあるので, この送信が
        !            88: ブロックされることはない.
        !            89: \item エンジンは
        !            90: {\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす.
        !            91: {\tt OX\_SYNC\_BALL} を受け取ったら通常状態に戻る.
1.2       noro       92: \end{enumerate}
                     93: */
                     94: /*&eg
                     95: A client can send a signal to an engine by using the control channel
                     96: at any time. However, I/O operations are usually buffered,
                     97: which may cause troubles.
                     98: To reset an engine safely the following are required.
                     99:
                    100: \begin{enumerate}
                    101: \item Any OX message must be a synchronized object in the sense of Java.
                    102:
                    103: \item After restarting an engine, a request from a client
                    104: must correctly corresponds to the response from the engine.
                    105: \end{enumerate}
                    106:
                    107: {\tt SM\_control\_reset\_connection} is a stack machine command to
                    108: initiate a safe resetting of an engine.
                    109: The control server sends {\tt SIGUSR1} to the engine if it receives
                    110: {\tt SM\_control\_reset\_connection} from the client.
                    111: Under the OpenXM reset protocol, an engine and a client act as follows.
                    112:
                    113: \vskip 2mm
                    114: \noindent
                    115: {\it Client side}
                    116: \begin{enumerate}
                    117: \item After sending {\tt SM\_control\_reset\_connection} to the
                    118: control server, the client enters the resetting state. It discards all {\tt
                    119: OX} messages from the engine until it receives {\tt OX\_SYNC\_BALL}.
                    120: \item After receiving {\tt OX\_SYNC\_BALL} the client sends
                    121: {\tt OX\_SYNC\_BALL} to the engine and returns to the usual state.
                    122: \end{enumerate}
                    123:
                    124: \noindent
                    125: {\it Engine side}
                    126: \begin{enumerate}
                    127: \item
                    128: After receiving {\tt SIGUSR1} from the control server,
                    129: the engine enters the resetting state.
                    130: The engine sends {\tt OX\_SYNC\_BALL} to the client.
                    131: The operation does not block because
                    132: the client is now in the resetting state.
                    133: \item The engine discards all OX messages from the engine until it
                    134: receives {\tt OX\_SYNC\_BALL}. After receiving {\tt OX\_SYNC\_BALL}
                    135: the engine returns to the usual state.
                    136: \end{enumerate}
                    137: */
                    138:
                    139: /*&eg
                    140: Figure \ref{reset} illustrates the flow of data.
                    141: {\tt OX\_SYNC\_BALL} is a special OX message and
                    142: is used to mark the end of data remaining in the
                    143: I/O streams. After reading it, it is assured that each stream is empty
                    144: and that the subsequent request from a client correctly
                    145: corresponds to the response from the engine.
                    146: */
                    147: /*&jp
1.13    ! takayama  148: 図 \ref{reset} はデータの流れを示す.
        !           149: {\tt OX\_SYNC\_BALL} は特殊な OX メッセージであり,
        !           150: I/O stream に残るデータの終りを示す.
        !           151: {\tt OX\_SYNC\_BALL} を読んだ後, それぞれの stream は空であり,
        !           152: 後に続くクライアントからのリクエストと, エンジンからの返答が
        !           153: 正しく対応する.
1.2       noro      154: */
1.3       noro      155: \begin{figure}[htbp]
1.5       noro      156: \epsfxsize=10cm
                    157: \begin{center}
1.3       noro      158: \epsffile{reset.eps}
1.5       noro      159: \end{center}
1.3       noro      160: \caption{OpenXM reset procedure}
                    161: \label{reset}
                    162: \end{figure}
                    163:
1.2       noro      164: \subsection{Control message (SMObject/TCPIP/Control)}
                    165:
                    166: \begin{enumerate}
                    167: \item
                    168: \begin{verbatim}
                    169: SM_control_reset_connection
                    170: \end{verbatim}
                    171: /*&jp
1.13    ! takayama  172: コントロールサーバに, {\tt SIGUSR1} をエンジンに送るよう要求する.
1.2       noro      173: */
                    174: /*&eg
                    175: It requests a control server to send {\tt SIGUSR1} to the engine.
                    176: The control server should immediately reply an acknowledgment to
                    177: the client.
                    178: */
                    179: Request:
1.1       noro      180: \begin{tabular}{|c|c|}  \hline
                    181: {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection}  \\
                    182: \hline
                    183: \end{tabular}
1.12      takayama  184: Result:   none. \\
1.10      takayama  185: /*&jp
1.13    ! takayama  186:   すべてエンジンは reset protocol を実装することが推奨されるが,
        !           187: 実装していない場合は, mathcap の第4引数の option list で
        !           188: {\tt no\_ox\_reset} を送信すべきである (参照: oxpari). \\
1.10      takayama  189: */
                    190: /*&eg
                    191:   All engines are encouraged to install the reset protocol,
                    192: but when it is not implemented,
                    193: {\tt no\_ox\_reset} option should be included in the fourth argument
1.12      takayama  194: (option list) of the mathcap (ref: oxpari). \\
                    195: */
                    196: /*&jp
1.13    ! takayama  197: 注意:  古い実装(2000年以前)の control server, client では,
        !           198: 次の形式の result code が戻ることを仮定している場合がある.
        !           199: これら古い実装は更新することが必要である. \\
1.12      takayama  200: */
                    201: /*&eg
                    202: Note: Some old implementations of control servers and clients (before 2000)
                    203: assume the result code of the following format.
                    204: These obsolete implementations should be updated.\\
1.10      takayama  205: */
1.12      takayama  206: \begin{tabular}{|c|c|}  \hline
                    207: {\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\
                    208: \hline
                    209: \end{tabular}\\
1.1       noro      210:
                    211: \item
1.2       noro      212: \begin{verbatim}
                    213: SM_control_kill
                    214: \end{verbatim}
                    215: /*&jp
1.13    ! takayama  216: サーバはこのメッセージを受信したら
        !           217: %ただちに返答をおくり,
        !           218: すべてのファイルをクローズして終了する.
1.2       noro      219: */
                    220: /*&eg
                    221: It requests a control server to terminate the engine and the control server
                    222: itself.
                    223: %The control server should immediately reply an acknowledgment to
                    224: %the client.
                    225: All files and streams should be closed before the termination of servers.
                    226: */
                    227: Request:
1.1       noro      228: \begin{tabular}{|c|c|}  \hline
                    229: {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill}  \\
                    230: \hline
1.4       noro      231: \end{tabular}\\
1.2       noro      232: Result: none.
1.1       noro      233: \end{enumerate}
                    234:
                    235: \medbreak
                    236: \noindent
1.13    ! takayama  237: //&jp {\bf 例}: (シリアル番号は省略してある.)
1.2       noro      238: //&eg {\bf Example}: (serial numbers are omitted.)
1.1       noro      239: \begin{verbatim}
                    240: 0  0 2 01 (OX_COMMAND)
                    241: 0  0 4 06 (SM_control_reset_connection)
                    242: \end{verbatim}
                    243:
1.13    ! takayama  244: %//&jp Reset に対する返事.
1.12      takayama  245: %//&eg Reply to the reset request
                    246: %\begin{verbatim}
                    247: %0  0 2 02 (OX_DATA)
                    248: %0  0 0  2 (CMO_INT32)
                    249: %0  0 0  0 (  0   )
                    250: %\end{verbatim}
1.1       noro      251:
                    252:
1.13    ! takayama  253: //&jp 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が取られる.
1.2       noro      254: //&eg {\tt OX\_SYNC\_BALL} are exchanged on the data channel for synchronization.
                    255:
1.1       noro      256: \begin{verbatim}
                    257: 0   0   2   03   (OX_SYNC_BALL)
                    258: \end{verbatim}
                    259:
1.7       takayama  260: \subsection{Notification from servers}
1.1       noro      261:
1.7       takayama  262: /*&jp
1.13    ! takayama  263: OpenXM サーバは, 可能であるかぎり寡黙である.
        !           264: たとえばエラーをおこしても, エラーはサーバのエンジンスタックにつまれる
        !           265: だけであり, サーバはクライアントが {\tt pop\_cmo} メッセージをおくらない
        !           266: かぎり何も送信しない.
1.7       takayama  267: */
                    268: /*&eg
1.9       takayama  269: OpenXM servers try to be as quiet as possible.
1.7       takayama  270: For example, engine errors of a server are only put on the engine stack and
                    271: the engine does not send error packets unless the client sends the message
                    272: {\tt pop\_cmo}.
                    273: */
                    274:
                    275: /*&jp
1.13    ! takayama  276: OpenXM はこの原則をやぶる例外的な方法を一つ用意している.
        !           277: コントロールサーバは,
        !           278: {\tt OX\_NOTIFY} ヘッダおよびそれにつづく {\tt OX\_DATA} パケットを送る
        !           279: ことができる.
        !           280: この機能は mathcap で禁止することも可能である.
1.7       takayama  281: */
                    282: /*&eg
1.9       takayama  283: OpenXM provides a method to notify events.
1.7       takayama  284: Control server may send {\tt OX\_NOTIFY} header and an {\tt OX\_DATA} packet.
1.9       takayama  285: This transmission may be prohibited by mathcap.
1.7       takayama  286: */
                    287:
                    288: /*&jp
1.13    ! takayama  289: この機能をどのように使うか例をあげて説明しよう.
        !           290: {\tt Asir} の {\tt ox\_plot} サーバは, quit ボタンをもっている.
        !           291: quit ボタンがおされると canvas が消滅するが, エンジン自体は存在を
        !           292: つづける.  この状態で描画命令がくると,
        !           293: エンジンスタックに, ``canvas does not exist'' というエラーがつまれる.
        !           294: エンジンがこのエラーが生じたことを緊急に知らせたいときに
        !           295: {\tt OX\_NOTIFY} を用いる.
1.7       takayama  296: */
                    297: /*&eg
1.9       takayama  298: Let us explain how to use {\tt OX\_NOTIFY} by an example.
1.7       takayama  299: The {\tt ox\_plot} server of {\tt asir} has a quit button.
                    300: If the quit button is pressed, the canvas dissappears, but the engine
                    301: does not terminate.
                    302: If the client sends drawing messages without the canvas,
                    303: then the engine pushes
                    304: error packets ``canvas does not exist'' on the engine stack.
                    305: If the engine wants to notify the error to the client immediately,
                    306: the {\tt OX\_NOTIFY} message should be used.
                    307: */
                    308:
                    309: /*&jp
1.13    ! takayama  310: ここで, {\tt OX\_NOTIFY} をおくるのは, コントロールプロセスで
        !           311: あることに注意しよう.
        !           312: したがってエンジンはなんらかの方法で, コントロールサーバに
        !           313: {\tt OX\_NOTIFY} をおくることを依頼しないといけない.
        !           314: この方法は, OS によりいろいろな方法が可能だか,
        !           315: たとえば, unix では
        !           316: ファイル {\tt /tmp/.ox\_notify.pid} に touch することでこれを
        !           317: 一つの実現することが可能である.
        !           318: ここで {\tt pid} はエンジンのプロセス番号である.
        !           319: コントロールサーバはファイル {\tt /tmp/.ox\_notify.pid} が
        !           320: touch されたことを検出したら, クライアントに
        !           321: {\tt OX\_NOTIFY} パケットおよび {\tt OX\_DATA} で {\tt cmo\_null} を送る.
        !           322: エンジンはファイルを用いてコントロールサーバに急を知らせる以外に,
        !           323: 共有メモリやシグナルを用いてしらせてもよい.
1.7       takayama  324: */
                    325: /*&eg
1.9       takayama  326: Let us note that only the control process is allowed to send {\tt OX\_NOTIFY}.
1.7       takayama  327: Therefore, the engine must ask the control server to send
                    328: {\tt OX\_NOTIFY}.
1.9       takayama  329: Methods to ask the control process from the engine
                    330: depends on operating system.
                    331: In case of unix, one method is the use of a file;
                    332: for instance,
                    333: if the engine touches the file
1.7       takayama  334: {\tt /tmp/.ox\_notify.pid}, then the control server sends
                    335: the {\tt OX\_NOTIFY} header and the {\tt OX\_DATA} packet
                    336: of {\tt cmo\_null}.
                    337: Here, {\tt pid} is the process id of the engine.
                    338: Engines and control processes may use a shared memory or a signal
1.9       takayama  339: instead of the file {\tt /tmp/.ox\_notify.pid}.
1.7       takayama  340: */

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>