From 3ef021296d613d79502afc6ecd06fbbcb11ba528 Mon Sep 17 00:00:00 2001
From: Vitalii Koshura <lestat.de.lionkur@gmail.com>
Date: Sun, 2 Apr 2023 02:32:45 +0200
Subject: [PATCH] Update TrickleApi.md

Signed-off-by: Vitalii Koshura <lestat.de.lionkur@gmail.com>
---
 TrickleApi.md | 122 +++++++++++++++++++++++++++++---------------------
 1 file changed, 71 insertions(+), 51 deletions(-)

diff --git a/TrickleApi.md b/TrickleApi.md
index 50e240f..6fb718c 100644
--- a/TrickleApi.md
+++ b/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.
\ No newline at end of file
+This works only with 6.13.5+ clients.