BOINCのAPI
BOINCのAPI |
|
BOINCのAPIはC++言語で書かれた関数の集まりです。 とくに明記しないかぎり、これら関数は整数の復帰値でエラーコードを返します。 値 0 が成功を示します。 [0 でない場合、つまり] 失敗で復帰したときには、 [そのAPIを呼び出した]アプリケーションはその[復帰値を]ステイタスとして exitするべきです。 BOINCのグラフィクスAPIについては、 分けて 説明します。
int boinc_init(bool standalone=false);
引数 standalone を true で呼んだ場合は、
アプリケーションはBOINCコア・クライアントとは独立に機能します。
（この動作は、テストのときに役に立ちます(訳注1)）。
アプリケーションが終了するときには、
int boinc_finish(int status);
を呼ばなければなりません。 もしエラーに遭遇していた場合は、
status は 0でない値にします。
この関数は復帰しません。
int boinc_resolve_filename(char *logical_name, char *physical_name, int len);
または、
int boinc_resolve_filename(char *logical_name, string& physical_name);
を呼ぶ必要があります。 たとえば、
f = fopen("my_file", "r");
と書くかわりに、アプリケーションは、たとえば
string resolved_name;
retval = boinc_resolve_filename("my_file", resolved_name);
if (retval) fail("can't resolve filename");
f = fopen(resolved_name.c_str(), "r");
という使い方をするという具合です。
boinc_resolve_filename() は、一時的なファイルには使う必要はありません。
チェック・ポインティングの頻度は、利用者の好み(preference)で設定可能です。 （たとえば、ラップトップ型マシンだったら、まれにしかチェックポイントを とらないかもしれません）。 アプリケーションは、 チェックポイントをとることが可能なところにきたら、いつでも、
bool boinc_time_to_checkpoint();
を呼ぶ必要があります。
この関数が true を返したら、アプリケーションは状態ファイルへの書き出しを
行い、全ての出力ファイルをフラッシュしてから、
void boinc_checkpoint_completed();
を呼んでください。
boinc_time_to_checkpoint()は高速ですから、
頻繁に（毎秒100〜1000回）呼んでも問題ありません。
チェックポイントをアトミックに取るのが楽になるよう、
アプリケーションは出力ファイルと状態ファイルへの書き出し処理に、
MFILE クラスを使えるようにしてあります。
class MFILE {
public:
int open(char* path, char* mode);
int _putchar(char);
int puts(char*);
int printf(char* format, ...);
size_t write(const void* buf, size_t size, size_t nitems);
int close();
int flush();
};
MFILE はデータをメモリ上に溜め込んで、
flush() または close() が呼ばれたときだけ、
ディスクへの書き込みをします。 これを使えば、出力ファイルと状態ファイルを
ほとんどアトミックに書き出すことができます。
コア・クライアントのGUIは、計算中のワークユニットの完了率(%)を表示します。 この表示を最新に保つため、アプリケーションは定期的に
boinc_fraction_done(double fraction_done);という関数を呼ぶ必要があります。 ここで、
fraction_done
という引数が、おおまかに推定したワークユニットの完了率
（０〜１の間の値）です。
この関数は高速ですから、頻繁に呼んで問題ありません。
下記の関数群によって、コア・クライアントから種々の情報を取り出すことができます。 グラフィクスの表示に便利ではないでしょうか。
int boinc_get_init_data(APP_INIT_DATA&);
struct APP_INIT_DATA {
char project_preferences[4096];
char user_name[256];
char team_name[256];
double user_total_credit;
double user_expavg_credit;
double team_total_credit;
double team_expavg_credit;
};
この関数を使って取り出せる情報は、以下のとおりです：
| project_preferences | XML形式の文字列。 この参加者のプロジェクトごとの好みの設定（preference)を表現しています。 |
| user_name | このプロジェクトにおける、この参加者の 「スクリーンネーム(訳注3)」。 |
| team_name | この参加者の所属するチーム名（チームに入っている場合のみ）。 |
| user_total_credit | この参加者がこのプロジェクトでこなした仕事の総計。 |
| user_expavg_credit | この参加者が最近こなしている日ごとの仕事の平均量。 |
| team_total_credit | [この参加者の属する]チームが、 このプロジェクトでこなした仕事の総量。 |
| team_expavg_credit | [この参加者の属する]チームが、 最近こなしている日ごとの仕事の平均量。 |
アプリケーションは、費やした総CPU時間を得るのに
int boinc_wu_cpu_time(double &cpu_time);
という関数を使えます。 （得られるCPU時間は、処理中のワークユニットを
計算し始めたときからの累計です。 最近の再開時点からの時間ではありません）。
グラフィクスの描画にかかったCPU時間は、この値では除かれています。
個々のプログラムは、それらごとに状態ファイルを持つべきであり、 取りまとめ役(coordinator)である主プログラムの状態ファイルは、 どの子プログラムが最後に動作していたかを記録します。
完了率を正しく実装するためには、主プログラムは子プログラムに対して （おそらくコマンドライン引数として）、その子プログラムが 開始する時点と終了する時点の完了率の情報を示してやるべきでしょう。
この取りまとめ役のプログラムは、子プロセスを作る(folkする）前に、
void boinc_child_start();
を呼ばなければなりません。
子プロセスが終了したら、取りまとめ役のプログラムは、
次の子プロセスを作る前に、
void boinc_child_done(double total_cpu);
という関数を呼んで、終了した子プロセスが使ったCPU時間を得る
必要があります。