[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.11

1.11    ! takayama    1: %% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.10 2016/08/22 09:08:50 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.2       noro        6: OpenXM では, 次に述べるような単純かつロバストなサーバの制御方法
                      7: を採用している.
                      8:
                      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 のためのコマンドである.
                     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.8       takayama   41: OpenXM RFC 101 Draft を見よ
                     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
                     52: クライアントはコントロールサーバ経由でいつでもエンジンに signal を
                     53: 送ることができる. しかし, I/O 操作は通常バッファリングされている
                     54: ため, トラブルが生ずる場合がある. エンジンを安全にリセットするため
                     55: 次が必要である.
                     56:
1.1       noro       57: \begin{enumerate}
1.2       noro       58: \item 全ての OX メッセージは Java の意味で synchronized object である.
                     59:
                     60: \item エンジンのリセット後に送られるクライアントからの計算要求メッセージと
                     61: エンジンからの返答が正しく対応していなければならない.
                     62: \end{enumerate}
                     63:
                     64: {\tt SM\_control\_reset\_connection} は, エンジンの安全なリセットを
                     65: 行う一連の手続きを開始するための SM コマンドである.
                     66: クライアントから {\tt SM\_control\_reset\_connection} がコントロール
                     67: サーバに送られると, コントロールサーバは {\tt SIGUSR1} をエンジンに
                     68: 送る. 以後の手続きは次の通りである.
                     69:
                     70: \vskip 2mm
                     71: \noindent
                     72: {\it クライアント側}
                     73: \begin{enumerate}
                     74: \item {\tt SM\_control\_reset\_connection} をコントロールサーバに
                     75: 送った後, クライアントはリセット状態に入る. リセット状態では,
                     76: {\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす.
                     77: \item {\tt OX\_SYNC\_BALL} を受け取ったあと, クライアントは
                     78: {\tt OX\_SYNC\_BALL} をエンジンに送り, 通常状態に戻る.
                     79: \end{enumerate}
                     80:
                     81: \noindent
                     82: {\it エンジン側}
                     83: \begin{enumerate}
                     84: \item
                     85: {\tt SIGUSR1} をコントロールサーバから受け取ったら, エンジンは
                     86: リセット状態に入る. {\tt OX\_SYNC\_BALL} をクライアントに送る.
                     87: この時点でクライアントは既にリセット状態にあるので, この送信が
                     88: ブロックされることはない.
                     89: \item エンジンは
                     90: {\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす.
                     91: {\tt OX\_SYNC\_BALL} を受け取ったら通常状態に戻る.
                     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
                    148: 図 \ref{reset} はデータの流れを示す.
                    149: {\tt OX\_SYNC\_BALL} は特殊な OX メッセージであり,
                    150: I/O stream に残るデータの終りを示す.
                    151: {\tt OX\_SYNC\_BALL} を読んだ後, それぞれの stream は空であり,
                    152: 後に続くクライアントからのリクエストと, エンジンからの返答が
                    153: 正しく対応する.
                    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
                    172: コントロールサーバに, {\tt SIGUSR1} をエンジンに送るよう要求する.
                    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.2       noro      184: Result:
1.1       noro      185: \begin{tabular}{|c|c|}  \hline
                    186: {\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\
                    187: \hline
1.11    ! takayama  188: \end{tabular}\\
1.10      takayama  189: /*&jp
                    190:   すべてエンジンは reset protocol を実装することが推奨されるが,
                    191: 実装していない場合は, mathcap の第4引数の option list で
                    192: {\tt no\_ox\_reset} を送信すべきである (参照: oxpari).
                    193: */
                    194: /*&eg
                    195:   All engines are encouraged to install the reset protocol,
                    196: but when it is not implemented,
                    197: {\tt no\_ox\_reset} option should be included in the fourth argument
                    198: (option list) of the mathcap (ref: oxpari).
                    199: */
1.1       noro      200:
                    201: \item
1.2       noro      202: \begin{verbatim}
                    203: SM_control_kill
                    204: \end{verbatim}
                    205: /*&jp
                    206: サーバはこのメッセージを受信したら
                    207: %ただちに返答をおくり,
                    208: すべてのファイルをクローズして終了する.
                    209: */
                    210: /*&eg
                    211: It requests a control server to terminate the engine and the control server
                    212: itself.
                    213: %The control server should immediately reply an acknowledgment to
                    214: %the client.
                    215: All files and streams should be closed before the termination of servers.
                    216: */
                    217: Request:
1.1       noro      218: \begin{tabular}{|c|c|}  \hline
                    219: {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill}  \\
                    220: \hline
1.4       noro      221: \end{tabular}\\
1.2       noro      222: Result: none.
1.1       noro      223: \end{enumerate}
                    224:
                    225: \medbreak
                    226: \noindent
1.2       noro      227: //&jp {\bf 例}: (シリアル番号は省略してある.)
                    228: //&eg {\bf Example}: (serial numbers are omitted.)
1.1       noro      229: \begin{verbatim}
                    230: 0  0 2 01 (OX_COMMAND)
                    231: 0  0 4 06 (SM_control_reset_connection)
                    232: \end{verbatim}
                    233:
1.2       noro      234: //&jp Reset に対する返事.
                    235: //&eg Reply to the reset request
1.1       noro      236: \begin{verbatim}
                    237: 0  0 2 02 (OX_DATA)
                    238: 0  0 0  2 (CMO_INT32)
                    239: 0  0 0  0 (  0   )
                    240: \end{verbatim}
                    241:
                    242:
1.2       noro      243: //&jp 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が取られる.
                    244: //&eg {\tt OX\_SYNC\_BALL} are exchanged on the data channel for synchronization.
                    245:
1.1       noro      246: \begin{verbatim}
                    247: 0   0   2   03   (OX_SYNC_BALL)
                    248: \end{verbatim}
                    249:
1.7       takayama  250: \subsection{Notification from servers}
1.1       noro      251:
1.7       takayama  252: /*&jp
                    253: OpenXM サーバは, 可能であるかぎり寡黙である.
                    254: たとえばエラーをおこしても, エラーはサーバのエンジンスタックにつまれる
                    255: だけであり, サーバはクライアントが {\tt pop\_cmo} メッセージをおくらない
                    256: かぎり何も送信しない.
                    257: */
                    258: /*&eg
1.9       takayama  259: OpenXM servers try to be as quiet as possible.
1.7       takayama  260: For example, engine errors of a server are only put on the engine stack and
                    261: the engine does not send error packets unless the client sends the message
                    262: {\tt pop\_cmo}.
                    263: */
                    264:
                    265: /*&jp
                    266: OpenXM はこの原則をやぶる例外的な方法を一つ用意している.
                    267: コントロールサーバは,
                    268: {\tt OX\_NOTIFY} ヘッダおよびそれにつづく {\tt OX\_DATA} パケットを送る
                    269: ことができる.
                    270: この機能は mathcap で禁止することも可能である.
                    271: */
                    272: /*&eg
1.9       takayama  273: OpenXM provides a method to notify events.
1.7       takayama  274: Control server may send {\tt OX\_NOTIFY} header and an {\tt OX\_DATA} packet.
1.9       takayama  275: This transmission may be prohibited by mathcap.
1.7       takayama  276: */
                    277:
                    278: /*&jp
                    279: この機能をどのように使うか例をあげて説明しよう.
                    280: {\tt Asir} の {\tt ox\_plot} サーバは, quit ボタンをもっている.
                    281: quit ボタンがおされると canvas が消滅するが, エンジン自体は存在を
                    282: つづける.  この状態で描画命令がくると,
                    283: エンジンスタックに, ``canvas does not exist'' というエラーがつまれる.
                    284: エンジンがこのエラーが生じたことを緊急に知らせたいときに
                    285: {\tt OX\_NOTIFY} を用いる.
                    286: */
                    287: /*&eg
1.9       takayama  288: Let us explain how to use {\tt OX\_NOTIFY} by an example.
1.7       takayama  289: The {\tt ox\_plot} server of {\tt asir} has a quit button.
                    290: If the quit button is pressed, the canvas dissappears, but the engine
                    291: does not terminate.
                    292: If the client sends drawing messages without the canvas,
                    293: then the engine pushes
                    294: error packets ``canvas does not exist'' on the engine stack.
                    295: If the engine wants to notify the error to the client immediately,
                    296: the {\tt OX\_NOTIFY} message should be used.
                    297: */
                    298:
                    299: /*&jp
                    300: ここで, {\tt OX\_NOTIFY} をおくるのは, コントロールプロセスで
                    301: あることに注意しよう.
                    302: したがってエンジンはなんらかの方法で, コントロールサーバに
                    303: {\tt OX\_NOTIFY} をおくることを依頼しないといけない.
1.9       takayama  304: この方法は, OS によりいろいろな方法が可能だか,
                    305: たとえば, unix では
                    306: ファイル {\tt /tmp/.ox\_notify.pid} に touch することでこれを
                    307: 一つの実現することが可能である.
1.7       takayama  308: ここで {\tt pid} はエンジンのプロセス番号である.
                    309: コントロールサーバはファイル {\tt /tmp/.ox\_notify.pid} が
                    310: touch されたことを検出したら, クライアントに
                    311: {\tt OX\_NOTIFY} パケットおよび {\tt OX\_DATA} で {\tt cmo\_null} を送る.
                    312: エンジンはファイルを用いてコントロールサーバに急を知らせる以外に,
                    313: 共有メモリやシグナルを用いてしらせてもよい.
                    314: */
                    315: /*&eg
1.9       takayama  316: Let us note that only the control process is allowed to send {\tt OX\_NOTIFY}.
1.7       takayama  317: Therefore, the engine must ask the control server to send
                    318: {\tt OX\_NOTIFY}.
1.9       takayama  319: Methods to ask the control process from the engine
                    320: depends on operating system.
                    321: In case of unix, one method is the use of a file;
                    322: for instance,
                    323: if the engine touches the file
1.7       takayama  324: {\tt /tmp/.ox\_notify.pid}, then the control server sends
                    325: the {\tt OX\_NOTIFY} header and the {\tt OX\_DATA} packet
                    326: of {\tt cmo\_null}.
                    327: Here, {\tt pid} is the process id of the engine.
                    328: Engines and control processes may use a shared memory or a signal
1.9       takayama  329: instead of the file {\tt /tmp/.ox\_notify.pid}.
1.7       takayama  330: */

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