Implements an asynchronous socket connector with retries
The typical usage of the API is as such:
1. The client creates an async connector instance by calling async_socket_connector_new
routine, supplying there address of the socket to connect, and a callback
to invoke on connection events.
2. The client then proceeds with calling async_socket_connector_connect that
would initiate connection attempts.
The main job on the client side falls on the client's callback routine that
serves the connection events. Once connection has been initiated, the connector
will invoke that callback to report current connection status.
In general, there are three connection events passed to the callback:
1. Success.
2. Failure.
3. Retry.
Typically, when client's callback is called for successful connection, the
client will pull connected socket's FD from the connector, and then this FD
will be used by the client for I/O on the connected socket. If socket's FD
is pulled by the client, it must return ASC_CB_KEEP from the callback.
When client's callback is invoked with an error (ASC_CONNECTION_FAILED event),
the client has an opportunity to review the error (available in 'errno'), and
either abort the connection by returning ASC_CB_ABORT, or schedule a retry
by returning ASC_CB_RETRY from the callback. If client returns ASC_CB_ABORT
from the callback, the connector will stop connection attempts, and will
self-destruct. If ASC_CB_RETRY is returned from the callback, the connector
will retry connection attempt after timeout that was set by the caller in the
call to async_socket_connector_new routine.
When client's callback is invoked with ASC_CONNECTION_RETRY, the client has an
opportunity to cancel further connection attempts by returning ASC_CB_ABORT,
or it can allow another connection attempt by returning ASC_CB_RETRY.
The client has no control over the lifespan of initialized connector instance.
It always self-destructs after client's cllback returns with a status other
than ASC_CB_RETRY.
Change-Id: I39b0057013e45ee10d1ef98905b8a5210656a26c
4 files changed
