Merge "installer: Avoid <doclink/> hack for 'config-sidebar' rendering"

[lhc/web/wiklou.git] / includes / libs / rdbms / database / IDatabase.php

diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php
index a462916..3b9d1af 100644 (file)
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -42,6 +42,8 @@ interface IDatabase {
        const TRIGGER_COMMIT = 2;
        /** @var int Callback triggered by ROLLBACK */
        const TRIGGER_ROLLBACK = 3;
+       /** @var int Callback triggered by atomic section cancel (ROLLBACK TO SAVEPOINT) */
+       const TRIGGER_CANCEL = 4;
 
        /** @var string Transaction is requested by regular caller outside of the DB layer */
        const TRANSACTION_EXPLICIT = '';
@@ -1580,6 +1582,9 @@ interface IDatabase {
         *
         * This is useful for combining cooperative locks and DB transactions.
         *
+        * Note this is called when the whole transaction is resolved. To take action immediately
+        * when an atomic section is cancelled, use onAtomicSectionCancel().
+        *
         * @note do not assume that *other* IDatabase instances will be AUTOCOMMIT mode
         *
         * The callback takes the following arguments:
@@ -1661,6 +1666,31 @@ interface IDatabase {
         */
        public function onTransactionPreCommitOrIdle( callable $callback, $fname = __METHOD__ );
 
+       /**
+        * Run a callback when the atomic section is cancelled.
+        *
+        * The callback is run just after the current atomic section, any outer
+        * atomic section, or the whole transaction is rolled back.
+        *
+        * An error is thrown if no atomic section is pending. The atomic section
+        * need not have been created with the ATOMIC_CANCELABLE flag.
+        *
+        * Queries in the function may be running in the context of an outer
+        * transaction or may be running in AUTOCOMMIT mode. The callback should
+        * use atomic sections if necessary.
+        *
+        * @note do not assume that *other* IDatabase instances will be AUTOCOMMIT mode
+        *
+        * The callback takes the following arguments:
+        *   - IDatabase::TRIGGER_CANCEL or IDatabase::TRIGGER_ROLLBACK
+        *   - This IDatabase instance
+        *
+        * @param callable $callback
+        * @param string $fname Caller name
+        * @since 1.34
+        */
+       public function onAtomicSectionCancel( callable $callback, $fname = __METHOD__ );
+
        /**
         * Run a callback after each time any transaction commits or rolls back
         *
@@ -1914,7 +1944,7 @@ interface IDatabase {
         *
         * @throws DBError
         */
-       public function commit( $fname = __METHOD__, $flush = '' );
+       public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
 
        /**
         * Rollback a transaction previously started using begin().
@@ -1936,7 +1966,7 @@ interface IDatabase {
         * @throws DBError
         * @since 1.23 Added $flush parameter
         */
-       public function rollback( $fname = __METHOD__, $flush = '' );
+       public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
 
        /**
         * Commit any transaction but error out if writes or callbacks are pending
@@ -1947,10 +1977,20 @@ interface IDatabase {
         * useful to call on a replica DB after waiting on replication to catch up to the master.
         *
         * @param string $fname Calling function name
+        * @param string $flush Flush flag, set to situationally valid IDatabase::FLUSHING_*
+        *   constant to disable warnings about explicitly committing implicit transactions,
+        *   or calling commit when no transaction is in progress.
+        *
+        *   This will trigger an exception if there is an ongoing explicit transaction.
+        *
+        *   Only set the flush flag if you are sure that these warnings are not applicable,
+        *   and no explicit transactions are open.
+        *
         * @throws DBError
         * @since 1.28
+        * @since 1.34 Added $flush parameter
         */
-       public function flushSnapshot( $fname = __METHOD__ );
+       public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE );
 
        /**
         * Convert a timestamp in one of the formats accepted by wfTimestamp()
@@ -2082,7 +2122,7 @@ interface IDatabase {
         *
         * @param string $lockName Name of lock to aquire
         * @param string $method Name of the calling method
-        * @param int $timeout Acquisition timeout in seconds
+        * @param int $timeout Acquisition timeout in seconds (0 means non-blocking)
         * @return bool
         * @throws DBError
         */