Updated support for getReplica

The parsing of the arguments should probably be refactored
into a helper function.

Change-Id: I3e2dafeb7a6d10901d828eb9c8890c18796b815b
Reviewed-on: http://review.couchbase.org/27364
Reviewed-by: Matt Ingenthron <matt@couchbase.com>
Tested-by: Trond Norbye <trond.norbye@gmail.com>

Author: trondn

apidecl.c

@@ -375,6 +375,11 @@ ZEND_ARG_ARRAY_INFO(1, cas, 1)
 ZEND_ARG_INFO(0, flags)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_INFO_EX(arginfo_m_getreplica, 0, 0, 1)
+ZEND_ARG_INFO(0, ids)
+ZEND_ARG_INFO(0, strategy)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_INFO_EX(arginfo_m_getdelayed, 0, 0, 1)
 ZEND_ARG_ARRAY_INFO(0, ids, 0)
 ZEND_ARG_INFO(0, with_cas)
@@ -597,8 +602,7 @@ static zend_function_entry couchbase_methods[] = {
 	PHP_ME(couchbase, cas, arginfo_m_cas, ZEND_ACC_PUBLIC)
 	PHP_ME(couchbase, get, arginfo_m_get, ZEND_ACC_PUBLIC)
 	PHP_ME(couchbase, getMulti, arginfo_m_getmulti, ZEND_ACC_PUBLIC)
-	PHP_ME(couchbase, getReplica, arginfo_m_get, ZEND_ACC_PUBLIC)
-	PHP_ME(couchbase, getReplicaMulti, arginfo_m_getmulti, ZEND_ACC_PUBLIC)
+	PHP_ME(couchbase, getReplica, arginfo_m_getreplica, ZEND_ACC_PUBLIC)
 	PHP_ME(couchbase, getDelayed, arginfo_m_getdelayed, ZEND_ACC_PUBLIC)
 	PHP_ME(couchbase, getAndLock, arginfo_m_get_and_lock, ZEND_ACC_PUBLIC)
 	PHP_ME(couchbase, getAndLockMulti, arginfo_m_get_and_lock_multi, ZEND_ACC_PUBLIC)
@@ -655,12 +659,7 @@ PHP_METHOD(couchbase, getMulti)
 
 PHP_METHOD(couchbase, getReplica)
 {
-	php_couchbase_get_impl(INTERNAL_FUNCTION_PARAM_PASSTHRU, 0, 1, 0, 0, 1);
-}
-
-PHP_METHOD(couchbase, getReplicaMulti)
-{
-	php_couchbase_get_impl(INTERNAL_FUNCTION_PARAM_PASSTHRU, 1, 1, 0, 0, 1);
+	php_couchbase_get_replica_impl(INTERNAL_FUNCTION_PARAM_PASSTHRU);
 }
 
 PHP_METHOD(couchbase, getAndLock)
@@ -1290,7 +1289,11 @@ PHP_GINIT_FUNCTION(couchbase)
 	XX("COMPRESSION_FASTLZ", COUCHBASE_COMPRESSION_FASTLZ) \
 	XX("COMPRESSION_ZLIB", COUCHBASE_COMPRESSION_ZLIB) \
 	XX("GET_PRESERVE_ORDER", COUCHBASE_GET_PRESERVE_ORDER) \
-	XX("OPT_VOPTS_PASSTHROUGH", COUCHBASE_OPT_VOPTS_PASSTHROUGH)
+	XX("OPT_VOPTS_PASSTHROUGH", COUCHBASE_OPT_VOPTS_PASSTHROUGH) \
+	/* REPLICA */ \
+	XX("REPLICA_FIRST", LCB_REPLICA_FIRST) \
+	XX("REPLICA_ALL", LCB_REPLICA_ALL) \
+	XX("REPLICA_SELECT", LCB_REPLICA_SELECT)
 
 PHP_MINIT_FUNCTION(couchbase)
 {

apidecl.h

@@ -45,6 +45,9 @@ PHP_COUCHBASE_LOCAL
 void php_couchbase_get_impl(INTERNAL_FUNCTION_PARAMETERS, int multi,
 							int oo, int lock, int touch, int replica);
 
+PHP_COUCHBASE_LOCAL
+void php_couchbase_get_replica_impl(INTERNAL_FUNCTION_PARAMETERS);
+
 PHP_COUCHBASE_LOCAL
 void php_couchbase_get_delayed_impl(INTERNAL_FUNCTION_PARAMETERS, int oo);
 

config.m4

@@ -49,6 +49,7 @@ if test "$PHP_COUCHBASE" != "no"; then
                      observe.c \
                      options.c \
                      remove.c \
+                     replica.c \
                      resmgr.c \
                      simple_observe.c \
                      stat.c \

config.w32

@@ -23,6 +23,7 @@ if (PHP_COUCHBASE != "no") {
 		ADD_SOURCES(configure_module_dirname, "observe.c", "couchbase");
 		ADD_SOURCES(configure_module_dirname, "options.c", "couchbase");
 		ADD_SOURCES(configure_module_dirname, "remove.c", "couchbase");
+		ADD_SOURCES(configure_module_dirname, "replica.c", "couchbase");
 		ADD_SOURCES(configure_module_dirname, "resmgr.c", "couchbase");
 		ADD_SOURCES(configure_module_dirname, "stat.c", "couchbase");
 		ADD_SOURCES(configure_module_dirname, "simple_observe.c", "couchbase");

example/couchbase-api.php

@@ -86,7 +86,6 @@
  */
         const COUCHBASE_UNKNOWN_HOST = 0x15; //LCB_UNKNOWN_HOST
 
-
 ////////////////////////////////////////////////////////
 //                                                    //
 //        The following option constants exist        //
@@ -151,6 +150,34 @@
         const COUCHBASE_PRESERVE_ORDER = 1;
 
 
+////////////////////////////////////////////////////////
+//                                                    //
+//      The following replica strategies exist        //
+//                                                    //
+////////////////////////////////////////////////////////
+
+/**
+ * The caller will get a reply from the first replica to successfully
+ * reply within the timeout for the operation or will receive an
+ * error.
+ */
+const COUCHBASE_REPLICA_FIRST = LCB_REPLICA_FIRST;
+
+/**
+ * Ask all replicas to send documents/items back. The order of the
+ * replicas does not imply anything and is just the order they are
+ * received from the servers (one server may be more busy than
+ * the other etc).
+ */
+const COUCHBASE_REPLICA_ALL = LCB_REPLICA_ALL;
+
+/**
+ * Select one replica by the index in the configuration starting from
+ * zero. This approach can more quickly receive all possible replies
+ * for a given topology, but it can also generate false negatives
+ */
+const COUCHBASE_REPLICA_SELECT = LCB_REPLICA_SELECT;
+
 class Couchbase {
 
     /**
@@ -349,21 +376,44 @@ function getMulti($ids, &$cas = array(), $flags = 0) {
     /**
      * Retrieve a replica of a document from the cluster.
      *
-     * Please note that this method is currently experimental and its
-     * signature may change in a future release.
+     * Examples:
+     * <code>
+     *    $obj = $cb->getReplica("key",
+     *                           array("strategy" => COUCHBASE_REPLICA_SELECT,
+     *                                 "index" => 0));
      *
-     * @param string $id identifies the object to retrieve
-     * @param callable $callback a callback function to call for missing
-     *                 objects. The function signature looks like:
-     *                 <code>bool function($res, $id, &$val)</code>
-     *                 if the function returns <code>true</code> the value
-     *                 returned through $val is returned. Please note that
-     *                 the cas field is not updated in these cases.
-     * @param string $cas where to store the cas identifier of the object
+     *    returns
+     *      [ "foo" => [ "value" => "bar", "cas" => 0] ]
+     *
+     *
+     *    $obj = $cb->getReplica("foo", COUCHBASE_REPLICA_ALL);
+     *
+     *    returns
+     *      [ "foo" => [ [ "value" => "bar", "cas" => 0],
+     *                   [ "value" => "bar", "cas" => 0] ]
+     *      ]
+     *
+     *
+     *    $obj = $cb->getReplica(array("foo", "bar"), COUCHBASE_REPLICA_ALL);
+     *
+     *    returns
+     *      [ "foo" => [ [ "value" => "bar", "cas" => 0],
+     *                   [ "value" => "bar", "cas" => 0] ],
+     *        "bar" => [ [ "value" => "val", "cas" => 0],
+     *                   [ "value" => "val", "cas" => 0] ]
+     *      ]
+     *
+     * </code>
+     *
+     * @param string $ids The document id(s) to get. Pass an array to
+     *                    retrieve multiple documets
+     * @param string $strategy Which strategy to use to pick the replica.
+     *                         Pass in an array to specify extra options
+     *                         to the strategy.
      * @return object The document from the cluster
      * @throws CouchbaseException if an error occurs
      */
-    function getReplica($id, $callback = NULL, &$cas = "") {
+    function getReplica($id, $strategy = COUCHBASE_REPLICA_FIRST) {
 
     }
 
@@ -375,10 +425,12 @@ function getReplica($id, $callback = NULL, &$cas = "") {
      *
      * @param array $ids an array containing all of the document identifiers
      * @param array $cas an array to store the cas identifiers of the documents
+     * @param string $strategy Which strategy to use to pick the replica
+     * @param int $replicaidx Index (for COUCHBASE_REPLICA_SELECT)
      * @return array an array containing the documents
      * @throws CouchbaseException if an error occurs
      */
-    function getReplicaMulti($ids, &$cas = array()) {
+    function getReplicaMulti($ids, &$cas = array(), $strategy, $replicaidx) {
 
     }
 

internal.h

@@ -194,7 +194,6 @@ PHP_METHOD(couchbase, cas);
 PHP_METHOD(couchbase, get);
 PHP_METHOD(couchbase, getMulti);
 PHP_METHOD(couchbase, getReplica);
-PHP_METHOD(couchbase, getReplicaMulti);
 PHP_METHOD(couchbase, getDelayed);
 PHP_METHOD(couchbase, getAndLock);
 PHP_METHOD(couchbase, getAndLockMulti);