version 1.1, 2000/01/20 08:52:46 |
version 1.13, 2020/03/14 01:21:56 |
|
|
%% $OpenXM$ |
%% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.12 2016/08/27 02:11:01 takayama Exp $ |
//&jp \section{コントロールメッセージ (SMObject/TCPIP/Control)} |
\section{Session Management} |
//&eg \section{Control message (SMObject/TCPIP/Control)} (This section has not been translated.) |
|
|
|
|
\subsection{Control server} |
/*&jp |
/*&jp |
|
OpenXM с, 罨<菴違鴻膣ゃ鴻泣若九勝号 |
|
。. |
|
|
|
OpenXM 泣若茫 2 ゃ I/O channel : 筝鴻荐膊若 |
|
с, 篁鴻荐膊九勝с. 九勝 channel 泣若九勝 |
|
潟潟篏帥. |
|
泣潟泣若 ({\tt oxmain.c}) с, 潟潟若<祉若 |
|
ャ祉鴻茵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} |
\begin{enumerate} |
\item |
\item OX <祉若吾 Java 潟 synchronized object с. |
サーバは {\tt SM\_control\_reset\_connection} |
|
メッセージを受信したら, 現在の計算を中断する. |
\item 潟吾潟祉緇ゃ≪潟荐膊荀羆<祉若吾 |
中断操作は細心の注意をもって行なわないといけない. |
潟吾潟菴膈罩c鎛上違. |
サンプルサーバ ({\tt oxmain.c})では, コントロールメッセージの |
\end{enumerate} |
処理は別のプロセスがおこなっており, SIGUSR1 割り込みをスタックマシンへ |
|
かける. |
{\tt SM\_control\_reset\_connection} , 潟吾潟絎祉 |
もしサーバがメッセージの通信中であれば, このコントロールメッセージ |
茵筝c膓紮 SM 潟潟с. |
をすぐには実行せず, メッセージ通信を終了するのを待つ. |
ゃ≪潟 {\tt SM\_control\_reset\_connection} 潟潟若 |
当然, メッセージを発信中に, このメッセージを送信してもいけない. |
泣若, 潟潟若泣若 {\tt SIGUSR1} 潟吾潟 |
(Java 風にいえば, すべての メッセージは synchronized object である.) |
. 篁ュ膓罨<с. |
また, たとえば file IO なども, 中断をうけてはならない, synchronized な |
|
操作であろう. |
\vskip 2mm |
クライアントがサーバに controlResetConnection コントロールメッセージを |
\noindent |
おくったら, サーバは, 現在の受信バッファをすべてクリアし, |
{\it ゃ≪潟} |
クライアントへ |
\begin{enumerate} |
{\tt OX\_SYNC\_BALL} |
\item {\tt SM\_control\_reset\_connection} 潟潟若泣若 |
を送る. |
c緇, ゃ≪潟祉倶ャ. 祉倶с, |
クライアントは, コントロールメッセージをおくったあと, |
{\tt OX\_SYNC\_BALL} 障с鴻<祉若吾茯帥違. |
待機モードに入り, {\tt OX\_SYNC\_BALL} |
\item {\tt OX\_SYNC\_BALL} c, ゃ≪潟 |
をうけとるまですべてのメッセージを読み飛ばす. |
{\tt OX\_SYNC\_BALL} 潟吾潟, 絽悟倶祉. |
クライアントは {\tt OX\_SYNC\_BALL} をうけとったら, |
\end{enumerate} |
サーバに {\tt OX\_SYNC\_BALL} を送る. |
|
サーバは, 最初の {\tt OX\_SYNC\_BALL} を投げたあと, |
\noindent |
待機モードに入り, |
{\it 潟吾喝} |
{\tt OX\_SYNC\_BALL} |
\begin{enumerate} |
をうけとるまですべてのメッセージを読み飛ばす. |
\item |
%% 最後に, サーバ |
{\tt SIGUSR1} 潟潟若泣若c, 潟吾潟 |
%% はすべての操作が終了したことを通知するため, |
祉倶ャ. {\tt OX\_SYNC\_BALL} ゃ≪潟. |
%% クライアントに |
鴻сゃ≪潟≪祉倶, 篆< |
%% {\tt OX\_SYNC\_BALL} を投げる. |
. |
\\ Request: |
\item 潟吾潟 |
|
{\tt OX\_SYNC\_BALL} 障с鴻<祉若吾茯帥違. |
|
{\tt OX\_SYNC\_BALL} c絽悟倶祉. |
|
\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 腥冴с, |
|
緇膓ゃ≪潟鴻, 潟吾潟菴膈 |
|
罩c鎛上. |
|
*/ |
|
\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 |
\begin{tabular}{|c|c|} \hline |
{\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection} \\ |
{\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_reset\_connection} \\ |
\hline |
\hline |
\end{tabular} |
\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 |
\begin{tabular}{|c|c|} \hline |
{\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\ |
{\tt int32 OX\_DATA} & {\tt CMO\_INT32} {\rm result} \\ |
\hline |
\hline |
\end{tabular} |
\end{tabular}\\ |
|
|
@@@ |
|
|
|
\item |
\item |
サーバはこのメッセージを受信したらただちにコントロールメッセージへの |
\begin{verbatim} |
返答をおくり, すべてのファイルをクローズして終了する. |
SM_control_kill |
\\ Request: |
\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 |
\begin{tabular}{|c|c|} \hline |
{\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill} \\ |
{\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill} \\ |
\hline |
\hline |
\end{tabular} |
\end{tabular}\\ |
\\ Result: |
Result: none. |
Empty \\ |
|
|
|
|
|
\end{enumerate} |
\end{enumerate} |
|
|
\medbreak |
\medbreak |
\noindent |
\noindent |
{\bf 例}: (シリアル番号は省略してある.)\ |
//&jp {\bf 箴}: (激≪垩ャ.) |
|
//&eg {\bf Example}: (serial numbers are omitted.) |
\begin{verbatim} |
\begin{verbatim} |
0 0 2 01 (OX_COMMAND) |
0 0 2 01 (OX_COMMAND) |
0 0 4 06 (SM_control_reset_connection) |
0 0 4 06 (SM_control_reset_connection) |
\end{verbatim} |
\end{verbatim} |
|
|
Reset に対する返事. |
%//&jp Reset 絲障菴篋. |
\begin{verbatim} |
%//&eg Reply to the reset request |
0 0 2 02 (OX_DATA) |
%\begin{verbatim} |
0 0 0 2 (CMO_INT32) |
%0 0 2 02 (OX_DATA) |
0 0 0 0 ( 0 ) |
%0 0 0 2 (CMO_INT32) |
\end{verbatim} |
%0 0 0 0 ( 0 ) |
|
%\end{verbatim} |
|
|
|
|
第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が |
//&jp 膃1c潟с罨< {\tt OX\_SYNC\_BALL} 篋ゆ. |
取られる. |
//&eg {\tt OX\_SYNC\_BALL} are exchanged on the data channel for synchronization. |
|
|
\begin{verbatim} |
\begin{verbatim} |
0 0 2 03 (OX_SYNC_BALL) |
0 0 2 03 (OX_SYNC_BALL) |
\end{verbatim} |
\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 帥潟c. |
|
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} , 潟潟若祉鴻 |
|
羈. |
|
c潟吾潟号, 潟潟若泣若 |
|
{\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}. |
|
*/ |