=================================================================== RCS file: /home/cvs/OpenXM/doc/OpenXM-specs/control.tex,v retrieving revision 1.1.1.1 retrieving revision 1.13 diff -u -p -r1.1.1.1 -r1.13 --- OpenXM/doc/OpenXM-specs/control.tex 2000/01/20 08:52:46 1.1.1.1 +++ OpenXM/doc/OpenXM-specs/control.tex 2020/03/14 01:21:56 1.13 @@ -1,89 +1,340 @@ -%% $OpenXM$ -//&jp \section{コントロールメッセージ (SMObject/TCPIP/Control)} -//&eg \section{Control message (SMObject/TCPIP/Control)} (This section has not been translated.) +%% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.12 2016/08/27 02:11:01 takayama Exp $ +\section{Session Management} +\subsection{Control server} /*&jp +OpenXM с, 罨＜菴違鴻膣ゃ鴻泣若九勝号 +｡. + +OpenXM 泣若茫 2 ゃ I/O channel : 筝鴻荐膊若 +с, 篁鴻荐膊九勝с. 九勝 channel 泣若九勝 +潟潟篏帥. +泣潟泣若 ({\tt oxmain.c}) с, 潟潟若＜祉若 +ャ祉鴻茵ｃ. 篁ヤ, 祉鴻潟潟若泣若 +若. 絲障, 荐膊泣若潟吾潟若. +潟潟若泣若潟吾潟筝激割у篏. +, 潟潟若泣若潟吾潟 signal 絎号с. +潟潟若泣若篏 OX 鴻帥激潟с +{\tt SM\_control\_*} 潟潟. 潟吾潟吾 +signal 篆, engine process 腟篋 request 潟潟с. +*/ + +/*&eg +In OpenXM we adopted the following simple and robust method to +control servers. + +An OpenXM server has logically two I/O channels: one for exchanging +data for computations and the other for controlling computations. The +control channel is used to send commands to control execution on the +nserver. The sample server ({\tt oxmain.c}) processes such control +messages on another process. We call such a process a {\it +control server}. In contrast, we call a server for computation an {\it +engine}. As the control server and the engine runs on the +same machine, it is easy to send a signal from the control server. +A control server is also an +OpenXM stack machine and it accepts {\tt SM\_control\_*} commands +to send signals to a server or to terminate a server. +*/ + +\subsection{New OpenXM control servers} +/*&jp +OpenXM RFC 101 Draft 荀 +\htmladdnormallink{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}. +*/ +/*&eg +See OpenXM RFC 101 Draft. +\htmladdnormallink{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}{http://www.math.kobe-u.ac.jp/OpenXM/OpenXM-RFC.html}. +*/ + +\subsection{OpenXM reset protocol} + +/*&jp +ゃ≪潟潟潟若泣若腟宴сゃс潟吾潟 signal +с. , I/O 篏絽吾＜潟違 +, 翫. 潟吾潟絎祉 +罨＜綽荀с. + \begin{enumerate} -\item -サーバは {\tt SM\_control\_reset\_connection} -メッセージを受信したら, 現在の計算を中断する. -中断操作は細心の注意をもって行なわないといけない. -サンプルサーバ ({\tt oxmain.c})では, コントロールメッセージの -処理は別のプロセスがおこなっており, SIGUSR1 割り込みをスタックマシンへ -かける. -もしサーバがメッセージの通信中であれば, このコントロールメッセージ -をすぐには実行せず, メッセージ通信を終了するのを待つ. -当然, メッセージを発信中に, このメッセージを送信してもいけない. -(Java 風にいえば, すべての メッセージは synchronized object である.) -また, たとえば file IO なども, 中断をうけてはならない, synchronized な -操作であろう. -クライアントがサーバに controlResetConnection コントロールメッセージを -おくったら, サーバは, 現在の受信バッファをすべてクリアし, -クライアントへ -{\tt OX\_SYNC\_BALL} -を送る. -クライアントは, コントロールメッセージをおくったあと, -待機モードに入り, {\tt OX\_SYNC\_BALL} -をうけとるまですべてのメッセージを読み飛ばす. -クライアントは {\tt OX\_SYNC\_BALL} をうけとったら, -サーバに {\tt OX\_SYNC\_BALL} を送る. -サーバは, 最初の {\tt OX\_SYNC\_BALL} を投げたあと, -待機モードに入り, -{\tt OX\_SYNC\_BALL} -をうけとるまですべてのメッセージを読み飛ばす. -%% 最後に, サーバ -%% はすべての操作が終了したことを通知するため, -%% クライアントに -%% {\tt OX\_SYNC\_BALL} を投げる. -\\ Request: +\item OX ＜祉若吾 Java 潟 synchronized object с. + +\item 潟吾潟祉緇ゃ≪潟荐膊荀羆＜祉若吾 +潟吾潟菴膈罩ｃ鎛上違. +\end{enumerate} + +{\tt SM\_control\_reset\_connection} , 潟吾潟絎祉 +茵筝ｃ膓紮 SM 潟潟с. +ゃ≪潟 {\tt SM\_control\_reset\_connection} 潟潟若 +泣若, 潟潟若泣若 {\tt SIGUSR1} 潟吾潟 +. 篁ュ膓罨＜с. + +\vskip 2mm +\noindent +{\it ゃ≪潟} +\begin{enumerate} +\item {\tt SM\_control\_reset\_connection} 潟潟若泣若 +ｃ緇, ゃ≪潟祉倶ャ. 祉倶с, +{\tt OX\_SYNC\_BALL} 障с鴻＜祉若吾茯帥違. +\item {\tt OX\_SYNC\_BALL} ｃ, ゃ≪潟 +{\tt OX\_SYNC\_BALL} 潟吾潟, 絽悟倶祉. +\end{enumerate} + +\noindent +{\it 潟吾喝} +\begin{enumerate} +\item +{\tt SIGUSR1} 潟潟若泣若ｃ, 潟吾潟 +祉倶ャ. {\tt OX\_SYNC\_BALL} ゃ≪潟. +鴻сゃ≪潟≪祉倶, 篆＜ +. +\item 潟吾潟 +{\tt OX\_SYNC\_BALL} 障с鴻＜祉若吾茯帥違. +{\tt OX\_SYNC\_BALL} ｃ絽悟倶祉. +\end{enumerate} +*/ +/*&eg +A client can send a signal to an engine by using the control channel +at any time. However, I/O operations are usually buffered, +which may cause troubles. +To reset an engine safely the following are required. + +\begin{enumerate} +\item Any OX message must be a synchronized object in the sense of Java. + +\item After restarting an engine, a request from a client +must correctly corresponds to the response from the engine. +\end{enumerate} + +{\tt SM\_control\_reset\_connection} is a stack machine command to +initiate a safe resetting of an engine. +The control server sends {\tt SIGUSR1} to the engine if it receives +{\tt SM\_control\_reset\_connection} from the client. +Under the OpenXM reset protocol, an engine and a client act as follows. + +\vskip 2mm +\noindent +{\it Client side} +\begin{enumerate} +\item After sending {\tt SM\_control\_reset\_connection} to the +control server, the client enters the resetting state. It discards all {\tt +OX} messages from the engine until it receives {\tt OX\_SYNC\_BALL}. +\item After receiving {\tt OX\_SYNC\_BALL} the client sends +{\tt OX\_SYNC\_BALL} to the engine and returns to the usual state. +\end{enumerate} + +\noindent +{\it Engine side} +\begin{enumerate} +\item +After receiving {\tt SIGUSR1} from the control server, +the engine enters the resetting state. +The engine sends {\tt OX\_SYNC\_BALL} to the client. +The operation does not block because +the client is now in the resetting state. +\item The engine discards all OX messages from the engine until it +receives {\tt OX\_SYNC\_BALL}. After receiving {\tt OX\_SYNC\_BALL} +the engine returns to the usual state. +\end{enumerate} +*/ + +/*&eg +Figure \ref{reset} illustrates the flow of data. +{\tt OX\_SYNC\_BALL} is a special OX message and +is used to mark the end of data remaining in the +I/O streams. After reading it, it is assured that each stream is empty +and that the subsequent request from a client correctly +corresponds to the response from the engine. +*/ +/*&jp + \ref{reset} 若帥羌腓冴. +{\tt OX\_SYNC\_BALL} 号 OX ＜祉若吾с, +I/O stream 罧若帥腟腓冴. +{\tt OX\_SYNC\_BALL} 茯緇, stream 腥冴с, +緇膓ゃ≪潟鴻, 潟吾潟菴膈 +罩ｃ鎛上. +*/ +\begin{figure}[htbp] +\epsfxsize=10cm +\begin{center} +\epsffile{reset.eps} +\end{center} +\caption{OpenXM reset procedure} +\label{reset} +\end{figure} + +\subsection{Control message (SMObject/TCPIP/Control)} + +\begin{enumerate} +\item +\begin{verbatim} +SM_control_reset_connection +\end{verbatim} +/*&jp +潟潟若泣若, {\tt SIGUSR1} 潟吾潟荀羆. +*/ +/*&eg +It requests a control server to send {\tt SIGUSR1} to the engine. +The control server should immediately reply an acknowledgment to +the client. +*/ +Request: \begin{tabular}{|c|c|} \hline {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection} \\ \hline \end{tabular} -\\ Result: +Result: none. \\ +/*&jp + 鴻潟吾潟 reset protocol 絎茖ｨ絅, +絎茖翫, mathcap 膃鐚綣違 option list +{\tt no\_ox\_reset} 篆＜鴻с (: oxpari). \\ +*/ +/*&eg + All engines are encouraged to install the reset protocol, +but when it is not implemented, +{\tt no\_ox\_reset} option should be included in the fourth argument +(option list) of the mathcap (ref: oxpari). \\ +*/ +/*&jp +羈: ゃ絎茖(2000綛岩札) control server, client с, +罨＜綵√ result code 祉篁絎翫. +ゃ絎茖贋違綽荀с. \\ +*/ +/*&eg +Note: Some old implementations of control servers and clients (before 2000) +assume the result code of the following format. +These obsolete implementations should be updated.\\ +*/ \begin{tabular}{|c|c|} \hline {\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\ \hline -\end{tabular} +\end{tabular}\\ -@@@ - \item -サーバはこのメッセージを受信したらただちにコントロールメッセージへの -返答をおくり, すべてのファイルをクローズして終了する. -\\ Request: +\begin{verbatim} +SM_control_kill +\end{verbatim} +/*&jp +泣若＜祉若吾篆＜ +%＜菴膈, +鴻＜ゃ若冴腟篋. +*/ +/*&eg +It requests a control server to terminate the engine and the control server +itself. +%The control server should immediately reply an acknowledgment to +%the client. +All files and streams should be closed before the termination of servers. +*/ +Request: \begin{tabular}{|c|c|} \hline {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill} \\ \hline -\end{tabular} -\\ Result: -Empty \\ - - +\end{tabular}\\ +Result: none. \end{enumerate} \medbreak \noindent -{\bf 例}: (シリアル番号は省略してある.)\ +//&jp {\bf 箴}: (激≪垩ャ.) +//&eg {\bf Example}: (serial numbers are omitted.) \begin{verbatim} 0 0 2 01 (OX_COMMAND) 0 0 4 06 (SM_control_reset_connection) \end{verbatim} -Reset に対する返事. -\begin{verbatim} -0 0 2 02 (OX_DATA) -0 0 0 2 (CMO_INT32) -0 0 0 0 ( 0 ) -\end{verbatim} +%//&jp Reset 絲障菴篋. +%//&eg Reply to the reset request +%\begin{verbatim} +%0 0 2 02 (OX_DATA) +%0 0 0 2 (CMO_INT32) +%0 0 0 0 ( 0 ) +%\end{verbatim} -第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が -取られる. +//&jp 膃1ｃ潟с罨＜ {\tt OX\_SYNC\_BALL} 篋ゆ. +//&eg {\tt OX\_SYNC\_BALL} are exchanged on the data channel for synchronization. + \begin{verbatim} 0 0 2 03 (OX_SYNC_BALL) \end{verbatim} +\subsection{Notification from servers} + +/*&jp +OpenXM 泣若, 純с絲♂с. +違若, 若泣若潟吾潟鴻帥ゃ障 +с, 泣若ゃ≪潟 {\tt pop\_cmo} ＜祉若吾 +篏篆＜. */ +/*&eg +OpenXM servers try to be as quiet as possible. +For example, engine errors of a server are only put on the engine stack and +the engine does not send error packets unless the client sends the message +{\tt pop\_cmo}. +*/ +/*&jp +OpenXM 吟箴紊号筝ょ. +潟潟若泣若, +{\tt OX\_NOTIFY} 潟ゃャ {\tt OX\_DATA} 宴 +с. +罘純 mathcap х罩≪純с. +*/ +/*&eg +OpenXM provides a method to notify events. +Control server may send {\tt OX\_NOTIFY} header and an {\tt OX\_DATA} packet. +This transmission may be prohibited by mathcap. +*/ +/*&jp +罘純篏帥箴茯. +{\tt Asir} {\tt ox\_plot} 泣若, quit 帥潟ｃ. +quit 帥潟 canvas 羔羯, 潟吾活篏絖 +ゃャ. 倶ф糸巡擦, +潟吾潟鴻帥, ``canvas does not exist'' 若ゃ障. +潟吾潟若膩ャャ +{\tt OX\_NOTIFY} . +*/ +/*&eg +Let us explain how to use {\tt OX\_NOTIFY} by an example. +The {\tt ox\_plot} server of {\tt asir} has a quit button. +If the quit button is pressed, the canvas dissappears, but the engine +does not terminate. +If the client sends drawing messages without the canvas, +then the engine pushes +error packets ``canvas does not exist'' on the engine stack. +If the engine wants to notify the error to the client immediately, +the {\tt OX\_NOTIFY} message should be used. +*/ + +/*&jp +, {\tt OX\_NOTIFY} , 潟潟若祉鴻 +羈. +ｃ潟吾潟号, 潟潟若泣若 +{\tt OX\_NOTIFY} 箴若. +号, OS 号純, +, unix с +＜ゃ {\tt /tmp/.ox\_notify.pid} touch с +筝ゃ絎憗純с. + {\tt pid} 潟吾潟祉合垩с. +潟潟若泣若＜ゃ {\tt /tmp/.ox\_notify.pid} +touch 罎冴, ゃ≪潟 +{\tt OX\_NOTIFY} 宴 {\tt OX\_DATA} {\tt cmo\_null} . +潟吾潟＜ゃ潟潟若泣若ャャ篁ュ, +掩＜≪激違. +*/ +/*&eg +Let us note that only the control process is allowed to send {\tt OX\_NOTIFY}. +Therefore, the engine must ask the control server to send +{\tt OX\_NOTIFY}. +Methods to ask the control process from the engine +depends on operating system. +In case of unix, one method is the use of a file; +for instance, +if the engine touches the file +{\tt /tmp/.ox\_notify.pid}, then the control server sends +the {\tt OX\_NOTIFY} header and the {\tt OX\_DATA} packet +of {\tt cmo\_null}. +Here, {\tt pid} is the process id of the engine. +Engines and control processes may use a shared memory or a signal +instead of the file {\tt /tmp/.ox\_notify.pid}. +*/