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

1 files changed, 158 insertions, 0 deletions

diff --git a/android/async-socket-connector.h b/android/async-socket-connector.h
new file mode 100644
index 0000000..998d0c8
--- /dev/null
+++ b/android/async-socket-connector.h
@@ -0,0 +1,158 @@
+/*
+ * Copyright (C) 2011 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#ifndef ANDROID_ASYNC_SOCKET_CONNECTOR_H_
+#define ANDROID_ASYNC_SOCKET_CONNECTOR_H_
+
+/*
+ * Contains declaration of an API that allows asynchronous connection to a
+ * socket with retries.
+ *
+ * The typical usage of this 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.
+ */
+
+/* Declares async socket connector descriptor. */
+typedef struct AsyncSocketConnector AsyncSocketConnector;
+
+/* Enumerates connection events.
+ * Values from this enum are passed to the callback that connector's client uses
+ * to monitor connection status / progress.
+ */
+typedef enum ASCEvent {
+    /* Connection with the socket has been successfuly established. */
+    ASC_CONNECTION_SUCCEEDED,
+    /* A failure has occured while establising connection, with errno containing
+     * the actual error. */
+    ASC_CONNECTION_FAILED,
+    /* Async socket connector is about to retry the connection. */
+    ASC_CONNECTION_RETRY,
+} ASCEvent;
+
+/* Enumerates return values from the callback to the connector's client.
+ */
+typedef enum ASCCbRes {
+    /* Keep established connection. */
+    ASC_CB_KEEP,
+    /* Abort connection attempts. */
+    ASC_CB_ABORT,
+    /* Retry connection attempt. */
+    ASC_CB_RETRY,
+} ASCCbRes;
+
+/* Enumerates values returned from the connector routine.
+ */
+typedef enum ASCConnectRes {
+    /* Connection has succeeded in the connector routine. */
+    ASC_CONNECT_SUCCEEDED,
+    /* Connection has failed in the connector routine. */
+    ASC_CONNECT_FAILED,
+    /* Connection is in progress, and will be completed asynchronously. */
+    ASC_CONNECT_IN_PROGRESS,
+} ASCConnectRes;
+
+/* Declares callback that connector's client uses to monitor connection
+ * status / progress.
+ * Param:
+ *  opaque - An opaque pointer associated with the client.
+ *  connector - Connector instance for thecallback.
+ *  event - Event that has occured. If event is set to ASC_CONNECTION_FAILED,
+ *      errno contains connection error.
+ * Return:
+ *  One of ASCCbRes values.
+ */
+typedef ASCCbRes (*asc_event_cb)(void* opaque,
+                                 AsyncSocketConnector* connector,
+                                 ASCEvent event);
+
+/* Creates and initializes AsyncSocketConnector instance.
+ * Param:
+ *  address - Initialized socket address to connect to.
+ *  retry_to - Retry timeout in milliseconds.
+ *  cb, cb_opaque - Callback to invoke on connection events. This callback is
+ *      required, and must not be NULL.
+ * Return:
+ *  Initialized AsyncSocketConnector instance. Note that AsyncSocketConnector
+ *  instance returned from this routine will be destroyed by the connector itself,
+ *  when its work on connecting to the socket is completed. Typically, the
+ * connector wil destroy the descriptor after client's callback routine returns
+ * with the status other than ASC_CB_RETRY.
+ */
+extern AsyncSocketConnector* async_socket_connector_new(const SockAddress* address,
+                                                        int retry_to,
+                                                        asc_event_cb cb,
+                                                        void* cb_opaque);
+
+/* Initiates asynchronous connection.
+ * Param:
+ *  connector - Initialized AsyncSocketConnector instance.
+ * Return:
+ *  Status indicating state of the connection: completed, failed, or in progress.
+ *  Note that the connector will always invoke a callback passed to the
+ *  async_socket_connector_new routine prior to exiting from this routine with
+ *  statuses other ASC_CONNECT_IN_PROGRESS.
+ */
+extern ASCConnectRes async_socket_connector_connect(AsyncSocketConnector* connector);
+
+/* Pulls socket's file descriptor from the connector.
+ * This routine should be called from the connection callback on successful
+ * connection status. This will provide the connector's client with operational
+ * socket FD, and at the same time this will tell the connector not to close
+ * the FD when connector descriptor gets destroyed.
+ * Param:
+ *  connector - Initialized AsyncSocketConnector instance.
+ * Return:
+ *  File descriptor for the connected socket.
+ */
+extern int async_socket_connector_pull_fd(AsyncSocketConnector* connector);
+
+#endif  /* ANDROID_ASYNC_SOCKET_CONNECTOR_H_ */