Hi,

As part of a reply to a question posed by Sam in the jabber room last
night, here's a first stab on documentation of server fallback behaviour
for libradsec (see "** Timeouts").

Note that the read/write timeout implementation isn't present in the
public repo atm, only the connect timeout.

Comments are welcome.

--8<---------------cut here---------------start------------->8---
** Modes of operation
libradsec can be used in one of two modes -- blocking mode and
non-blocking mode.  This has nothing to do with blocking and
non-blocking I/O as known by users of the unix socket API but rather
who is running the event loop, the user or libradsec.

When using libradsec in blocking mode, the user of the library simply
calls rs_packet_send() which returns when the connection has been
established and the packet has been sent.  In non-blocking mode, all
rs_packet_send() does is preparing for the connection to be
established and the packet to be sent as soon as the user calls one of
the libevent dispatch functions.

TODO: Describe how the user can dispatch using another event loop than
libevent.  (Is this still possible?  I do hope so.)

** Timeouts
When using libradsec in blocking mode, i.e. when the library does the
dispatching by running the event loop for the user, the timeout
handling works as described in this section.

Only one single timeout value is being used, configured using the
`timeout' configuration option.  This value is used as the timeout
value, in seconds, on each of the operations connect, write and read.
One effect of this is that with a configured timeout value of T, a
complete connect+send+receive sequence can take up to 3*T seconds to
finish without the timeout firing.  If this is a problem the user will
have to use libradsec in non-blocking mode instead in order to get
more fine grained control of the timeout handling.

When using libradsec in non-blocking mode the only connect timeout is
in effecxt.  TODO: Explain why.
*** Connect timeout
The first time rs_packet_send() is used on a connection, a TCP connect
and TLS handshake will occur.  If this takes more than the number of
seconds configured in the `timeout' configuration option, the value of
the `retries' configuration option is used to determine whether
another peer should be used or not.  Each configured peer is contacted
exactly once, within the limits of $retries -- the $retries + 1 first
peers in the configuration are used.

If $retries + 1 connection attempts fail, rs_packet_send() will return
RSE_TIMEOUT_CONN.
*** Send timeout
If writing a message takes more than $timeout seconds to finish,
rs_packet_send() will return RSE_TIMEOUT_IO.
*** Receive timeout
If receiving a message takes more than $timeout seconds to finish,
rs_conn_receive_packet() will return RSE_TIMEOUT_IO.
--8<---------------cut here---------------end--------------->8---