OpenXM/src/ox_toolkit/README - diff

Return to README CVS log

Up to [local] / OpenXM / src / ox_toolkit

Diff for /OpenXM/src/ox_toolkit/README between version 1.4 and 1.14

-version 1.4, 1999/12/15 08:04:50
+version 1.14, 2000/11/20 17:59:34
 Line 1
 Line 1
 Line 1
  # Author: 小原功任 @ 金沢大学理学部計算科学教室
  # URI:    http://omega.s.kanazawa-u.ac.jp/ohara/
- # $OpenXM: OpenXM/src/ox_toolkit/README,v 1.3 1999/12/15 02:44:12 ohara Exp $
+ # $OpenXM: OpenXM/src/ox_toolkit/README,v 1.13 2000/10/11 20:34:28 ohara Exp $
  /*&ja ox_toolkit ユーザガイド
  */
- /*&en A user's guide for ox_toolkit.
+ /*&en A user's guide for OpenXM C library.
  */
+ /* &ja いきさつ
+ このライブラリは ox_math および math2ox を開発するために設計された。
+ ライブラリ自身には、 Mathematica に依存した部分はない。
+ */
+ /* &en Introduction
+ */
  /*&ja
  libox.a を利用するには次のヘッダファイルをインクルードする必要があります。
  */
  /*&en
  How to use OpenXM C library?
- The OpenXM C libraiy has header files:
+ In order to use libox.a, you need to include the following header files:
  */
  /*&common
- #include <oxtag.h>
+ #include <ox_toolkit.h>
- #include <ox.h>
- #include <parse.h>
  */
  /*&ja
-Line 35  The OpenXM C libraiy has header files:
+Line 40  The OpenXM C libraiy has header files:
 Line 35  The OpenXM C libraiy has header files:
 Line 40  The OpenXM C libraiy has header files:
 . Types
 .1 CMO (Common Math Object)
- The following structures is defined in ox.h:
+ The following structures are defined in ox_toolkit.h:
  */
  /*&common
-Line 65  cmo_error2
+Line 70  cmo_error2
 Line 65  cmo_error2
 Line 70  cmo_error2
  */
  /*&en
- The cmo above is similer to abstract base class;
+ The cmo above is abstract base class; you never make an object of cmo
- you never make an object of cmo class.
+ class.
  */
  /*&ja
-Line 75  you never make an object of cmo class.
+Line 80  you never make an object of cmo class.
 Line 75  you never make an object of cmo class.
 Line 80  you never make an object of cmo class.
  */
  /*&en
 .2 OX objects
- The following structures is defined in ox.h:
+ The following structures are defined in ox_toolkit.h:
  */
  /*&common
-Line 101  The ox above is abstract base class.
+Line 106  The ox above is abstract base class.
 Line 101  The ox above is abstract base class.
 Line 106  The ox above is abstract base class.
  /*&en
 . How to make CMObjects?
- You may use new functions which generate an object and return its pointer.
+ Use the following functions to generate an object.  It returns a
- */
+ pointer to the object.  */ /*&common
- /*&common
  new_cmo_null();
  new_cmo_int32(int i);
-Line 125  new_cmo_error2(cmo* ob);
+Line 129  new_cmo_error2(cmo* ob);
 Line 125  new_cmo_error2(cmo* ob);
 Line 129  new_cmo_error2(cmo* ob);
  */
  /*&ja
-. 高水準 API
+. コネクション
+ OXFILE は OpenXM での通信路を表現するクラスである。このクラスのオブジェ
+ クトを明示的には生成しないこと。必ずコンストラクタを利用しなければなら
+ ない。これはクライアントとサーバで接続時の手順が異なることに由来する。
+ バイトオーダに関連した処理はこのクラスのメソッドで実現される。このクラ
+ スのメソッドとして次のものが用意されている。
+.1 コンストラクタ
+ OXFILE *oxf_connect_active(char *hostname, short port);
+ 能動的に接続する場合のコンストラクタ。通常、サーバで利用する。
+ OXFILE *oxf_connect_passive(int listened);
+ 受動的に接続するためのコンストラクタ。
+ 内部で accept() を呼ぶので、listened には mysocketListen() の返した値が必要。
+ OXFILE *oxf_open(int fd);
+ インスタンスを生成するだけで、接続は行わない。すでにオープンされたファ
+ イルディスクリプタを fd に指定する。計算サーバでの利用を想定。
+.2 認証に関連したメソッド
+ int  oxf_confirm_client(OXFILE *oxfp, char *passwd);
+ クライアント側での認証を行う。返り値が1のときに成功、0のときに失敗。
+ int  oxf_confirm_server(OXFILE *oxfp, char *passwd);
+ サーバ側での認証を行う。常に成功する。
+ void oxf_determine_byteorder_client(OXFILE *oxfp);
+ void oxf_determine_byteorder_server(OXFILE *oxfp);
+ oxfp の指す通信路でのバイトオーダを決定し、oxfp のインスタンスを書き換える。
+ void oxf_setopt(OXFILE *oxfp, int mode);
+ oxfp の設定を行う。oxf_determine_byteorder_XXX() で用いられている。
+.3 その他のメソッド
+ int oxf_read(void *buffer, size_t size, size_t num, OXFILE *oxfp);
+ int oxf_write(void *buffer, size_t size, size_t num, OXFILE *oxfp);
+ void oxf_flush(OXFILE *oxfp);
+ void oxf_close(OXFILE *oxfp);
+ fread, fwrite, fflush, fclose に準拠。
+ */
+ /*&ja
+. 高水準 API(この記述は古いので使わないこと)
  高水準 API は「OpenXM クライアント」から利用することを前提に設計されている。
 .1 通信の開始
  通信を開始する場合には、次の関数のいずれかを利用する。
  */
  /*&en
 . High-level API
- High-level API is prepared for implementation of your OpenXM clients.
+ High-level API is prepared to help an implementation of OpenXM clients.
-.1 How to make connection to OpenXM server?
+.1 How to make connections to OpenXM servers?
- You may call ox_start or ox_start_insecure_nonreverse.
+ In order to open a connection to an OpenXM server, you need to call
+ ox_start() or to call ox_start_insecure_nonreverse().
  */
  /*&common
- ox_file_t ox_start(char* host, char* prog1, char* prog2);
+ OXFILE *ox_start(char* host, char* prog1, char* prog2);
- ox_file_t ox_start_insecure_nonreverse(char* host, short portControl, short portStream);
+ OXFILE *ox_start_insecure_nonreverse(char* host, short portControl, short portStream);
  */
  /*&ja
-Line 165  portStream は計算サーバとの通信のためのポート番号であ�
+Line 224  portStream は計算サーバとの通信のためのポート番号であ�
 Line 165  portStream は計算サーバとの通信のためのポート番号であ�
 Line 224  portStream は計算サーバとの通信のためのポート番号であ�
  この識別子は高水準 API の各関数で利用される。
  */
+ /*&en
+ The ox_start() function invoke an OpenXM server on its local machine
+ and open a connection to the server with "reverse" mode.  The client
+ choose a port number of TCP/IP automatically.
+ The ox_start_insecure_nonreverse() function open a connection to an
+ OpenXM server run on a remote host and you need to provide port numbers.
+ */
  /*&ja
 .2 通信の終了
  通信の終了のためには次の二つの関数が用意されている。
  */
  /*&en
-.2 How to close connection to OpenXM server?
+.2 How to close connections to OpenXM servers?
- You may call ox_close or ox_shutdown.
+ In order to close a connection to an OpenXM server, you need to call
+ ox_close() or to call ox_shutdown().
  */
  /*&common
- void ox_close(ox_file_t sv);
+ void ox_close(OXFILE *sv);
- void ox_shutdown(ox_file_t sv);
+ void ox_shutdown(OXFILE *sv);
  */
  /*&ja
-Line 187  void ox_shutdown(ox_file_t sv);
+Line 256  void ox_shutdown(ox_file_t sv);
 Line 187  void ox_shutdown(ox_file_t sv);
 Line 256  void ox_shutdown(ox_file_t sv);
  サーバを終了させる。第二の関数は計算サーバに SM_shutdown を送ることに
  よって、サーバを終了させる(予定)。
- /*
+ */
  /*&ja
 .3 SM コマンドの送信
  */
  /*&en
-.3 How to command to OpenXM stack machine?
+.3 How to command to OpenXM stack machines?
  */
  /*&common
- void  ox_push_cmd(ox_file_t sv, int sm_code);
+ void  ox_push_cmd(OXFILE *sv, int sm_code);
  */
  /*&ja
  サーバにスタックマシンコマンドを送る。コマンドはコマンド番号で与える。
  */
  /*&en
- This function send operation code to an OpenXM stack machine.
+ ox_push_cmd() sends an operation code to an OpenXM stack machine.
- Table of opecode is defined in oxtag.h.
+ See OpenXM/include/ox_toolkit_tags.h for a list of operation codes.
  */
  /*&ja
 .4 CMO の送受信
+ */
+ /*&en
+.4 How to receive a CMO?
+ */
+ /*&common
- void  ox_push_cmo(ox_file_t sv, cmo *c);
+ void  ox_push_cmo(OXFILE *sv, cmo *c);
- cmo*  ox_pop_cmo(ox_file_t sv);
+ cmo*  ox_pop_cmo(OXFILE *sv);
- char* ox_popString(ox_file_t sv);
+ char* ox_popString(OXFILE *sv);
+ */
+ /*&ja
  ox_push_cmo は cmo を送信、ox_pop_cmo は cmo を受信する。ox_popString
  は cmo を文字列形式に変換して受信するが、変換の結果はサーバによって異
  なる。
-.5 スタック処理
+ */
+ /*&en
+ */
+ /*&ja
+.5 スタック処理
+ */
+ /*&common
- int ox_pops(ox_file_t sv, int num);
+ int ox_pops(OXFILE *sv, int num);
+ */
+ /*&ja
  スタック上の num 個のオブジェクトを廃棄する。
-.6
+ */
+ /*&ja
+.6 通信路のフラッシュ
+ */
+ /*&common
- int ox_flush(ox_file_t sv);
+ int ox_flush(OXFILE *sv);
+ */
+ /*&ja
  通信路を flush する(実際には何もしない)。
-.7
+ */
+ /*&ja
+.7 通信の中断
+ */
+ /*&common
- void ox_reset(ox_file_t sv);
+ void ox_reset(OXFILE *sv);
+ */
+ /*&ja
  計算を中断する。
-.8
+ */
+ /*&ja
+.8 ローカル言語で書かれたコマンドの評価
+ */
+ /*&common
- void ox_execute_string(ox_file_t sv, char* str);
+ void ox_execute_string(OXFILE *sv, char* str);
+ */
+ /*&ja
  サーバのローカル言語で書かれた命令を評価し、結果をスタックに積む。
-.9
+ */
+ /*&ja
+.9 関数呼び出し
+ */
+ /*&common
- int   ox_cmo_rpc(ox_file_t sv, char *function, int argc, cmo *argv[]);
+ int ox_cmo_rpc(OXFILE *sv, char *function, int argc, cmo *argv[]);
+ */
+ /*&ja
  function(argv[1], ...) を計算し、結果をスタックに積む。
-.10
+ */
+ /*&ja
+.10 Mathcap の受信
- cmo_mathcap* ox_mathcap(ox_file_t sv);
+ */
+ /*&common
+ cmo_mathcap* ox_mathcap(OXFILE *sv);
+ */
+ /*&ja
  Mathcap を受け取る。現在は Mathcap の処理はユーザプログラムに任されている。
  いずれこの関数は廃止される予定。
  */
  /*&ja
-. 低水準 API
+. 低水準 API
  低水準 API はファイルディスクリプタを直接利用する。
 .1 通信に使われるバイトオーダの決定
  */
  /*&en
-. Low-level API.
-.1 How to decide a byte order of integers?
+. Low-level API.
+ In this section, ``fd'' is an identifier of an OpenXM connection.
+.1 How to decide a byte order of integers?
  */
  /*&common
  int decideByteOrderServer(int fd, int order);
-Line 281  int decideByteOrderServer(int fd, int order);
+Line 397  int decideByteOrderServer(int fd, int order);
 Line 281  int decideByteOrderServer(int fd, int order);
 Line 397  int decideByteOrderServer(int fd, int order);
  いる。詳しくは、高山-野呂, "OpenXM の設計と実装" を参照せよ。
  (注意) クライアント側でのバイトオーダの設定は、高水準 API で自動的に行われる。
  */
+ /*&en
+ You need to call it when your OpenXM server is initialized.
+ This function always choose the network byte order
+ as an expression for integers.
+ */
  /*&common
-.2
- int send_int32(int fd, int integer);
+.2
  */
- /*&ja
- fd に 32bit 整数を書き込む。
- */
  /*&common
+ int send_int32(int fd, int integer);
  int receive_int32(int fd);
  */
  /*&ja
+ fd に 32bit 整数を書き込む。
  fd から 32bit 整数を読み込む。
  */
+ /*&en
+ send_int32() writes 32bits integer to an OpenXM connection.
+ receive_int32() reads 32bits integer from an OpenXM connection.
+ */
  /*&common
-.3
- int  send_cmo(int fd, cmo* m);
+.3
  */
- /*&ja
- fd に cmo を書き込む。
- */
  /*&common
+ int  send_cmo(int fd, cmo* m);
  cmo* receive_cmo(int fd);
  */
  /*&ja
+ fd に cmo を書き込む。
  fd から cmo を読み込む。
+ */
+ /*&en
+ send_cmo() writes an CMObject to an OpenXM connection.
+ receive_cmo() reads an CMObject from an OpenXM connection.
+ */
+ /*&common
 .4
+ */
+ /*&common
  int next_serial();
+ */
+ /*&ja
  シリアルナンバを生成する。
+ */
+ /*&en
+ next_serial() generates a serial number for ox message.
+ */
+ /*&common
 .5
+ */
+ /*&common
  int  send_ox_tag(int fd, int tag);
- fd に OX メッセージのヘッダ(tag+id)を書き込む。
- シリアル番号は自動的に生成される。
  int  receive_ox_tag(int fd);
- fd から OX メッセージのヘッダ(tag+id)を読み込む。
+ */
+ /*&ja
+ fd に OX メッセージのヘッダ(tag+serial#)を書き込む。シリアル番号は
+ 自動的に生成される。
+ fd から OX メッセージのヘッダ(tag+serial#)を読み込む。
+ */
+ /*&en
+ send_ox_tag() writes a tag and an automatically generated serial number
+ of an ox message to an OpenXM conection.
+ receive_ox_tag() reads a tag and a serial number of an ox message.
+ */
+ /*&common
-.6
+.6 Sending OX messages.
+ */
+ /*&common
  int  send_ox(int fd, ox* m);
  int  send_ox_cmo(int fd, cmo* m);
  void send_ox_command(int fd, int sm_command);
- ox メッセージを送信する。
- */
+ */
+ /*&ja
+ OX メッセージを送信する。
+ */
+ /*&ja
+. OX expression パーサ
+ */
+ /*&en
+. Parser for OX expressions
+ */
+ /*&ja
+ OpenXM C library には 文字列表現された OX expression および CMO
+ expression から、ox 構造体または cmo 構造体を生成するためのパーサが付
+ 属している。ここではこのパーサについて説明する。
+ */
+ /*&en
+ We have a parser which generate an OX object or a CMO from a string
+ encoded OX/CMO expression.  In this section, we explain the parser.
+ */
+ /*&en
+.1 Setting an option
+ */
+ /*&ja
+.1 オプション
+ */
+ /*&common
+ int setflag_parse(int flag);
+ */
+ /*&ja
+ setflag_parse(PFLAG_ADDREV) によって、CMO の短縮表現を許す。
+ */
+ /*&en
+ We set an option for the parser.  If we call
+ setflag_parse(PFLAG_ADDREV), then the parser admits external
+ expressios.
+ */
+ /*&en
+.2 Initializing
+ */
+ /*&ja
+.2 初期化
+ */
+ /*&common
+ int init_parser(char *str);
+ */
+ /*&ja
+ パーサが処理すべき文字列をセットする。
+ */
+ /*&en
+ We give the parser an OX/CMO expression, that is, a Lisp style string.
+ */
+ /*&en
+.3 Getting an object
+ */
+ /*&ja
+.3 結果を得る
+ */
+ /*&common
+ cmo *parse();
+ */
+ /*&ja
+ Lisp 表現による OX expression, CMO expression の構文解析器。あらかじめ
+ 設定された文字列を解析して ox 構造体、あるいは cmo 構造体を生成する。
+ */
+ /*&en
+ The parser returns an OX/CMO object.  If the given string is illegal,
+ then the parser returns NULL.
+ */
+ /*&ja
+. Mathcap データベース
+.1. 概要
+ Mathcap データベースは、各通信路ごとに生成される局所データベースと、通
+ 信路に関係なく保持される大域データベースからなる。大域データベースは、
+ 局所データベースの生成時に初期値としても利用される。局所データベースと
+ $大域データベースの関係は次のように理解すればよい。すなわち、Mathcap ク
+ ラスのインスタンスが局所データベースであり、静的メンバが大域データベー
+ スである。
+.2. メソッド
+ Mathcap データベースは mathcap.c で実装されている。ユーザは次の関数を
+ 介して、Mathcap データベースにアクセスすることができる。
+ void mathcap_global_init(int version, char *id, char *sysname, int cmo[], sm_cmd[]);
+ 大域データベースを初期化する。クライアントおよびサーバはプログラムを開
+ 始するときに、この関数を呼ばなければならない。cmo は CMO のタグのリス
+ トであって、0 で終端しなければならない。sm_cmd も同様。
+ cmo_mathcap *mathcap_get(mathcap *this);
+ Mathcap クラスのインスタンスを cmo_mathcap クラスのインスタンスに変換する。
+ mathcap *mathcap_update(mathcap *this, cmo_mathcap *mc);
+ 通信相手から入手したcmo_mathcap オブジェクトを用いて、Mathcap データベー
+ スを更新する。
+.3. ox_toolkit における実装の問題点(obsolete)
+ 現在はシステム全体で一つの Mathcap データベースしかもたないような実装
+ になっている。ところが、OpenXM クライアントは複数の計算サーバと同時に
+ 接続されることが許されている。これらの計算サーバは同種あるいは異種であ
+ るが、異種の場合、それら OX サーバの許容する CMO の範囲は異なる。した
+ がって、計算サーバごとに Mathcap データベースをもつ必要がある。具体的
+ には OXFILE クラスの(static ではない)メンバになるような実装でなければ
+ ならない。
+ */
+ /*&ja
+. 付属プログラムについて
+ */
+ /*&en
+. Sample programs.
+ */
+ /*&common
+ testclient
+ */
+ /*&ja
+ テスト用の小さな OpenXM クライアント。OX expression を入力して送信する
+ ことのみ可能。SM_popCMO, SM_popString を含むメッセージを送信した場合に
+ は、サーバから送られてくるメッセージを表示する。
+ */
+ /*&en
+ This is a small OpenXM client.  We send an OX message by inputting an
+ OX expression and display data messages gotten from a server.
+ */
+ /*&common
+ bconv
+ */
+ /*&ja
+ バイトコードエンコーダ。OX expression あるいは CMO expression を入力す
+ ると、対応するバイト列を表示する。
+ */
+ /*&en
+ A byte code encoder.  It shows a byte stream which corresponds to an
+ OX expression.
+ */
+ /*&common
+ ox_Xsample
+ */
+ /*&ja
+ GUI 表示する OpenXM サーバのサンプル。
+ */
+ /*&ja
+. 付録
+.1 ox.c における関数の命名規則
+ (1) receive_cmo 関数はCMOタグとデータ本体を受信する. この関数は CMOタ
+ グの値が事前に分からないときに使用する. 返り値として、cmo へのポインタ
+ を返す.
+ (2) receive_cmo_X 関数は, CMOタグを親の関数で受信してから呼び出される
+ 関数で、データ本体のみを受信し、cmo_X へのポインタを返す.  しかも、関
+ 数内部で new_cmo_X 関数を呼び出す.
+ (3) send_cmo 関数はCMOタグとデータ本体を送信する.
+ (4) send_cmo_X 関数はCMOタグを親の関数で送信してから呼び出される関数で、
+ データ本体のみを送信する.
+ (5) ただし receive_ox_tag を除いて, receive_ox_X 関数は作らない.
+ receive_cmo を利用する.
+ (6) send_ox_X 関数は OX タグを含めて送信する.
+ (7) ox_X 関数は一連の送受信を含むより抽象的な操作を表現する.  ox_X 関
+ 数は、第一引数として、ox_file_t型の変数 sv をとる.
+ (8) Y_cmo 関数と Y_cmo_X 関数の関係は次の通り:
+ まず Y_cmo 関数で cmo のタグを処理し、タグを除いた残りの部分をY_cmo_X
+ 関数が処理する.  cmo の内部に cmo_Z へのポインタがあるときには、その種
+ 類によらずに Y_cmo 関数を呼び出す.
+ */

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>