mirror of https://github.com/BOINC/boinc.git
121 lines
3.0 KiB
PHP
121 lines
3.0 KiB
PHP
<?
|
|
require_once("docutil.php");
|
|
page_head("Trickle messages");
|
|
echo "
|
|
<h2>Trickle messages</h2>
|
|
<p>
|
|
<b>Trickle messages</b>
|
|
let applications communicate with the server
|
|
during the execution of a workunit.
|
|
They are intended for applications that have
|
|
long work units (multiple days).
|
|
Trickle messages may go in either direction:
|
|
'trickle up' messages go from application to server,
|
|
'trickle down' messages go from server to application.
|
|
Typical uses of this mechanism:
|
|
<ul>
|
|
<li>
|
|
The 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).
|
|
|
|
<li>
|
|
The application sends a trickle-up message
|
|
containing a summary of the computational state,
|
|
so that server logic can decide if the computation should be aborted.
|
|
|
|
<li>
|
|
The server sends a trickle-down message
|
|
telling the application to abort.
|
|
</ul>
|
|
|
|
<p>
|
|
Trickle messages are asynchronous and reliable.
|
|
Trickle messages are conveyed in scheduler RPC messages,
|
|
so they may not be delivered immediately after being generated.
|
|
|
|
|
|
<p>
|
|
To handle trickle-down messages a project must include the line
|
|
<pre>
|
|
<trickle_down/>
|
|
</pre>
|
|
in the configuration (config.xml) file.
|
|
|
|
|
|
<h3>API (client)</h3>
|
|
|
|
<pre>
|
|
<code>int boinc_send_trickle_up(char*)</code>
|
|
</pre>
|
|
sends a trickle message.
|
|
Returns zero if success.
|
|
<p>
|
|
<pre>
|
|
<code>bool boinc_receive_trickle_down(char* buf, int len)</code>
|
|
</pre>
|
|
receives a trickle message.
|
|
Returns true if there was a message.
|
|
Messages are delivered in order.
|
|
|
|
<h3>API (server)</h3>
|
|
|
|
The server C library API:
|
|
",html_text("
|
|
int get_trickle_up(
|
|
int applicationid,
|
|
int& resultid,
|
|
int& messageid,
|
|
char* buf,
|
|
int len
|
|
);
|
|
int mark_trickle_up_processed(int messageid);
|
|
|
|
int send_trickle_down(
|
|
int resultid,
|
|
char* buf
|
|
);
|
|
"),"
|
|
get_trickle_up() gets an unprocessed trickle-up message
|
|
for the given application,
|
|
returning the result and message IDs as well as the message itself.
|
|
mark_trickle_up_processed() marks a trickle-up message as processed.
|
|
send_trickle_down() sends a trickle-down message to the
|
|
client handling the given result.
|
|
<p>
|
|
These functions are also available as scriptable command-line programs.
|
|
|
|
<h3>Implementation</h3>
|
|
<p>
|
|
On the client,
|
|
<code>boinc_send_trickle_up()</code>
|
|
creates a file 'trickle' in the slot directory
|
|
and signals the core client via shared memory.
|
|
When the core client gets this signal,
|
|
or when the application exits,
|
|
it moves the file from 'slot/trickle'
|
|
to 'project/trickle_resultid_time'.
|
|
<p>
|
|
When the core client sends an RPC to a server,
|
|
it scans the project directory for trickle-up files
|
|
and includes them in the request.
|
|
On successful RPC completion it deletes the files.
|
|
|
|
<p>
|
|
On the server,
|
|
messages are stored in database tables 'trickle_up' and 'trickle_down'.
|
|
<p>
|
|
boinc_receive_trickle_down() creates a trickle_down record.
|
|
The scheduler RPC handler checks this table for unsent
|
|
messages for the given host.
|
|
<p>
|
|
The scheduling server extracts trickle messages from
|
|
the request message and inserts them in trickle_up.
|
|
|
|
|
|
";
|
|
|
|
page_tail();
|
|
?>
|