Application Program Interface 仕様 (Perl Version 0)

この API は perl ver.5 で実現する事を前提として設計されている。
なお、現在、アプリケーションの高速化を図るために、 C による実現を前提とした API も開発中である。

API の利用方法

この様な環境の下で、 perl ver.5 で書かれたアプリケーション・プログラムの中から、 use GlueLogic; で API パッケージを呼び出したのち、 API 関数群を呼び出す。

なお、標準入力から文字単位の入力を望む場合には、 同様に GlueLogicChar.pm を library search path に入れ、 use GlueLogicChar; でパッケージを呼び出す。

API の構成

• Glue Logic の初期化／終了を行なうもの
• Glue Logic とのデータのやりとりを行なうもの
• ユーティリティ関数

API 変数は、システムの実行環境を記述するものと、 Glue Logic Server からの変更通知メッセージを受け取るもの、 その変更通知に応じて処理関数を dispatch するための関数管理変数に分けられる。

#Integer
$FloatingPoint
"CharacterString
@Link
%Expression
UNBOUND

名前の持つ属性は、 その名前の表現の後にアポストロフィーで区切って属性の識別子を付ける事で表現する。

$GlueLogicAgent

Glue Logic の Server が Client を識別するシンボル名称が入る。 &GlueLogicConnect の呼び出し前に値か確定している時には その値が実際に使われ、未確定であった場合は環境変数または &GlueLogicConnect の引数の値が代入される。
&GlueLogicParseArgs を実行した場合には、 標準コマンドライン・オプションである -Agent の値がセットされる。

$GlueLogicAnchor

他のアプリケーションが Glue Logic 経由で交信する時に使う名前が入る。 &GlueLogicConnect の呼び出し前に 値か確定している時にはその値が実際に使われ、 未確定であった場合は環境変数または &GlueLogicConnect の引数の値が代入される。
&GlueLogicParseArgs を実行した場合には、 標準コマンドライン・オプションである -Anchor の値がセットされる。

$GlueLogicServer

Server の稼働しているホストとポート番号が入る。 値は文字列で "ServerHost:Port" の形式を採る。 &GlueLogicConnect の呼び出し前に値か確定している時には その値が実際に使われ、 未確定であった場合は環境変数または &GlueLogicConnect の 引数の値が代入される。
&GlueLogicParseArgs を実行した場合には、 標準コマンドライン・オプションである -Server の値がセットされる。

$GlueLogic????

&GlueLogicParseArgs の引数に与えられた名前のオプションが、 client の起動コマンドに指定されていた場合に、そのオプションの値が代入される。 値の指定は一般に、 -Option Value の形で与える。 フラグとしてオプション名だけが指定されていた場合は整数 1 が代入される。
この変数の名前は、文字列 "GlueLogic" に、 指定したオプションの名前文字列の 先頭文字だけを大文字にそれに続く文字列を全て小文字に変換したものを 接合したものである。

@GlueLogicMessageQueue

Server から送られたメッセージを入れる待ち行列。
Server との接続が切れると、 undef を返す。 Event loop は予期しない接続の切断を必ずチェックしなければならない。

@GlueLogicStdinQueue

標準入力から送られた行を入れる待ち行列。
行末の改行文字は取り除かれない。 標準入力からのファイルの終わりが検出されると、 undef を返す。 Event loop は予期しないファイルの終わりを必ずチェックしなければならない。

ただし、 GlueLogicChar.pm パッケージを使用している時には、 この待ち行列には標準入力から与えられたデータが 1 バイトづつ要素として入れられる。

%GlueLogicMessageDispatch

アンカー名にメッセージが書き込まれた時に、 起動するべき関数の名称を 受け取ったメッセージの最初の単語をキーとして納めた連想配列。 対応する関数の指定が無い場合にはそのメッセージは単に無視される。 指定された関数を起動する際には、メッセージの最初の単語が第一引数に、 残りの部分が第二引数に、それぞれ文字列で渡される。

%GlueLogicChangeDispatch

Server からアンカー名以外の名前の変更通知を受け取った時に、 起動するべき関数の名称を 値の変更を通知された名前をキーとして納めた連想配列。 対応する関数の指定が無い場合にはその変更通知は単に無視される。 指定された関数を起動する時には、通知された名前が引数として渡される。

%GlueLogicCommandDispatch

標準入力コマンド文字列を受け取った時に、 起動するべき関数の名称を 入力されたコマンドの最初の単語をキーとして納めた連想配列。 対応する関数の指定が無い場合には、 その入力に対して "Unknown Command" という行が標準出力に印字される。 指定された関数を起動する時には、 入力された行が最後の復帰改行文字だけ取り除かれて渡される。

&GlueLogicConnect ( AgentID, ServerSpec, AnchorName )

Glue Logic を初期化し、通信路を確立する。 引数は順に、アプリケーション・エージェント識別子、 Glue Logic Server のホスト名と接続すべきポート番号、 アプリケーション・エージェントがアンカーとして使う名前、 である。
この関数の引数で指定する値は、最も優先度の低い、 default として使うべき値である。各々に対応する環境変数 GLUELOGICAGENT, GLUELOGICSERVER, GLUELOGICANCHOR が設定されていればそれらの方が優先して利用され、 もしもこの関数が呼び出される前に変数 $GlueLogicAgent, $GlueLogicServer, $GlueLogicAnchor が設定されている場合には、その値が最も優先して使われる。
この機能は &GlueLogicParseArgs がセットした、 標準コマンドライン・オプションから与えられた値を 容易に利用できるようにするものである。

&GlueLogicDisconnect ( )

Glue Logic の通信路を閉鎖する。

&GlueLogicAccess ( OperationList )

Glue Logic とのデータのやりとりを行なう。 引数には任意の個数の操作を指定でき、 各操作に対してサーバが送り返して来たデータをリストにして返す。 操作の指定はクライアント−サーバ間のプロトコルに依存する。
詳細は Glue Logic Protocol 仕様を参照のこと。

&GlueLogicEnqueueMessage ( )

Glue Logic Server からの通知メッセージが到着しておればそれらを @GlueLogicMessageQueue に取り込むと同時に、 標準入力からの入力行があればそれを @GlueLogicStdinQueue に取り込む。
標準入力からの入力行では、行末の改行文字は取り除かれない。

なお、メニューのオペレーションなど、標準入力から文字単位の入力を望む場合のために、 GlueLogicChar.pm というパッケージが別に用意されている。 このパッケージでは入力から与えられる文字の 1 バイトづつが @GlueLogicStdinQueue の要素となる点のみが異なっている。

&GlueLogicWaitForMessage ( )

Glue Logic からの変更通知メッセージの到着、 あるいは標準入力からの入力行の到着の、 いずれかが発生するまで待ち合わせる。

&GlueLogicSleepUntil ( Time )

指定した時刻が来るまで処理を中断する。 時刻の指定は perl の time 関数や UNIX の gettimeofday システム・コールで返されるものと同じ、 1970 年 1 月 1 日からの経過秒数で行なう。 処理を中断している間に、Glue Logic からの変更通知メッセージの到着、 あるいは標準入力からの入力行の到着の、 いずれかが発生した場合には、 指定時刻になる前であっても処理を再開する。

&GlueLogicWaitForChanged ( NameList )

指定したリスト NameList に含まれる名前に関する変更通知メッセージが届くまで待ち合わせる。
@GlueLogicMessageQueue には一切変更を加えない。

&GlueLogicDequeueChanged ( NameList )

リスト NameList に含まれる名前に関する変更通知メッセージを @GlueLogicMessageQueue から削除する。

&GlueLogicParseArgs ( OptionList )

アプリケーションの起動コマンドのオプション引数の解析を行ない、 Glue Logic で定義された標準コマンドライン・オプションや、 引数に挙げられたユーザ定義オプションが指定されていれば、 その値を所定の変数に代入する。
解析の対象となるオプションは、-Agent, -Server, -Anchor および引数の OptionList に示した アプリケーション依存のオプション群となる。 これらの値はそれぞれ $GlueLogicAgent, $GlueLogicServer, $GlueLogicAnchor および $GlueLogicXxxxxx の値となる。

&GlueLogicMainLoop ( )

三つの連想配列 %GlueLogicMessageDispatch, %GlueLogicChangeDispatch , %GlueLogicCommandDispatch を用いて、アンカー名に対するメッセージの送付、その他の名前に対する変更通知、 標準入力から入力されたコマンド行のそれぞれのイベントに対応した 処理関数を起動するような top level event loop を実現する。
標準入力からファイルの終わりを入力されると top loop を抜ける。