1 files changed, 128 insertions, 0 deletions
diff --git a/man/qmail-todo.8 b/man/qmail-todo.8
new file mode 100644
index 0000000..740f5b3
--- /dev/null
+++ b/man/qmail-todo.8
@@ -0,0 +1,128 @@
+.TH s/qmail: qmail-todo 8
+.SH NAME
+qmail-todo \- schedule state change of message for delivery
+.SH SYNOPSIS
+.B qmail-todo
+.SH DESCRIPTION
+.B s/qmail 
+with a high local and remote concurrency number 
+is able to deliver a tremendous amount of messages (throughput).
+Depending on the provided resources however,
+often this can not be achieved since
+.B qmail-send
+becomes a bottleneck on delivery.
+
+.B qmail-send 
+preprocesses all new messages before deploying them for 
+.I local
+or for 
+.I remote 
+delivering. In a particulur run,
+.B qmail-send 
+does one 'todo' processing, but has the ability to close multiple jobs. 
+Due to this layout, potentially 
+.B qmail-send 
+can not feed all the new available (local/remote) delivery slots 
+and therefore, it is not possible to achieve the maximum throughput.
+
+This is a minor problem, given
+.B qmail-send 
+is able to complete this in short time; but due to
+many file system calls (fsync and (un)link) a 'todo'
+run is expensive and throttles the throughput.
+
+.B qmail-todo
+solves this 'silly qmail (queue) problem'
+which is apparent only on system with high injection rates,
+delegating the scheduling of 'todo' runs to a dedicated process.
+
+.SH "COMMUNICATION"
+.B qmail-todo
+interfaces with 
+.B qmail-send
+on file descriptors \fI[1,8]\fR on sending
+and \fI[7,0]\fR for receiving. 
+.B qmail-todo 
+communicates with
+.B qmail-clean
+on file descriptors \fI[2,0]\fR for sending
+and \fI[3,1]\fR for receiving.
+
+.B qmail-todo 
+and
+.B qmail-send
+share an extended and peristent message exchange format:
+
+.EX
+D[LRB]<mesgid>\0
+  Start delivery for new message with id <messid>.
+  The character L, R or B defines the type
+  of delivery: Local, Remote, or Both, respectively.
+.EE
+
+.EX
+L<string>\0
+  Dump string to the logger without adding additional
+ '\\n' or similar.
+.EE
+
+.B qmail-todo 
+sends "\\0" terminated messages, whereas 
+.B qmail-send 
+just sends one character to 
+.BR qmail-todo .
+
+.SH "BIG PICTURE"
+.EX
+               +-------+   +-------+
+               | clean |   | clean |
+               +--0-1--+   +--0-1--+       +-----------+
+         trigger  ^ |         ^ |        +->0,1 lspawn |
+            |     | v         | v       /  +-----------+
+ +-------+  v  +--2-3--+   +--5-6--+   /
+ |       |  |  |       0<--7     1,2<-+ 
+ | queue |--+--| todo  |   | send  | 
+ |       |  |  |       1-->8     3,4<-+ 
+ +-------+     +-------+   +---0---+   \\ 
+                               |        \\  +-----------+
+                               v         +->0,1 rspwan |
+                           +---0---+       +-----------+
+                           | logger|
+                           +-------+
+.EE
+
+.SH "EXIT CODES"
+.B qmail-todo 
+exits
+.I 0 
+if the messages have been processed successfully.
+It exits
+.I 1
+in case there is a communication problem with
+.BR qmail-send . 
+The exit code 
+.I 111 
+together with a diagnostic message is facilitated by
+.B qmail-todo
+in case it failes reading the required control files.
+
+.SH "DIAGNOSTICS"
+.B qmail-todo
+provides additional diagnostic messages to
+.B qmail-send
+to be displayed in the logs. In particular, in
+case of problems creating and (un)linking files. 
+
+.SH "CREDITS"
+.B qmail-todo
+included in 
+.B s/qmail
+has been created by Andre Oppermann (http://www.nrg4u.com) 
+as part of this LDAP patch for 
+.BR qmail .
+This man-page uses parts of his EXTERNAL discription.
+
+
+.SH "SEE ALSO"
+qmail-send(8),
+qmail-queue(8).