Annotation of OpenXM/doc/OpenXM-specs/control.tex, Revision 1.7
1.7 ! takayama 1: %% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.6 2000/07/27 09:51:04 ohara 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:
39: \subsection{New specification for OpenXM control servers}
40:
41: /*&jp
42:
43: 我々は新しいコントロールサーバを提案する。そのサンプル実装として oxc が
44: 提供される。新しいコントロールサーバは以下の点で従来のものと異なる。
45: \begin{enumerate}
46: \item コントロールサーバは OpenXM スタックマシンであり、
1.7 ! takayama 47: CMObject/Primitive をサポートする。
1.6 ohara 48: \item 計算サーバの起動はスタックマシンコマンドを介して行う。
49: \item 一つのコントロールサーバから複数の計算サーバを起動できる。
50: \end{enumerate}
51:
52: oxc の導入により、いままでのサーバの起動手順はコントロールサーバの起動と
53: 計算サーバの起動に分離される。コントロールサーバを起動するには次の手順を
54: 取る。まず、適当なオプション(後述)をつけて、コントロールサーバを起動する
55: と、コントロールサーバはソケットを作成し、connect する。クライアントは、
56: listen, accept する。接続後、バイトオーダを決定する。バイトオーダの決定
57: については???を見よ。その後、コントロールサーバは待機状態にはいる。コン
58: トロールサーバは OpenXM スタックマシンであるから、mathcap の交換などの手
59: 続きに入ってもよい。
60:
61: 計算サーバの起動は、oxc のローカル関数 oxc\_open による。oxc\_open は少
62: なくとも 4 個の引数を持つ。すなわち、
63: \begin{verbatim}
64: oxc_open(計算サーバ名, ホスト名, ポート番号, モード, ...)
65: \end{verbatim}
66: という形式である。ここで、「計算サーバ名」、「ホスト名」は CMO\_STRING
1.7 ! takayama 67: 型のオブジェクト、「ポート番号」、「モード」は CMO\_INT32型
! 68: のオブジェクトである。ホスト名というのはOpenXMクライアントのホ
1.6 ohara 69: スト名のことである。ローカル関数の実行は SM\_executeFunction による。す
70: なわち各引数を順にスタックに積み、最後にSM\_executeFunction を実行する。
71: SM\_executeStringByLocalParser は利用できないので注意する。
72:
73: oxc\_open は、計算サーバの起動に成功したら (CMO\_INT32, サーバID) を、失
74: 敗したらエラーオブジェクトをスタックに積む。例えば計算サーバが発見できな
75: かった場合にはエラーオブジェクトを積むことになる。コントロールサーバは
76: access(2) を用いて PATH から計算サーバを探す。もし見つからなければ、fork
77: をせずに、エラーオブジェクトをスタックに積む。
78:
79: コントロールサーバの実行形式は以下のオプションを許す。
80: \begin{verbatim}
81: --pass
82: --host
83: --port
84: \end{verbatim}
85: */
86:
87:
1.2 noro 88:
89: \subsection{OpenXM reset protocol}
90:
91: /*&jp
92: クライアントはコントロールサーバ経由でいつでもエンジンに signal を
93: 送ることができる. しかし, I/O 操作は通常バッファリングされている
94: ため, トラブルが生ずる場合がある. エンジンを安全にリセットするため
95: 次が必要である.
96:
1.1 noro 97: \begin{enumerate}
1.2 noro 98: \item 全ての OX メッセージは Java の意味で synchronized object である.
99:
100: \item エンジンのリセット後に送られるクライアントからの計算要求メッセージと
101: エンジンからの返答が正しく対応していなければならない.
102: \end{enumerate}
103:
104: {\tt SM\_control\_reset\_connection} は, エンジンの安全なリセットを
105: 行う一連の手続きを開始するための SM コマンドである.
106: クライアントから {\tt SM\_control\_reset\_connection} がコントロール
107: サーバに送られると, コントロールサーバは {\tt SIGUSR1} をエンジンに
108: 送る. 以後の手続きは次の通りである.
109:
110: \vskip 2mm
111: \noindent
112: {\it クライアント側}
113: \begin{enumerate}
114: \item {\tt SM\_control\_reset\_connection} をコントロールサーバに
115: 送った後, クライアントはリセット状態に入る. リセット状態では,
116: {\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす.
117: \item {\tt OX\_SYNC\_BALL} を受け取ったあと, クライアントは
118: {\tt OX\_SYNC\_BALL} をエンジンに送り, 通常状態に戻る.
119: \end{enumerate}
120:
121: \noindent
122: {\it エンジン側}
123: \begin{enumerate}
124: \item
125: {\tt SIGUSR1} をコントロールサーバから受け取ったら, エンジンは
126: リセット状態に入る. {\tt OX\_SYNC\_BALL} をクライアントに送る.
127: この時点でクライアントは既にリセット状態にあるので, この送信が
128: ブロックされることはない.
129: \item エンジンは
130: {\tt OX\_SYNC\_BALL} を受け取るまですべてのメッセージを読みとばす.
131: {\tt OX\_SYNC\_BALL} を受け取ったら通常状態に戻る.
132: \end{enumerate}
133: */
134: /*&eg
135: A client can send a signal to an engine by using the control channel
136: at any time. However, I/O operations are usually buffered,
137: which may cause troubles.
138: To reset an engine safely the following are required.
139:
140: \begin{enumerate}
141: \item Any OX message must be a synchronized object in the sense of Java.
142:
143: \item After restarting an engine, a request from a client
144: must correctly corresponds to the response from the engine.
145: \end{enumerate}
146:
147: {\tt SM\_control\_reset\_connection} is a stack machine command to
148: initiate a safe resetting of an engine.
149: The control server sends {\tt SIGUSR1} to the engine if it receives
150: {\tt SM\_control\_reset\_connection} from the client.
151: Under the OpenXM reset protocol, an engine and a client act as follows.
152:
153: \vskip 2mm
154: \noindent
155: {\it Client side}
156: \begin{enumerate}
157: \item After sending {\tt SM\_control\_reset\_connection} to the
158: control server, the client enters the resetting state. It discards all {\tt
159: OX} messages from the engine until it receives {\tt OX\_SYNC\_BALL}.
160: \item After receiving {\tt OX\_SYNC\_BALL} the client sends
161: {\tt OX\_SYNC\_BALL} to the engine and returns to the usual state.
162: \end{enumerate}
163:
164: \noindent
165: {\it Engine side}
166: \begin{enumerate}
167: \item
168: After receiving {\tt SIGUSR1} from the control server,
169: the engine enters the resetting state.
170: The engine sends {\tt OX\_SYNC\_BALL} to the client.
171: The operation does not block because
172: the client is now in the resetting state.
173: \item The engine discards all OX messages from the engine until it
174: receives {\tt OX\_SYNC\_BALL}. After receiving {\tt OX\_SYNC\_BALL}
175: the engine returns to the usual state.
176: \end{enumerate}
177: */
178:
179: /*&eg
180: Figure \ref{reset} illustrates the flow of data.
181: {\tt OX\_SYNC\_BALL} is a special OX message and
182: is used to mark the end of data remaining in the
183: I/O streams. After reading it, it is assured that each stream is empty
184: and that the subsequent request from a client correctly
185: corresponds to the response from the engine.
186: */
187: /*&jp
188: 図 \ref{reset} はデータの流れを示す.
189: {\tt OX\_SYNC\_BALL} は特殊な OX メッセージであり,
190: I/O stream に残るデータの終りを示す.
191: {\tt OX\_SYNC\_BALL} を読んだ後, それぞれの stream は空であり,
192: 後に続くクライアントからのリクエストと, エンジンからの返答が
193: 正しく対応する.
194: */
1.3 noro 195: \begin{figure}[htbp]
1.5 noro 196: \epsfxsize=10cm
197: \begin{center}
1.3 noro 198: \epsffile{reset.eps}
1.5 noro 199: \end{center}
1.3 noro 200: \caption{OpenXM reset procedure}
201: \label{reset}
202: \end{figure}
203:
1.2 noro 204: \subsection{Control message (SMObject/TCPIP/Control)}
205:
206: \begin{enumerate}
207: \item
208: \begin{verbatim}
209: SM_control_reset_connection
210: \end{verbatim}
211: /*&jp
212: コントロールサーバに, {\tt SIGUSR1} をエンジンに送るよう要求する.
213: */
214: /*&eg
215: It requests a control server to send {\tt SIGUSR1} to the engine.
216: The control server should immediately reply an acknowledgment to
217: the client.
218: */
219: Request:
1.1 noro 220: \begin{tabular}{|c|c|} \hline
221: {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection} \\
222: \hline
223: \end{tabular}
1.2 noro 224: Result:
1.1 noro 225: \begin{tabular}{|c|c|} \hline
226: {\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\
227: \hline
228: \end{tabular}
229:
230: \item
1.2 noro 231: \begin{verbatim}
232: SM_control_kill
233: \end{verbatim}
234: /*&jp
235: サーバはこのメッセージを受信したら
236: %ただちに返答をおくり,
237: すべてのファイルをクローズして終了する.
238: */
239: /*&eg
240: It requests a control server to terminate the engine and the control server
241: itself.
242: %The control server should immediately reply an acknowledgment to
243: %the client.
244: All files and streams should be closed before the termination of servers.
245: */
246: Request:
1.1 noro 247: \begin{tabular}{|c|c|} \hline
248: {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill} \\
249: \hline
1.4 noro 250: \end{tabular}\\
1.2 noro 251: Result: none.
1.1 noro 252: \end{enumerate}
253:
254: \medbreak
255: \noindent
1.2 noro 256: //&jp {\bf 例}: (シリアル番号は省略してある.)
257: //&eg {\bf Example}: (serial numbers are omitted.)
1.1 noro 258: \begin{verbatim}
259: 0 0 2 01 (OX_COMMAND)
260: 0 0 4 06 (SM_control_reset_connection)
261: \end{verbatim}
262:
1.2 noro 263: //&jp Reset に対する返事.
264: //&eg Reply to the reset request
1.1 noro 265: \begin{verbatim}
266: 0 0 2 02 (OX_DATA)
267: 0 0 0 2 (CMO_INT32)
268: 0 0 0 0 ( 0 )
269: \end{verbatim}
270:
271:
1.2 noro 272: //&jp 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が取られる.
273: //&eg {\tt OX\_SYNC\_BALL} are exchanged on the data channel for synchronization.
274:
1.1 noro 275: \begin{verbatim}
276: 0 0 2 03 (OX_SYNC_BALL)
277: \end{verbatim}
278:
1.7 ! takayama 279: \subsection{Notification from servers}
1.1 noro 280:
1.7 ! takayama 281: /*&jp
! 282: OpenXM サーバは, 可能であるかぎり寡黙である.
! 283: たとえばエラーをおこしても, エラーはサーバのエンジンスタックにつまれる
! 284: だけであり, サーバはクライアントが {\tt pop\_cmo} メッセージをおくらない
! 285: かぎり何も送信しない.
! 286: */
! 287: /*&eg
! 288: OpenXM servers try to be quiet as far as possible.
! 289: For example, engine errors of a server are only put on the engine stack and
! 290: the engine does not send error packets unless the client sends the message
! 291: {\tt pop\_cmo}.
! 292: */
! 293:
! 294: /*&jp
! 295: OpenXM はこの原則をやぶる例外的な方法を一つ用意している.
! 296: コントロールサーバは,
! 297: {\tt OX\_NOTIFY} ヘッダおよびそれにつづく {\tt OX\_DATA} パケットを送る
! 298: ことができる.
! 299: この機能は mathcap で禁止することも可能である.
! 300: */
! 301: /*&eg
! 302: OpenXM provides a method to break this principle.
! 303: Control server may send {\tt OX\_NOTIFY} header and an {\tt OX\_DATA} packet.
! 304: This transmission can be prohibited by mathcap.
! 305: */
! 306:
! 307: /*&jp
! 308: この機能をどのように使うか例をあげて説明しよう.
! 309: {\tt Asir} の {\tt ox\_plot} サーバは, quit ボタンをもっている.
! 310: quit ボタンがおされると canvas が消滅するが, エンジン自体は存在を
! 311: つづける. この状態で描画命令がくると,
! 312: エンジンスタックに, ``canvas does not exist'' というエラーがつまれる.
! 313: エンジンがこのエラーが生じたことを緊急に知らせたいときに
! 314: {\tt OX\_NOTIFY} を用いる.
! 315: */
! 316: /*&eg
! 317: Let us explain how to use {\tt OX\_NOTIFY}.
! 318: The {\tt ox\_plot} server of {\tt asir} has a quit button.
! 319: If the quit button is pressed, the canvas dissappears, but the engine
! 320: does not terminate.
! 321: If the client sends drawing messages without the canvas,
! 322: then the engine pushes
! 323: error packets ``canvas does not exist'' on the engine stack.
! 324: If the engine wants to notify the error to the client immediately,
! 325: the {\tt OX\_NOTIFY} message should be used.
! 326: */
! 327:
! 328: /*&jp
! 329: ここで, {\tt OX\_NOTIFY} をおくるのは, コントロールプロセスで
! 330: あることに注意しよう.
! 331: したがってエンジンはなんらかの方法で, コントロールサーバに
! 332: {\tt OX\_NOTIFY} をおくることを依頼しないといけない.
! 333: OpenXM の規格では,
! 334: ファイル {\tt /tmp/.ox\_notify.pid} に touch することでこれの
! 335: 一つの実現方法を与えている.
! 336: ここで {\tt pid} はエンジンのプロセス番号である.
! 337: コントロールサーバはファイル {\tt /tmp/.ox\_notify.pid} が
! 338: touch されたことを検出したら, クライアントに
! 339: {\tt OX\_NOTIFY} パケットおよび {\tt OX\_DATA} で {\tt cmo\_null} を送る.
! 340: エンジンはファイルを用いてコントロールサーバに急を知らせる以外に,
! 341: 共有メモリやシグナルを用いてしらせてもよい.
! 342: */
! 343: /*&eg
! 344: Let us note that it is the control process that sends {\tt OX\_NOTIFY}.
! 345: Therefore, the engine must ask the control server to send
! 346: {\tt OX\_NOTIFY}.
! 347: In the OpenXM, if the engine touches the file
! 348: {\tt /tmp/.ox\_notify.pid}, then the control server sends
! 349: the {\tt OX\_NOTIFY} header and the {\tt OX\_DATA} packet
! 350: of {\tt cmo\_null}.
! 351: Here, {\tt pid} is the process id of the engine.
! 352: Engines and control processes may use a shared memory or a signal
! 353: instead of the file {\tt /tmp.ox\_notify.pid}.
! 354: */
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to control.tex CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM / doc / OpenXM-specs