[BOINC 开发文档]Developing a BOINC application 部分

碧城仙

Developing a BOINC application 部分

待翻译的页面列表见：http://boinc.berkeley.edu/create_project.php
http://boinc.equn.com/dev/create_project.html

Developing a BOINC application

　　·The BOINC API
　　　　Basic API                     ——>感谢 Youth 翻译！
　　　　Diagnostics API                     ——>感谢 Youth 翻译！
　　　　Graphics API                    ——>感谢 bonny95 翻译！
　　　　Trickle messages API                     ——>感谢 bonny95 翻译！
　　　　Intermediate upload API                     ——>感谢 bonny95 翻译！
　　·Application development
　　　　Application development tips                     ——>感谢 dogcatdog 翻译！
　　　　Application debugging                      ——>感谢 dogcatdog 翻译！
            App development cookbook                    ——>感谢 Firenet 翻译！
　　·FORTRAN applications
　　·Compound applications                    ——>感谢 fwjmath 翻译！

Youth

这里的页面太长,我适当分开一下,大家要校正也方便些。

http://boinc.berkeley.edu/api.php

The BOINC application programming interface (API)
Last modified 7:24 PM UTC, March 15 2006

BOINC 应用程序编程接口 (API)

The BOINC API is a set of C++ functions. Most of the functions have a C interface, so that they can be used from programs written in C and other languages. Unless otherwise specified, the functions return an integer error code; zero indicates success.

BOINC 的 API 是一套 C++ 的函数。大多数函数也有 C 的接口，因此可以在用 C 或其它编程写的程序中使用。除非特别说明，函数均返回一个整型的错误码；如果是零就表示操作成功。

BOINC applications may generate graphics, allowing them to provide a screensaver. This API is described here.

BOINC 的计算程序可以生成图形，允许它们提供一个屏保。相关的 API 请看这里。

BOINC applications may consist of several programs that are executed in sequence; these are called compound applications. This API is described here.

BOINC 的计算程序可以包含几个依次执行的程序；这种被称之为复合计算程序。相关的 API 请看这里。

Initialization and termination

初始化和终结

Applications should initialize diagnostics before any other BOINC calls.

计算程序应该在使用所有其它的 BOINC 调用前，首先初始化诊断接口。

Initialization for graphical and compound applications are described elsewhere (see links above). Other applications must call

    int boinc_init();

before calling other BOINC functions or doing I/O.

图形和复合计算程序的初始化在其它页面进行说明（请看上文的链接）。而其它类型的计算程序必须在调用其它 BOINC 函数前调用：

When the application has completed it must call

    int boinc_finish(int status);

status is nonzero if an error was encountered. This call does not return.

当计算程序完成时，它必须调用：

如果发生错误，status是一个非零值。该调用并不返回。

Is your application running under the control of the BOINC client?

您的计算程序正在 BOINC 客户端的控制下运行吗？

BOINC applications can be run in "standalone" mode for testing, or under the control of the BOINC client. You might want your application to behave differently in the two cases. For example you might want to output debugging information if the application is running standalone. To determine if the application is running in standalone mode or under the control of the BOINC client, call

    int boinc_is_standalone(void);

This returns non-zero (True) if the application is running standalone, and zero (False) if the application is running under the control of the BOINC client.

BOINC 的计算程序可独立模式运行以进行测试，或者在 BOINC 客户端控制下运行。您也许希望您的计算程序在两种模式下的执行情况有所不同。比如，你可能会想在独立模式运行时输出一些调试信息。要检测计算程序是运行在独立模式还是在 BOINC 客户端控制下，调用

如果计算程序运行在独立模式下，函数将返回非零值(逻辑真)，否则将返回零(逻辑假)，这时计算程序是在 BOINC 客户端控制下的。

Resolving file names

文件名的解析

Applications that use named input or output files must call

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

or

    int boinc_resolve_filename_s(char *logical_name, std::string& physical_name);

to convert logical file names to physical names. For example, instead of

    f = fopen("my_file", "r");

the application might use

    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() doesn't need to be used for temporary files.

计算程序在使用命名的输入或输出文件时必须调用：

或者：
       
以将逻辑文件名转换为物理文件名。比如，计算程序不应直接进行如下调用：

而应该：

如果要使用临时文件不需要调用 boinc_resolve_filename()。
       
I/O wrappers

I/O 封装

Applications should replace fopen() calls with

boinc_fopen(char* path, char* mode);

This deals with platform-specific problems. On Windows, where security and indexing programs can briefly lock files, boinc_fopen() does several retries at 1-second intervals. On Unix, where signals can cause fopen() to fail with EINTR, boinc_fopen checks for this and does a few retries; it also sets the 'close-on-exec' flag.

计算程序应该将对 fopen() 的调用替换成：

该函数用来处理一些平台相关的问题。在 Windows 平台上，系统中的安全或索引程序可能会锁定文件，boinc_fopen() 将以1秒的间隔重试若干次。在 Unix 平台上，一些信号可能导致 fopen() 操作失败并返回 EINTR，boinc_fopen() 将对其进行检查并重试若干次；它也会设置 'close-on-exec' 标志位。

Youth

Checkpointing

进度保存

Computations that use a significant amount of time per work unit may want to periodically write the current state of the computation to disk. This is known as checkpointing. The state file must include everything required to start the computation again at the same place it was checkpointed. On startup, the application reads the state file to determine where to begin computation. If the BOINC client quits or exits, the computation can be restarted from the most recent checkpoint.

对于那些需要很长时间才能完成的任务包，计算程序可能想要定期地将当前的计算状态写入到磁盘。这就是所谓的进度保存。状态文件中必须包含从计算被保存的进度再次启动计算所需的一切信息。启动计算时，计算程序将读取状态文件以决定从何处开始计算。如果 BOINC 客户端退出，下一次计算将从最近一次的保存进度开始。

Frequency of checkpointing is a user preference (e.g. laptop users might want to checkpoint infrequently). An application must call

    int boinc_time_to_checkpoint();

whenever it reaches a point where it is able to checkpoint. If this returns nonzero (True) then the application should checkpoint immediately (i.e., write the state file and flush all output files), then call

    void boinc_checkpoint_completed();

boinc_time_to_checkpoint() is fast, so it can be called frequently (hundreds or thousands of times a second).

进度保存的频率涉及到一个用户参数(比如笔记本电脑的用户可能希望保存的频率低一些)。计算程序必须在到达它认为可以保存进度的时候先调用：

如果函数返回是非零值(逻辑真)，那计算程序应该立即保存进度(比如写状态文件，提交所有输出文件)，然后调用：

boinc_time_to_checkpoint() 执行很快，因此它可以被频繁地调用(比如每秒钟成百上千次)。

Critical sections

临界区

void boinc_begin_critical_section();
void boinc_end_critical_section();

Call these around code segments during which you don't want to be suspended or killed by the core client. NOTE: this is done automatically while checkpointing.

在一段代码的前后分别调用这两个函数，可以防止这段代码的执行过程中被抢占或是被客户端给关闭进程。注意：这些函数会在保存进度的时候自动被调用。

Atomic file update

原子级的文件更新

To facilitate atomic checkpoint, an application can write to output and state files using the MFILE class.

为达到原子级的进度保存，计算程序可以使用 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 buffers data in memory and writes to disk only on flush() or close(). This lets you write output files and state files more or less atomically.

MFILE 将数据缓存在内存中，在 flush() 或 close() 被调用时才写入到磁盘。这或多或少使得您可以原子级地写输出文件和状态文件。

Credit reporting

积分上报

By default, the claimed credit of a result is based on the product of its total CPU time and the benchmark values obtained by the core client. This can produce results that are too low if the application uses processor-specific optimizations not present in the core client, is compiled with different compiler settings, or uses a GPU or other non-CPU computing resource. To handle such cases, the following functions can be used.

缺省情况下，一个计算结果的申请积分是基于总计算时间和客户端基准测结果的乘积。如果计算程序使用了客户端没有使用的处理器优化技术，或者使用了不同的编译器设置，或者利用了 GPU 或其它非 CPU 的处理资源，都可能导致申请分大幅降低。在这种情况下，可以使用如下的函数：

void boinc_ops_per_cpu_second(double floating_point_ops, double integer_ops);

This reports the results of an application-specific benchmark, expressed as number of floating-point and integer operations per CPU second.

该函数将上报应用程序指定的基准测试值，参数分别为每 CPU 秒可执行的浮点和整数操作数。

void boinc_ops_cumulative(double floating_point_ops, double integer_ops);

This reports the total number of floating-point and integer operations since the start of the result. It must be called just before boinc_finish(), and optionally at intermediate points.

该函数将上报从结果开始计算后总的浮点操作数和整数操作数。必须在每次调用 boinc_finish() 前被调用，也可以在保存进度时调用。

Communicating with the core client

与客户端的通讯

The core client GUI displays the percent done of workunits in progress. To keep this display current, an application should periodically call

   boinc_fraction_done(double fraction_done);
   
客户端的界面会显示任务包的完成进度。为了更新这个进度，计算程序应该定期调用：

The fraction_done argument is an estimate of the workunit fraction complete (0 to 1). This function is fast and can be called frequently. The sequence of arguments in successive calls should be non-decreasing. An application should never 'reset' and start over if an error occurs; it should exit with an error code.

参数 fraction_done 是对任务完成进度的估计(0到1之间)。这个函数执行很快，可以频繁地调用。如果多次调用该函数，该参数的值不应该变小。如果碰到错误，计算程序不能“重置”并重新开始；它应该返回一个错误码。

   double boinc_get_fraction_done();

returns the last value set, or -1 if none has been set (this would typically be called from graphics code).

返回最近一次的设定值，如果从未设置过，就返回-1，该函数主要是在图形代码中被调用。

Youth

The following functions get information from the core client; this information may be useful for graphics.

下面的函数用于从客户端获取信息；这些信息可能在图形中会用到。

    int boinc_get_init_data(APP_INIT_DATA&);

    struct APP_INIT_DATA {
        int core_version;
        char app_name[256];
        char project_preferences[65536];
        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 team_total_credit;
        double team_expavg_credit;
        HOST_INFO host_info;
    };

to get the following information:

可以得到的信息如下：

core version         The version number of the core client
app_name         The application name (from the server's DB)
project_preferences         An XML string containing the user's project-specific preferences.
user_name         the user's 'screen name' on this project.
team_name         the user's team name, if any.
project_dir         absolute path of project directory
boinc_dir         absolute path of BOINC root directory
wu_name         name of workunit being processed
authenticator         user's authenticator for this project
slot         The number of the app's 'slot' (0, 1, ...)
user_total_credit         user's total work for this project.
user_expavg_credit         user's recent average work per day.
team_total_credit         team's total work for this project.
team_expavg_credit         team's recent average work per day.
host_info         A structure describing the host hardware and OS

core version         客户端的版本
app_name         计算程序在服务端数据库中的名称
project_preferences         XML 字符串，包含用户的项目相关参数。
user_name         用户在当前项目的显示名称。
team_name         用户所在的团队名称，前提是用户加入了某个团队。
project_dir         项目文件夹的绝对路径。
boinc_dir         BOINC 根文件夹的绝对路径。
wu_name         正在处理的任务包名称。
authenticator         用户在当前项目的验证码。
slot         当前总的计算槽位(0, 1, ...)。
user_total_credit         用户在当前项目的总积分。
user_expavg_credit         用户的近期日平均积分。
team_total_credit         用户所在团队在当前项目的所有任务。
team_expavg_credit         用户所在团队的近期日平均积分。
host_info         用来描述主机硬件和操作系统的一个数据结构。

An application may call

    int boinc_wu_cpu_time(double &cpu_time);

to get its total CPU time (from the beginning of the work unit, not just since the last restart). This excludes CPU time used to render graphics.

计算程序可以调用：

以得到它的总 CPU 时间(从任务包最初开始时计时，而不是上次重启后)。这个值不包括用于渲染图形所耗费的 CPU 时间。

Non-CPU-intensive periods

不需要太多处理能力的时候

Some applications may have periods when they don't use much CPU time (e.g. because they're doing network communication). Call the following functions at the start and end of these periods.

void boinc_not_using_cpu();
void boinc_using_cpu();

This allows the BOINC client to schedule other applications during these periods.

一些计算程序可能会在某些时间不需要使用太多的 CPU 时间(比如他们在进行网络通讯的时候)。请在这期间的开始和结束时分别调用如下的函数：

这将允许 BOINC 客户端在这期间将处理器调度给其它的计算程序。

Requesting network connection

请求网络连接

If it appears that there is no physical network connection (e.g. gethostbyname() fails for a valid name) then

    * Call boinc_need_network(). This will alert the user that a network connection is needed.
    * Periodically call boinc_network_poll() until it returns zero.
    * Do whatever communication is needed.
    * When done, call boinc_network_done(). This enables that hangup of a modem connection, if needed.

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

Note: this should be enclosed in boinc_not_using_cpu() ... boinc_using_cpu().

如果碰到没有物理网络连接的时候(比如 gethostbyname() 不能返回一个合法的名称时)，就进行如下操作：

* 调用 boinc_need_network()。这将通知用户建立一个网络连接。
* 定期地调用 boinc_network_poll() 直到它返回零。
* 进行所有需要的网络通讯。
* 完成通讯后，调用 boinc_network_done()。以允许在需要的时候挂断调制解调器的连接。

注意：这些操作应该被包含在 boinc_not_using_cpu() 和 boinc_using_cpu() 之间。

Youth

http://boinc.berkeley.edu/diagnostics.php

The BOINC diagnostics API  
Last modified 6:18 AM UTC, October 19 2004  

BOINC 的诊断 API

BOINC applications can call
int boinc_init_diagnostics(int flags)
to initialize various diagnostic functions. This call should be made early in the program - before boinc_init() - so that error info is routed appropriately. flags is formed by or'ing together a subset of the following flags:

BOINC 的计算程序可以如下函数来初始化各种类型的诊断函数：

该函数应该在程序中尽早调用 - 在 boinc_init() 之前 - 以便可以正确地找到错误信息。错误标志由下列标志位的子集所组成：

#define BOINC_DIAG_DUMPCALLSTACKENABLED     0x00000001L
#define BOINC_DIAG_HEAPCHECKENABLED         0x00000002L
#define BOINC_DIAG_MEMORYLEAKCHECKENABLED   0x00000004L
#define BOINC_DIAG_ARCHIVESTDERR            0x00000008L
#define BOINC_DIAG_ARCHIVESTDOUT            0x00000010L
#define BOINC_DIAG_REDIRECTSTDERR           0x00000020L
#define BOINC_DIAG_REDIRECTSTDOUT           0x00000040L
#define BOINC_DIAG_REDIRECTSTDERROVERWRITE  0x00000080L
#define BOINC_DIAG_REDIRECTSTDOUTOVERWRITE  0x00000100L
#define BOINC_DIAG_TRACETOSTDERR            0x00000200L
#define BOINC_DIAG_TRACETOSTDOUT            0x00000400L

The flags are as follows. Applications are advised to use at least BOINC_DIAG_DUMPCALLSTACKENABLED, BOINC_DIAG_REDIRECTSTDERR, and BOINC_DIAG_TRACETOSTDERR.

标志位的意义如下所示。建议计算程序至少使用 BOINC_DIAG_DUMPCALLSTACKENABLED，BOINC_DIAG_REDIRECTSTDERR 和 BOINC_DIAG_TRACETOSTDERR 这些标志位。

BOINC_DIAG_DUMPCALLSTACKENABLED If the application crashes, write a symbolic call stack to stderr. If you use this in a Windows app, you must include lib/stackwalker_win.cpp in the compile, and you must include the .pdb (symbol) file in your app version bundle.
BOINC_DIAG_HEAPCHECKENABLED Check the integrity of the malloc heap every N allocations. (N is line 120 in diagnostics.C; default 1024).
BOINC_DIAG_MEMORYLEAKCHECKENABLED When process exits, write descriptions of any outstanding memory allocations to stderr.
BOINC_DIAG_ARCHIVESTDERR Rename stderr.txt to stderr.old on startup.
BOINC_DIAG_ARCHIVESTDOUT Rename stdout.txt to stdout.old on startup.
BOINC_DIAG_REDIRECTSTDERR Redirect stderr to stderr.txt.
BOINC_DIAG_REDIRECTSTDOUT Redirect stdout to stdout.txt.
BOINC_DIAG_REDIRECTSTDERROVERWRITE Overwrite stderr.txt (default is to append).
BOINC_DIAG_REDIRECTSTDOUTOVERWRITE Overwrite stdout.txt (default is to append).
BOINC_DIAG_TRACETOSTDERR Write TRACE macros to stderr (Windows specific).
BOINC_DIAG_TRACETOSTDOUT Write TRACE macros to stdout (Windows specific).

BOINC_DIAG_DUMPCALLSTACKENABLED 如果计算程序崩溃，将符号形式的调用栈定到标准错误输出。如果你是在 Windows 程序中使用，你必须在编译时包含 lib/stackwalker_win.cpp，你也必须在计算程序版本的发行包中包含对应的 .pdb (符号)文件。
BOINC_DIAG_HEAPCHECKENABLED 每 N 次内存分配时检查内存分配堆的完整性。(N 在 diagnostics.C 的第120行；缺少值是1024。)
BOINC_DIAG_MEMORYLEAKCHECKENABLED 当进程退出时，将未解决的内存分配信息写入到标准错误输出(stderr)。
BOINC_DIAG_ARCHIVESTDERR 在启动时将 stderr.txt 重命名为 stderr.old。
BOINC_DIAG_ARCHIVESTDOUT 在启动时将 stdout.txt 重命名为 stdout.old。
BOINC_DIAG_REDIRECTSTDERR 将标准错误输出(stderr)重定向到 stderr.txt。
BOINC_DIAG_REDIRECTSTDOUT 将标准输出(stdout)重定向到 stdout.txt。
BOINC_DIAG_REDIRECTSTDERROVERWRITE 覆盖 stderr.txt (缺省为追加)。
BOINC_DIAG_REDIRECTSTDOUTOVERWRITE 覆盖 stdout.txt (缺省为追加)。
BOINC_DIAG_TRACETOSTDERR 将 TRACE 宏写到标准错误输出 (仅适用于 Windows 平台)。
BOINC_DIAG_TRACETOSTDOUT 将 TRACE 宏写到标准输出 (仅适用于 Windows 平台)。

碧城仙

2～4 楼已转至：http://boinc.equn.com/dev/api.html ，5 楼已转：http://boinc.equn.com/dev/diagnostics.html

请 Youth 斑竹略微检查一下，其他已经翻译好的页面我再一个一个转。

Youth

好的，辛苦大仙啦！:)

bonny95

THE BOINC GRAPHICS API
http://boinc.berkeley.edu/graphics.php

[原文]
BOINC applications can optionally provide graphics, which are displayed either in an application window or in a full-screen window (when the BOINC screensaver is selected).

You are encouraged to implement graphics using OpenGL. This makes it easy for your application to show graphics on all platforms.

Integrated graphics
Graphics can either be integrated in your main application or generated by a separate program. The integrated approach is recommended, and we'll describe it first. In this approach, instead of boinc_init(), an application calls

#if defined(_WIN32) || defined(__APPLE__)
    retval = boinc_init_graphics(worker);
#else
    retval = boinc_init_graphics_lib(worker, argv[0]);
#endif

where worker() is the main function of your application. Your application must supply rendering and input-handling functions (see below).
These functions creates a worker thread that runs the main application function. The original thread becomes the graphics thread, which handles GUI events and does rendering.

On Unix, your graphics code must be put in a separate shared library (.so) file. This is because Unix hosts may not have the needed libraries (OpenGL, GLUT, X11). If an application is linked dynamically to these libraries, it will fail on startup if the libraries are not present. On the other hand, if an application is linked statically to these libraries, graphics will be done very inefficiently on most hosts.

The shared library must have the same name as the executable followed by '.so'. It must be linked with libboinc_graphics_impl.a, with your rendering and input-handling functions, and (dynamically) with glut and opengl. You must bundle the main program and the shared library together as a multi-file application version. Unix/Linux applications that use graphics should compile all files with -D_REENTRANT, since graphics uses multiple threads.

The BOINC example application uses this technique, and shows the Makefile command that are needed to produce the shared library on Unix.

Rendering and input-handling functions
Programs that use integrated graphics must supply the following functions:

    void app_graphics_render(int xs, ys, double time_of_day);

This will be called periodically in the graphics thread. It should generate the current graphic. xs and ys are the X and Y sizes of the window, and time_of_day is the relative time in seconds. Applications that don't do graphics must also supply a dummy app_graphics_render() to link with the API.
    void app_graphics_init();

This is called in the graphics thread when a window is created. It must make any calls needed to initialize graphics in the window.
    void app_graphics_resize(int x, int y);

Called when the window size changes.
    void app_graphics_reread_prefs();

This is called, in the graphics thread, whenever the user's project preferences change. It can call
    boinc_parse_init_data_file();
    boinc_get_init_data(APP_INIT_DATA&);

to get the new preferences.
The application must supply the following input-handling functions:

void boinc_app_mouse_move(
    int x, int y,       // new coords of cursor
    bool left,          // whether left mouse button is down
    bool middle,
    bool right
);

void boinc_app_mouse_button(
    int x, int y,       // coords of cursor
    int which,          // which button (0/1/2)
    bool is_down        // true iff button is now down
);

void boinc_app_key_press(
    int, int            // system-specific key encodings
)

void boinc_app_key_release(
    int, int            // system-specific key encodings
)

Limiting frame rate
The following global variables control frame rate:

boinc_max_fps is an upper bound on the number of frames per second (default 30).

boinc_max_gfx_cpu_frac is an upper bound on the fraction of CPU time used for graphics (default 0.5).

Support classes
Several graphics-related classes were developed for SETI@home. They may be of general utility.

REDUCED_ARRAY
Represents a two-dimensional array of data, which is reduced to a smaller dimension by averaging or taking extrema. Includes member functions for drawing the reduced data as a 3D graph in several ways (lines, rectangles, connected surface).
PROGRESS and PROGRESS_2D
Represent progress bars, depicted in 3 or 2 dimensions.
RIBBON_GRAPH
Represents of 3D graph of a function of 1 variable.
MOVING_TEXT_PANEL
Represents a flanged 3D panel, moving cyclically in 3 dimentions, on which text is displayed.
STARFIELD
Represents a set of randomly-generated stars that move forwards or backwards in 3 dimensions.
TEXTURE_DESC
Represents an image (JPEG, Targa, BMP, PNG, or RGB) displayed in 3 dimensions.
The file api/txf_util.C has support functions from drawing nice-looking 3D text.

Static graphics
An application can display a pre-existing image file (JPEG, GIFF, BMP or Targa) as its graphic. This is the simplest approach since you don't need to develop any code. You must include the image file with each workunit. To do this, link the application with api/static_graphics.C (edit this file to use your filename). You can change the image over time, but you must change the (physical, not logical) name of the file each time.

Graphics in a separate program
In this approach, an application bundles a 'main program' and a 'graphics program'. The main program executes the graphics program, and kills it when done. The main and graphics programs typically communicate using shared memory; you can use the functions in boinc/lib/shmem.C for this.

The main program should initialize using

    int boinc_init_options_graphics(BOINC_OPTIONS&, WORKER_FUNC_PTR worker);

The graphics application can be implemented using the BOINC framework, in which case it must initialize with

    int boinc_init_options_graphics(BOINC_OPTIONS&, NULL);

and supply rendering and input-handling functions.
Either the graphics or the main program can handle graphics messages from the core client. It's easiest to have the graphics program handle them; if the main program handles them, it must convey them to the graphics program.

[译文]
       
BOINC程序可以随意的产生图形，这些图形或者在一个程序窗口或者在一个全屏窗口显示（当BOINC的全屏按钮被选中）。
        你可以利用OpenGL实现图形。这可以使你的程序在任何平台上显示图形变得容易。

集成图形算法
图形算法既可以集成在主程序中，又可以由一个独立的程序产生。我们推荐使用集成算法，并将首先介绍该用法。在该方法中，一个程序并不调用boinc_init(), 而是调用
#if defined (_WIN32) || defined (__APPLE__)
    retval = boinc_init_graphics(worker);
#else
    retval = boinc_init_graphics_lib (worker, argv[0]);
#endif
其中worker()是你的程序中的主函数。你的程序必须提供显示和输入处理程序（见下）。
这些函数产生一个worker线程来运行住程序函数。最初的线程变为图形线程，处理GUI事件并显示。
在Unix上，你的图形代码必须放入一个独立的共享库(.so)文件中。这是因为Unix主机不一定有需要的库(OpenGL, GLUT, X11)。如果一个程序动态链接到这些库，若库不存在它不能开始运行。另外，如果一个程序静态链接到这些库，在大多主机上图形处理将非常缓慢。
共享库必须和可执行库具有相同名字的“.so”文件。它必须链接到libboinc_graphics_impl.a，链接到你的显示和输入处理程序，并且要（动态）连接到glut和opengl。你必须将主程序和共享库打包成一个多文件应用程序。由于Unix/Linux图形算法利用多线程技术，因此Unix/Linux程序使用可以用-D_REENTRANT编译所有文件的图形算法。
BOINC示例程序应用这项技术，并且展示了在Unix上产生共享库所需的Makefile命令。

显示和输入处理程序
集成图形算法程序必须提供如下的函数：
void app_graphics_render(int xs, ys, double time_of_day);
该函数将在图形算法线程中被周期调用。该函数将显示当前图形。xs和ys是窗口X轴和Y轴的大小，time_of_day是以秒为单位的相对时间。不执行图形处理的程序也必须提供一个虚app_graphics_render()函数链接到API。
void app_graphics_init();
当一个窗口被创建时调用该函数。它使任何必须的调用在窗口中初始化图形。
void app_graphics_resize(int x, int y);
该函数当窗口大小变化时被调用。
void app_graphics_reread_prefs();
当用户的项目参数发生变化时，图像算法线程调用该函数。它可以调用
boinc_parse_init_data_file();
boinc_get_init_data(APP_INIT_DATA&);
得到新参数。
程序必须提供如下的输入处理函数：
void boinc_app_mouse_move(
    int x, int y,               // 新鼠标指针坐标
    bool left,          // 鼠标左键是否按下
    bool middle,
    bool right
);
void boinc_app_mouse_button(
    int x, int y,       // 新鼠标指针坐标
    int which,          //哪一个键(0/1/2)
    bool is_down        // 如果现在鼠标键按下为真
);

void boinc_app_key_press(
    int, int            // 某系统键编码
)

void boinc_app_key_release(
int, int            //某系统键编码
)

限制帧频率
下面的全局变量控制帧频率：
boinc_max_fps        是每秒帧数的上界（默认30）。
boinc_max_gfx_cpu_frac        是执行图形算法的CPU时间片的上界（默认0.5）。

支撑类
我们为SETI@home开发了一些和图形算法相关的类。他们也许比较通用。
REDUCED_ARRAY
        表示一个二维数据向量，这些数据平均或取极值后变成更小的维。该向量包含用不同方法(直线,矩形, 连接面)将简化的数据绘制为3D图形的成员函数。
PROGRESS 和 PROGRESS_2D
        表示进度条，用2维或3维描述。
RIBBON_GRAPH
        表示单变量函数的3D图形。
MOVING_TEXT_PANEL
        表示一个显示文本的凸边3D面板，在3个维度循环移动。
STARFIELD
        表示一个在3个维度向前或向后移动的随机产生的星号的集合。
TEXTURE_DESC
        表示一个3维显示的图像(JPEG, Targa, BMP, PNG, or RGB)。
文件api/txf_util.C有绘制漂亮的3D文本的支撑函数。

静态图像
一个程序可以显示一个先于图像文件(JPEG, Targa, BMP, PNG, or RGB)而存在的图形。这是最简单的应用，因为你不需要编写任何代码。你必须在每个工作单元中包含图像文件。为了做到这一点，可以把应用程序链接到api/static_graphics.C（用你自己的文件名编辑这个文件）。随着时间的推移，你可以改变这个图像，但你必须每次改变（物理，而不是逻辑）文件名。
单独程序中的图形算法
在这种用法中，一个程序由“主程序”和“图形算法程序”打包而成。主程序执行图形算法程序，并且在每次执行完成后将其吊销。主程序和图形算法程序主要通过共享内存进行通信；你可以利用boinc/lib/shmem.C里的函数实现。
主程序应该利用如下函数初始化：
int boinc_init_options_graphics(BOINC_OPTIONS&, WORKER_FUNC_PTR worker);
图形程序可以利用BOINC框架实现，在此情况下它必须利用如下函数初始化：
int boinc_init_options_graphics(BOINC_OPTIONS&, NULL);
并且提供显示和输入处理程序。
        无论是图形程序还是主程序都可以处理来自核心客户端的图形信息。应用图形程序处理这些图形信息最简单；如果由主程序处理，它必须将这些图形信息传递给图形程序。


初学乍练，多多指教。

bonny95

[原文]
Trickle message API
http://boinc.berkeley.edu/trickle_api.php

API (application)
int boinc_send_trickle_up(char* variety, char* text)

sends a trickle message of the given variety. Returns zero if success.

int boinc_receive_trickle_down(char* buf, int len)

receives a trickle message. Returns true (nonzero) if there was a message. Messages are delivered in order.
API (server)
To handle trickle messages, use the daemon process 'trickle_handler'. You must supply the following function:
int handle_trickle(TRICKLE_UP&);

You may send trickle-down messages, from this function or elsewhere, as follows:
DB_TRICKLE_DOWN tdown;
// ... populate the tdown object
tdown.insert();


[译文]
涓流消息API

API(应用程序)
int boinc_send_trickle_up(char* variety, char* text)
发送给定变量的涓流消息。如果成功则返回0。
int boinc_receive_trickle_down(char* buf, int len)
接收涓流消息。如果有消息则返回真（非零）。所有消息顺序到达。
API(服务器)
为了处理涓流消息，利用后台消息处理进程‘trickle_handler’。你必须提供如下函数：
int handle_trickle(TRICKLE_UP&);
你可以在本函数内或其它地方发送trickle_down消息，如下所示：
DB_TRICKLE_DOWN tdown;
// ... populate the tdown object
tdown.insert();

bonny95

[原文]
Intermediate upload
http://boinc.berkeley.edu/int_upload.php

Long-running applications can upload particular output files before the result as a whole is finished. To initiate the upload of an output file, call
   extern int boinc_upload_file(std::string& name);

where 'name' is the logical name of the file. The application cannot modify the file after making this call.
To check on the status of a file being uploaded, call

   extern int boinc_upload_status(std::string& name);

This will return zero if the upload of the file is finished successfully.

[译文]
中间上传

长期运行的程序能够在最终整体结果出来之前把某些中间输出文件上传。要开始上传一个输出文件，调用：
extern int boinc_upload_file(std::string& name);
其中‘name’是文件的逻辑名字。执行该函数调用后，程序便不能在修改文件。
要检查一个正在上传的文件的状态，可以调用：
extern int boinc_upload_status(std::string& name);
如果文件上传成功，函数返回0。

碧城仙

“Trickle message”翻译成“涓流消息”恐怕还是难以理解。

网上搜索了一下，有一个相关词汇，叫做 涓流经济学，trickle-down economics，还有一个经济学术语叫做“涓流效应”。

继续搜索，搜到“ticker”的解释：a message that scrolls past at the bottom of the screen, with the copyright and anti-copy telephone number 。意思是：某些 DVD 播放过程中，在屏幕下方滚动的消息，包含版权和反盗版电话号码。

有时也表示“一点一点慢慢出来的少量信息”。

我想是不是可以翻译成“滚动消息”或者其他更贴切更容易理解的？

bonny95

我就是看到trickle-down economics的翻译才把Trickle message翻译成“涓流消息”的。这个术语从没见过，所以我就自作主张了。
“滚动”是否有一种连绵不绝的意思呢？而“trickle”是“一点一点慢慢出来”，不知道国内是否有专业人士已经对此术语有过翻译了？如果有的话可以参考一下；如果没有我们就要好好想一个名字，免得贻害后人，呵呵

碧城仙

这个词组我以前也没碰到过，网上也搜不到，看来我们这里的翻译结果将是首创翻译，不可马虎。

的确，翻译成“滚动”也不妥当。“滚动字幕”是 roller caption 或者 rolling title 。

Google 的自动翻译将“Trickle message”翻译成“信息流”，将“滚动消息”翻译成“Rolling news”，将“滚动字幕”翻译成“Rolling subtitles”。

trickle: [ 'trikl ]  
n. 滴,细流
v. 滴流,细细地流

例句与用法:
1. The stream is reduced to a mere trickle in summer.
夏天那条小河的水量减少，成了涓涓溪流。
2. She trickles oil into the mixture.
她把油一点点地注入混合物中。
3. Blood trickled from the wound.
血从伤口一滴一滴流出来。
4. The stream had thinned down to a mere trickle.
小河越来越窄，最后变成了涓涓细流。

解释:

名词 trickle:
1. flowing in drops; the formation and falling of drops of liquid
同义词：drip, dribble

动词 trickle:
1. run or flow slowly, as in drops or in an unsteady stream
同义词：dribble, filter

碧城仙

下面是转载自 非官方的 BOINC Wiki 上的解释，英文的，该站点已经无法访问了，通过 Google 快照转出：http://boinc-doc.net/boinc-wiki/index.php?title=Trickle ，可以参考参考。

Trickle Message
From BOINC-Wiki

General

Large Work Units obviously take a long time to process into a Result. Those Projects with these long Work Units may want to give you the opportunity to get Credit more frequently. Mostly so you do not have to wait years for the processing to complete, like with the more common Work Unit that only takes hours to process. Therefore Projects can build their Science Applications so that these Work Units can report how much processing the Participant has gotten done. These intermediate reports are called Trickle Messages.

Expanded Explanation

Trickle Messages let Science Applications communicate with the Scheduling Server during the execution of a Work Unit. They are intended for Science Applications that have long Work Units (multiple days). Trickle Messages may go in either direction: 'trickle up' messages go from Science Application to the Scheduling Server, 'trickle down' messages go from the Scheduling Server to the Science Application. Typical uses of this mechanism:

·The Science Application sends a trickle-up message containing its current CPU usage, so that users can be granted incremental credit (rather than waiting until the end of the Work Unit).
·The Science Application sends a trickle-up message containing a summary of the computational state, so that Scheduling Server logic can decide if the computation should be aborted.
·The Scheduling Server sends a trickle-down message telling the application to abort.
·The Scheduling Server sends a trickle-down message containing the user's current Total Credit.

Trickle Messages are asynchronous and reliable. Trickle Messages are conveyed in Scheduler Request Messages, so they may not be delivered immediately after being generated.

To handle trickle-down messages, a project must include a line, in the configuration (config.xml) file:

<msg_to_host/>

In the BOINC Client Software, the function boinc_send_trickle_up() creates a file 'trickle_up' in the slot directory and signals the BOINC Daemon via shared memory. When the BOINC Daemon gets this signal, or when the Science Application exits, it moves the file from 'slot/trickle' to 'project/trickle_up_resultid_time'.

When the BOINC Daemon sends an RPC to a server, it scans the project directory for these trickle-up files includes them in the request, and appends '.sent' to their filenames. On successful RPC completion it deletes trickle-up files that were sent earlier.

On the server, messages are stored in database tables 'trickle_up' and 'trickle_down'. The Scheduling Server extracts trickle messages from the request message and inserts them in the trickle_up table. If the 'trickle_down' flag in the configuration is set, it scans the database for trickle-down messages for this host and includes them in the reply message, setting the 'handled' flag in the DB record.

The BOINC Daemon parses trickle-down messages in the Scheduler Reply Message, creates files of the form trickle_down_createtime_id in the slot directory, and signals the Science Application via shared memory that a message is available.

Youth

我之前是翻译成触发消息（类似于trigger了...），而涓流消息从字面上来看是比较准确的，只是略有些拗口