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>
|
|
|
|
|
Do use checkpoint, an application should write to output and
|
|
|
|
|
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.
|
2002-07-30 18:06:39 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<hr>
|
|
|
|
|
<h3>Implementation</h3>
|
|
|
|
|
<p>
|
2002-07-31 05:59:43 +00:00
|
|
|
Application are executed in separate "catbox" directories,
|
|
|
|
|
allowing them to create and use temporary files without name conflicts.
|
|
|
|
|
Input and output files are kept outside the catbox.
|
|
|
|
|
The mappings from virtual to physical filenames use
|
|
|
|
|
"symbolic link" files in the catbox directory.
|
2002-07-30 18:06:39 +00:00
|
|
|
The name of such a file is the virtual name,
|
2002-08-05 00:29:34 +00:00
|
|
|
and the file contains an XML tag with the physical name.
|
|
|
|
|
(This scheme is used because of the lack of filesystem links in Windows.)
|
2002-07-30 18:06:39 +00:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
Communication between the core client and applications
|
2002-07-31 05:59:43 +00:00
|
|
|
is done through XML files in the catbox directory.
|
2002-07-30 18:06:39 +00:00
|
|
|
Several files are used.
|
|
|
|
|
<p>
|
|
|
|
|
<b>Files created by the core client, read by the app:</b>
|
2002-07-31 05:59:43 +00:00
|
|
|
(Once, at start of app)
|
2002-07-30 18:06:39 +00:00
|
|
|
<ul>
|
2002-07-31 05:59:43 +00:00
|
|
|
<li> Symbolic link files
|
|
|
|
|
<li> <b>fd_init.xml</b>:
|
2002-07-30 18:06:39 +00:00
|
|
|
specifies the mappings of file descriptors (stdin/stdout/stderr)
|
|
|
|
|
to physical files.
|
|
|
|
|
|
2002-07-31 05:59:43 +00:00
|
|
|
<li> <b>init_data.xml</b>: this contains the initialization data
|
|
|
|
|
returned by <tt>boinc_init()</tt> (see above),
|
|
|
|
|
as well as the minimum checkpoint period.
|
2002-07-30 18:06:39 +00:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
2002-07-31 05:59:43 +00:00
|
|
|
<b>Files created by the API implementation, read by the core client:</b>
|
2002-07-30 18:06:39 +00:00
|
|
|
<ul>
|
|
|
|
|
<li>
|
2002-08-05 00:29:34 +00:00
|
|
|
<b>fraction_done.xml</b>:
|
|
|
|
|
contains the WU fraction done and the current CPU time from start of WU.
|
2002-07-31 05:59:43 +00:00
|
|
|
Written by the timer routine as needed.
|
2002-07-30 18:06:39 +00:00
|
|
|
|
2002-08-05 00:29:34 +00:00
|
|
|
<li>
|
2002-07-31 05:59:43 +00:00
|
|
|
<b>checkpoint_cpu.xml</b>
|
|
|
|
|
CPU time (from start of WU) at last checkpoint.
|
|
|
|
|
Written by checkpoint_completed.
|
2002-07-29 19:01:38 +00:00
|
|
|
|
2002-07-30 18:06:39 +00:00
|
|
|
</ul>
|
|
|
|
|
<p>
|
2002-07-31 05:59:43 +00:00
|
|
|
The API implementation uses a timer (60Hz);
|
|
|
|
|
the real-time clock is not available to applications.
|
|
|
|
|
This timer is used for several purposes:
|
|
|
|
|
<ul>
|
|
|
|
|
<li> To tell the app when to checkpoint;
|
2002-08-05 00:29:34 +00:00
|
|
|
<li> To regenerate the fraction done file
|
2002-07-31 05:59:43 +00:00
|
|
|
<li> To refresh graphics
|
|
|
|
|
</ul>
|
2002-08-05 00:29:34 +00:00
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
<b>Exit status</b>
|
|
|
|
|
The core client does a wait() to get the status.
|
|
|
|
|
boinc_finish() ends with an exit(status);
|
|
|
|
|
<p>
|
|
|
|
|
<b>Accounting of CPU time</b>:
|
|
|
|
|
(note: in Unix, a parent can't get the CPU time of a child
|
|
|
|
|
until the child exits. So we're forced to measure it in the child.)
|
|
|
|
|
The core passes the WU CPU time in init_data.xml.
|
|
|
|
|
boinc_checkpoint_done() and boinc_finish() compute the new WU CPU time,
|
|
|
|
|
and write it to checkpoint_cpu.xml.
|
|
|
|
|
The core deletes this after reading.
|
|
|
|
|
If on exit there is no checkpoint_cpu.xml, it means the app
|
|
|
|
|
called exit(0) rather than boinc_finish().
|
|
|
|
|
In this case the core measures the child CPU itself.
|
|
|
|
|
<p>
|
|
|
|
|
The core client maintains
|
|
|
|
|
<p>
|
|
|
|
|
<b>Timing of checkpoints</b>
|
|
|
|
|
<p>
|
|
|
|
|
The app library maintains time_until_checkpoint,
|
|
|
|
|
decremented from the timer handler.
|
|
|
|
|
boinc_time_to_checkpoint() returns true if this is zero or less.
|
|
|
|
|
boinc_checkpoint_done() resets it.
|
|
|
|
|
|
|
|
|
|
<p>
|
|
|
|
|
<b>Maintaining fraction done and current CPU</b>
|
|
|
|
|
<p>
|
|
|
|
|
These two quantities are transferred from the app library to
|
|
|
|
|
the core client in the file fraction_done.xml.
|
|
|
|
|
The parameter <tt>time_until_fraction_done_update</tt>,
|
|
|
|
|
passed in the initialization file,
|
|
|
|
|
determines how often this file is written.
|
|
|
|
|
It is written from the timer handler.
|
|
|
|
|
<p>
|
|
|
|
|
For multi-program applications, only the active application
|
|
|
|
|
must write the file.
|
|
|
|
|
The functions boinc_child_start() and boinc_child_done()
|
|
|
|
|
tell the app library to stop and start writing the file.
|
|
|
|
|
<p>
|
|
|
|
|
TO DO: this creates disk traffic.
|
|
|
|
|
Either figure out a way of increasing the period for users who don't
|
|
|
|
|
want disk access, or don't use disk files.
|
