= 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 [TrickleApi 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 [TrickleApi#Replicatedtrickle-upmessages 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 [CreditOptions 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 [ProjectConfigFile 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.