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 の第４引数の 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>
![[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