分散計算
****

Distributed computation
***********************

OpenXM
======

Asir は, 分散計算における通信プロトコルとして, OpenXM (Open message eXchange for Mathematics) プロトコルを採用している. OpenXM プロジェクトについては, http://www.math.sci.kobe-u.ac.jp/OpenXM/ を参照してほしい.

OpenXM プロトコルは, 主として数学オブジェクトをプロセス間でやりとりするための規約である. OpenXM においては

On Asir distributed computations are done under OpenXM (Open message eXchange protocol for Mathematics), which is a protocol for exchanging mainly mathematical objects between processes. See http://www.math.sci.kobe-u.ac.jp/OpenXM/ for the details of OpenXM. In OpenXM a distributed computation is done as follows:

 1. client が server に対して計算実行依頼のメッセージを送る.

 2. server が計算を実行する.

 3. client が server に結果送付依頼のメッセージを送る.

 4. server は結果を返し, client は結果を受け取る

 5. A client requests something to a server.

 6. The server does works according to the request.

 7. The client requests to send data to the server.

 8. The server sends the data to the client and the client gets the data.

という形で分散計算が行われる. server はスタックマシンである. すなわち, client から送られたデータオブジェクトは, 指定がない限り server のスタックに積まれ, コマンドが送られた時に, 必要なだけスタックからデータを取り出して, 関数呼び出しの引数とする.

The server is a stack machine. That is data objects sent by the client are pushed to the stack of the server. If the server gets a command, then the data are popped form the stack and they are used as arguments of a function call.

OpenXM において特徴的なことは, 計算結果は単に server のスタックに積まれるだけで, client からの依頼がない限り, 通信路にデータは流れないという点である.

In OpenXM, the result of a computation done in the server is simply pushed to the stack and the data is not written to the communication stream without requests from the client.

プロトコルには, オブジェクトの共通フォーマットを規定する CMO (Common Mathematical Object format), プロセスに対する動作を指定する SM (Stack Machine command) が含まれる. これらは, データを送る際に, データの種類を指定するための OX expression としてラッピングされる.

OpenXM による分散計算を行う場合には, まず, server を立ち上げて, 通信を成立させる必要がある. このために, ox_launch(), ox_launch_nox(), ox_launch_generic() などの関数が用意されている. さらに, 通信の成立した server に対して以下のような操作が関数として用意されている.

OpenXM protocol consists of two components: CMO (Common Mathematical Object format) which determines a common format of data representations and SM (StackMachine command) which specifies actions on servers. These are wrapped as OX expressions to indicate the sort of data when they are sent.

To execute a distributed computation by OpenXM, one has to invoke OpenXM servers and to establish communications between the client and the servers. ox_launch(), ox_launch_nox(), ox_launch_generic() are preprared for such purposes. Furthermore the following functions are available.

ox_push_cmo()

     データを server のスタックに積む

     It requests a server to push an object to the stack of a server.

ox_pop_cmo()
     データを server のスタックから取り出す.

     It request a server to pop an object from the stack of a server.

ox_cmo_rpc()

     server の関数を呼び出し, 結果をスタックに積む.

     It requests to execute a function on a server. The result is pushed to the stack of the server.

ox_execute_string()

     server 固有のユーザ言語 (Asir なら Asir 言語) で書かれた文字列を server が実行し, 結果をスタックに積む.

     It requests a server to parse and execute a string by the parser and the evaluater of the server. The result is pushed to the stack of the server.

ox_push_cmd()

     SM コマンドの送信.

     It requests a server to execute a command.

ox_get()

     既に通信路にあるデータの取り出し.

     It gets an object from a data stream.

Mathcap
=======

server, client ともに, OpenXM で規定されている全てのCMO フォーマット, SM コマンドを実装しているとは限らない. 相手の知らないデータ, コマンドを送った場合, 現状では結果は予想できない. このため, OpenXM では, あらかじめ互いのサポートする CMO, SM のリストを交換しあって, 相手の知らないデータを送らないようにする仕組みを提唱している. このためのデータが Mathcap である. Mathcap は CMO としてはリストであり, その要素は 32 bit 整数または文字列である. 現在の規定では, Mathcap は長さが 3 のリストで,

[[version 番号, server 名],SMtaglist,[[OXtag,CMOtaglist], [OXtag,CMOtaglist],...]]

という形をしている. [OXtag,CMOtaglist] は, OXtag で示されるカテゴリのデータに対して, どのような CMO が使用可能かを示すものである. この指定を複数許すことにより, 例えば ox_asir のように, CMO データ以外に, Asir 固有のデータ形式により, CMOより多くの種類のデータ送受信を行えることを示せる.

データ送信の際に, 相手プロセスの Mathcap が既に登録されている場合, Mathcap によるチェックを行うか否かは, ctrl コマンドの "ox_check" スイッチにより決まる. このスイッチの初期値は 1 で, チェックを行うことを意味する. ctrl("ox_check",0) によりチェックを行わないようにできる.

A server or a client does not necessarily implement full specifications of OpenXM. If a program sends data unknown to its peer, an unrecoverable error may occur. To avoid such a case OpenXM provides a scheme not to send data unknown to peers. It is realized by exchanging the list of supported CMO and SM. The list is called mathcap. Mathcap is also defined as a CMO and the elements are 32bit integers or strings. The format of mathcap is as follows.

[[version number, server name],SMtaglist, [[OXtag,CMOtaglist],[OXtag,CMOtaglist],...]]

[OXtag,CMOtaglist] indicates that available object tags for a category of data specified by OXtag. For example ox_asir accepts the local object format used by Asir and the mathcap from ox_asir reflects the fact.

If "ox_check" switch of ctrl is set to 1, the check by a mathcap is done before data is sent. If "ox_check" switch of ctrl is set to 0, the check is not done. By default it is set to 1.

スタックマシンコマンド
===========

Stackmachine commands
=====================

スタックマシンコマンドは, スタックマシンである server に何らかの操作を行わせるために用意されている. いくつかのコマンドは, よく用いられる形で, 他のコマンド, データとともに, Asir の組み込み関数により送られるが, ユーザが明示的にあるコマンドを送る必要がしばしば生ずる. スタックマシンコマンドは 32 bit 以下の整数であり, ox_push_cmd() コマンドで送信できる. 以下で, 代表的なスタックマシンコマンドについて解説する. SM_xxx=yyy で, SM_xxx が mnemonic, yyy が値である.

以下で, スタックからデータを取り出すとは, スタックの一番上からデータを取り除くことを言う.

The stackmachine commands are provided to request a server to execute various operations. They are automatically sent by built-in functions of Asir, but one often has to send them manually. They are represented by 32bit integers. One can send them by calling ox_push_cmd(). Typical stackmachine commands are as follows. SM_xxx=yyy means that SM_xxx is a mnemonic and that yyy is its value.

SM_popSerializedLocalObject=258

     server が ox_asir の場合に, 必ずしも CMO で定義されていないオブジェクトをスタックから取り出し, 通信路に流す.

     An object not necessarily defined as CMO is popped from the stack and is sent to the client. This is available only on ox_asir.

SM_popCMO=262

     CMO オブジェクトをスタックから取り出し, 通信路に流す.

     A CMO object is popped from the stack and is sent to the client.

SM_popString=263

     スタックからデータを取り出し, 可読形式の文字列に変換して通信路に流す.

     An object is popped from the stack and is sent to the client as a readable string.

SM_mathcap=264

     server の mathcap をスタックに積む.

     The server's mathcap is pushed to the stack.

SM_pops=265

     スタックから取り出したデータを個数として, その個数分スタックからデータを取り除く.

     Objects are removed from the stack. The number of object to be removed is specified by the object at the top of the stack.

SM_setName=266

     スタックからデータを変数名として取り出し, 次に取り出したデータをその変数に割り当てる. この割り当ては, server 固有の処理として行われる.

     A variable name is popped form the stack. Then an object is popped and it is assigned to the variable. This assignment is done by the local language of the server.

SM_evalName=267

     スタックから取り出したデータを変数名として, その値をスタックに載せる.

     A variable name is popped from the stack. Then the value of the variable is pushed to the stack.

SM_executeStringByLocalParser=268

     スタックから取り出したデータを, server 固有の parser, evaluator で処理し, 結果をスタックに載せる.

     A string popped from the stack is parsed and evaluated. The result is pushed to the stack.

SM_executeFunction=269

     スタックから, 関数名, 引数の個数, 個数分の引数を取り出し, 関数を呼び出し結果をスタックに載せる.

     A function name, the number of arguments and the arguments are popped from the stack. Then the function is executed and the result is pushed to the stack.

SM_beginBlock=270
     データブロックのはじまり.

     It indicates the beginning of a block.

SM_endBlock=271
     データブロックの終り.

     It indicates the end of a block.

SM_shutdown=272

     server との交信を切断し, server を終了させる.

     It shuts down communications and terminates servers.

SM_setMathcap=273

     スタックのデータを client の mathcap として, server に登録を要求する.

     It requests a server to register the data at the top of the stack as the client's mathcap.

SM_getsp=275

     現在スタックに積まれているデータの数をスタックに載せる.

     The number of objects in the current stack is pushed to the stack.

SM_dupErrors=276

     現在スタックに積まれているオブジェクトの内, エラーオブジェクトのみをリストにして, スタックに載せる.

     The list of all the error objects in the current stack is pushed to the stack.

SM_nop=300

     なにもしない.

     Nothing is done.

デバッグ
====

Debugging
=========

分散計算においては, 一般にデバッグが困難となる. ox_asir においては, デバッグのためのいくつかの機能を提供している.

In general, it is difficult to debug distributed computations. ox_asir provides several functions for debugging.

エラーオブジェクト
---------

Error object
------------

OpenXM server が実行中にエラーを起こした場合, 結果のかわりに CMO エラーオブジェクトをスタックに積む. エラーオブジェクトは, 対応する SM コマンドのシリアル番号と, エラーメッセージからなり, それによってどの SM コマンドがどのようなエラーを起こしたがある程度判明する.

When an error has occurred on an OpenXM server, an error object is pushed to the stack instead of a result of the computation. The error object consists of the serial number of the SM command which caused the error, and an error message.

     [340] ox_launch();
     0
     [341] ox_rpc(0,"fctr",1.2*x);
     0
     [342] ox_pop_cmo(0);
     error([8,fctrp : invalid argument])

リセット
----

Resetting a server
------------------

ox_reset() は現在実行中の server をリセットして, コマンド受け付け状態に戻す. この機能は, 通常の Asir セッションにおけるキーボード割り込みとほぼ同様に, OpenXM server をリセットできる. また, 何らかの原因で, 通信路のデータが載ったままの状態で ox_rpc() などを実行すると, ox_pop_cmo() など, スタックからの取り出しと, 実際に読まれるデータの対応が不正になる. そのような場合にも有効である.

ox_reset() resets a process whose identifier is NUMBER. After its execution the process is ready for receiving data. This function corresponds to the keyboard interrupt on an usual Asir session. It often happens that a request of a client does not correspond correctly to the result from a server. It is caused by remaining data on data streams. ox_reset is effective for such cases.

デバッグ用ポップアップウィンドウ
----------------

Pop-up command window for debugging
-----------------------------------

server には, client におけるキーボードに相当する入力機能がないため, server 側で動作しているユーザ言語プログラムのデバッグが困難になる. このため, server 側でのユーザ言語プログラム実行中のエラーおよび, client からの ox_rpc(ID,"debug") 実行により, server にデバッグコマンドを入力するための小さなウィンドウがポップアップする. このウィンドウからの入力に対する出力は, log 用の xterm に表示される. このウィンドウを閉じるには, quit を入力すればよい.

As a server does not have any standard input device such as a keyboard, it is difficult to debug user programs running on the server. ox_asir pops up a small command window to input debug commands when an error has occurred during user a program execution or ox_rpc(ID,"debug") has been executed. The responses to commands are shown in xterm to display standard outputs from the server. To close the small window, input quit.

分散計算に関する関数
==========

Functions for distributed computation
=====================================

ox_launch, ox_launch_nox, ox_shutdown
-------------------------------------

ox_launch([HOST[,DIR],COMMAND])
ox_launch_nox([HOST[,DIR],COMMAND])
     :: 遠隔プロセスの起動および通信を開始する.

     :: Initialize OpenXM servers.

ox_shutdown(ID)
     :: 遠隔プロセスを終了させ, 通信を終了する.

     :: Terminates OpenXM servers.

return
     整数

     integer

host
     文字列または 0

     string or 0

dir command
     文字列

     string

id
     整数

     integer

  * ox_launch() は, ホスト HOST 上でコマンド COMMAND を起動し, このプロセスと通信を開始する. 引数が 3 つの場合, HOST 上で, DIR にある ox_launch というサーバ起動用プログラムを立ち上げる. ox_launch は COMMAND を起動する. HOST が 0 の時, Asir が動作しているマシン上でコマンドを起動する. 無引数の場合, HOST は 0, DIR は get_rootdir() で返されるディレクトリ, COMMAND は同じディレクトリの ox_asir を意味する.

  * HOST が 0, すなわちサーバを local に起動する場合には, DIR を省略できる. この場合, DIR は get_rootdir() で返されるディレクトリとなる.

  * COMMAND が / で始まる文字列の場合, 絶対パスと解釈される. それ以外の場合, DIR からの相対パスと解釈される.

  * UNIX 版においては, ox_launch() は, COMMAND の標準出力, 標準エラー出力を表示するための xterm を起動する. ox_launch_nox() は, X なしの環境の場合, あるいは xterm を起動せずにサーバを立ち上げる場合に用いる. この場合, COMMAND の出力は /dev/null に接続される. ox_launch() の場合でも, 環境変数 DISPLAY が設定されていない場合には, ox_launch_nox() と同じ動作をする.

  * 返される整数は通信のための識別子となる.

  * Asir と通信するプロセスは同一のマシン上で動作している必要はない. また, 通信におけるバイトオーダは server, client 間での最初の negotiation で決まるため, 相手先のマシンとバイトオーダが異なっていても構わない.

  * HOST にマシン名を指定する場合, 以下の準備が必要である. ここで, Asir の動いているホストを A, 通信相手のプロセスが起動されるホストを B とする.

      1. ホスト B の ~/.rhosts に, ホスト A のホスト名を登録する.

      2. ox_plot など, X とのコネクションも用いられる場合, Xserver に対し, 必要なホストを authorize させる. xhost で必要なホスト名を追加すればよい.

      3. COMMAND によっては, スタックを大量に使用するものもあるため, .cshrc でスタックサイズを大きめ (16MB 程度) に指定しておくのが安全である. スタックサイズは limit stacksize 16m などと指定する.

  * COMMAND が, X 上にウインドウを開ける場合, DISPLAYが指定されればその文字列を, 省略時には環境変数 DISPLAY の値を用いる.

  * 環境変数 ASIR_RSH がセットされている場合, サーバの立ち上げプログラムとしてrsh の代わりにこの変数の値が用いられる. 例えば,

          % setenv ASIR_RSH "ssh -f -X -A "

     により, サーバの立ち上げに ssh が用いられ, X11 の通信が forwarding される. 詳しくは ssh のマニュアルを参照.

  * ox_shutdown() は識別子 ID に対応する遠隔プロセスを終了させる.

  * Asir が正常した場合には全ての入出力ストリームは自動的に閉じられ, 起動されているプロセスは全て終了するが, 異常終了した場合, 遠隔プロセスが終了しない場合もある. Asir が異常終了した場合, 遠隔プロセスを起動したマシン上で ps などを起動して, もし Asir から起動したプロセスが残っている場合, kill する必要がある.

  * log 表示用 xterm は -name ox_term オプションで起動される. よって, ox_term なるリソース名に対して xterm のリソース設定を行えば, log 用 xterm の挙動のみを変えることができる. 例えば,

          ox_xterm*iconic:on
          ox_xterm*scrollBar:on
          ox_xterm*saveLines:1000

     により, icon で起動, scrollbar つき, scrollbar で参照できる行数が最大 1000 行, という指定ができる.

  * Function ox_launch() invokes a process to execute COMMAND on a host HOST and enables Asir to communicate with that process. If the number of arguments is 3, ox_launch in DIR is invoked on HOST. Then ox_launch invokes COMMAND. If HOST is equal to 0, all the commands are invoked on the same machine as the Asir is running. If no arguments are specified, HOST, DIR and COMMAND are regarded as 0, the value of get_rootdir() and ox_asir in the same directory respectively.

  * If HOST is equal to 0, then DIR can be omitted. In such a case DIR is regarded as the value of get_rootdir().

  * If COMMAND begins with /, it is regarded as an absolute pathname. Otherwise it is regarded as a relative pathname from DIR.

  * On UNIX, ox_launch() invokes xterm to display standard outputs from COMMAND. If X11 is not available or one wants to invoke servers without xterm, use ox_launch_nox(), where the outputs of COMMAND are redirected to /dev/null. If the environment variable DISPLAY is not set, ox_launch() and ox_launch_nox() behave identically.

  * The returned value is used as the identifier for communication.

  * The peers communicating with Asir are not necessarily processes running on the same machine. The communication will be successful even if the byte order is different from those of the peer processes, because the byte order for the communication is determined by a negotiation between a client and a server.

  * The following preparations are necessary. Here, Let A be the host on which Asir is running, and B the host on which the peer process will run.

      1. Register the hostname of the host A to the ~/.rhosts of the host B. That is, you should be allowed to access the host B from A without supplying a password.

      2. For cases where connection to X is also used, let Xserver authorize the relevant hosts. Adding the hosts can be done by command xhost.

      3. If an environment variable ASIR_RSH is set, the content of this variable is used as a promgram to invoke remote servers instead of RSH. For example,

               % setenv ASIR_RSH "ssh -f -X -A "

          implies that remote servers are invoked by ssh and that X11 forwarding is enabled. See the manual of ssh for the detail.

      4. Some COMMAND's consume much stack space.  You are recommended to set the stack size to about 16MB large in .cshrc for safe. To specify the size, put limit stacksize 16m for an example.

  * When COMMAND opens a window on X, it uses the string specified for DISPLAY; if the specification is omitted, it uses the value set for the environment variable DISPLAY.

  * ox_shutdown() terminates OpenXM servers whose identifier is ID.

  * When Asir is terminated successfully, all I/O streams are automatically closed, and all the processes invoked are also terminated. However, some remote processes may not terminated when Asir is terminated abnormally. If ever Asir is terminated abnormally, you have to kill all the unterminated process invoked by Asir on every remote host. Check by ps command on the remote hosts to see if such processed are alive.

  * xterm for displaying the outputs from COMMAND is invoked with -name ox_term option. Thus, by specifying resources for the resource name ox_term, only the behaviour of the xterm can be customized.

          /* iconify on start */
          ox_xterm*iconic:on
          /* activate the scroll bar */
          ox_xterm*scrollBar:on
          /* 1000 lines can be shown by the scrollbar */
          ox_xterm*saveLines:1000

     [219] ox_launch();
     0
     [220] ox_rpc(0,"fctr",x^10-y^10);
     0
     [221] ox_pop_local(0);
     [[1,1],[x^4+y*x^3+y^2*x^2+y^3*x+y^4,1],
     [x^4-y*x^3+y^2*x^2-y^3*x+y^4,1],[x-y,1],[x+y,1]]
     [222] ox_shutdown(0);
     0

参照

References
     ox_rpc ox_cmo_rpc ox_execute_string, ox_pop_cmo ox_pop_local, ifplot conplot plot polarplot plotover

ox_launch_generic
-----------------

ox_launch_generic(HOST,LAUNCH,SERVER,USE_UNIX,USE_SSH,USE_X,CONN_TO_SERV)
     :: 遠隔プロセスの起動および通信を開始する.

     :: Initialize OpenXM servers.

return
     整数

     integer

host
     文字列または 0

     string or 0

launcher server
     文字列

     string

use_unix use_ssh use_x conn_to_serv
     整数

     integer

  * ox_launch_generic() は, ホスト HOST 上で, コントロールプロセス LAUNCH およびサーバプロセス SERVER を起動する. その他の引数は, 使用する protocol の種類, X の使用/不使用, rsh/ssh によるプロセス起動, connect 方法の指定などを行うスイッチである.

  * HOST が 0 の場合, Asir が動作しているマシン上に, LAUNCH, SERVER を立ち上げる. この場合, USE_UNIX の値にかかわらず, UNIX internal protocol が用いられる.

  * USE_UNIX が 1 の場合, UNIX internal protocol を用いる. 0 の場合, Internet protocol を用いる.

  * USE_SSH が 1 の場合, ssh (Secure Shell) によりコントロール, サーバプロセスを立ち上げる. ssh-agent などを利用していな場合, パスワードの入力が必要となる. 相手先で sshd が動いていない場合, 自動的に rsh が用いられるが, パスワードが必要となる場合には, その場で起動に失敗する.

  * USE_X が 1 の場合, X 上での動作を仮定し, 設定されている DISPLAY変数を用いて, log 表示用 xterm のもとで SERVER が起動される. DISPLAY 変数がセットされていない場合には, 自動的に X なしの設定となる. DISPLAY が不適切にセットされている場合には, コントロール, サーバがハングするので要注意である.

  * CONN_TO_SERV が 1 の場合, Asir (client) が生成したポートに対し, client が bind,listen し, 起動されたプロセスが connect する. CONN_TO_SERV が 0 の場合, 起動されたプロセスが bind, listen し, client が connect する.

  * ox_launch_generic() invokes a control process LAUNCH and a server process SERVER on HOST. The other arguments are switches for protocol family selection, on/off of the X environment, method of process invocation and selection of connection type.

  * If HOST is equal to 0, processes are invoked on the same machine as the Asir is running. In this case UNIX internal protocol is always used.

  * If USE_UNIX is equal to 1, UNIX internal protocol is used. If USE_UNIX is equal to 0, Internet protocol is used.

  * If USE_SSH is equal to 1,ssh (Secure Shell) is used to invoke processes. If one does not use ssh-agent, a password (passphrase) is required. If sshd is not running on the target machine, rsh is used instead. But it will immediately fail if a password is required.

  * If USE_X is equal to 1, it is assumed that X environment is available. In such a case SERVER is invoked under xterm by using the current DISPLAY variable. If DISPLAY is not set, it is invoked without X. Note that the processes will hang up if DISPLAY is incorrectly set.

  * If CONN_TO_SERV is equal to 1, Asir (client) executes bind and listen, and the invoked processes execute connect. If CONN_TO_SERV is equal to 0, Asir (client) the invoked processes execute bind and listen, and the client executes connect.

     [342] LIB=get_rootdir();
     /export/home/noro/ca/Kobe/build/OpenXM/lib/asir
     [343] ox_launch_generic(0,LIB+"/ox_launch",LIB+"/ox_asir",0,0,0,0);
     1
     [344] ox_launch_generic(0,LIB+"/ox_launch",LIB+"/ox_asir",1,0,0,0);
     2
     [345] ox_launch_generic(0,LIB+"/ox_launch",LIB+"/ox_asir",1,1,0,0);
     3
     [346] ox_launch_generic(0,LIB+"/ox_launch",LIB+"/ox_asir",1,1,1,0);
     4
     [347] ox_launch_generic(0,LIB+"/ox_launch",LIB+"/ox_asir",1,1,1,1);
     5
     [348] ox_launch_generic(0,LIB+"/ox_launch",LIB+"/ox_asir",1,1,0,1);
     6

参照

References
     ox_launch ox_launch_nox ox_shutdown, ox_launch_generic

generate_port, try_bind_listen, try_connect, try_accept, register_server
------------------------------------------------------------------------

generate_port([USE_UNIX])
     :: port の生成

     :: Generates a port number.

try_bind_listen(PORT)
     :: port に対して bind, listen

     :: Binds and listens on a port.

try_connect(HOST,PORT)
     :: port に対して connect

     :: Connects to a port.

try_accept(SOCKET,PORT)
     :: connect 要求を accept

     :: Accepts a connection request.

register_server(CONTROL_SOCKET,CONTROL_PORT,SERVER_SOCKET,SERVER_PORT)
     :: connection の成立した control socket, server socket の登録

     :: Registers the sockets for which connections are established.

return
     generate_port() のみ整数または文字列. その他は整数.

     integer or string for generate_port(), integer for the others

use_unix
     0 または 1

     0 or 1

host
     文字列

     string

port control_port server_port
     整数または文字列

     integer or string

socket control_socket server_socket
     整数

     integer

  * これらの関数は, 遠隔プロセスと通信を成立させるためのプリミティブである.

  * generate_port() は通信のための port を生成する. 無引数あるいは引数が 0 の場合, Internet domain の socket のための port 番号, それ以外の場合には, UNIX domain (host-internal protocol) のための, ファイル名を生成する. port 番号は random に生成されるが, その port が使用中でない保証はない.

  * try_bind_listen() は, 与えられた port に対し, その protocol に対応した socket を生成し, bind, listen する. 成功した場合, socket 識別子を返す. 失敗した場合, -1 が返る.

  * try_connect() は, ホスト HOST の port PORT に対し connect を試みる. 成功した場合, socket 識別子を返す. 失敗した場合 -1 が返る.

  * try_accept() は, SOCKET に対する connect 要求を accept し, 新たに生成された socket を返す. 失敗した場合 -1 が返る. いずれの場合にも, SOCKET は自動的に close される. 引数 PORT は, SOCKET の protocol を判別するために与える.

  * register_server() は, control, server それぞれの socket を一組にして, server list に登録し, ox_push_cmo() などで用いるプロセス識別子を返す.

  * 遠隔プロセスの起動は, shell() または手動で行う.

  * These functions are primitives to establish communications between a client and servers.

  * generate_port() generates a port name for communication. If the argument is not specified or equal to 0, a port number for Internet domain socket is generated randomly. Otherwise a file name for UNIX domain (host-internal protocol) is generated. Note that it is not assured that the generated port is not in use.

  * try_bind_listen() creates a socket according to the protocol family indicated by the given port and executes bind and listen. It returns a socket identifier if it is successful. -1 indicates an error.

  * try_connect() tries to connect to a port PORT on a host HOST. It returns a socket identifier if it is successful. -1 indicates an error.

  * try_accept() accepts a connection request to a socket SOCKET. It returns a new socket identifier if it is successful. -1 indicates an error. In any case SOCKET is automatically closed. PORT is specified to distinguish the protocol family of SOCKET.

  * register_server() registers a pair of a control socket and a server socket. A process identifier indicating the pair is returned. The process identifier is used as an argument of ox functions such as ox_push_cmo().

  * Servers are invoked by using shell(), or manually.

     [340] CPort=generate_port();
     39896
     [341] SPort=generate_port();
     37222
     [342] CSocket=try_bind_listen(CPort);
     3
     [343] SSocket=try_bind_listen(SPort);
     5

     /*

     ここで, ox_launch を起動 :

     ox_launch is invoked here :

     %  ox_launch "127.1" 0 39716 37043 ox_asir "shio:0"
     */

     [344] CSocket=try_accept(CSocket,CPort);
     6
     [345] SSocket=try_accept(SSocket,SPort);
     3
     [346] register_server(CSocket,CPort,SSocket,SPort);
     0

参照

References
     ox_launch ox_launch_nox ox_shutdown, ox_launch_generic, shell, ox_push_cmo ox_push_local

ox_asir
-------

ox_asir は, Asir のほぼ全ての機能を OpenXM サーバとして提供する. ox_asir は, ox_launch または ox_launch_nox で起動する. 後者は X 環境を用いない場合のために用意されている.

ox_asir provides almost all the functionalities of Asir as an OpenXM server. ox_asir is invoked by ox_launch or ox_launch_nox. If X environment is not available or is not necessary, one can use ox_launch_nox.

     [5] ox_launch();
     0

     [5] ox_launch_nox("127.0.0.1","/usr/local/lib/asir",
     "/usr/local/lib/asir/ox_asir");
     0

     [7] RemoteLibDir = "/usr/local/lib/asir/"$
     [8] Machines = ["sumire","rokkaku","genkotsu","shinpuku"];
     [sumire,rokkaku,genkotsu,shinpuku]
     [9] Servers = map(ox_launch,Machines,RemoteLibDir,
     RemoteLibDir+"ox_asir");
     [0,1,2,3]

参照

References
     ox_launch ox_launch_nox ox_shutdown

ox_rpc, ox_cmo_rpc, ox_execute_string
-------------------------------------

ox_rpc(NUMBER,"FUNC",ARG0,...)
ox_cmo_rpc(NUMBER,"FUNC",ARG0,...)
ox_execute_string(NUMBER,"COMMAND",...)
     :: プロセスの函数呼び出し

     :: Calls a function on an OpenXM server

return
     0

number
     数 (プロセス識別子)

     integer (process identifier)

func
     函数名

     function name

command
     文字列

     string

arg0 ...
     任意 (引数)

     arbitrary (arguments)

  * 識別子 NUMBER のプロセスの函数を呼び出す.

  * 函数の計算終了を待たず, 直ちに 0 を返す.

  * ox_rpc() は, サーバが ox_asir の場合のみ用いることができる. それ以外の場合は, ox_cmo_rpc() を用いる.

  * 函数が返す値は ox_pop_local(), ox_pop_cmo() により取り出す.

  * サーバが ox_asir 以外のもの (例えば Kan サーバ ox_sm1など) の場合には, Open_XM プロトコルでサポートされているデータのみを送ることができる.

  * ox_execute_string は, 送った文字列 COMMAND をサーバが自らのユーザ言語パーザで解析し, 評価した結果をサーバのスタックに置くように指示する.

  * Calls a function on an OpenXM server whose identifier is NUMBER.

  * It returns 0 immediately. It does not wait the termination of the function call.

  * ox_rpc() can be used when the server is ox_asir. Otherwise ox_cmo_rpc() should be used.

  * The result of the function call is put on the stack of the server. It can be received by ox_pop_local() or ox_pop_cmo().

  * If the server is not ox_asir, only data defined in OpenXM can be sent.

  * ox_execute_string requests the server to parse and execute COMMAND by the parser and the evaluater of the server. The result is pushed to the stack.

     [234] ox_cmo_rpc(0,"dp_ht",dp_ptod((x+y)^10,[x,y]));
     0
     [235] ox_pop_cmo(0);
     (1)*<<10,0>>
     [236] ox_execute_string(0,"12345 % 678;");
     0
     [237] ox_pop_cmo(0);
     141

参照

References
     ox_pop_cmo ox_pop_local

ox_reset,ox_intr,register_handler
---------------------------------

ox_reset(NUMBER)
     :: プロセスのリセット

     :: Resets an OpenXM server

ox_intr(NUMBER)
     :: プロセスのに SIGINT 送付

     :: Sends SIGINT to an OpenXM server

register_handler(FUNC)
     :: プロセスのリセットのための関数登録

     :: Registers a function callable on a keyboard interrupt.

return
     1

number
     数 (プロセス識別子)

     integer(process identifier)

func
     関数子または 0

     functor or 0

  * ox_reset() は, 識別子 NUMBER のプロセスをリセットし, コマンド受け付け状態にする.

  * そのプロセスが既に書き出した, あるいは現在書き出し中のデータがある場合, それを全部読み出し, 出力バッファを空にした時点で戻る.

  * 子プロセスが RUN 状態の場合でも, 割り込みにより強制的に計算を終了させる.

  * 分散計算を行う函数の先頭で, 使用するプロセスに対して実行する. あるいは計算途中での強制中断に用いる.

  * ox_intr() は, 識別子 NUMBER のプロセスをに対して SIGINT を送付する. SIGINT に対するプロセスの動作は規定されていないが, ox_asir の場合, ただちに debug mode に入る. X 上で動作している場合, デバッグコマンド入力用のウィンドウがポップアップする.

  * register_handler() は, C-c などによる割り込みの際に, u を指定することで, 無引数ユーザ定義関数 FUNC() が呼び出されるように設定する. この関数に, ox_reset() を呼び出させることで, 割り込みの際に自動的に OpenXM server のリセットを行うことができる.

  * FUNC に 0 を指定することで, 設定を解除できる.

  * ox_reset() resets a process whose identifier is NUMBER. After its execution the process is ready for receiving data.

  * After executing ox_reset(), sending/receiving buffers and stream buffers are assured to be empty.

  * Even if a process is running, the execution is safely stopped.

  * ox_reset() may be used prior to a distirbuted computation. It can be also used to interrupt a distributed computation.

  * ox_intr() sends SIGINT to a process whose identifier is NUMBER. The action of a server against SIGINT is not specified in OpenXM. ox_asir immediately enters the debug mode and pops up an window to input debug commands on X window system.

  * register_handler() registers a function FUNC(). If u is specified on a keybord interrupt, FUNC() is executed before returning the toplevel. If ox_reset() calls are included in FUNC(), one can automatically reset OpenXM servers on a keyboard interrupt.

  * If FUNC is equal to 0, the setting is reset.

     [10] ox_launch();
     0
     [11] ox_rpc(0,"fctr",x^100-y^100);
     0

     [12] ox_reset(0); /* xterm のウィンドウには                             */
     1                 /* usr1 : return to toplevel by SIGUSR1 が表示される. */

     [12] ox_reset(0); /* usr1 : return to toplevel by SIGUSR1 */
     1                 /* is displayed on the xterm.           */

     [340] Procs=[ox_launch(),ox_launch()];
     [0,1]
     [341] def reset() { extern Procs; map(ox_reset,Procs);}
     [342] map(ox_rpc,Procs,"fctr",x^100-y^100);
     [0,0]
     [343] register_handler(reset);
     1
     [344] interrupt ?(q/t/c/d/u/w/?) u
     Abort this computation? (y or n) y
     Calling the registered exception handler...done.
     return to toplevel

参照

References
     ox_rpc ox_cmo_rpc ox_execute_string

ox_push_cmo, ox_push_local
--------------------------

ox_push_cmo(NUMBER,OBJ)
ox_push_local(NUMBER,OBJ)
     :: OBJ を識別子 NUMBER のプロセスに送信

     :: Sends OBJ to a process whose identifier is NUMBER.

return
     0

number
     数(プロセス識別子)

     integer(process identifier)

obj
     オブジェクト

     object

  * 識別子 NUMBER のプロセスに OBJ を送信する.

  * ox_push_cmo は, Asir 以外の Open_XM サーバに送信する際に用いる.

  * ox_push_local は, ox_asir, ox_plot にデータを送る場合に用いることができる.

  * バッファがいっぱいにならない限り, ただちに復帰する.

  * Sends OBJ to a process whose identifier is NUMBER.

  * ox_push_cmo is used to send data to an Open_XM other than ox_asir and ox_plot.

  * ox_push_local is used to send data to ox_asir and ox_plot.

  * The call immediately returns unless the stream buffer is full.

参照

References
     ox_rpc ox_cmo_rpc ox_execute_string, ox_pop_cmo ox_pop_local

ox_pop_cmo, ox_pop_local
------------------------

ox_pop_local(NUMBER)
     :: プロセス識別子 NUMBER からデータを受信する.

     :: Receives data from a process whose identifier is NUMBER.

return
     受信データ

     received data

number
     数 (プロセス識別子)

     integer(process identifier)

  * プロセス識別子 NUMBER のプロセスからデータを受信する.

  * ox_pop_cmo は, Asir 以外の Open_XM サーバから受信する際に用いる.

  * ox_pop_local は, ox_asir, ox_plot からデータを受け取る場合に用いることができる.

  * サーバが計算中の場合ブロックする. これを避けるためには, ox_push_cmd で SM_popCMO (262) または SM_popSerializedLocalObject (258) を送っておき, ox_select でプロセスが ready になっていることを確かめてから ox_get すればよい.

  * Receives data from a process whose identifier is NUMBER.

  * ox_pop_cmo can be used to receive data form an OpenXM server other than ox_asir and ox_plot.

  * ox_pop_local can be used to receive data from ox_asir, ox_plot.

  * If no data is available, these functions block. To avoid it, send SM_popCMO (262) or SM_popSerializedLocalObject (258). Then check the process status by ox_select. Finally call ox_get for a ready process.

     [3] ox_rpc(0,"fctr",x^100-y^100);
     0
     [4] ox_push_cmd(0,258);
     0
     [5] ox_select([0]);
     [0]
     [6] ox_get(0);
     [[1,1],[x^2+y^2,1],[x^4-y*x^3+y^2*x^2-y^3*x+y^4,1],...]

参照

References
     ox_rpc ox_cmo_rpc ox_execute_string, ox_push_cmd ox_sync, ox_select, ox_get

ox_push_cmd, ox_sync
--------------------

ox_push_cmd(NUMBER,COMMAND)
     :: プロセス識別子 NUMBER のプロセスにコマンド COMMAND を送信する.

     :: Sends a command COMMAND to a process whose identifier is NUMBER.

ox_sync(NUMBER)
     :: プロセス識別子 NUMBER のプロセスに OX_SYNC_BALL を送信する.

     :: Sends OX_SYNC_BALL to a process whose identifier is NUMBER.

return
     0

number
     数 (プロセス識別子)

     integer(process identifier)

command
     数 (コマンド識別子)

     integer(command identifier)

  * 識別子 NUMBER のプロセスにコマンドまたは OX_SYNC_BALL を送信する.

  * Open_XM において送受信データは OX_DATA, OX_COMMAND, OX_SYNC_BALLの 3 種類に分かれる. 通常, コマンドは何らかの操作に付随して暗黙のうちに送信されるが, これをユーザが個別に送りたい場合に用いられる.

  * OX_SYNC_BALL は ox_reset による計算中断, 復帰の際に送受信されるが, これを個別に送りたい場合に用いる. なお, 通常状態では OX_SYNC_BALL は無視される.

  * Sends a command or OX_SYNC_BALL to a process whose identifier is NUMBER.

  * Data in OpenXM are categorized into three types: OX_DATA, OX_COMMAND, OX_SYNC_BALL. Usually OX_COMMAND and OX_SYNC_BALL are sent implicitly with high level operations, but these functions are prepared to send these data explicitly.

  * OX_SYNC_BALL is used on the reseting operation by ox_reset. Usually OX_SYNC_BALL will be ignored by the peer.

参照

References
     ox_rpc ox_cmo_rpc ox_execute_string, ox_reset ox_intr register_handler

ox_get
------

ox_get(NUMBER)
     :: プロセス識別子 NUMBER のプロセスからデータを受信する.

     :: Receives data form a process whose identifer is NUMBER.

return
     受信データ

number
     数(プロセス識別子)

     integer(process identifier)

  * プロセス識別子 NUMBER のプロセスからデータを受信する. 既にストリーム上にデータがあることを仮定している.

  * ox_push_cmd と組み合わせて用いる.

  * ox_pop_cmo, ox_pop_local は, ox_push_cmd と ox_get の組み合わせで実現されている.

  * Receives data form a process whose identifer is NUMBER.

  * One may use this function with ox_push_cmd.

  * ox_pop_cmo and ox_pop_local is realized as combinations of ox_push_cmd and ox_get.

     [11] ox_push_cmo(0,123);
     0
     [12] ox_push_cmd(0,262); /* 262=OX_popCMO */
     0
     [13] ox_get(0);
     123

参照

References
     ox_pop_cmo ox_pop_local, ox_push_cmd ox_sync

ox_pops
-------

ox_pops(NUMBER[,NITEM])
     :: プロセス識別子 NUMBER のプロセスのスタックからデータを取り除く.

     :: Removes data form the stack of a process whose identifier is NUMBER.

return
     0

number
     数 (プロセス識別子)

     integer(process identifier)

nitem
     自然数

     non-negative integer

  * プロセス識別子 NUMBER のプロセスのスタックからデータを取り除く. NITEM が指定されている場合は NITEM 個, 指定のない場合は 1 個取り除く.

  * Removes data form the stack of a process whose identifier is NUMBER. If NITEM is specified, NITEM items are removed. If NITEM is not specified, 1 item is removed.

     [69] for(I=1;I<=10;I++)ox_push_cmo(0,I);
     [70] ox_pops(0,4);
     0
     [71] ox_pop_cmo(0);
     6

参照

References
     ox_pop_cmo ox_pop_local

ox_select
---------

ox_select(NLIST[,TIMEOUT])
     :: 読み出し可能なプロセスの識別子を返す.

     :: Returns the list of process identifiers on which data is available.

return
     リスト

     list

nlist
     数 (子プロセス識別子) のリスト

     list of integers (process identifier)

timeout
     数

     number

  * 識別子リスト NLIST のプロセスのうち既に出力を返しているプロセスの識別子リストを返す.

  * 全てのプロセスが RUN 状態のとき, いずれかのプロセスの終了を待つ. 但し, TIMEOUT が指定されている場合, TIMEOUT 秒だけ待つ.

  * ox_push_cmd() で SM_popCMO あるいは SM_popSerializedLocalObject を送っておき, ox_select() で ready 状態のプロセスを調べてox_get() することで, ox_pop_local(), ox_pop_cmo()で待ち状態に入るのを防ぐことができる.

  * Returns the list of process identifiers on which data is available.

  * If all the processes in NLIST are running, it blocks until one of the processes returns data. If TIMEOUT is specified, it waits for only TIMEOUT seconds.

  * By sending SM_popCMO or SM_popSerializedLocalObject with ox_push_cmd() in advance and by examining the process status with ox_select(), one can avoid a hanging up caused by ox_pop_local() or ox_pop_cmo(). In such a case, data can be received by ox_get().

     ox_launch();
     0
     [220] ox_launch();
     1
     [221] ox_launch();
     2
     [222] ox_rpc(2,"fctr",x^500-y^500);
     0
     [223] ox_rpc(1,"fctr",x^100-y^100);
     0
     [224] ox_rpc(0,"fctr",x^10-y^10);
     0
     [225] P=[0,1,2];
     [0,1,2]
     [226] map(ox_push_cmd,P,258);
     [0,0,0]
     [227] ox_select(P);
     [0]
     [228] ox_get(0);
     [[1,1],[x^4+y*x^3+y^2*x^2+y^3*x+y^4,1],
     [x^4-y*x^3+y^2*x^2-y^3*x+y^4,1],[x-y,1],[x+y,1]]

参照

References
     ox_pop_cmo ox_pop_local, ox_push_cmd ox_sync, ox_get

ox_flush
--------

ox_flush(ID)
     :: 送信バッファの強制 flush

     :: Flushes the sending buffer.

return
     1

id
     子プロセス識別子

     process identifier

  * 通常はバッチモードは off であり, データ, コマンド送信ごとに送信バッファは flush される.

  * バッチモードは "ctrl" コマンドの "ox_batch" スイッチで on/off できる.

  * 細かいデータを多数送る場合に, ctrl("ox_batch",1) でバッチモードを on にすると, バッファがいっぱいになった場合にのみ flush されるため, overhead が小さくなる場合がある. ただしこの場合には, 最後に ox_flush(ID) を実行して, バッファを強制的に flush する必要がある.

  * ox_pop_cmo, ox_pop_local のように, コマンド送信後ただちにデータ待ちに入る関数がハングしないよう, これらの関数の内部では強制 flush が実行されている.

  * By default the batch mode is off and the sending buffer is flushed at every sending operation of data and command.

  * The batch mode is set by "ox_batch" switch of "ctrl".

  * If one wants to send many pieces of small data, ctrl("ox_batch",1) may decrease the overhead of flush operations. Of course, one has to call ox_flush(ID) at the end of the sending operations.

  * Functions such as ox_pop_cmo and ox_pop_local enter a waiting mode immediately after sending a command. These functions always flush the sending buffer.

     [340] ox_launch_nox();
     0
     [341] cputime(1);
     0
     7e-05sec + gc : 4.8e-05sec(0.000119sec)
     [342] for(I=0;I<10000;I++)ox_push_cmo(0,I);
     0.232sec + gc : 0.006821sec(0.6878sec)
     [343] ctrl("ox_batch",1);
     1
     4.5e-05sec(3.302e-05sec)
     [344] for(I=0;I<10000;I++)ox_push_cmo(0,I); ox_flush(0);
     0.08063sec + gc : 0.06388sec(0.4408sec)
     [345] 1
     9.6e-05sec(0.01317sec)

参照

References
     ox_pop_cmo ox_pop_local, ctrl

ox_get_serverinfo
-----------------

ox_get_serverinfo([ID])
     :: server の Mathcap, 動作中のプロセス識別子の取得

     :: Gets server's mathcap and proess id.

return
     リスト

     list

id
     子プロセス識別子

     process identifier

  * 引数 ID があるとき, プロセス識別子 ID のプロセスの Mathcap をリストとして返す.

  * 引数なしのとき, 現在動作中のプロセス識別子およびその Mathcap からなるペアを, リストとして返す.

  * If ID is specified, the mathcap of the process whose identifier is ID is returned.

  * If ID is not specified, the list of [ID,MATHCAP] is returned, where ID is the identifier of a currently active process, and MATHCAP is the mathcap of the process. identifier ID is returned.

     [343] ox_get_serverinfo(0);
     [[199909080,Ox_system=ox_sm1.plain,Version=2.991118,HOSTTYPE=FreeBSD],
     [262,263,264,265,266,268,269,272,273,275,276],
     [[514],[2130706434,1,2,4,5,17,19,20,22,23,24,25,26,30,31,60,61,27,
     33,40,16,34]]]
     [344] ox_get_serverinfo();
     [[0,[[199909080,Ox_system=ox_sm1.plain,Version=2.991118,
     HOSTTYPE=FreeBSD],
     [262,263,264,265,266,268,269,272,273,275,276],
     [[514],[2130706434,1,2,4,5,17,19,20,22,23,24,25,26,30,31,60,61,27,33,
     40,16,34]]]],
     [1,[[199901160,ox_asir],
     [276,275,258,262,263,266,267,268,274,269,272,265,264,273,300,270,271],
     [[514,2144202544],
     [1,2,3,4,5,2130706433,2130706434,17,19,20,21,22,24,25,26,31,27,33,60],
     [0,1]]]]]

参照

References
     Mathcap.

ifplot, conplot, plot, polarplot, plotover
------------------------------------------

ifplot(FUNC [,GEOMETRY] [,XRANGE] [,YRANGE] [,ID] [,NAME])
     :: 2 変数関数の実数上での零点を表示する.

     :: Displays real zeros of a bi-variate function.

conplot(FUNC [,GEOMETRY] [,XRANGE] [,YRANGE] [,ZRANGE] [,ID] [,NAME])
     :: 2 変数関数の実数上での等高線を表示する.

     :: Displays real contour lines of a bi-variate function.

plot(FUNC [,GEOMETRY] [,XRANGE] [,ID] [,NAME])
     :: 1 変数関数のグラフを表示する.

     :: Displays the graph of a univariate function.

polarplot(FUNC [,GEOMETRY] [,THETARANGE] [,ID] [,NAME])
     :: 極形式で与えられた曲線を表示する.

     :: Displays the graph of a curve given in polar form.

plotover(FUNC,ID,NUMBER)
     :: すでに存在しているウィンドウへ描画する.

     Plots on the existing window real zeros of a bivariate function.

return
     整数

     integer

func
     多項式

     polynomial

geometry  xrange  yrange  zrange
     リスト

     list

id  number
     整数

     integer

name
     文字列

     string

  * ifplot() は, 2 変数関数 FUNC の実数上での零点のグラフの表示を行う. conplot() は, 同様の引数に対し, 等高線の表示を行う. plot() は 1 変数関数のグラフの表示を行う. polarplot() は 極形式 R=F(THETA) で表された曲線のグラフの表示を行う.

  * これらは OpenXM サーバとして実現されている. UNIX 上では ox_plot が, Windows 上では engine がこれらの機能を提供しており, これらは Asir の標準ライブラリディレクトリにある. アクティブな ox_plot の id が ID として指定された場合, そのサーバが用いられる. id の指定がない場合には, 起動されているサーバのうち, ox_plot があればそのサーバが用いられる. ox_plot が起動されていない場合には, ox_launch_nox() が自動的に実行されて, ox_plot が立ち上がり, それが用いられる.

  * 引数の内, FUNC は必須である. その他の引数はオプションである. オプションの形式およびそのデフォルト値 (カッコ内) は次の通り.

     geometry
          ウィンドウのサイズをドット単位で [X,Y] で指定する. ([300,300]. )

     xrange  yrange
          変数の範囲の指定で, [V,VMIN,VMAX] で指定する. (いずれの変数も [V,-2,2].) この指定がない場合, FUNC に含まれる変数の内変数順序の上の変数が x, 下の変数が y として扱われる. これを避けるためには XRANGE, YRANGE を指定する. また, FUNC が 1 変数の場合, これらの指定は必須となる.

     zrange
          conplot() の場合のみ指定できる. 形式は [V,VMIN,VMAX [,STEP ]] で, STEP が指定された場合には, 等高線の間隔が (VMAX-VMIN)/STEP となる. ([Z,-2,2,16].)

     id
          遠隔プロセスの番号, すなわち ox_launch() が返した番号を指定する. (一番最近に作られ, かつアクティブなプロセスに対応する番号.)

     name
          ウィンドウの名前. (Plot.) 生成されたウィンドウのタイトルは NAME:N/M となる. これは, プロセス番号 N のプロセスの, M 番のウィンドウを意味する. この番号は, plotover() で用いられる.

  * 一つのプロセス上で描画できるウィンドウの数は最大 128 個である.

  * plotover() は, 指定したウィンドウ上に, 引数である 2 変数多項式の零点を上書きする.

  * 描画終了後のウィンドウ上で, マウスの左ボタンを押しながらのドラッグで範囲を指定しボタンを離すと新たなウィンドウが生成され, 指定した範囲が拡大して表示される. ドラッグは左上から右下へと行う. ドラッグを始めた後キャンセルする場合は, マウスポインタを始点の上か左に持っていってボタンを離せばよい. 新しいウインドウの形は, 指定領域と相似で, 最大辺が, 元のウィンドウの最大辺と一致するように定められる. 以下で説明する precise が on の場合, 選択した領域が同一 window 上で書き直される.

  * ウィンドウ内で右ボタンを押すと, その点の座標がウィンドウの下部に表示される.

  * conplot() で生成したウィンドウにおいて, ウィンドウの右側のマーカを中ボタンでドラッグすると, 対応する等高線の色が変わり, 右上のウィンドウに対応するレベルが表示される.

  * UNIX 版ではいくつかのボタンによりいくつかの設定変更, 操作ができる. UNIX 版では次のボタンがある.

     quit
          window を破壊する. 計算を中断する場合, ox_reset() を用いる.

     wide (トグル)
          現在の表示部分を縦横各 10 倍した領域を表示する. 現在表示されている範囲はこの表示において中央部に長方形で示される. この表示で範囲指定を行うと, その範囲が新しいウィンドウに描画される.

     precise (トグル)
          選択領域を, 整数演算により, より正確に再描画する. これは, FUNC が有理数係数の 2 変数多項式の場合にのみ有効である. このモードでは Sturm 列と二分法により, 区間内の零点の個数を正確に求めていくもので, デフォルトの計算法よりも正確な描画が期待できる. ただし, 描画時間は余計にかかる場合が多い. この説明から明らかなように, この機能は有理数係数の多項式の描画に対してのみ有効である. ((x^2+y^2-1)^2 の描画で試してみよ.)

     formula
          対応する式を表示する.

     noaxis (トグル)
          座標軸を消す.

  * ox_plot が起動されるマシンによっては, スタックを大量に使用するものもあるため, .cshrc でスタックサイズを大きめ (16MB 程度) に指定しておくのが安全である. スタックサイズは limit stacksize 16m などと指定する.

  * X では、ウインドウの各部分について resource により色付けや、ボタンの形を変えることができる。 resource の指定の仕方は以下の通り。（デフォルトを示しておく） plot*form*shapeStyle は、rectangle, oval, ellipse, roundedRectangle が、指定できる。

  * Function ifplot() draws a graph of real zeros of a bi-variate function. Function conplot() plots the contour lines for a same argument. Function plot() draws the graph of a uninivariate function. Function polarplot() draws the graph of a curve given in polar form R=F(THETA).

  * The plotting functions are realized by an OpenXM server. On UNIX it is ox_plot in Asir root directory. On Windows engine acts as ox_plot. Of course, it must be activated by ox_launch() ox_launch_nox(). If the identifier of an active ox_plot is specified as ID, the server is used for drawing pictures. If ID is not specified, an available ox_plot server is used if it exists. If no ox_plot server is available, then ox_launch_nox() is automatically executed to invoke ox_plot.

  * Argument FUNC is indispensable. Other arguments are optional. The format of optional arguments and their default values (parenthesized) are listed below.

     geometry
          Window size is specified by [X,Y] in unit `dot.' [300,300] for UNIX version;

     xrange  yrange
          Value ranges of the variables are specified by [V,VMIN,VMAX]. ([V,-2,2] for each variable.) If this specification is omitted, the indeterminate having the higher order in FUNC is taken for x and the one with lower order is taken for y.  To change this selection, specify explicitly by XRANGE and/or YRANGE. For an uni-variate function, the specification is mandatory.

     zrange
          This specification applies only to conplot().  The format is [V,VMIN,VMAX [,STEP ]]. If STEP is specified, the height difference of contours is set to (VMAX-VMIN)/STEP. ([Z,-2,2,16].)

     id
          This specifies the number of the remote process by which you wish to draw a graph. (The number for the newest active process.)

     name
          The name of the window. (Plot.) The created window is titled NAME:N/M which means the M-th window of the process with process number N. These numbers are used for plotover().

  * The maximum number of the windows that can be created on a process is 128.

  * Function plotover() superposes reals zeros of its argument bi-variate function onto the specified window.

  * Enlarged plot can be obtained for rectangular area which is specified, on an already existing window with a graph, by dragging cursor with the left button of mouse from the upper-left corner to lower-right corner and then releasing it. Then, a new window is created whose shape is similar to the specified area and whose size is determined so that the largest side of the new window has the same size of the largest side of the original window. If you wish to cancel the action, drag the cursor to any point above or left of the starting point.

     This facility is effective when precise button switch is inactive.  If precise is selected and active, the area specified by the cursor dragging will be rewritten on the same window. This will be explained later.

  * A click of the right button will display the current coordinates of the cursor at the bottom area of the window.

  * Place the cursor at any point in the right marker area on a window created by conplot(), and drag the cursor with the middle mutton.  Then you will find the contour lines changing their colors depending on the movement of the cursor and the corresponding height level displayed on the upper right corner of the window.

  * Several operations are available on the window: by button operations for UNIX version, and pull-down menus for Windows version.

     quit
          Destroys (kills) the window.  While computing, quit the current computation. If one wants to interrupt the computation, use ox_reset().

     wide (toggle)
          Will display, on the same window, a new area enlarged by 10 times as large as the current area for both width-direction and height-direction.  The current area will be indicated by a rectangle placed at the center.  Area specification by dragging the cursor will create a new window with a plot of the graph in the specified area.

     precise (toggle)
          When selected and active, ox_plot redraws the specified area more precisely by integer arithmetic. This mode uses bisection method based on Sturm sequence computation to locate real zeros precisely.  More precise plotting can be expected by this technique than by the default plotting technique, at the expense of significant increase of computing time.  As you see by above explanation, this function is only effective to polynomials with rational coefficients. (Check how they differ for (x^2+y^2-1)^2.)

     formula
          Displays the expression for the graph.

     noaxis (toggle)
          Erase the coordinates.

  * Program ox_plot may consume much stack space depending on which machine it is running. You are recommended to set the stack size to about 16MB as large in .cshrc for safe. To specify the size, put limit stacksize 16m for an example.

  * You can customize various resources of a window on X, e.g., coloring, shape of buttons etc. The default setting of resources is shown below. For plot*form*shapeStyle you can select among rectangle, oval, ellipse, and roundedRectangle.

          plot*background:white
          plot*form*shapeStyle:rectangle
          plot*form*background:white
          plot*form*quit*background:white
          plot*form*wide*background:white
          plot*form*precise*background:white
          plot*form*formula*background:white
          plot*form*noaxis*background:white
          plot*form*xcoord*background:white
          plot*form*ycoord*background:white
          plot*form*level*background:white
          plot*form*xdone*background:white
          plot*form*ydone*background:white

参照

References
     ox_launch ox_launch_nox ox_shutdown, ox_reset ox_intr register_handler

open_canvas, clear_canvas, draw_obj, draw_string
------------------------------------------------

open_canvas(ID[,GEOMETRY])
     :: 描画用ウィンドウ (キャンバス) を生成する.

     :: Opens a canvas, which is a window for drawing objects.

clear_canvas(ID,INDEX)
     :: キャンバスをクリアする.

     :: Clears a canvas.

draw_obj(ID,INDEX,POINTORSEGMENT [,COLOR])
     :: キャンバス上に点または線分を描画する.

     :: Draws a point or a line segment on a canvas.

draw_string(ID,INDEX,[X,Y],STRING [,COLOR])
     :: キャンバス上に文字列を描画する.

     :: Draws a character string on a canvas.

return
     0

id  index  color  x  y
     整数

     integer

pointorsegment
     リスト

     list

string
     文字列

     character string

  * これらは OpenXM サーバ ox_plot (Windows 上では engine) により提供される.

     These functions are supplied by the OpenXM server ox_plot (engine on Windows).

  * open_canvas は, 描画用のウィンドウ(キャンバス)を生成する. GEOMETRY によりウィンドウのサイズを pixel 単位で [X,Y] で指定する. default size は [300,300]. キャンバスの識別子として, 整数値を OpenXM サーバのスタックに push する. この識別子は draw_obj の呼び出しに必要であり, ox_pop_cmo により取り出して保持する必要がある.

     open_canvas opens a canvas, which is a window for drawing objecgts. One can specifies the size of a canvas in pixel by supplying GEOMETRY option [X,Y]. The default size is [300,300]. This function pushes an integer value onto the stack of the OpenXM server. The value is used to distiguish the opened canvas and one has to pop and maintain the value by ox_pop_cmo for subsequent calls of draw_obj.

  * clear_canvas は, サーバ id ID, キャンバス id INDEX で指定されるキャンバスをクリアする.

     clear_canvas clears a canvas specified by a server id ID and a canvas id INDEX.

  * draw_obj は, サーバ id ID, キャンバス id INDEX で指定されるキャンバスに点または線分を描画する. POINTORSEGMENT が [X,Y] の場合点の座標, [X,Y,U,V] の場合 [X,Y], [U,V] を結ぶ線分を表すと見なされる. キャンバスの座標は, 左上隅を原点として横方向に第一座標, 縦方向に第二座標をとる. 値は pixel 単位で指定する. COLOR の指定がある場合, COLOR/65536 mod 256, COLOR/256 mod 256, COLOR mod 256 をそれぞれ Red, Green, Blue の値 (最大 255) とみなす.

     draw_obj draws a point or a line segment on a canvas specified by a server id ID and a canvas id INDEX. If POINTORSEGMENT is [X,Y], it is regarded as a point. If POINTORSEGMENT is [X,Y,U,V], it is regarded as a line segment which connects [X,Y] and [U,V]. If COLOR is specified, COLOR/65536 mod 256, COLOR/256 mod 256, COLOR mod 256 are regarded as the vaules of Red, Green, Blue (Max. 255) respectively.

  * draw_string は, サーバ id ID, キャンバス id INDEX で指定されるキャンバスに文字列を描画する. 位置は [X,Y] により指定する.

     draw_string draws a character string STRING on a canvas specified by a server id ID and a canvas id INDEX. The position of the string is specified by [X,Y].

     [182] Id=ox_launch_nox(0,"ox_plot");
     0
     [183] open_canvas(Id);
     0
     [184] Ind=ox_pop_cmo(Id);
     0
     [185] draw_obj(Id,Ind,[100,100]);
     0
     [186] draw_obj(Id,Ind,[200,200],0xffff);
     0
     [187] draw_obj(Id,Ind,[10,10,50,50],0xff00ff);
     0
     [187] draw_string(Id,Ind,[100,50],"hello",0xffff00);
     0
     [189] clear_canvas(Id,Ind);
     0

参照

References
     ox_launch ox_launch_nox ox_shutdown, ox_reset ox_intr register_handler, ox_pop_cmo ox_pop_local.