database: rename clearSnapshot() => flushSnapshot()

* This is more consistent with the name flushReplicaSnapshots().
* Also add it to IDatabase, which defines the modern OLTP methods
  of DatabaseBase. This methods is useful for callers that get
  locks or wait for a replica DB to catch up before querying it.

Change-Id: Ia31e480bb9ccf461bf05ede4278920918eec4f16

diff --git a/includes/db/DBConnRef.php b/includes/db/DBConnRef.php
index 1019e72..9997f2c 100644 (file)
--- a/includes/db/DBConnRef.php
+++ b/includes/db/DBConnRef.php
@@ -469,6 +469,10 @@ class DBConnRef implements IDatabase {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
+       public function flushSnapshot( $fname = __METHOD__ ) {
+               return $this->__call( __FUNCTION__, func_get_args() );
+       }
+
        public function listTables( $prefix = null, $fname = __METHOD__ ) {
                return $this->__call( __FUNCTION__, func_get_args() );
        }

diff --git a/includes/db/Database.php b/includes/db/Database.php
index a011107..ced7379 100644 (file)
--- a/includes/db/Database.php
+++ b/includes/db/Database.php
@@ -3044,7 +3044,7 @@ abstract class DatabaseBase implements IDatabase {
                }
        }
 
-       public function clearSnapshot( $fname = __METHOD__ ) {
+       public function flushSnapshot( $fname = __METHOD__ ) {
                if ( $this->writesOrCallbacksPending() || $this->explicitTrxActive() ) {
                        // This only flushes transactions to clear snapshots, not to write data
                        throw new DBUnexpectedError(

diff --git a/includes/db/IDatabase.php b/includes/db/IDatabase.php
index fa24144..f312357 100644 (file)
--- a/includes/db/IDatabase.php
+++ b/includes/db/IDatabase.php
@@ -1420,7 +1420,7 @@ interface IDatabase {
         * will cause a warning, unless the current transaction was started
         * automatically because of the DBO_TRX flag.
         *
-        * @param string $fname
+        * @param string $fname Calling function name
         * @param string $mode A situationally valid IDatabase::TRANSACTION_* constant [optional]
         * @throws DBError
         */
@@ -1458,7 +1458,7 @@ interface IDatabase {
         * throwing an Exception is preferrable, using a pre-installed error handler to trigger
         * rollback (in any case, failure to issue COMMIT will cause rollback server-side).
         *
-        * @param string $fname
+        * @param string $fname Calling function name
         * @param string $flush Flush flag, set to a situationally valid IDatabase::FLUSHING_*
         *   constant to disable warnings about calling rollback when no transaction is in
         *   progress. This will silently break any ongoing explicit transaction. Only set the
@@ -1468,6 +1468,20 @@ interface IDatabase {
         */
        public function rollback( $fname = __METHOD__, $flush = '' );
 
+       /**
+        * Commit any transaction but error out if writes or callbacks are pending
+        *
+        * This is intended for clearing out REPEATABLE-READ snapshots so that callers can
+        * see a new point-in-time of the database. This is useful when one of many transaction
+        * rounds finished and significant time will pass in the script's lifetime. It is also
+        * useful to call on a replica DB after waiting on replication to catch up to the master.
+        *
+        * @param string $fname Calling function name
+        * @throws DBUnexpectedError
+        * @since 1.28
+        */
+       public function flushSnapshot( $fname = __METHOD__ );
+
        /**
         * List all tables on the database
         *

diff --git a/includes/db/loadbalancer/LoadBalancer.php b/includes/db/loadbalancer/LoadBalancer.php
index 907cbc8..1f4b993 100644 (file)
--- a/includes/db/loadbalancer/LoadBalancer.php
+++ b/includes/db/loadbalancer/LoadBalancer.php
@@ -1181,7 +1181,7 @@ class LoadBalancer {
                        function ( DatabaseBase $conn ) use ( $fname, &$failures ) {
                                $conn->setTrxEndCallbackSuppression( true );
                                try {
-                                       $conn->clearSnapshot( $fname );
+                                       $conn->flushSnapshot( $fname );
                                } catch ( DBError $e ) {
                                        MWExceptionHandler::logException( $e );
                                        $failures[] = "{$conn->getServer()}: {$e->getMessage()}";
@@ -1215,7 +1215,7 @@ class LoadBalancer {
                                        if ( $conn->writesOrCallbacksPending() ) {
                                                $conn->commit( $fname, $conn::FLUSHING_ALL_PEERS );
                                        } elseif ( $restore ) {
-                                               $conn->clearSnapshot( $fname );
+                                               $conn->flushSnapshot( $fname );
                                        }
                                } catch ( DBError $e ) {
                                        MWExceptionHandler::logException( $e );
@@ -1337,7 +1337,7 @@ class LoadBalancer {
         */
        public function flushReplicaSnapshots( $fname = __METHOD__ ) {
                $this->forEachOpenReplicaConnection( function ( DatabaseBase $conn ) {
-                       $conn->clearSnapshot( __METHOD__ );
+                       $conn->flushSnapshot( __METHOD__ );
                } );
        }
 

diff --git a/tests/phpunit/includes/db/DatabaseTest.php b/tests/phpunit/includes/db/DatabaseTest.php
index 16297ad..0f9a401 100644 (file)
--- a/tests/phpunit/includes/db/DatabaseTest.php
+++ b/tests/phpunit/includes/db/DatabaseTest.php
@@ -324,18 +324,18 @@ class DatabaseTest extends MediaWikiTestCase {
        }
 
        /**
-        * @covers DatabaseBase::clearSnapshot()
+        * @covers DatabaseBase::flushSnapshot()
         */
-       public function testClearSnapshot() {
+       public function testFlushSnapshot() {
                $db = $this->db;
 
-               $db->clearSnapshot( __METHOD__ ); // ok
-               $db->clearSnapshot( __METHOD__ ); // ok
+               $db->flushSnapshot( __METHOD__ ); // ok
+               $db->flushSnapshot( __METHOD__ ); // ok
 
                $db->setFlag( DBO_TRX, $db::REMEMBER_PRIOR );
                $db->query( 'SELECT 1', __METHOD__ );
                $this->assertTrue( (bool)$db->trxLevel(), "Transaction started." );
-               $db->clearSnapshot( __METHOD__ ); // ok
+               $db->flushSnapshot( __METHOD__ ); // ok
                $db->restoreFlags( $db::RESTORE_PRIOR );
 
                $this->assertFalse( (bool)$db->trxLevel(), "Transaction cleared." );