Merge "Type hint against LinkTarget in WatchedItemStore"

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

diff --git a/includes/libs/rdbms/database/DBConnRef.php b/includes/libs/rdbms/database/DBConnRef.php
index d80a718..2c9858a 100644 (file)
--- a/includes/libs/rdbms/database/DBConnRef.php
+++ b/includes/libs/rdbms/database/DBConnRef.php
@@ -5,8 +5,23 @@ namespace Wikimedia\Rdbms;
 use InvalidArgumentException;
 
 /**
- * Helper class to handle automatically marking connections as reusable (via RAII pattern)
- * as well handling deferring the actual network connection until the handle is used
+ * Helper class used for automatically marking an IDatabase connection as reusable (once it no
+ * longer matters which DB domain is selected) and for deferring the actual network connection
+ *
+ * This uses an RAII-style pattern where calling code is expected to keep the returned reference
+ * handle as a function variable that falls out of scope when no longer needed. This avoids the
+ * need for matching reuseConnection() calls for every "return" statement as well as the tedious
+ * use of try/finally.
+ *
+ * @par Example:
+ * @code
+ *     function getRowData() {
+ *         $conn = $this->lb->getConnectedRef( DB_REPLICA );
+ *         $row = $conn->select( ... );
+ *         return $row ? (array)$row : false;
+ *         // $conn falls out of scope and $this->lb->reuseConnection() gets called
+ *     }
+ * @endcode
  *
  * @ingroup Database
  * @since 1.22
@@ -115,7 +130,7 @@ class DBConnRef implements IDatabase {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
-       public function setLBInfo( $name, $value = null ) {
+       public function setLBInfo( $nameOrArray, $value = null ) {
                // Disallow things that might confuse the LoadBalancer tracking
                throw new DBUnexpectedError( $this, "Changing LB info is disallowed to enable reuse." );
        }
@@ -634,15 +649,15 @@ class DBConnRef implements IDatabase {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
-       public function commit( $fname = __METHOD__, $flush = '' ) {
+       public function commit( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
-       public function rollback( $fname = __METHOD__, $flush = '' ) {
+       public function rollback( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
                return $this->__call( __FUNCTION__, func_get_args() );
        }
 
-       public function flushSnapshot( $fname = __METHOD__ ) {
+       public function flushSnapshot( $fname = __METHOD__, $flush = self::FLUSHING_ONE ) {
                return $this->__call( __FUNCTION__, func_get_args() );
        }