2
require_once("docutil.php");
3
page_head("The BOINC application programming interface (API) [ Deprectated - Wiki ]");
6
The BOINC API is a set of C++ functions.
7
Most of the functions have a C interface,
8
so that they can be used from programs written in C and other languages.
9
Unless otherwise specified,
10
the functions return an integer error code; zero indicates success.
12
BOINC applications may generate graphics,
13
allowing them to provide a screensaver.
14
This API is described <a href=graphics.php>here</a>.
16
BOINC applications may consist of several programs that are
18
these are called <b>compound applications</b>.
19
This API is described <a href=compound_app.php>here</a>.
22
<h3>Initialization and termination</h3>
26
<a href=diagnostics.php>initialize diagnostics</a>
27
before any other BOINC calls.
29
Initialization for graphical and compound applications
30
are described elsewhere (see links above).
31
Other applications must call
35
before calling other BOINC functions or doing I/O.
37
When the application has completed it must call
39
int boinc_finish(int status);
41
<code>status</code> is nonzero if an error was encountered.
42
This call does not return.
44
<h3>Is your application running under the control of the BOINC client?</h3>
46
BOINC applications can be run in \"standalone\" mode for testing, or under
47
the control of the BOINC client. You might want your application to behave differently
48
in the two cases. For example you might want to output debugging information if
49
the application is running standalone. To determine if the application is
50
running in standalone mode or under the control of the BOINC client, call
52
int boinc_is_standalone(void);
54
This returns non-zero (True) if the application is running standalone, and zero (False) if the application
55
is running under the control of the BOINC client.
59
<h3>Resolving file names</h3>
60
Applications that use named input or output files must call
62
int boinc_resolve_filename(char *logical_name, char *physical_name, int len);
66
int boinc_resolve_filename_s(char *logical_name, std::string& physical_name);
68
to convert logical file names to physical names.
69
For example, instead of
71
f = fopen(\"my_file\", \"r\");
74
the application might use
77
retval = boinc_resolve_filename(\"my_file\", resolved_name);
78
if (retval) fail(\"can't resolve filename\");
79
f = fopen(resolved_name.c_str(), \"r\");
81
<code>boinc_resolve_filename()</code> doesn't need to be used for temporary files.
85
Applications should replace fopen() calls with
87
boinc_fopen(char* path, char* mode);
89
This deals with platform-specific problems.
90
On Windows, where security and indexing programs can briefly lock files,
91
boinc_fopen() does several retries at 1-second intervals.
92
On Unix, where signals can cause fopen() to fail with EINTR,
93
boinc_fopen checks for this and does a few retries;
94
it also sets the 'close-on-exec' flag.
96
<h3>Checkpointing</h3>
98
Computations that use a significant amount of time
99
per work unit may want to periodically write the current
100
state of the computation to disk.
101
This is known as <b>checkpointing</b>.
102
The state file must include everything required
103
to start the computation again at the same place it was checkpointed.
104
On startup, the application
105
reads the state file to determine where to begin computation.
106
If the BOINC client quits or exits,
107
the computation can be restarted from the most recent checkpoint.
109
Frequency of checkpointing is a user preference
110
(e.g. laptop users might want to checkpoint infrequently).
111
An application must call
113
int boinc_time_to_checkpoint();
115
whenever it reaches a point where it is able to checkpoint.
116
If this returns nonzero (True) then
117
the application should checkpoint immediately
118
(i.e., write the state file and flush all output files),
121
void boinc_checkpoint_completed();
123
<code>boinc_time_to_checkpoint()</code> is fast,
124
so it can be called frequently (hundreds or thousands of times a second).
126
<h3>Critical sections</h3>
128
void boinc_begin_critical_section();
129
void boinc_end_critical_section();
131
Call these around code segments during which you
132
don't want to be suspended or killed by the core client.
133
NOTE: this is done automatically while checkpointing.
135
<h3>Atomic file update</h3>
137
To facilitate atomic checkpoint, an application can write to output and
138
state files using the <code>MFILE</code> class.
142
int open(char* path, char* mode);
145
int printf(char* format, ...);
146
size_t write(const void* buf, size_t size, size_t nitems);
151
MFILE buffers data in memory
152
and writes to disk only on <code>flush()</code> or <code>close()</code>.
153
This lets you write output files and state files more or less atomically.
156
<h3>Credit reporting</h3>
158
By default, the claimed credit of a result is based on
159
the product of its total CPU time and the
160
benchmark values obtained by the core client.
161
This can produce results that are too low if
162
the application uses processor-specific optimizations
163
not present in the core client,
164
is compiled with different compiler settings,
165
or uses a GPU or other non-CPU computing resource.
166
To handle such cases, the following functions can be used.
168
void boinc_ops_per_cpu_second(double floating_point_ops, double integer_ops);
170
This reports the results of an application-specific benchmark,
171
expressed as number of floating-point and integer operations per CPU second.
173
void boinc_ops_cumulative(double floating_point_ops, double integer_ops);
175
This reports the total number of floating-point and integer operations
176
since the start of the result.
177
It must be called just before boinc_finish(),
178
and optionally at intermediate points.
180
<h3>Communicating with the core client</h3>
182
The core client GUI displays the percent done of workunits in progress.
183
To keep this display current, an application should periodically call
185
boinc_fraction_done(double fraction_done);
187
The <code>fraction_done</code> argument is an estimate of the
188
workunit fraction complete (0 to 1).
189
This function is fast and can be called frequently.
190
The sequence of arguments in successive calls should be non-decreasing.
191
An application should never 'reset' and start over
192
if an error occurs; it should exit with an error code.
194
double boinc_get_fraction_done();
196
returns the last value set, or -1 if none has been set
197
(this would typically be called from graphics code).
200
The following functions get information from the core client;
201
this information may be useful for graphics.
204
int boinc_get_init_data_p(APP_INIT_DATA*);
205
int boinc_get_init_data(APP_INIT_DATA&);
207
struct APP_INIT_DATA {
214
char acct_mgr_url[256];
215
char* project_preferences;
221
char project_dir[256];
224
char authenticator[256];
226
double user_total_credit;
227
double user_expavg_credit;
228
double host_total_credit;
229
double host_expavg_credit;
230
double resource_share_fraction;
232
PROXY_INFO proxy_info; // in case app wants to use network
233
GLOBAL_PREFS global_prefs;
236
double rsc_fpops_est;
237
double rsc_fpops_bound;
238
double rsc_memory_bound;
239
double rsc_disk_bound;
241
// the following are used for compound apps,
242
// where each stage of the computation is a fixed
243
// fraction of the total.
244
double fraction_done_start;
245
double fraction_done_end;
248
to get the following information:
251
list_item("core version", "The version number of the core client");
252
list_item("app_name", "The application name (from the server's DB)");
253
list_item("project_preferences", "An XML string containing
254
the user's project-specific preferences.");
255
list_item("user_name", " the user's 'screen name' on this project.");
256
list_item("team_name", " the user's team name, if any.");
257
list_item("project_dir", "absolute path of project directory");
258
list_item("boinc_dir", "absolute path of BOINC root directory");
259
list_item("wu_name", "name of workunit being processed");
260
list_item("authenticator", "user's authenticator for this project");
261
list_item("slot", "The number of the app's 'slot' (0, 1, ...)");
262
list_item("user_total_credit", " user's total work for this project.");
263
list_item("user_expavg_credit", " user's recent average work per day.");
264
list_item("team_total_credit", " team's total work for this project.");
265
list_item("team_expavg_credit", " team's recent average work per day.");
266
list_item("host_info", "A structure describing the host hardware and OS");
270
An application may call
272
int boinc_wu_cpu_time(double &cpu_time);
273
"), "to get its total CPU time
274
(from the beginning of the work unit, not just since the last restart).
275
This excludes CPU time used to render graphics.
277
<h3>Requesting network connection</h3>
279
If it appears that there is no physical network connection
280
(e.g. gethostbyname() fails for a valid name) then
282
<li> Call <code>boinc_need_network()</code>.
283
This will alert the user that a network connection is needed.
284
<li> Periodically call <code>boinc_network_poll()</code>
285
until it returns zero.
286
<li> Do whatever communication is needed.
287
<li> When done, call <code>boinc_network_done()</code>.
288
This enables that hangup of a modem connection, if needed.
291
void boinc_need_network();
292
int boinc_network_poll();
293
void boinc_network_done();
296
Note: this should be enclosed in
297
<code>boinc_not_using_cpu() ... boinc_using_cpu()</code>.
added
removed
doc/api.php
