Annotation of OpenXM/doc/OpenXM-specs/control.tex, Revision 1.12
1.12 ! takayama 1: %% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.11 2016/08/22 09:23:31 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.12 ! takayama 184: Result: none. \\
1.10 takayama 185: /*&jp
186: すべてエンジンは reset protocol を実装することが推奨されるが,
187: 実装していない場合は, mathcap の第４引数の option list で
1.12 ! takayama 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
! 197: 注意: 古い実装(2000年以前)の control server, client では,
! 198: 次の形式の result code が戻ることを仮定している場合がある.
! 199: これら古い実装は更新することが必要である. \\
! 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
216: サーバはこのメッセージを受信したら
217: %ただちに返答をおくり,
218: すべてのファイルをクローズして終了する.
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.2 noro 237: //&jp {\bf 例}: (シリアル番号は省略してある.)
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.12 ! takayama 244: %//&jp Reset に対する返事.
! 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.2 noro 253: //&jp 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が取られる.
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
263: OpenXM サーバは, 可能であるかぎり寡黙である.
264: たとえばエラーをおこしても, エラーはサーバのエンジンスタックにつまれる
265: だけであり, サーバはクライアントが {\tt pop\_cmo} メッセージをおくらない
266: かぎり何も送信しない.
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
276: OpenXM はこの原則をやぶる例外的な方法を一つ用意している.
277: コントロールサーバは,
278: {\tt OX\_NOTIFY} ヘッダおよびそれにつづく {\tt OX\_DATA} パケットを送る
279: ことができる.
280: この機能は mathcap で禁止することも可能である.
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
289: この機能をどのように使うか例をあげて説明しよう.
290: {\tt Asir} の {\tt ox\_plot} サーバは, quit ボタンをもっている.
291: quit ボタンがおされると canvas が消滅するが, エンジン自体は存在を
292: つづける. この状態で描画命令がくると,
293: エンジンスタックに, ``canvas does not exist'' というエラーがつまれる.
294: エンジンがこのエラーが生じたことを緊急に知らせたいときに
295: {\tt OX\_NOTIFY} を用いる.
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
310: ここで, {\tt OX\_NOTIFY} をおくるのは, コントロールプロセスで
311: あることに注意しよう.
312: したがってエンジンはなんらかの方法で, コントロールサーバに
313: {\tt OX\_NOTIFY} をおくることを依頼しないといけない.
1.9 takayama 314: この方法は, OS によりいろいろな方法が可能だか,
315: たとえば, unix では
316: ファイル {\tt /tmp/.ox\_notify.pid} に touch することでこれを
317: 一つの実現することが可能である.
1.7 takayama 318: ここで {\tt pid} はエンジンのプロセス番号である.
319: コントロールサーバはファイル {\tt /tmp/.ox\_notify.pid} が
320: touch されたことを検出したら, クライアントに
321: {\tt OX\_NOTIFY} パケットおよび {\tt OX\_DATA} で {\tt cmo\_null} を送る.
322: エンジンはファイルを用いてコントロールサーバに急を知らせる以外に,
323: 共有メモリやシグナルを用いてしらせてもよい.
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>
![[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