=================================================================== RCS file: /home/cvs/OpenXM/doc/OpenXM-specs/control.tex,v retrieving revision 1.2 retrieving revision 1.12 diff -u -p -r1.2 -r1.12 --- OpenXM/doc/OpenXM-specs/control.tex 2000/01/23 00:41:08 1.2 +++ OpenXM/doc/OpenXM-specs/control.tex 2016/08/27 02:11:01 1.12 @@ -1,4 +1,4 @@ -%% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.1.1.1 2000/01/20 08:52:46 noro Exp $ +%% $OpenXM: OpenXM/doc/OpenXM-specs/control.tex,v 1.11 2016/08/22 09:23:31 takayama Exp $ \section{Session Management} \subsection{Control server} @@ -26,7 +26,7 @@ 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 -server. The sample server ({\tt oxmain.c}) processes such control +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 @@ -36,6 +36,16 @@ OpenXM stack machine and it accepts {\tt SM\_control\_ 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 @@ -126,13 +136,6 @@ the engine returns to the usual state. \end{enumerate} */ -\begin{figure}[htbp] -\epsfxsize=17cm -\epsffile{reset.eps} -\caption{OpenXM reset procedure} -\label{reset} -\end{figure} - /*&eg Figure \ref{reset} illustrates the flow of data. {\tt OX\_SYNC\_BALL} is a special OX message and @@ -149,6 +152,15 @@ I/O 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} @@ -169,11 +181,32 @@ Request: {\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 \begin{verbatim} @@ -195,7 +228,7 @@ Request: \begin{tabular}{|c|c|} \hline {\tt int32 OX\_COMMAND} & {\tt int32 SM\_control\_kill} \\ \hline -\end{tabular} +\end{tabular}\\ Result: none. \end{enumerate} @@ -208,13 +241,13 @@ Result: none. 0 0 4 06 (SM_control_reset_connection) \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} +%//&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} //&jp 第1のチャンネルでは次の {\tt OX\_SYNC\_BALL} が交換されて同期が取られる. @@ -224,4 +257,84 @@ Result: none. 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}. +*/