wiki:TrickleMessages

Version 10 (modified by davea, 6 years ago) (diff)

--

Trickle messages

Trickle messages let applications communicate with the server during the execution of a workunit. Messages are XML documents, and they may go from client to server or vice-versa. Trickle messages are asynchronous, ordered, and reliable. Since they are conveyed in scheduler RPC messages, they may not be delivered immediately after being generated.

See the APIs for sending and handling trickle messages.

Trickle-up messages

Trickle-up messages go from application to server. By default they are sent to the project's scheduler; you can optionally replicate them to other schedulers as well.

They are handled by trickle handler daemons running on the server. Each message is tagged with a 'variety' (a character string). Each daemon handles messages of a particular variety. (This is used, typically, to distinguish different applications.) Example uses:

  • The application sends a trickle-up message containing its current runtime, so that users can be granted credit incrementally (rather than waiting until the end of the work unit). BOINC supplies a trickle handler for this purpose.
  • 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.

To create a trickle handler daemon, modify the program sched/trickle_handler.cpp, replacing the function handle_trickle() with your own function. Add an entry in your config.xml to run this program as a daemon.

Trickle-down messages

Trickle-down messages go from server to application. Each one is addressed to a particular host, and must include an element <result_name> identifying the result to which the message is addressed. If that result is still running on the host, it is delivered to it. Example uses:

  • The server sends a message telling the application to abort.
  • The server sends a message containing the user's current total credit.