Trickle message API

The interface for trickle messages includes both client-side and server-side components.

Client-side API

To send a trickle-up message, call

int boinc_send_trickle_up(char* variety, char* text)

To receive a trickle-down message, call

int boinc_receive_trickle_down(char* buf, int len)

This returns true (nonzero) if there was a message.

Server-side API

To handle trickle-up messages, use a 'trickle_handler' daemon. This is a program, based on sched/trickle_handler.cpp, linked with a function

int handle_trickle(MSG_FROM_HOST&);

struct MSG_FROM_HOST {
    int create_time;
    int hostid;
    char variety[256];              // project-defined; what kind of msg
    char xml[MSG_FROM_HOST_BLOB_SIZE];
};

This function should return zero if the message was handled successfully; otherwise it will be retried later. The 'hostid' field identifies the host from which the message was sent. The daemon must be passed a '-variety X' command-line argument, telling it what kind of messages to handle. The daemon should be specified in the project configuration file.

To send send trickle-down messages (from a trickle handler daemon or other program) you must insert a record in the 'msg_to_host' table. From C/C++, this is done as follows:

DB_MSG_TO_HOST mth;

mth.clear();
mth.create_time = time(0);
mth.hostid = hostid;
sprintf(mth.xml,
    "<trickle_down>\n"
    "   <result_name>%s</result_name>\n"
    "   ...\n"
    "</trickle_down>\n",
    ...
);
retval = mth.insert();

To send trickle-down messages, you must include

<msg_to_host/>

in your configuration (config.xml) file.

If you use either type of trickle message, you should include

<task>
  <output>purge_trickles.out</output>
  <cmd>run_in_ops purge_trickles.php</cmd>
  <period>24 hours</period>
</task>

in your configuration (config.xml) file, to delete unneeded trickle-related records from your database.