.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).