2002-09-05 11:46:10 +00:00
|
|
|
<title>The BOINC application programming interface (API)</title>
|
2002-08-20 23:54:17 +00:00
|
|
|
<body bgcolor=ffffff>
|
2002-09-05 11:46:10 +00:00
|
|
|
<h2>The BOINC application programming interface (API)</h2>
|
2002-07-30 18:06:39 +00:00
|
|
|
|
2002-09-05 11:46:10 +00:00
|
|
|
<p>
|
2002-07-31 05:59:43 +00:00
|
|
|
The BOINC API is a set of C++ functions.
|
|
|
|
|
Unless otherwise specified,
|
|
|
|
|
the functions return an integer error code; zero indicates success.
|
|
|
|
|
The graphics API is described <a href=graphics.html>separately</a>.
|
2002-07-30 18:06:39 +00:00
|
|
|
|
|
|
|
|
<h3>Initialization and termination</h3>
|
2002-07-31 05:59:43 +00:00
|
|
|
The application must call
|
2002-07-30 18:06:39 +00:00
|
|
|
<pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
int boinc_init();
|
2002-07-30 18:06:39 +00:00
|
|
|
</pre>
|
|
|
|
|
before calling other BOINC functions or doing I/O.
|
2002-08-05 00:29:34 +00:00
|
|
|
It may call
|
2002-07-31 05:59:43 +00:00
|
|
|
<pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
struct APP_INIT_DATA {
|
|
|
|
|
char project_preferences[4096];
|
|
|
|
|
char user_name[256];
|
|
|
|
|
char team_name[256];
|
|
|
|
|
double wu_cpu_time; // cpu time from previous sessions
|
|
|
|
|
double total_cobblestones;
|
|
|
|
|
double recent_avg_cobblestones;
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
int boinc_get_init_data(APP_INIT_DATA&);
|
2002-07-31 05:59:43 +00:00
|
|
|
</pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
to get the following information:
|
2002-07-31 05:59:43 +00:00
|
|
|
<ul>
|
2002-08-05 00:29:34 +00:00
|
|
|
<li> <b>project_preferences</b>: An XML string containing
|
|
|
|
|
the user's project-specific preferences.
|
|
|
|
|
<li> <b>user_name</b>: the user's "screen name" on this project.
|
|
|
|
|
<li> <b>team_name</b>: the user's team name, if any.
|
|
|
|
|
<li> <b>wu_cpu_time</b>: the CPU time spent on this WU so far
|
|
|
|
|
<li> <b>total_cobblestones</b>: the user's total work for this project.
|
|
|
|
|
<li> <b>recent_avg_cobblestones</b>: the recent average work per day.
|
2002-07-31 05:59:43 +00:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
|
|
|
|
These items might be used by the application in its graphics.
|
2002-08-05 00:29:34 +00:00
|
|
|
At any time it may call
|
2002-07-30 18:06:39 +00:00
|
|
|
<pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
double boinc_cpu_time();
|
2002-07-30 18:06:39 +00:00
|
|
|
</pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
to get its current CPU time.
|
|
|
|
|
<p>
|
|
|
|
|
When the application has completed it must call
|
2002-07-30 18:06:39 +00:00
|
|
|
<pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
int boinc_finish(int status);
|
2002-07-30 18:06:39 +00:00
|
|
|
</pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
<tt>status</tt> is nonzero if an error was encountered.
|
2002-07-30 18:06:39 +00:00
|
|
|
|
|
|
|
|
<h3>Resolving file names</h3>
|
|
|
|
|
Applications that use named input or output files must call
|
|
|
|
|
<pre>
|
2002-07-31 05:59:43 +00:00
|
|
|
int boinc_resolve_filename(char *logical_name, char *physical_name);</tt>
|
2002-07-30 18:06:39 +00:00
|
|
|
</pre>
|
|
|
|
|
to convert logical file names to physical names.
|
|
|
|
|
For example, instead of
|
|
|
|
|
<pre>
|
|
|
|
|
f = fopen("my_file", "r");
|
|
|
|
|
</pre>
|
2002-07-29 19:01:38 +00:00
|
|
|
</p>
|
2002-07-30 18:06:39 +00:00
|
|
|
the application might use
|
|
|
|
|
<p>
|
|
|
|
|
<pre>
|
|
|
|
|
char resolved_name[256];
|
2002-07-31 05:59:43 +00:00
|
|
|
retval = boinc_resolve_filename("my_file", resolved_name);
|
2002-07-30 18:06:39 +00:00
|
|
|
if (retval) fail("can't resolve filename");
|
|
|
|
|
f = fopen(resolved_name, "r");
|
|
|
|
|
</pre>
|
2002-07-31 05:59:43 +00:00
|
|
|
<tt>boinc_resolve_filename()</tt> doesn't need to be used for temporary files.
|
2002-07-30 18:06:39 +00:00
|
|
|
|
|
|
|
|
<h3>Checkpointing</h3>
|
|
|
|
|
|
|
|
|
|
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 <b>checkpointing</b>.
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
<p>
|
2003-06-03 16:56:45 +00:00
|
|
|
To use checkpoint, an application should write to output and
|
2002-07-30 18:06:39 +00:00
|
|
|
state files using the <tt>MFILE</tt> class.
|
|
|
|
|
<pre>
|
|
|
|
|
class MFILE {
|
|
|
|
|
public:
|
|
|
|
|
int open(char* path, char* mode);
|
|
|
|
|
int _putchar(char);
|
|
|
|
|
int puts(char*);
|
|
|
|
|
int printf(char* format, ...);
|
2002-08-05 00:29:34 +00:00
|
|
|
size_t write(const void* buf, size_t size, size_t nitems);
|
2002-07-30 18:06:39 +00:00
|
|
|
int close();
|
|
|
|
|
int flush();
|
|
|
|
|
};
|
|
|
|
|
</pre>
|
|
|
|
|
MFILE buffers data in memory
|
|
|
|
|
and writes to disk only on <tt>flush()</tt> or <tt>close()</tt>.
|
|
|
|
|
This lets you write output files and state files
|
|
|
|
|
more or less atomically.
|
|
|
|
|
Frequency of checkpointing is a user preference
|
|
|
|
|
(e.g. laptop users might want to checkpoint infrequently).
|
|
|
|
|
An application must call
|
|
|
|
|
<pre>
|
2002-07-31 05:59:43 +00:00
|
|
|
bool boinc_time_to_checkpoint();
|
2002-07-30 18:06:39 +00:00
|
|
|
</pre>
|
|
|
|
|
whenever it reaches a point where it is able to checkpoint.
|
|
|
|
|
If this returns true,
|
|
|
|
|
the application should write the state file and flush all output files,
|
|
|
|
|
then call
|
|
|
|
|
<pre>
|
2002-07-31 05:59:43 +00:00
|
|
|
void boinc_checkpoint_completed();
|
2002-07-30 18:06:39 +00:00
|
|
|
</pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
A call to <tt>boinc_time_to_checkpoint()</tt> is extremely fast,
|
|
|
|
|
so there is little penalty in calling it frequently.
|
2002-07-30 18:06:39 +00:00
|
|
|
|
|
|
|
|
<h3>Fraction done</h3>
|
|
|
|
|
The core client GUI displays the percent done of workunits in progress.
|
|
|
|
|
To keep this display current, an application should
|
|
|
|
|
periodically call
|
|
|
|
|
<pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
boinc_fraction_done(double fraction_done);
|
2002-07-30 18:06:39 +00:00
|
|
|
</pre>
|
|
|
|
|
The <tt>fraction_done</tt> argument is a rough estimate of the
|
2002-07-31 05:59:43 +00:00
|
|
|
workunit fraction complete (0 to 1).
|
2002-08-05 00:29:34 +00:00
|
|
|
This function is extremely fast and can be called often.
|
2002-07-30 18:06:39 +00:00
|
|
|
|
|
|
|
|
<h3>Multi-program applications</h3>
|
|
|
|
|
Some applications consist of multiple programs:
|
|
|
|
|
a <b>main program</b> that acts as coordinator,
|
|
|
|
|
and one or more subsidiary programs.
|
2002-08-05 00:29:34 +00:00
|
|
|
Each program should use the BOINC API as described above.
|
2002-07-30 18:06:39 +00:00
|
|
|
<p>
|
2002-08-05 00:29:34 +00:00
|
|
|
Each program should have its own state file;
|
2002-07-30 18:06:39 +00:00
|
|
|
the state file of the coordinator program records
|
|
|
|
|
which subsidiary program was last active.
|
|
|
|
|
<p>
|
2002-08-05 00:29:34 +00:00
|
|
|
To correctly implement fraction done,
|
2002-07-30 18:06:39 +00:00
|
|
|
the main program should pass information to subsidiary programs
|
2002-08-05 00:29:34 +00:00
|
|
|
(perhaps as command-line arguments) indicating the starting and ending
|
2002-07-30 18:06:39 +00:00
|
|
|
fractions for that program.
|
2002-07-31 05:59:43 +00:00
|
|
|
<p>
|
|
|
|
|
The coordinator must call
|
|
|
|
|
<pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
void boinc_child_start();
|
2002-07-31 05:59:43 +00:00
|
|
|
</pre>
|
|
|
|
|
prior to forking a child process.
|
|
|
|
|
When the child is done, the coordinator
|
|
|
|
|
must get the child's CPU time, then call
|
|
|
|
|
<pre>
|
2002-08-05 00:29:34 +00:00
|
|
|
void boinc_child_done(double total_cpu);
|
2002-07-31 05:59:43 +00:00
|
|
|
</pre>
|
|
|
|
|
before forking the next child process.
|
