objectcache: make the $flags argument appear more consistently in BagOStuff

Change-Id: I08879ede5e9f0ab227497bb1dab89ea61b65abce

diff --git a/includes/libs/objectcache/BagOStuff.php b/includes/libs/objectcache/BagOStuff.php
index bace22b..2f10708 100644 (file)
--- a/includes/libs/objectcache/BagOStuff.php
+++ b/includes/libs/objectcache/BagOStuff.php
@@ -91,8 +91,8 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
        const READ_LATEST = 1; // use latest data for replicated stores
        const READ_VERIFIED = 2; // promise that caller can tell when keys are stale
        /** Bitfield constants for set()/merge() */
-       const WRITE_SYNC = 1; // synchronously write to all locations for replicated stores
-       const WRITE_CACHE_ONLY = 2; // Only change state of the in-memory cache
+       const WRITE_SYNC = 4; // synchronously write to all locations for replicated stores
+       const WRITE_CACHE_ONLY = 8; // Only change state of the in-memory cache
 
        /**
         * $params include:
@@ -144,7 +144,7 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
         * @param string $key
         * @param int $ttl Time-to-live (seconds)
         * @param callable $callback Callback that derives the new value
-        * @param int $flags Bitfield of BagOStuff::READ_* constants [optional]
+        * @param int $flags Bitfield of BagOStuff::READ_* or BagOStuff::WRITE_* constants [optional]
         * @return mixed The cached value if found or the result of $callback otherwise
         * @since 1.27
         */
@@ -157,7 +157,7 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
                        }
                        $value = call_user_func( $callback );
                        if ( $value !== false ) {
-                               $this->set( $key, $value, $ttl );
+                               $this->set( $key, $value, $ttl, $flags );
                        }
                }
 
@@ -287,9 +287,10 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
         * @param callable $callback Callback method to be executed
         * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
         * @param int $attempts The amount of times to attempt a merge in case of failure
+        * @param int $flags Bitfield of BagOStuff::WRITE_* constants
         * @return bool Success
         */
-       protected function mergeViaCas( $key, $callback, $exptime = 0, $attempts = 10 ) {
+       protected function mergeViaCas( $key, $callback, $exptime = 0, $attempts = 10, $flags = 0 ) {
                do {
                        $this->clearLastError();
                        $reportDupes = $this->reportDupes;
@@ -315,10 +316,10 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
                                $success = true; // do nothing
                        } elseif ( $currentValue === false ) {
                                // Try to create the key, failing if it gets created in the meantime
-                               $success = $this->add( $key, $value, $exptime );
+                               $success = $this->add( $key, $value, $exptime, $flags );
                        } else {
                                // Try to update the key, failing if it gets changed in the meantime
-                               $success = $this->cas( $casToken, $key, $value, $exptime );
+                               $success = $this->cas( $casToken, $key, $value, $exptime, $flags );
                        }
                        if ( $this->getLastError() ) {
                                $this->logger->warning(
@@ -340,10 +341,11 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
         * @param string $key
         * @param mixed $value
         * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
+        * @param int $flags Bitfield of BagOStuff::WRITE_* constants
         * @return bool Success
         * @throws Exception
         */
-       protected function cas( $casToken, $key, $value, $exptime = 0 ) {
+       protected function cas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) {
                if ( !$this->lock( $key, 0 ) ) {
                        return false; // non-blocking
                }
@@ -351,7 +353,7 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
                $curCasToken = null; // passed by reference
                $this->getWithToken( $key, $curCasToken, self::READ_LATEST );
                if ( $casToken === $curCasToken ) {
-                       $success = $this->set( $key, $value, $exptime );
+                       $success = $this->set( $key, $value, $exptime, $flags );
                } else {
                        $this->logger->info(
                                __METHOD__ . ' failed due to race condition for {key}.',
@@ -423,13 +425,14 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
         *
         * @param string $key
         * @param int $expiry
+        * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
         * @return bool Success Returns false if there is no key
         * @since 1.28
         */
-       public function changeTTL( $key, $expiry = 0 ) {
+       public function changeTTL( $key, $expiry = 0, $flags = 0 ) {
                $value = $this->get( $key );
 
-               return ( $value === false ) ? false : $this->set( $key, $value, $expiry );
+               return ( $value === false ) ? false : $this->set( $key, $value, $expiry, $flags );
        }
 
        /**
@@ -568,49 +571,55 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
 
        /**
         * Get an associative array containing the item for each of the keys that have items.
-        * @param array $keys List of strings
+        * @param string[] $keys List of keys
         * @param int $flags Bitfield; supports READ_LATEST [optional]
         * @return array
         */
        public function getMulti( array $keys, $flags = 0 ) {
                $res = [];
                foreach ( $keys as $key ) {
-                       $val = $this->get( $key );
+                       $val = $this->get( $key, $flags );
                        if ( $val !== false ) {
                                $res[$key] = $val;
                        }
                }
+
                return $res;
        }
 
        /**
-        * Batch insertion
-        * @param array $data $key => $value assoc array
+        * Batch insertion/replace
+        * @param mixed[] $data Map of (key => value)
         * @param int $exptime Either an interval in seconds or a unix timestamp for expiry
+        * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
         * @return bool Success
         * @since 1.24
         */
-       public function setMulti( array $data, $exptime = 0 ) {
+       public function setMulti( array $data, $exptime = 0, $flags = 0 ) {
                $res = true;
                foreach ( $data as $key => $value ) {
-                       if ( !$this->set( $key, $value, $exptime ) ) {
+                       if ( !$this->set( $key, $value, $exptime, $flags ) ) {
                                $res = false;
                        }
                }
+
                return $res;
        }
 
        /**
+        * Insertion
         * @param string $key
         * @param mixed $value
         * @param int $exptime
+        * @param int $flags Bitfield of BagOStuff::WRITE_* constants (since 1.33)
         * @return bool Success
         */
-       public function add( $key, $value, $exptime = 0 ) {
+       public function add( $key, $value, $exptime = 0, $flags = 0 ) {
                // @note: avoid lock() here since that method uses *this* method by default
                if ( $this->get( $key ) === false ) {
-                       return $this->set( $key, $value, $exptime );
+                       return $this->set( $key, $value, $exptime, $flags );
                }
+
                return false; // key already set
        }
 
@@ -624,7 +633,7 @@ abstract class BagOStuff implements IExpiringStore, LoggerAwareInterface {
                if ( !$this->lock( $key, 1 ) ) {
                        return false;
                }
-               $n = $this->get( $key );
+               $n = $this->get( $key, self::READ_LATEST );
                if ( $this->isInteger( $n ) ) { // key exists?
                        $n += intval( $value );
                        $this->set( $key, max( 0, $n ) ); // exptime?

diff --git a/includes/libs/objectcache/EmptyBagOStuff.php b/includes/libs/objectcache/EmptyBagOStuff.php
index 3bf58df..9300dc2 100644 (file)
--- a/includes/libs/objectcache/EmptyBagOStuff.php
+++ b/includes/libs/objectcache/EmptyBagOStuff.php
@@ -31,7 +31,7 @@ class EmptyBagOStuff extends BagOStuff {
                return false;
        }
 
-       public function add( $key, $value, $exp = 0 ) {
+       public function add( $key, $value, $exp = 0, $flags = 0 ) {
                return true;
        }
 

diff --git a/includes/libs/objectcache/MemcachedBagOStuff.php b/includes/libs/objectcache/MemcachedBagOStuff.php
index 47e04d0..06e90a0 100644 (file)
--- a/includes/libs/objectcache/MemcachedBagOStuff.php
+++ b/includes/libs/objectcache/MemcachedBagOStuff.php
@@ -65,7 +65,7 @@ class MemcachedBagOStuff extends BagOStuff {
                        $this->fixExpiry( $exptime ) );
        }
 
-       protected function cas( $casToken, $key, $value, $exptime = 0 ) {
+       protected function cas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) {
                return $this->client->cas( $casToken, $this->validateKeyEncoding( $key ),
                        $value, $this->fixExpiry( $exptime ) );
        }
@@ -74,7 +74,7 @@ class MemcachedBagOStuff extends BagOStuff {
                return $this->client->delete( $this->validateKeyEncoding( $key ) );
        }
 
-       public function add( $key, $value, $exptime = 0 ) {
+       public function add( $key, $value, $exptime = 0, $flags = 0 ) {
                return $this->client->add( $this->validateKeyEncoding( $key ), $value,
                        $this->fixExpiry( $exptime ) );
        }
@@ -83,7 +83,7 @@ class MemcachedBagOStuff extends BagOStuff {
                return $this->mergeViaCas( $key, $callback, $exptime, $attempts );
        }
 
-       public function changeTTL( $key, $exptime = 0 ) {
+       public function changeTTL( $key, $exptime = 0, $flags = 0 ) {
                return $this->client->touch( $this->validateKeyEncoding( $key ),
                        $this->fixExpiry( $exptime ) );
        }

diff --git a/includes/libs/objectcache/MemcachedPeclBagOStuff.php b/includes/libs/objectcache/MemcachedPeclBagOStuff.php
index a6646bc..62a57b6 100644 (file)
--- a/includes/libs/objectcache/MemcachedPeclBagOStuff.php
+++ b/includes/libs/objectcache/MemcachedPeclBagOStuff.php
@@ -159,7 +159,7 @@ class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
 
        public function set( $key, $value, $exptime = 0, $flags = 0 ) {
                $this->debugLog( "set($key)" );
-               $result = parent::set( $key, $value, $exptime );
+               $result = parent::set( $key, $value, $exptime, $flags = 0 );
                if ( $result === false && $this->client->getResultCode() === Memcached::RES_NOTSTORED ) {
                        // "Not stored" is always used as the mcrouter response with AllAsyncRoute
                        return true;
@@ -167,9 +167,9 @@ class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
                return $this->checkResult( $key, $result );
        }
 
-       protected function cas( $casToken, $key, $value, $exptime = 0 ) {
+       protected function cas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) {
                $this->debugLog( "cas($key)" );
-               return $this->checkResult( $key, parent::cas( $casToken, $key, $value, $exptime ) );
+               return $this->checkResult( $key, parent::cas( $casToken, $key, $value, $exptime, $flags ) );
        }
 
        public function delete( $key, $flags = 0 ) {
@@ -182,7 +182,7 @@ class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
                return $this->checkResult( $key, $result );
        }
 
-       public function add( $key, $value, $exptime = 0 ) {
+       public function add( $key, $value, $exptime = 0, $flags = 0 ) {
                $this->debugLog( "add($key)" );
                return $this->checkResult( $key, parent::add( $key, $value, $exptime ) );
        }
@@ -248,12 +248,7 @@ class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
                return $this->checkResult( false, $result );
        }
 
-       /**
-        * @param array $data
-        * @param int $exptime
-        * @return bool
-        */
-       public function setMulti( array $data, $exptime = 0 ) {
+       public function setMulti( array $data, $exptime = 0, $flags = 0 ) {
                $this->debugLog( 'setMulti(' . implode( ', ', array_keys( $data ) ) . ')' );
                foreach ( array_keys( $data ) as $key ) {
                        $this->validateKeyEncoding( $key );
@@ -262,7 +257,7 @@ class MemcachedPeclBagOStuff extends MemcachedBagOStuff {
                return $this->checkResult( false, $result );
        }
 
-       public function changeTTL( $key, $expiry = 0 ) {
+       public function changeTTL( $key, $expiry = 0, $flags = 0 ) {
                $this->debugLog( "touch($key)" );
                $result = $this->client->touch( $key, $expiry );
                return $this->checkResult( $key, $result );

diff --git a/includes/libs/objectcache/MultiWriteBagOStuff.php b/includes/libs/objectcache/MultiWriteBagOStuff.php
index f549876..5cf9de4 100644 (file)
--- a/includes/libs/objectcache/MultiWriteBagOStuff.php
+++ b/includes/libs/objectcache/MultiWriteBagOStuff.php
@@ -143,7 +143,7 @@ class MultiWriteBagOStuff extends BagOStuff {
                return $this->doWrite( $this->cacheIndexes, $this->asyncWrites, 'delete', $key );
        }
 
-       public function add( $key, $value, $exptime = 0 ) {
+       public function add( $key, $value, $exptime = 0, $flags = 0 ) {
                // Try the write to the top-tier cache
                $ok = $this->doWrite( [ 0 ], $this->asyncWrites, 'add', $key, $value, $exptime );
                if ( $ok ) {

diff --git a/includes/libs/objectcache/RedisBagOStuff.php b/includes/libs/objectcache/RedisBagOStuff.php
index 3926604..2bf0c48 100644 (file)
--- a/includes/libs/objectcache/RedisBagOStuff.php
+++ b/includes/libs/objectcache/RedisBagOStuff.php
@@ -189,12 +189,7 @@ class RedisBagOStuff extends BagOStuff {
                return $result;
        }
 
-       /**
-        * @param array $data
-        * @param int $expiry
-        * @return bool
-        */
-       public function setMulti( array $data, $expiry = 0 ) {
+       public function setMulti( array $data, $expiry = 0, $flags = 0 ) {
                $batches = [];
                $conns = [];
                foreach ( $data as $key => $value ) {
@@ -238,7 +233,7 @@ class RedisBagOStuff extends BagOStuff {
                return $result;
        }
 
-       public function add( $key, $value, $expiry = 0 ) {
+       public function add( $key, $value, $expiry = 0, $flags = 0 ) {
                list( $server, $conn ) = $this->getConnection( $key );
                if ( !$conn ) {
                        return false;
@@ -299,7 +294,7 @@ class RedisBagOStuff extends BagOStuff {
                return $result;
        }
 
-       public function changeTTL( $key, $expiry = 0 ) {
+       public function changeTTL( $key, $expiry = 0, $flags = 0 ) {
                list( $server, $conn ) = $this->getConnection( $key );
                if ( !$conn ) {
                        return false;

diff --git a/includes/libs/objectcache/ReplicatedBagOStuff.php b/includes/libs/objectcache/ReplicatedBagOStuff.php
index e2b9a52..6afdc1c 100644 (file)
--- a/includes/libs/objectcache/ReplicatedBagOStuff.php
+++ b/includes/libs/objectcache/ReplicatedBagOStuff.php
@@ -94,7 +94,7 @@ class ReplicatedBagOStuff extends BagOStuff {
                return $this->writeStore->delete( $key, $flags );
        }
 
-       public function add( $key, $value, $exptime = 0 ) {
+       public function add( $key, $value, $exptime = 0, $flags = 0 ) {
                return $this->writeStore->add( $key, $value, $exptime );
        }
 

diff --git a/includes/objectcache/SqlBagOStuff.php b/includes/objectcache/SqlBagOStuff.php
index eeb7355..66b488e 100644 (file)
--- a/includes/objectcache/SqlBagOStuff.php
+++ b/includes/objectcache/SqlBagOStuff.php
@@ -311,7 +311,7 @@ class SqlBagOStuff extends BagOStuff {
                return $values;
        }
 
-       public function setMulti( array $data, $expiry = 0 ) {
+       public function setMulti( array $data, $expiry = 0, $flags = 0 ) {
                $keysByTable = [];
                foreach ( $data as $key => $value ) {
                        list( $serverIndex, $tableName ) = $this->getTableByKey( $key );
@@ -381,7 +381,7 @@ class SqlBagOStuff extends BagOStuff {
                return $ok;
        }
 
-       protected function cas( $casToken, $key, $value, $exptime = 0 ) {
+       protected function cas( $casToken, $key, $value, $exptime = 0, $flags = 0 ) {
                list( $serverIndex, $tableName ) = $this->getTableByKey( $key );
                $db = null;
                $silenceScope = $this->silenceTransactionProfiler();
@@ -493,7 +493,7 @@ class SqlBagOStuff extends BagOStuff {
        }
 
        public function merge( $key, callable $callback, $exptime = 0, $attempts = 10, $flags = 0 ) {
-               $ok = $this->mergeViaCas( $key, $callback, $exptime, $attempts );
+               $ok = $this->mergeViaCas( $key, $callback, $exptime, $attempts, $flags );
                if ( ( $flags & self::WRITE_SYNC ) == self::WRITE_SYNC ) {
                        $ok = $this->waitForReplication() && $ok;
                }
@@ -501,7 +501,7 @@ class SqlBagOStuff extends BagOStuff {
                return $ok;
        }
 
-       public function changeTTL( $key, $expiry = 0 ) {
+       public function changeTTL( $key, $expiry = 0, $flags = 0 ) {
                list( $serverIndex, $tableName ) = $this->getTableByKey( $key );
                $db = null;
                $silenceScope = $this->silenceTransactionProfiler();