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.3 and 1.14

-version 1.3, 1999/12/15 02:44:12
+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.2 1999/12/15 01:59:58 ohara Exp $
+ # $OpenXM: OpenXM/src/ox_toolkit/README,v 1.13 2000/10/11 20:34:28 ohara Exp $
- ☆ libox.a マニュアル。
+ /*&ja ox_toolkit ユーザガイド
- libox.a を利用するには次のヘッダファイルをインクルードする必要があります。
+ */
+ /*&en A user's guide for OpenXM C library.
- #include <oxtag.h>
+ */
- #include <ox.h>
+ /* &ja いきさつ
- #include <parse.h>
+ このライブラリは ox_math および math2ox を開発するために設計された。
+ ライブラリ自身には、 Mathematica に依存した部分はない。
+ */
+ /* &en Introduction
- 各構造体および関数の宣言はそれぞれのヘッダファイルを見てください。
+ */
- ここでは基本的な考え方について説明します。
+ /*&ja
+ libox.a を利用するには次のヘッダファイルをインクルードする必要があります。
+ */
+ /*&en
+ How to use OpenXM C library?
- まず、すべての CMO データはそのデータ型に対応した new 関数によって生成
+ In order to use libox.a, you need to include the following header files:
- します。たとえば CMO_ZZ 型のオブジェクトは new_cmo_zz() 関数によって生
+ */
- 成されます。
+ /*&common
- CMO データを送受信するには、CMO の種類によらず send_cmo(),
+ #include <ox_toolkit.h>
- receive_cmo() を用います。これらの関数は OX ヘッダを扱いませんので、OX
- メッセージを送受信するときには send_ox_tag(), receive_ox_tag() をその
- 前に呼ぶ必要があります。
+ */
+ /*&ja
 . データ型
  このツールキットで定義されている各構造体の生成については次節を参照せよ。
 .1 CMO (Common Math Object)
  次のデータ型(構造体)が用意されている。
+ */
+ /*&en
+. Types
+.1 CMO (Common Math Object)
+ The following structures are defined in ox_toolkit.h:
+ */
+ /*&common
  cmo
  cmo_null
  cmo_int32
-Line 46  cmo_distributed_polynomial
+Line 61  cmo_distributed_polynomial
 Line 46  cmo_distributed_polynomial
 Line 61  cmo_distributed_polynomial
  cmo_indeterminate
  cmo_error2
+ */
+ /*&ja
  このうち cmo 型はいわば抽象基底クラスに相当するものであり、この型のオ
  ブジェクトを明示的には生成されない。このクラスはポインタ型のキャストの
  ために用意されている。また cmo_distributed_polynomial は cmo_list の派
  生クラスであると思ってもよい。
+ */
+ /*&en
+ The cmo above is abstract base class; you never make an object of cmo
+ class.
+ */
+ /*&ja
 .2 OX オブジェクト
  次のデータ型(構造体)が用意されている。
+ */
+ /*&en
+.2 OX objects
+ The following structures are defined in ox_toolkit.h:
+ */
+ /*&common
  ox
  ox_command
  ox_data
+ */
+ /*&ja
  このうち、ox 型は抽象基底クラスなので、オブジェクトをつくってはいけない。
+ */
+ /*&en
+ The ox above is abstract base class.
+ */
+ /*&ja
 . オブジェクトの生成
  オブジェクトを生成するために、new 関数群が用意されている。それぞれの関
  数はオブジェクトを生成して、そのオブジェクトへのポインタを返す。
+ */
+ /*&en
+. How to make CMObjects?
+ Use the following functions to generate an object.  It returns a
+ pointer to the object.  */ /*&common
  new_cmo_null();
  new_cmo_int32(int i);
  new_cmo_string(char* s);
-Line 83  new_cmo_ring_by_name(cmo* ob);
+Line 127  new_cmo_ring_by_name(cmo* ob);
 Line 83  new_cmo_ring_by_name(cmo* ob);
 Line 127  new_cmo_ring_by_name(cmo* ob);
  new_cmo_indeterminate(cmo* ob);
  new_cmo_error2(cmo* ob);
-. 高水準 API
+ */
+ /*&ja
+. コネクション
+ 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
- ox_file_t ox_start(char* host, char* prog1, char* prog2);
+ High-level API is prepared to help an implementation of OpenXM clients.
- ox_file_t ox_start_insecure_nonreverse(char* host, short portControl, short portStream);
+.1 How to make connections to OpenXM servers?
+ In order to open a connection to an OpenXM server, you need to call
+ ox_start() or to call ox_start_insecure_nonreverse().
+ */
+ /*&common
+ OXFILE *ox_start(char* host, char* prog1, char* prog2);
+ OXFILE *ox_start_insecure_nonreverse(char* host, short portControl, short portStream);
+ */
+ /*&ja
  第一の関数は、ローカルマシン上に OpenXM サーバを起動し、そのサーバとの
  間に"reverse モード"で通信路を開設する。通信に使われるポート番号は自動
  的に生成される。host はローカルマシンのホスト名(あるいは "localhost")、
-Line 109  portStream は計算サーバとの通信のためのポート番号であ�
+Line 223  portStream は計算サーバとの通信のためのポート番号であ�
 Line 109  portStream は計算サーバとの通信のためのポート番号であ�
 Line 223  portStream は計算サーバとの通信のためのポート番号であ�
  それぞれの関数はサーバ(正確には二つのサーバの組)の識別子を返す。
  この識別子は高水準 API の各関数で利用される。
-.2 通信の終了
+ */
+ /*&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 通信の終了
  通信の終了のためには次の二つの関数が用意されている。
- void ox_close(ox_file_t sv);
+ */
- void ox_shutdown(ox_file_t sv);
+ /*&en
+.2 How to close connections to OpenXM servers?
+ 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(OXFILE *sv);
+ void ox_shutdown(OXFILE *sv);
+ */
+ /*&ja
  第一の関数はコントロールサーバに SM_control_kill を送ることによって、
  サーバを終了させる。第二の関数は計算サーバに SM_shutdown を送ることに
  よって、サーバを終了させる(予定)。
-.3 SM コマンドの送信
+ */
+ /*&ja
+.3 SM コマンドの送信
+ */
+ /*&en
+.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
  サーバにスタックマシンコマンドを送る。コマンドはコマンド番号で与える。
-.4 CMO の送受信
+ */
+ /*&en
+ ox_push_cmd() sends an operation code to an OpenXM stack machine.
+ See OpenXM/include/ox_toolkit_tags.h for a list of operation codes.
- void  ox_push_cmo(ox_file_t sv, cmo *c);
+ */
- cmo*  ox_pop_cmo(ox_file_t sv);
+ /*&ja
- char* ox_popString(ox_file_t sv);
+.4 CMO の送受信
+ */
+ /*&en
+.4 How to receive a CMO?
+ */
+ /*&common
+ void  ox_push_cmo(OXFILE *sv, cmo *c);
+ cmo*  ox_pop_cmo(OXFILE *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 はファイルディスクリプタを直接利用する。
 .1 通信に使われるバイトオーダの決定
+ */
+ /*&en
+. 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);
+ */
+ /*&ja
  このツールキットは、サーバが開始されるときにはすでに通信路が設定されて
  いるが、その通信路に用いるバイトオーダの決定は行われていないと仮定して
  いる。詳しくは、高山-野呂, "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
+ */
+ /*&common
  int send_int32(int fd, int integer);
- fd に 32bit 整数を書き込む。
  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
+ */
+ /*&common
  int  send_cmo(int fd, cmo* m);
- fd に cmo を書き込む。
  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>