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

version 1.6, 1999/12/22 11:29:15

version 1.14, 2000/11/20 17:59:34

Line 1

# Author: 小原功任 @ 金沢大学理学部計算科学教室

# URI: http://omega.s.kanazawa-u.ac.jp/ohara/

# $OpenXM: OpenXM/src/ox_toolkit/README,v 1.5 1999/12/15 09:24:46 ohara Exp $

# $OpenXM: OpenXM/src/ox_toolkit/README,v 1.13 2000/10/11 20:34:28 ohara Exp $

/*&ja ox_toolkit ユーザガイド

Line 8

/*&en A user's guide for OpenXM C library.

/* &ja いきさつ

このライブラリは ox_math および math2ox を開発するために設計された。

ライブラリ自身には、 Mathematica に依存した部分はない。

/* &en Introduction

/*&ja

libox.a を利用するには次のヘッダファイルをインクルードする必要があります。

Line 18 In order to use libox.a, you need to include the follo

Line 25 In order to use libox.a, you need to include the follo

/*&common

#include <oxtag.h>

#include <ox_toolkit.h>

#include <ox.h>

#include <parse.h>

/*&ja

Line 35 In order to use libox.a, you need to include the follo

Line 40 In order to use libox.a, you need to include the follo

1. Types

1.1 CMO (Common Math Object)

The following structures are defined in ox.h:

The following structures are defined in ox_toolkit.h:

/*&common

Line 65 cmo_error2

Line 70 cmo_error2

/*&en

The cmo above is 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.

/*&en

1.2 OX objects

The following structures are 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.

/*&en

2. How to make CMObjects?

Use the following functions to generate an object.

Use the following functions to generate an object. It returns a

It returns a pointer to the object.

pointer to the object. */ /*&common

/*&common

new_cmo_null();

new_cmo_int32(int i);

Line 126 new_cmo_error2(cmo* ob);

Line 129 new_cmo_error2(cmo* ob);

/*&ja

3. 高水準 API

3. コネクション

OXFILE は OpenXM での通信路を表現するクラスである。このクラスのオブジェ

クトを明示的には生成しないこと。必ずコンストラクタを利用しなければなら

ない。これはクライアントとサーバで接続時の手順が異なることに由来する。

バイトオーダに関連した処理はこのクラスのメソッドで実現される。このクラ

スのメソッドとして次のものが用意されている。

3.1 コンストラクタ

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 クライアント」から利用することを前提に設計されている。

3.1 通信の開始

4.1 通信の開始

通信を開始する場合には、次の関数のいずれかを利用する。

/*&en

3. High-level API

4. High-level API

High-level API is prepared to help an implementation of OpenXM clients.

3.1 How to make connections to OpenXM servers?

4.1 How to make connections to OpenXM servers?

In order to open a connection to an OpenXM server,

In order to open a connection to an OpenXM server, you need to call

you need to call ox_start() or to call ox_start_insecure_nonreverse().

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 167 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

3.2 通信の終了

4.2 通信の終了

通信の終了のためには次の二つの関数が用意されている。

/*&en

3.2 How to close connections to OpenXM servers?

4.2 How to close connections to OpenXM servers?

In order to close a connection to an OpenXM server,

In order to close a connection to an OpenXM server, you need to call

you need to call ox_close() or to call ox_shutdown().

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 190 void ox_shutdown(ox_file_t sv);

Line 256 void ox_shutdown(ox_file_t sv);

サーバを終了させる。第二の関数は計算サーバに SM_shutdown を送ることに

よって、サーバを終了させる(予定)。

/*&ja

3.3 SM コマンドの送信

4.3 SM コマンドの送信

/*&en

3.3 How to command to OpenXM stack machines?

4.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

ox_push_cmd() sends an operation code to an OpenXM stack machine.

See oxtag.h.

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

3.4 CMO の送受信

void ox_push_cmo(OXFILE *sv, cmo *c);

cmo* ox_pop_cmo(OXFILE *sv);

char* ox_popString(OXFILE *sv);

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);

ox_push_cmo は cmo を送信、ox_pop_cmo は cmo を受信する。ox_popString

は cmo を文字列形式に変換して受信するが、変換の結果はサーバによって異

なる。

3.5 スタック処理

/*&en

/*&ja

4.5 スタック処理

/*&common

int ox_pops(ox_file_t sv, int num);

int ox_pops(OXFILE *sv, int num);

/*&ja

スタック上の num 個のオブジェクトを廃棄する。

3.6

/*&ja

4.6 通信路のフラッシュ

/*&common

int ox_flush(ox_file_t sv);

int ox_flush(OXFILE *sv);

/*&ja

通信路を flush する(実際には何もしない)。

3.7

/*&ja

4.7 通信の中断

/*&common

void ox_reset(ox_file_t sv);

void ox_reset(OXFILE *sv);

/*&ja

計算を中断する。

3.8

/*&ja

4.8 ローカル言語で書かれたコマンドの評価

/*&common

void ox_execute_string(ox_file_t sv, char* str);

void ox_execute_string(OXFILE *sv, char* str);

/*&ja

サーバのローカル言語で書かれた命令を評価し、結果をスタックに積む。

3.9

/*&ja

4.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], ...) を計算し、結果をスタックに積む。

3.10

/*&ja

4.10 Mathcap の受信

cmo_mathcap* ox_mathcap(ox_file_t sv);

/*&common

cmo_mathcap* ox_mathcap(OXFILE *sv);

/*&ja

Mathcap を受け取る。現在は Mathcap の処理はユーザプログラムに任されている。

いずれこの関数は廃止される予定。

/*&ja

4. 低水準 API

5. 低水準 API

低水準 API はファイルディスクリプタを直接利用する。

4.1 通信に使われるバイトオーダの決定

5.1 通信に使われるバイトオーダの決定

/*&en

4. Low-level API.

5. Low-level API.

In this section, ``fd'' is an identifier of an OpenXM connection.

4.1 How to decide a byte order of integers?

5.1 How to decide a byte order of integers?

/*&common

int decideByteOrderServer(int fd, int order);

Line 293 as an expression for integers.

Line 405 as an expression for integers.

/*&common

4.2

5.2

/*&common

int send_int32(int fd, int integer);

int receive_int32(int fd);

Line 309 receive_int32() reads 32bits integer from an OpenXM co

Line 423 receive_int32() reads 32bits integer from an OpenXM co

/*&common

4.3

5.3

/*&common

int send_cmo(int fd, cmo* m);

cmo* receive_cmo(int fd);

Line 325 receive_cmo() reads an CMObject from an OpenXM connect

Line 441 receive_cmo() reads an CMObject from an OpenXM connect

/*&common

4.4

5.4

/*&common

int next_serial();

Line 338 next_serial() generates a serial number for ox message

Line 456 next_serial() generates a serial number for ox message

/*&common

4.5

5.5

/*&common

int send_ox_tag(int fd, int tag);

int receive_ox_tag(int fd);

Line 356 receive_ox_tag() reads a tag and a serial number of an

Line 476 receive_ox_tag() reads a tag and a serial number of an

/*&common

4.6

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 メッセージを送信する。

OX メッセージを送信する。

/*&ja

5. OX expression パーサ

6. OX expression パーサ

OpenXM C library には文字列表現された

OX expression および CMO expression から、

/*&en

ox 構造体または cmo 構造体を生成するためのパーサが付属している。

ここではこのパーサについて説明する。

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. 付属プログラムについて

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 関数を呼び出す.

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