X-Git-Url: https://git.heureux-cyclage.org/?a=blobdiff_plain;f=includes%2Fdb%2FIDatabase.php;h=f312357fe30b6d621bddcb4ed8533dde2d8f07a5;hb=c954a4efe8cd121a8f298f0d80011f9edd25d9fd;hp=b689e8230c3360d0c2b77a21906eb8b4b04bbe38;hpb=41746dec38dd7184a2c195bcb9e685caa57af0ed;p=lhc%2Fweb%2Fwiklou.git diff --git a/includes/db/IDatabase.php b/includes/db/IDatabase.php index b689e8230c..f312357fe3 100644 --- a/includes/db/IDatabase.php +++ b/includes/db/IDatabase.php @@ -35,9 +35,9 @@ interface IDatabase { /** @var int Callback triggered immediately due to no active transaction */ const TRIGGER_IDLE = 1; - /** @var int Callback triggered by commit */ + /** @var int Callback triggered by COMMIT */ const TRIGGER_COMMIT = 2; - /** @var int Callback triggered by rollback */ + /** @var int Callback triggered by ROLLBACK */ const TRIGGER_ROLLBACK = 3; /** @var string Transaction is requested by regular caller outside of the DB layer */ @@ -59,6 +59,11 @@ interface IDatabase { /** @var string Restore to the initial flag state */ const RESTORE_INITIAL = 'initial'; + /** @var string Estimate total time (RTT, scanning, waiting on locks, applying) */ + const ESTIMATE_TOTAL = 'total'; + /** @var string Estimate time to apply (scanning, applying) */ + const ESTIMATE_DB_APPLY = 'apply'; + /** * A string describing the current software version, and possibly * other details in a user-friendly way. Will be listed on Special:Version, etc. @@ -200,6 +205,7 @@ interface IDatabase { /** * Returns true if there is a transaction open with possible write * queries or transaction pre-commit/idle callbacks waiting on it to finish. + * This does *not* count recurring callbacks, e.g. from setTransactionListener(). * * @return bool */ @@ -210,10 +216,11 @@ interface IDatabase { * * High times could be due to scanning, updates, locking, and such * + * @param string $type IDatabase::ESTIMATE_* constant [default: ESTIMATE_ALL] * @return float|bool Returns false if not transaction is active * @since 1.26 */ - public function pendingWriteQueryDuration(); + public function pendingWriteQueryDuration( $type = self::ESTIMATE_TOTAL ); /** * Get the list of method names that did write queries for this transaction @@ -1228,20 +1235,20 @@ interface IDatabase { public function wasReadOnlyError(); /** - * Wait for the slave to catch up to a given master position + * Wait for the replica DB to catch up to a given master position * * @param DBMasterPos $pos * @param int $timeout The maximum number of seconds to wait for synchronisation - * @return int|null Zero if the slave was past that position already, + * @return int|null Zero if the replica DB was past that position already, * greater than zero if we waited for some period of time, less than * zero if it timed out, and null on error */ public function masterPosWait( DBMasterPos $pos, $timeout ); /** - * Get the replication position of this slave + * Get the replication position of this replica DB * - * @return DBMasterPos|bool False if this is not a slave. + * @return DBMasterPos|bool False if this is not a replica DB. */ public function getSlavePos(); @@ -1267,7 +1274,7 @@ interface IDatabase { * This is useful for combining cooperative locks and DB transactions. * * The callback takes one argument: - * How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK) + * - How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK) * * @param callable $callback * @return mixed @@ -1289,7 +1296,7 @@ interface IDatabase { * Updates will execute in the order they were enqueued. * * The callback takes one argument: - * How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_IDLE) + * - How the transaction ended (IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_IDLE) * * @param callable $callback * @since 1.20 @@ -1312,6 +1319,23 @@ interface IDatabase { */ public function onTransactionPreCommitOrIdle( callable $callback ); + /** + * Run a callback each time any transaction commits or rolls back + * + * The callback takes two arguments: + * - IDatabase::TRIGGER_COMMIT or IDatabase::TRIGGER_ROLLBACK + * - This IDatabase object + * Callbacks must commit any transactions that they begin. + * + * Registering a callback here will not affect writesOrCallbacks() pending + * + * @param string $name Callback name + * @param callable|null $callback Use null to unset a listener + * @return mixed + * @since 1.28 + */ + public function setTransactionListener( $name, callable $callback = null ); + /** * Begin an atomic section of statements * @@ -1396,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 */ @@ -1434,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 @@ -1444,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 * @@ -1485,12 +1523,13 @@ interface IDatabase { /** * Ping the server and try to reconnect if it there is no connection * + * @param float|null &$rtt Value to store the estimated RTT [optional] * @return bool Success or failure */ - public function ping(); + public function ping( &$rtt = null ); /** - * Get slave lag. Currently supported only by MySQL. + * Get replica DB lag. Currently supported only by MySQL. * * Note that this function will generate a fatal error on many * installations. Most callers should use LoadBalancer::safeGetLag() @@ -1501,7 +1540,7 @@ interface IDatabase { public function getLag(); /** - * Get the slave lag when the current transaction started + * Get the replica DB lag when the current transaction started * or a general lag estimate if not transaction is active * * This is useful when transactions might use snapshot isolation