1 files changed, 133 insertions, 0 deletions
diff --git a/src/mongo-sync-pool.h b/src/mongo-sync-pool.h
new file mode 100644
index 0000000..8750815
--- /dev/null
+++ b/src/mongo-sync-pool.h
@@ -0,0 +1,133 @@
+/* mongo-sync-pool.h - libmongo-client connection pool API
+ * Copyright 2011, 2012 Gergely Nagy <algernon@balabit.hu>
+ *
+ * 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.
+ */
+
+/** @file src/mongo-sync-pool.h
+ * MongoDB connection pool API public header.
+ *
+ * @addtogroup mongo_sync
+ * @{
+ */
+
+#ifndef LIBMONGO_POOL_H
+#define LIBMONGO_POOL_H 1
+
+#include <mongo-sync.h>
+#include <glib.h>
+
+G_BEGIN_DECLS
+
+/** @defgroup mongo_sync_pool_api Mongo Sync Pool API
+ *
+ * These commands implement connection pooling over the mongo_sync
+ * family of commands.
+ *
+ * Once a pool is set up, one can pick and return connections at one's
+ * leisure. Picking is done in a round-robin fashion (excluding
+ * connections that have been picked but not returned yet).
+ *
+ * @addtogroup mongo_sync_pool_api
+ * @{
+ */
+
+/** Opaque synchronous connection pool object.
+ *
+ * This represents a single connection within the pool.
+ */
+typedef struct _mongo_sync_pool_connection mongo_sync_pool_connection;
+
+/** Opaque synchronous pool object.
+ *
+ * This is the entire connection pool, with all its meta-data.
+ */
+typedef struct _mongo_sync_pool mongo_sync_pool;
+
+/** Create a new synchronous connection pool.
+ *
+ * Sets up a connection pool towards a given MongoDB server, and all
+ * its secondaries (if any).
+ *
+ * @param host is the address of the server.
+ * @param port is the port to connect to.
+ * @param nmasters is the number of connections to make towards the
+ * master.
+ * @param nslaves is the number of connections to make towards the
+ * secondaries.
+ *
+ * @note Either @a nmasters or @a nslaves can be zero, but not both at
+ * the same time.
+ *
+ * @note The @a host MUST be a master, otherwise the function will
+ * return an error.
+ *
+ * @returns A newly allocated mongo_sync_pool object, or NULL on
+ * error. It is the responsibility of the caller to close and free the
+ * pool when appropriate.
+ */
+mongo_sync_pool *mongo_sync_pool_new (const gchar *host,
+                                      gint port,
+                                      gint nmasters, gint nslaves);
+
+/** Close and free a synchronous connection pool.
+ *
+ * @param pool is the pool to shut down.
+ *
+ * @note The object will be freed, and shall not be used afterwards!
+ */
+void mongo_sync_pool_free (mongo_sync_pool *pool);
+
+/** Pick a connection from a synchronous connection pool.
+ *
+ * Based on given preferences, selects a free connection object from
+ * the pool, and returns it.
+ *
+ * @param pool is the pool to select from.
+ * @param want_master flags whether the caller wants a master connection,
+ * or secondaries are acceptable too.
+ *
+ * @note For write operations, always select a master!
+ *
+ * @returns A connection object from the pool.
+ *
+ * @note The returned object can be safely casted to
+ * mongo_sync_connection, and passed to any of the mongo_sync family
+ * of commands. Do note however, that one shall not close or otherwise
+ * free a connection object returned by this function.
+ */
+mongo_sync_pool_connection *mongo_sync_pool_pick (mongo_sync_pool *pool,
+                                                  gboolean want_master);
+
+/** Return a connection to the synchronous connection pool.
+ *
+ * Once one is not using a connection anymore, it should be returned
+ * to the pool using this function.
+ *
+ * @param pool is the pool to return to.
+ * @param conn is the connection to return.
+ *
+ * @returns TRUE on success, FALSE otherwise.
+ *
+ * @note The returned connection should not be used afterwards.
+ */
+gboolean mongo_sync_pool_return (mongo_sync_pool *pool,
+                                 mongo_sync_pool_connection *conn);
+
+/** @} */
+
+/** @} */
+
+G_END_DECLS
+
+#endif