[BACK]Return to README CVS log [TXT][DIR] Up to [local] / OpenXM / src / ox_toolkit

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

version 1.1, 1999/12/09 22:44:55 version 1.14, 2000/11/20 17:59:34
Line 1 
Line 1 
 # Author: 小原功任 @ 金沢大学理学部計算科学教室  # Author: 小原功任 @ 金沢大学理学部計算科学教室
 # URI:    http://omega.s.kanazawa-u.ac.jp/ohara/  # URI:    http://omega.s.kanazawa-u.ac.jp/ohara/
 # $OpenXM$  # $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 オブジェクト  このツールキットで定義されている各構造体の生成については次節を参照せよ。
   
   1.1 CMO (Common Math Object)
 次のデータ型(構造体)が用意されている。  次のデータ型(構造体)が用意されている。
   */
   /*&en
   1. Types
   
   1.1 CMO (Common Math Object)
   The following structures are defined in ox_toolkit.h:
   */
   /*&common
   
 cmo  cmo
 cmo_null  cmo_null
 cmo_int32  cmo_int32
Line 43  cmo_distributed_polynomial
Line 61  cmo_distributed_polynomial
 cmo_indeterminate  cmo_indeterminate
 cmo_error2  cmo_error2
   
   */
   /*&ja
 このうち cmo 型はいわば抽象基底クラスに相当するものであり、この型のオ  このうち cmo 型はいわば抽象基底クラスに相当するものであり、この型のオ
 ブジェクトをつくってはいけない。また cmo_distributed_polynomial は  ブジェクトを明示的には生成されない。このクラスはポインタ型のキャストの
 cmo_list の派生クラスであると思ってもよい。ユーザはオブジェクトの実体を  ために用意されている。また cmo_distributed_polynomial は cmo_list の派
 直接扱ってはならない。必ず、new_... 関数、すなわち  生クラスであると思ってもよい。
   
   */
   /*&en
   The cmo above is abstract base class; you never make an object of cmo
   class.
   
   */
   /*&ja
   1.2 OX オブジェクト
   次のデータ型(構造体)が用意されている。
   */
   /*&en
   1.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
   2. オブジェクトの生成
   
   オブジェクトを生成するために、new 関数群が用意されている。それぞれの関
   数はオブジェクトを生成して、そのオブジェクトへのポインタを返す。
   */
   /*&en
   2. 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_null();
 new_cmo_int32(int i);  new_cmo_int32(int i);
 new_cmo_string(char* s);  new_cmo_string(char* s);
Line 66  new_cmo_ring_by_name(cmo* ob);
Line 127  new_cmo_ring_by_name(cmo* ob);
 new_cmo_indeterminate(cmo* ob);  new_cmo_indeterminate(cmo* ob);
 new_cmo_error2(cmo* ob);  new_cmo_error2(cmo* ob);
   
 によってオブジェクトを生成し、ユーザはポインタのみを扱うこと。  */
   /*&ja
   3. コネクション
   
 ☆ OX オブジェクト  OXFILE は OpenXM での通信路を表現するクラスである。このクラスのオブジェ
 次のデータ型(構造体)が用意されている。  クトを明示的には生成しないこと。必ずコンストラクタを利用しなければなら
   ない。これはクライアントとサーバで接続時の手順が異なることに由来する。
   バイトオーダに関連した処理はこのクラスのメソッドで実現される。このクラ
   スのメソッドとして次のものが用意されている。
   
 ox  3.1 コンストラクタ
 ox_command  
 ox_data  
   
 このうち、ox 型は抽象基底クラスなので、オブジェクトをつくってはいけない。  OXFILE *oxf_connect_active(char *hostname, short port);
   
   能動的に接続する場合のコンストラクタ。通常、サーバで利用する。
   
   OXFILE *oxf_connect_passive(int listened);
   
   受動的に接続するためのコンストラクタ。
   内部で accept() を呼ぶので、listened には mysocketListen() の返した値が必要。
   
   OXFILE *oxf_open(int fd);
   
   インスタンスを生成するだけで、接続は行わない。すでにオープンされたファ
   イルディスクリプタを fd に指定する。計算サーバでの利用を想定。
   
   3.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.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
   4. 高水準 API(この記述は古いので使わないこと)
   
   高水準 API は「OpenXM クライアント」から利用することを前提に設計されている。
   
   4.1 通信の開始
   
   通信を開始する場合には、次の関数のいずれかを利用する。
   */
   /*&en
   4. High-level API
   
   High-level API is prepared to help an implementation of OpenXM clients.
   
   4.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")、
   prog1 はコントロールサーバの実行ファイル名、
   prog2 は計算サーバの実行ファイル名でなければならない。
   
   第二の関数は、リモートマシン上に既に起動されている OpenXM サーバとの間に
   通信路を開設する。通信に使われるポート番号は明示的に与えなければならない。
   host はリモートマシンのホスト名、
   portControl はコントロールサーバとの通信のためのポート番号、
   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
   4.2 通信の終了
   
   通信の終了のためには次の二つの関数が用意されている。
   
   */
   /*&en
   4.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 を送ることに
   よって、サーバを終了させる(予定)。
   
   */
   /*&ja
   4.3 SM コマンドの送信
   */
   /*&en
   4.3 How to command to OpenXM stack machines?
   */
   /*&common
   
   void  ox_push_cmd(OXFILE *sv, int sm_code);
   
   */
   /*&ja
   サーバにスタックマシンコマンドを送る。コマンドはコマンド番号で与える。
   
   */
   /*&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.
   
   */
   /*&ja
   4.4 CMO の送受信
   */
   /*&en
   4.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 を文字列形式に変換して受信するが、変換の結果はサーバによって異
   なる。
   
   */
   /*&en
   */
   /*&ja
   4.5 スタック処理
   */
   /*&common
   
   int ox_pops(OXFILE *sv, int num);
   
   */
   /*&ja
   スタック上の num 個のオブジェクトを廃棄する。
   
   */
   /*&ja
   4.6 通信路のフラッシュ
   */
   /*&common
   
   int ox_flush(OXFILE *sv);
   
   */
   /*&ja
   通信路を flush する(実際には何もしない)。
   
   */
   /*&ja
   4.7 通信の中断
   */
   /*&common
   
   void ox_reset(OXFILE *sv);
   
   */
   /*&ja
   計算を中断する。
   
   */
   /*&ja
   4.8 ローカル言語で書かれたコマンドの評価
   */
   /*&common
   
   void ox_execute_string(OXFILE *sv, char* str);
   
   */
   /*&ja
   サーバのローカル言語で書かれた命令を評価し、結果をスタックに積む。
   
   */
   /*&ja
   4.9 関数呼び出し
   */
   /*&common
   
   int ox_cmo_rpc(OXFILE *sv, char *function, int argc, cmo *argv[]);
   
   */
   /*&ja
   function(argv[1], ...) を計算し、結果をスタックに積む。
   
   */
   /*&ja
   4.10 Mathcap の受信
   
   */
   /*&common
   cmo_mathcap* ox_mathcap(OXFILE *sv);
   
   */
   /*&ja
   Mathcap を受け取る。現在は Mathcap の処理はユーザプログラムに任されている。
   いずれこの関数は廃止される予定。
   */
   /*&ja
   
   5. 低水準 API
   
   低水準 API はファイルディスクリプタを直接利用する。
   
   5.1 通信に使われるバイトオーダの決定
   */
   /*&en
   
   5. Low-level API.
   
   In this section, ``fd'' is an identifier of an OpenXM connection.
   
   5.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
   
   5.2
   
   */
   /*&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
   
   5.3
   
   */
   /*&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
   
   5.4
   
   */
   /*&common
   int next_serial();
   
   */
   /*&ja
   シリアルナンバを生成する。
   */
   /*&en
   next_serial() generates a serial number for ox message.
   */
   /*&common
   
   5.5
   
   */
   /*&common
   int  send_ox_tag(int fd, int tag);
   int  receive_ox_tag(int fd);
   
   */
   /*&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
   
   5.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);
   
   */
   /*&ja
   OX メッセージを送信する。
   */
   
   /*&ja
   
   6. OX expression パーサ
   
   */
   /*&en
   
   6. 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
   
   6.1 Setting an option
   */
   /*&ja
   
   6.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
   
   6.2 Initializing
   */
   /*&ja
   
   6.2 初期化
   */
   /*&common
   
   int init_parser(char *str);
   
   */
   /*&ja
   パーサが処理すべき文字列をセットする。
   */
   /*&en
   We give the parser an OX/CMO expression, that is, a Lisp style string.
   */
   /*&en
   
   6.3 Getting an object
   */
   /*&ja
   
   6.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
   
   7. Mathcap データベース
   
   7.1. 概要
   
   Mathcap データベースは、各通信路ごとに生成される局所データベースと、通
   信路に関係なく保持される大域データベースからなる。大域データベースは、
   局所データベースの生成時に初期値としても利用される。局所データベースと
   $大域データベースの関係は次のように理解すればよい。すなわち、Mathcap ク
   ラスのインスタンスが局所データベースであり、静的メンバが大域データベー
   スである。
   
   7.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 データベー
   スを更新する。
   
   7.3. ox_toolkit における実装の問題点(obsolete)
   
   現在はシステム全体で一つの Mathcap データベースしかもたないような実装
   になっている。ところが、OpenXM クライアントは複数の計算サーバと同時に
   接続されることが許されている。これらの計算サーバは同種あるいは異種であ
   るが、異種の場合、それら OX サーバの許容する CMO の範囲は異なる。した
   がって、計算サーバごとに Mathcap データベースをもつ必要がある。具体的
   には OXFILE クラスの(static ではない)メンバになるような実装でなければ
   ならない。
   */
   /*&ja
   
   8. 付属プログラムについて
   
   */
   /*&en
   
   8. 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
   9. 付録
   
   9.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 関数を呼び出す.
   
   */
   
Legend:
Removed from v.1.1  
changed lines
  Added in v.1.14
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>