%% $OpenXM: OpenXM/doc/OpenXM-specs/communication-model.tex,v 1.12 2020/03/14 01:21:56 takayama Exp $
//&jp \section{ OpenXM の通信モデル}
//&eg \section{ Communication model of OpenXM}

/*&jp
われわれは, 数学プロセスがメッセージを
交換しながら計算が進行していくというモデルを想定して設計をすすめている.
各プロセスはスタックマシンであり, これを OX スタックマシンとよぶ.
数学プロセスの間の通信路の確保の仕方としては以下のように
いろいろな実現方法を想定している.
\begin{enumerate}
\item ファイルを介して通信する.
\item Library として直接リンクして通信する.
\item TCP/IP ソケットの利用.
\item Remote Procedure call の利用.
\item JAVA RMI.
\item マルチスレッドの利用.
\item PVM ライブラリの利用.
\item MPI ライブラリの利用.
\end{enumerate}

通信とはプロセス間のメッセージのやりとりである.
メッセージは論理的に次のような構造をもつ: 
*/
/*&eg
In our model of computation, mathematical processes proceed 
a computation by exchanging messages. Each process is a stack machine,
which is called an OX stack machine.
The following methods are possible to realize communications between
mathematical processes.
\begin{enumerate}
\item Communication by files.
\item Linking as a subroutine library.
\item TCP/IP streams.
\item Remote Procedure call.
\item JAVA RMI.
\item Multi-thread.
\item PVM library.
\item MPI library.
\end{enumerate}

In OpenXM communication means exchange of messages between processes.
A message has the following structure:
*/
/*&C
\begin{center}
\begin{tabular}{|c|c|c|}
\cline{1-2}
{\tt destination} & {\tt origin} &  \multicolumn{1}{}{}  \\ \hline
{\tt extension}&{\tt ox message\_tag}&{\tt message\_body} \\ 
\hline
\end{tabular}
\end{center}
*/
/*&jp
このメッセージを, OX message (OpenXM message object) とよぶ.
OX Message はトップレベルのメッセージ object であり,
仕様書では, さまざまなグループに属する object が登場する.
グループ名は, たとえば, OX Message/TCPIP/Primitive などと書く.
{\tt message\_body} の部分の仕様は, OX Message
の上位に位置する部分であり,  SMobject または CMObject がくる.
これらの object はタグをもち, そのタグ定数は {\tt SM\_} または
{\tt CMO\_} ではじまる. 
SMobject は, スタックマシンコマンドメッセージ object であり,
やはり, グループ分けされている.
各グループ名は,
SMobject/Primitive,  SMobject/Basic などと書く.
SMobject の構造は
サーバスタックマシンの節で詳しく説明する.
CMObject についてはすでに Primitive の CMObject の説明をしたが,
あとで CMObject レベル 1の説明をする.
OX Message の
{\tt ox message\_tag} の定数は {\tt OX\_} で始まる.
*/
/*&eg
We call it an OX message (OpenXM message object).
OX message is the top level message object.
The OX messages are classified into three types: DATA, COMMAND,
and SPECIAL. They are distinguished by {\tt ox message\_tag}.
The name of an ox message tag begins with  {\tt OX\_}.
Typical OX message tags are {\tt OX\_COMMAND} followed by
SMobject and {\tt OX\_DATA} followed by CMObject.
Each message object also has its tag. For SMobject, the name
of a tag begins with {\tt SM\_}. For CMObject, the name of
a tag begins with {\tt CMO\_}.
An SMobject represents a stack machine command and categorized
into several groups such as SMobject/Primitive, SMobject/Basic.
The details of SMobjects will be explained in Section \ref{sec:stackmachine}.
We have already explained the Primitive CMObjects.
We will describe the Basic CMObjects in Section \ref{sec:basic1}.
*/
//&jp \subsection{  OX Message の 表現方法 }
//&eg \subsection{  OX Messages }

/*&jp
OpenXM で各プロセスは
\begin{center}
(OXexpression を理解するスタックマシン) $+$ (xxx 言語で動くエンジン)
\end{center}
なるハイブリッド構成である.
このプロセスを, OX スタックマシンと呼ぶ.
ここでは, OX スタックマシンとやりとりするメッセージである,
OX Message を表現するための OXexpression, および,
スタックマシンの operator に対応する, SMobject を表現するための SMexpression
を定義しよう.
OX Message を スタックマシンコマンド,
SMobject を スタックマシンオペレータともよぶ.
*/

/*&eg
In OpenXM, each process may have a hybrid interface; 
it may accept and execute not only stack machine commands,
but also its original command sequences.
We call such a process an OX stack machine.
Here we introduce OXexpression and SMexpression 
to express OX messages and SM objects respectively.
*/

//&jp  \subsubsection{ OX メッセージの表現法 (Lisp 風) }
//&eg  \subsubsection{ Expressions of OX messages (Lisp like) }
/*&C
\begin{eqnarray*}
\mbox{OXexpression}  
&:& \quad
\mbox{\tt (} \mbox{\tt OX\_tag} \ 
[\mbox{ expression}]  \mbox{\tt )}\\
\mbox{expression}
&:& \quad  \mbox{SMexpression} \\
&   &|\   \mbox{CMOexpression} \\
\mbox{SMexpression}
&:&  \mbox{\tt (} \mbox{\tt SM\_tag} \ 
\{ \mbox{CMOexpression} \} \mbox{\tt )}\\
\end{eqnarray*}
*/
/*&jp
expression の各要素を区切るために {\tt ,} (コンマ) を用いてもよい.
{\tt OX\_tag} は {\tt OX\_} で始まる定数である.
{\tt SM\_tag} は {\tt SM\_} で始まるスタックマシンオペレータを識別する定数である.
発信元 AAA, 受信先 BBB を書く必要があるときは,
From AAA, To BBB, を OXexpression の前に書く.
必要なければ省略する.

たとえば, あとで説明する, CMO string ``Hello'' を スタックにプッシュする
表現は次のように書く:
*/

/*&eg
A comma `{\tt ,}' may be used to separate elements in an expression.
{\tt OX\_tag} is a constant which denotes an OX message tag.
{\tt SM\_tag} is a constant which denotes an SM command tag.
If a sender AAA or a receiver BBB has to be specified,
'From AAA' or 'To BBB' is written before the OXexpression.

For example the following expression means a request to
push a CMO string ``Hello''.
*/
/*&C
\begin{center}
(OX\_DATA, (CMO\_STRING, 5, "Hello"))
\end{center}
*/


/*&eg
The following expression means a request to execute
a local function ``hoge''.
*/

/*&C
\begin{center}
(OX\_DATA, (CMO\_STRING, 4, "hoge")) 
\end{center}
\begin{center}
(OX\_COMMAND, SM\_executeStringByLocalParser)
\end{center}
*/

/*&jp
標準エンコード法では, それぞれのタグは 32 bit (4 bytes) の
ネットワークバイトオーダでの整数として表現される.
*/
/*&eg
In our standard encoding method, each tag is expressed as
a 32 bit (4 bytes) integer with the network byte order.
*/

/*&C

*/

//&jp  \subsubsection{ OX メッセージの表現 (XML) }
//&eg  \subsubsection{ Expression of OX messages (XML) }

/*&jp
OX メッセージは XML で表現することも可能である.  次に例を示す.
*/
/*&eg
OX messages can be expressed by XML.  The following is an example.
*/
/*&C
\begin{verbatim}
<ox>
   <ox_data>
      <ox_serial> <int32> 0 </int32> </ox_serial>
      <cmo>  <cmo_string> 
                 <int32 for="length"> 5 </int32>
                 <string> "Hello" </string>
             </cmo_string>
      </cmo>
   </ox_data>
   <ox_command> 
       <ox_serial> <int32> 1 </int32> </ox_serial>
       <sm_popCMO/> 
   </ox_command>
</ox>
\end{verbatim}
*/

//&jp \subsection{OXexpression の 標準 encoding と TCP/IP ソケットによる実装法}
//&eg \subsection{Standard encoding of OXexpressions and an implementation by TCP/IP sockets}
/*&jp
通信の実現方法は通信路のとりかたによりかわるが,
論理構造は統一的にあつかわないといけない.
OXexpression はその論理構造を記述している.

ここでは OXexpression の標準 encoding の概略を説明する.
この encoding 法はTCP/IP ソケット用の encoding 法として
現在存在しているサーバに使用されている.
さらにOX スタックマシンの計算状態を制御するための, コントロールメッセージに
ついても説明する.


{\tt destination}, {\tt origin} の部分は, ソケットによる
peer to peer の接続なので省略する.
{\tt extension} フィールドは
{\tt message\_tag} フィールドの次にくる.
{\tt extension} フィールドは OX パケットのシリアル番号がはいる.
シリアル番号は {\tt int32} である.
この番号は, サーバがエラーを起こした場合, エラーをおこした,
OX パケットの番号を戻すのに主に利用される.
以下 {\tt extension} フィールドは, {\tt message\_tag} の
に含まれると理解し {\tt extension} フィールドは省略する.
したがってパケットは
次のように記述する
*/

/*&eg
The logical structure of OX messages are independent of implementations
of communication. The OXexpression represents the logical structure.
Here we explain an outline of the standard encoding scheme of OXexpression.
This encoding scheme is used to implement OpenXM protocols on TCP/IP sockets.
In addition, we also explain the control messages to control stack machines.

As the socket connection is peer to peer, {\tt destination} and {\tt origin}
are omitted.
The {\tt extension} field is placed after the {\tt message\_tag} field.
The {\tt extension} field consists of the serial number for OX message,
which is {\tt int32}.
The serial number is used to identify an OX message which caused
an error on a server.
In the following we regard the {\tt extension} as a component of
the {\tt message\_tag} field and omit the {\tt extension} field.
Thus OX messages are represented as follows.
*/
/*&C
\begin{center}
\begin{tabular}{|c|c|}
\hline
{\tt ox message\_tag}&{\tt message\_body} \\ 
\hline
\end{tabular}
\end{center}
*/
//&jp \noindent が, もっとこまかく見ると,
//&eg \noindent More precisely it has the following representation.
/*&C
\begin{center}
\begin{tabular}{|c|c|}
\hline
{\tt ox message\_tag}, \ {\tt serial number}&{\tt message\_body} \\ 
\hline
\end{tabular}
\end{center}
*/
/*&jp
\noindent
となっている.

グループ OX Message/TCPIP/Primitive の
{\tt ox message\_tag} としては次のものが用意されている.
*/
//&eg \noindent As {\tt ox message\_tag} the following are provided.

/*&C
@plugin/oxMessageTag.h
\begin{verbatim}
#define   OX_COMMAND         513
#define   OX_DATA            514

#define   OX_DATA_WITH_LENGTH  521
#define   OX_DATA_OPENMATH_XML 523
#define   OX_DATA_OPENMATH_BINARY 524
#define   OX_DATA_MP           525

#define   OX_SYNC_BALL       515
#define   OX_NOTIFY          516
\end{verbatim}
*/

/*&jp
通信路は 2 つ用意する.
1番目の通信路は
\verb+  OX_COMMAND +
および
\verb+   OX_DATA +
がながれる.
2番目の通信路 ({\tt control}と呼ぶ) には,
\verb+  OX_COMMAND + およびそれに続くコントロールコマンド
\verb+  SM_control_* +
またはコントロール関係のデータ, つまり header
\verb+   OX_DATA + ではじまりそれに続く CMO データ
がながれる.
これらをコントロールメッセージおよびコントロールメッセージの結果
メッセージと呼ぶ.
サンプルサーバでは, この 2 つの通信路を, 2 つのポートを用いて
実現している.


\verb+ OX_COMMAND + メッセージは次の形のパケットで表現される: \\
*/
/*&eg
Two streams are provided for communication between a client and a server.
One is the stream to exchange data and to send stack machine commands.
The other is the stream to control stack machines.
Messages on the latter stream are called control messages and
results of control messages. The sample server implements
the above two streams by using two ports on TCP/IP.

The stack machine command message has the following forms: \\
*/
/*&C
\noindent
\begin{tabular}{|c|c|}
\hline
{\tt OX\_COMMAND} & {\tt int32 function\_id} \\  \hline
{\it message\_tag} & {\it message\_body}
\\ \hline
\end{tabular}, \quad
({\tt OX\_COMMAND}, ({\tt SM\_*}))
\\
*/

//&jp \verb+ OX_DATA + メッセージは次の形のパケットで表現される: \\
//&eg CMO data message has the following form:\\
/*&C
\begin{tabular}{|c|c|}
\hline
{\tt OX\_DATA} &  {\tt CMO data} \\  \hline
{\it message\_tag} & {\it message\_body}\\ \hline
\end{tabular}, \quad
({\tt OX\_DATA}, {\sl CMObject} data)
\\
*/
//&jp コントロールメッセージは次の形のパケットで表現される: \\
//&eg The control message has the following form:\\
/*&C
\begin{tabular}{|c|c|}
\hline
{\tt OX\_COMMAND} & {\tt int32 function\_id}  \\  \hline
\end{tabular},  \quad
({\tt OX\_COMMAND},({\tt SM\_control\_*}))
\\
*/
/*&jp
コントロールメッセージは, 計算を中断したい, debug 用の スレッドを起動する,
debug モードを抜けたい, などの用途に利用する.
*/
/*&eg
The control message is used to interrupt a computation, to invoke
debugging threads, or to exit form the debugging mode.
*/

//&jp コントロールメッセージの結果メッセージは次の形のパケットで表現される: \\
//&eg The result of a control message has the following form:\\
/*&C
\begin{tabular}{|c|c|l|}
\hline
{\tt OX\_DATA} & {\tt CMO\_INT32} & {\tt int32 data} \\  \hline
\end{tabular}, \quad
({\tt OX\_DATA}, {\sl Integer32 } n)
\\
*/


/*&jp
{\tt int32 function\_id}
の部分に, サーバスタックマシン の operator に対応する番号がはいる.
グループ SMobject/Primitive および SMobject/Basic に属する
タグとして以下のものがある. 
*/
/*&eg
{\tt int32 function\_id} is the value of a stack machine command.
SM tags in SMobject/Primitive and SMobject/Basic and corresponding
values are as follows.
*/
/*&C
@plugin/oxFunctionId.h
\begin{verbatim}
#define SM_popSerializedLocalObject 258
#define SM_popCMO 262
#define SM_popString 263 

#define SM_mathcap 264
#define SM_pops 265
#define SM_setName 266
#define SM_evalName 267 
#define SM_executeStringByLocalParser 268 
#define SM_executeFunction 269
#define SM_beginBlock  270
#define SM_endBlock    271
#define SM_shutdown    272
#define SM_setMathCap  273
#define SM_executeStringByLocalParserInBatchMode 274
#define SM_getsp       275
#define SM_dupErrors   276

#define SM_nop   300      /* do nothing */

#define SM_control_kill 1024
#define SM_control_reset_connection  1030
\end{verbatim}
*/

//&jp \noindent たとえば,
//&eg \noindent For example
/*&C
\begin{center}
(OX\_COMMAND, SM\_pops)
\end{center}
*/
//&jp \noindent は
//&eg \noindent is encoded as follows.
/*&C
\begin{center}
\begin{tabular}{|c|c|}
\hline
{\tt int32} 513  &  {\tt int32} 265 \\
\hline
\end{tabular}
\end{center}
*/
//&jp とエンコードされる.

/*&jp
operator の詳細は次の節で説明する.
これらの定数の名前はインプリメントのとき短縮形で表現してもよい.
*/
/*&eg
The details of the operators are described in Section \ref{sec:stackmachine}.
Names of these constants may be represented by abbreviated forms.
*/

