X-Git-Url: http://git.cyclocoop.org/%22.%24image2.%22?a=blobdiff_plain;f=includes%2Fdb%2FIDatabase.php;h=e1d1173b14041aa283f9dceeccc931efaa2b8c0e;hb=6e9b4f0e9ce4ccd6089c18b205065ef7fa077484;hp=4674c17bedca990ebd067f5ab7ebea6d9f01c74b;hpb=170e23a2410fd0402019a4477a95075d531f5828;p=lhc%2Fweb%2Fwiklou.git

diff --git a/includes/db/IDatabase.php b/includes/db/IDatabase.php
index 4674c17bed..e1d1173b14 100644
--- a/includes/db/IDatabase.php
+++ b/includes/db/IDatabase.php
@@ -174,7 +174,7 @@ interface IDatabase {
 	public function writesOrCallbacksPending();
 
 	/**
-	 * Get the time spend running write queries for this
+	 * Get the time spend running write queries for this transaction
 	 *
 	 * High times could be due to scanning, updates, locking, and such
 	 *
@@ -183,6 +183,14 @@ interface IDatabase {
 	 */
 	public function pendingWriteQueryDuration();
 
+	/**
+	 * Get the list of method names that did write queries for this transaction
+	 *
+	 * @return array
+	 * @since 1.27
+	 */
+	public function pendingWriteCallers();
+
 	/**
 	 * Is a connection to the database open?
 	 * @return bool
@@ -464,7 +472,7 @@ interface IDatabase {
 	 * @return bool|mixed The value from the field, or false on failure.
 	 */
 	public function selectField(
-		$table, $var, $cond = '', $fname = __METHOD__, $options = array()
+		$table, $var, $cond = '', $fname = __METHOD__, $options = []
 	);
 
 	/**
@@ -486,7 +494,7 @@ interface IDatabase {
 	 * @since 1.25
 	 */
 	public function selectFieldValues(
-		$table, $var, $cond = '', $fname = __METHOD__, $options = array()
+		$table, $var, $cond = '', $fname = __METHOD__, $options = []
 	);
 
 	/**
@@ -632,7 +640,7 @@ interface IDatabase {
 	 */
 	public function select(
 		$table, $vars, $conds = '', $fname = __METHOD__,
-		$options = array(), $join_conds = array()
+		$options = [], $join_conds = []
 	);
 
 	/**
@@ -653,7 +661,7 @@ interface IDatabase {
 	 */
 	public function selectSQLText(
 		$table, $vars, $conds = '', $fname = __METHOD__,
-		$options = array(), $join_conds = array()
+		$options = [], $join_conds = []
 	);
 
 	/**
@@ -671,7 +679,7 @@ interface IDatabase {
 	 * @return stdClass|bool
 	 */
 	public function selectRow( $table, $vars, $conds, $fname = __METHOD__,
-		$options = array(), $join_conds = array()
+		$options = [], $join_conds = []
 	);
 
 	/**
@@ -695,7 +703,7 @@ interface IDatabase {
 	 * @return int Row count
 	 */
 	public function estimateRowCount(
-		$table, $vars = '*', $conds = '', $fname = __METHOD__, $options = array()
+		$table, $vars = '*', $conds = '', $fname = __METHOD__, $options = []
 	);
 
 	/**
@@ -716,7 +724,7 @@ interface IDatabase {
 	 * @return int Row count
 	 */
 	public function selectRowCount(
-		$tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = array(), $join_conds = array()
+		$tables, $vars = '*', $conds = '', $fname = __METHOD__, $options = [], $join_conds = []
 	);
 
 	/**
@@ -793,7 +801,7 @@ interface IDatabase {
 	 *
 	 * @return bool
 	 */
-	public function insert( $table, $a, $fname = __METHOD__, $options = array() );
+	public function insert( $table, $a, $fname = __METHOD__, $options = [] );
 
 	/**
 	 * UPDATE wrapper. Takes a condition array and a SET array.
@@ -813,7 +821,7 @@ interface IDatabase {
 	 *   - LOW_PRIORITY: MySQL-specific, see MySQL manual.
 	 * @return bool
 	 */
-	public function update( $table, $values, $conds, $fname = __METHOD__, $options = array() );
+	public function update( $table, $values, $conds, $fname = __METHOD__, $options = [] );
 
 	/**
 	 * Makes an encoded list of strings from an array
@@ -888,7 +896,7 @@ interface IDatabase {
 	 * @since 1.23
 	 */
 	public function buildGroupConcatField(
-		$delim, $table, $field, $conds = '', $join_conds = array()
+		$delim, $table, $field, $conds = '', $join_conds = []
 	);
 
 	/**
@@ -1090,7 +1098,7 @@ interface IDatabase {
 	 */
 	public function insertSelect( $destTable, $srcTable, $varMap, $conds,
 		$fname = __METHOD__,
-		$insertOptions = array(), $selectOptions = array()
+		$insertOptions = [], $selectOptions = []
 	);
 
 	/**
@@ -1211,6 +1219,8 @@ interface IDatabase {
 	 * after the database is updated so that the jobs will see the data when they actually run.
 	 * It can also be used for updates that easily cause deadlocks if locks are held too long.
 	 *
+	 * Updates will execute in the order they were enqueued.
+	 *
 	 * @param callable $callback
 	 * @since 1.20
 	 */
@@ -1224,6 +1234,8 @@ interface IDatabase {
 	 * This is useful for updates that easily cause deadlocks if locks are held too long
 	 * but where atomicity is strongly desired for these updates and some related updates.
 	 *
+	 * Updates will execute in the order they were enqueued.
+	 *
 	 * @param callable $callback
 	 * @since 1.22
 	 */
@@ -1268,6 +1280,34 @@ interface IDatabase {
 	 */
 	public function endAtomic( $fname = __METHOD__ );
 
+	/**
+	 * Run a callback to do an atomic set of updates for this database
+	 *
+	 * The $callback takes the following arguments:
+	 *   - 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.
+	 *
+	 * This can be an alternative to explicit startAtomic()/endAtomic() calls.
+	 *
+	 * @see DatabaseBase::startAtomic
+	 * @see DatabaseBase::endAtomic
+	 *
+	 * @param string $fname Caller name (usually __METHOD__)
+	 * @param callable $callback Callback that issues DB updates
+	 * @throws DBError
+	 * @throws RuntimeException
+	 * @throws UnexpectedValueException
+	 * @since 1.27
+	 */
+	public function doAtomicSection( $fname, $callback );
+
 	/**
 	 * Begin a transaction. If a transaction is already in progress,
 	 * that transaction will be committed before the new transaction is started.
@@ -1453,8 +1493,8 @@ interface IDatabase {
 	 * Named locks are not related to transactions
 	 *
 	 * @param string $lockName Name of lock to aquire
-	 * @param string $method Name of method calling us
-	 * @param int $timeout
+	 * @param string $method Name of the calling method
+	 * @param int $timeout Acquisition timeout in seconds
 	 * @return bool
 	 */
 	public function lock( $lockName, $method, $timeout = 5 );
@@ -1465,7 +1505,7 @@ interface IDatabase {
 	 * Named locks are not related to transactions
 	 *
 	 * @param string $lockName Name of lock to release
-	 * @param string $method Name of method calling us
+	 * @param string $method Name of the calling method
 	 *
 	 * @return int Returns 1 if the lock was released, 0 if the lock was not established
 	 * by this thread (in which case the lock is not released), and NULL if the named
@@ -1473,6 +1513,25 @@ interface IDatabase {
 	 */
 	public function unlock( $lockName, $method );
 
+	/**
+	 * Acquire a named lock, flush any transaction, and return an RAII style unlocker object
+	 *
+	 * This is suitiable for transactions that need to be serialized using cooperative locks,
+	 * where each transaction can see each others' changes. Any transaction is flushed to clear
+	 * out stale REPEATABLE-READ snapshot data. Once the returned object falls out of PHP scope,
+	 * any transaction will be committed and the lock will be released.
+	 *
+	 * If the lock acquisition failed, then no transaction flush happens, and null is returned.
+	 *
+	 * @param string $lockKey Name of lock to release
+	 * @param string $fname Name of the calling method
+	 * @param int $timeout Acquisition timeout in seconds
+	 * @return ScopedCallback|null
+	 * @throws DBUnexpectedError
+	 * @since 1.27
+	 */
+	public function getScopedLockAndFlush( $lockKey, $fname, $timeout );
+
 	/**
 	 * Check to see if a named lock used by lock() use blocking queues
 	 *