mirror of https://github.com/BOINC/boinc.git
Update TrickleApi.md
Signed-off-by: Vitalii Koshura <lestat.de.lionkur@gmail.com>
Vitalii Koshura
parent
1907cb8c4f
commit
3ef021296d
122
TrickleApi.md
122
TrickleApi.md
|
|
@ -1,81 +1,101 @@
|
|||
[[PageOutline]]
|
||||
# Trickle message API
|
||||
|
||||
The interface for [trickle messages](TrickleMessages) 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)
|
||||
|
||||
```
|
||||
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)
|
||||
|
||||
```
|
||||
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
|
||||
# Handling trickle-up messages
|
||||
|
||||
|
||||
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];
|
||||
};
|
||||
|
||||
To handle trickle-up messages, use a 'trickle_handler' daemon.
|
||||
This is a program, based on sched/trickle_handler.cpp, linked with functions
|
||||
|
||||
```
|
||||
int handle_trickle_init(int argc, char** argv); // initialize
|
||||
int handle_trickle(MSG_FROM_HOST&); // handle a trickle message
|
||||
|
||||
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.
|
||||
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](ProjectDaemons).
|
||||
|
||||
By default, a trickle handler daemon enumerates msg_from_host records with handled==0,
|
||||
and when done sets handled=1.
|
||||
If you need multiple stages of trickle handling,
|
||||
you can do so by assigning **handled_enum** and **handled_set** in handle_trickle_init().
|
||||
For example, by setting these to 1 and 2 respectively you can add a 2nd stage of handling.
|
||||
|
||||
|
||||
# Sending trickle-down messages
|
||||
|
||||
To 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();
|
||||
|
||||
```
|
||||
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, include
|
||||
|
||||
|
||||
<msg_to_host/>
|
||||
|
||||
```
|
||||
<msg_to_host/>
|
||||
```
|
||||
|
||||
in your [configuration](ProjectOptions#Clientcontrol) (config.xml) file.
|
||||
|
||||
# Purging trickle messages
|
||||
|
||||
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>
|
||||
|
||||
```
|
||||
<task>
|
||||
<output>purge_trickles.out</output>
|
||||
<cmd>run_in_ops purge_trickles.php</cmd>
|
||||
<period>24 hours</period>
|
||||
</task>
|
||||
```
|
||||
|
||||
in your [configuration](ProjectOptions#Clientcontrol) (config.xml) file,
|
||||
to delete unneeded trickle-related records from your database.
|
||||
It you use multiple stages of trickle-up handling, use
|
||||
```
|
||||
purge_trickles.php msg_from_host 2
|
||||
```
|
||||
or whatever the final value of "handled" is.
|
||||
|
||||
# Replicated trickle-up messages
|
||||
|
||||
|
|
@ -83,14 +103,14 @@ You can arrange to have trickle-up messages sent not only the the project's sche
|
|||
but to other schedulers as well.
|
||||
To do this, including the following in your gui_urls.xml file:
|
||||
|
||||
|
||||
<trickle_up_urls>
|
||||
<url>http://a.b.edu/test2_cgi/cgi</url>
|
||||
[ ... ]
|
||||
</trickle_up_urls>
|
||||
|
||||
```
|
||||
<trickle_up_urls>
|
||||
<url>http://a.b.edu/test2_cgi/cgi</url>
|
||||
[ ... ]
|
||||
</trickle_up_urls>
|
||||
```
|
||||
|
||||
The messages sent to these trickle-up handlers
|
||||
are abbreviated versions of scheduler RPC requests.
|
||||
|
||||
This works only with 6.13.5+ clients.
|
||||
This works only with 6.13.5+ clients.
|
||||
|
|
|
|||
Loading…
Reference in New Issue