BOINCのAPI （古い記事です。 Wiki に移行済)

(英語のみ)

BOINCのAPIは Ｃ＋＋言語で書かれた関数の集まりです。 これらのほとんどは、Ｃ言語インタフェースでできており、 Ｃやその他の計算機言語から使えるようにしてあります。 とくに明記しないかぎり、 これら関数は整数の復帰値でエラーコードを返します。 値 0 が成功を示します。

BOINC のアプリケーションはグラフィクスを生成しても良く、 スクリーンセイバーの機能を提供することができます。 これについては、グラフィクス API で説明します。

BOINC のアプリケーションは、順番に実行される一連の複数のプログラムで 構成することもできます。 このようなアプリケーションは、 複合アプリケーションと呼ばれます。 このための API を 複合アプリケーションのページで説明しています。

初期化と使用終了

アプリケーションは、他のどのBOINC のAPI呼出しよりも前に、 診断機能の初期化 を呼び出さなければなりません。

グラフィクス用の初期化と、複合アプリケーション用の初期化については、 別途記述があります(上述のリンクをたどって下さい)。 その他のアプリケーションでは、他のBOINCの関数を呼んだり、 入出力処理をする前に下記の関数をよばなければなりません。

int boinc_init();

アプリケーションが終了するときには、

int boinc_finish(int status);

あなたのアプリケーションは BOINC の制御のもとで走っているか?

テストのために、BOINC のアプリケーションは 「スタンドアローン」モードで 動作させることもできますし、 BOINC クライアントのもとで走らせることもできます。 どちらの状態で動作しているかによって、そのアプリケーションの振る舞いを変えたいこともあるでしょう。 たとえば、スタンドアローン モードだったら、デバッグ情報を出力したいかもしれません。 スタンドアローン モードにいるのか、 BOINC クライアントの制御のもとで動作しているかを 調べるには、次の関数を呼んで下さい。

int boinc_is_standalone(void);

ファイル名の解決

int boinc_resolve_filename_s(char *logical_name, char *physical_name, int len);

int boinc_resolve_filename(char *logical_name, std::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");

I/O ラッパー

アプリケーションは、fopen() コールを以下で置き換える必要があります。

boinc_fopen(char* path, char* mode);

チェック・ポインティング

チェック・ポインティングの頻度は、利用者の好み(preference)で設定可能です。 (たとえば、ラップトップ型マシンだったら、まれにしかチェックポイントをとらないかもしれません)。 アプリケーションは、チェックポイントをとることが可能なところにきたら、いつでも、

int boinc_time_to_checkpoint();

void boinc_checkpoint_completed();

クリティカル・セクション

void boinc_begin_critical_section();
void boinc_end_critical_section();

アトミックな^訳注3ファイル更新

チェックポイントをアトミックに取るのが楽になるよう、 アプリケーションは出力ファイルと状態ファイルへの書き出し処理に、 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();
};

void boinc_ops_per_cpu_second(double floating_point_ops, double integer_ops);

void boinc_ops_cumulative(double floating_point_ops, double integer_ops);

boinc_fraction_done(double fraction_done);

double boinc_get_fraction_done();

下記の関数群によって、コア・クライアントから種々の情報を取り出すことができます。 グラフィクスの表示に便利ではないでしょうか。

int boinc_get_init_data_p(APP_INIT_DATA*);
int boinc_get_init_data(APP_INIT_DATA&);

struct APP_INIT_DATA {
    int major_version;
    int minor_version;
    int release;
    int app_version;
    char app_name[256];
    char symstore[256];
    char acct_mgr_url[256];
    char* project_preferences;
    int userid;
    int teamid;
    int hostid;
    char user_name[256];
    char team_name[256];
    char project_dir[256];
    char boinc_dir[256];
    char wu_name[256];
    char authenticator[256];
    int slot;
    double user_total_credit;
    double user_expavg_credit;
    double host_total_credit;
    double host_expavg_credit;
    double resource_share_fraction;
    HOST_INFO host_info;
    PROXY_INFO proxy_info;  // in case app wants to use network
    GLOBAL_PREFS global_prefs;

    // info about the WU
    double rsc_fpops_est;
    double rsc_fpops_bound;
    double rsc_memory_bound;
    double rsc_disk_bound;

    // the following are used for compound apps,
    // where each stage of the computation is a fixed
    // fraction of the total.
    double fraction_done_start;
    double fraction_done_end;
};

アプリケーションは、費やした総CPU時間を得るのに

int boinc_wu_cpu_time(double &cpu_time);

ネットワーク接続の要求

もし、ネットワーク接続が物理的に存在していないようであれば、 (例えば、gethostbyname() 呼出しが 正当な名前について失敗する場合) 下記を行ってください。

• 関数 boinc_need_network() を呼びます。 この関数は参加者にネットワーク接続が必要だという注意を喚起します。
• 0 が返されるまで、周期的に boinc_network_poll() を呼び出します。
• 通信が必要な処理を実施します。
• 終わったら、boinc_network_done() を呼びます。 この関数は必要なら、モデム接続を終了させます。

void boinc_need_network();
int boinc_network_poll();
void boinc_network_done();

(訳注1) fraction_done:

大まかに見積もった計算完了率。 APIを参照してください。

(訳注2) (削除)

(訳注3) アトミック(atomic):

ある処理が実行されるかされないかどちらかで、中途半端になることがないとき、 それをアトミック(原子的)という言い方をします。 この場合は、書き出し処理が 全部正常に終わるか、まったく書き出しがおこらないかどちらかで、途中まで書いたが あとは書けなかったということはないぞ、ということが理想のatomicです。 しかし、このクラス MFILE の説明からすると完全にatomicではなく、実用的にはこれで充分、という実装のようです。

(訳注4) スクリーンネーム(screen name):

プロジェクトごとに参加者が名乗ることのできるニックネームのようなもの。

(訳注5) 認証子(authenticator):

アカウント・キーのこと。

最終更新時刻 16:12:06, 2007年05月19日(JST)
Copyright © 2008 University of California. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation.
Copyright © 2008 Komori Hitoshi(je2bwm at jarl.com). Japanese translation from English web pages on BOINC. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation.