X-Git-Url: http://git.cyclocoop.org/?a=blobdiff_plain;f=includes%2Flibs%2Frdbms%2Fdatabase%2FIDatabase.php;h=47954b6e9e454342d1aca1a2c5a68421d7975156;hb=52aeaa7a5;hp=a5392c81cbbfd8106b7cea4b0cec42cff6243187;hpb=6c1cd929cb1c1fe0bcbde9fea59a1ff9bc2d9c6f;p=lhc%2Fweb%2Fwiklou.git

diff --git a/includes/libs/rdbms/database/IDatabase.php b/includes/libs/rdbms/database/IDatabase.php
index a5392c81cb..47954b6e9e 100644
--- a/includes/libs/rdbms/database/IDatabase.php
+++ b/includes/libs/rdbms/database/IDatabase.php
@@ -1580,19 +1580,19 @@ interface IDatabase {
 	/**
 	 * Begin an atomic section of statements
 	 *
-	 * If a transaction has been started already, just keep track of the given
-	 * section name to make sure the transaction is not committed pre-maturely.
-	 * This function can be used in layers (with sub-sections), so use a stack
-	 * to keep track of the different atomic sections. If there is no transaction,
-	 * start one implicitly.
+	 * If a transaction has been started already, sets a savepoint and tracks
+	 * the given section name to make sure the transaction is not committed
+	 * pre-maturely. This function can be used in layers (with sub-sections),
+	 * so use a stack to keep track of the different atomic sections. If there
+	 * is no transaction, one is started implicitly.
 	 *
 	 * The goal of this function is to create an atomic section of SQL queries
 	 * without having to start a new transaction if it already exists.
 	 *
-	 * All atomic levels *must* be explicitly closed using IDatabase::endAtomic(),
-	 * and any database transactions cannot be began or committed until all atomic
-	 * levels are closed. There is no such thing as implicitly opening or closing
-	 * an atomic section.
+	 * All atomic levels *must* be explicitly closed using IDatabase::endAtomic()
+	 * or IDatabase::cancelAtomic(), and any database transactions cannot be
+	 * began or committed until all atomic levels are closed. There is no such
+	 * thing as implicitly opening or closing an atomic section.
 	 *
 	 * @since 1.23
 	 * @param string $fname
@@ -1613,6 +1613,26 @@ interface IDatabase {
 	 */
 	public function endAtomic( $fname = __METHOD__ );
 
+	/**
+	 * Cancel an atomic section of SQL statements
+	 *
+	 * This will roll back only the statements executed since the start of the
+	 * most recent atomic section, and close that section. If a transaction was
+	 * open before the corresponding startAtomic() call, any statements before
+	 * that call are *not* rolled back and the transaction remains open. If the
+	 * corresponding startAtomic() implicitly started a transaction, that
+	 * transaction is rolled back.
+	 *
+	 * Note that a call to IDatabase::rollback() will also roll back any open
+	 * atomic sections.
+	 *
+	 * @since 1.31
+	 * @see IDatabase::startAtomic
+	 * @param string $fname
+	 * @throws DBError
+	 */
+	public function cancelAtomic( $fname = __METHOD__ );
+
 	/**
 	 * Run a callback to do an atomic set of updates for this database
 	 *
@@ -1620,17 +1640,18 @@ interface IDatabase {
 	 *   - This database object
 	 *   - The value of $fname
 	 *
-	 * If any exception occurs in the callback, then rollback() will be called and the error will
-	 * be re-thrown. It may also be that the rollback itself fails with an exception before then.
-	 * In any case, such errors are expected to terminate the request, without any outside caller
-	 * attempting to catch errors and commit anyway. Note that any rollback undoes all prior
-	 * atomic section and uncommitted updates, which trashes the current request, requiring an
-	 * error to be displayed.
+	 * If any exception occurs in the callback, then cancelAtomic() will be
+	 * called to back out any statements executed by the callback and the error
+	 * will be re-thrown. It may also be that the cancel itself fails with an
+	 * exception before then. In any case, such errors are expected to
+	 * terminate the request, without any outside caller attempting to catch
+	 * errors and commit anyway.
 	 *
-	 * This can be an alternative to explicit startAtomic()/endAtomic() calls.
+	 * This can be an alternative to explicit startAtomic()/endAtomic()/cancelAtomic() calls.
 	 *
 	 * @see Database::startAtomic
 	 * @see Database::endAtomic
+	 * @see Database::cancelAtomic
 	 *
 	 * @param string $fname Caller name (usually __METHOD__)
 	 * @param callable $callback Callback that issues DB updates
@@ -1638,7 +1659,9 @@ interface IDatabase {
 	 * @throws DBError
 	 * @throws RuntimeException
 	 * @throws UnexpectedValueException
-	 * @since 1.27
+	 * @since 1.27; prior to 1.31 this did a rollback() instead of
+	 *  cancelAtomic(), and assumed no callers up the stack would ever try to
+	 *  catch the exception.
 	 */
 	public function doAtomicSection( $fname, callable $callback );