From 19b7d29f3caf26464a7cf005c84c017ffdf800e6 Mon Sep 17 00:00:00 2001 From: Aaron Schulz Date: Thu, 8 Sep 2016 04:28:52 -0700 Subject: [PATCH] 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 --- includes/db/DBConnRef.php | 4 ++++ includes/db/Database.php | 2 +- includes/db/IDatabase.php | 18 ++++++++++++++++-- includes/db/loadbalancer/LoadBalancer.php | 6 +++--- tests/phpunit/includes/db/DatabaseTest.php | 10 +++++----- 5 files changed, 29 insertions(+), 11 deletions(-) diff --git a/includes/db/DBConnRef.php b/includes/db/DBConnRef.php index 1019e729ea..9997f2c4b1 100644 --- 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 a011107fd3..ced7379084 100644 --- 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 fa24144be6..f312357fe3 100644 --- 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 907cbc8ee8..1f4b993d6e 100644 --- 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 16297ad267..0f9a401cd4 100644 --- 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." ); -- 2.20.1