From: Aaron Schulz <aschulz@wikimedia.org>
Date: Thu, 15 Feb 2018 21:28:58 +0000 (-0800)
Subject: rdbms: improve ILoadBalancer comments about reuseConnection()
X-Git-Tag: 1.31.0-rc.0~592^2
X-Git-Url: https://git.heureux-cyclage.org/?p=lhc%2Fweb%2Fwiklou.git;a=commitdiff_plain;h=cb8d821fbe695804c197b8aacd57532b49d8c73d

rdbms: improve ILoadBalancer comments about reuseConnection()

Change-Id: I94f8e95f5ed9c3357d118e9bc66c55b389061e7f
---

diff --git a/includes/libs/rdbms/loadbalancer/ILoadBalancer.php b/includes/libs/rdbms/loadbalancer/ILoadBalancer.php
index e246b79f80..088c3f2c67 100644
--- a/includes/libs/rdbms/loadbalancer/ILoadBalancer.php
+++ b/includes/libs/rdbms/loadbalancer/ILoadBalancer.php
@@ -170,15 +170,21 @@ interface ILoadBalancer {
 	public function getAnyOpenConnection( $i );
 
 	/**
-	 * Get a connection by index
+	 * Get a connection handle by server index
 	 *
 	 * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
 	 *
+	 * If the caller uses $domain or sets CONN_TRX_AUTO in $flags, then it must also
+	 * call ILoadBalancer::reuseConnection() on the handle when finished using it.
+	 * In all other cases, this is not necessary, though not harmful either.
+	 *
 	 * @param int $i Server index or DB_MASTER/DB_REPLICA
 	 * @param array|string|bool $groups Query group(s), or false for the generic reader
 	 * @param string|bool $domain Domain ID, or false for the current domain
 	 * @param int $flags Bitfield of CONN_* class constants
 	 *
+	 * @note This method throws DBAccessError if ILoadBalancer::disable() was called
+	 *
 	 * @throws DBError
 	 * @return Database
 	 */
@@ -254,7 +260,11 @@ interface ILoadBalancer {
 	 *
 	 * Avoid using CONN_TRX_AUTO with sqlite (e.g. check getServerType() first)
 	 *
-	 * @note If disable() was called on this LoadBalancer, this method will throw a DBAccessError.
+	 * If the caller uses $domain or sets CONN_TRX_AUTO in $flags, then it must also
+	 * call ILoadBalancer::reuseConnection() on the handle when finished using it.
+	 * In all other cases, this is not necessary, though not harmful either.
+	 *
+	 * @note This method throws DBAccessError if ILoadBalancer::disable() was called
 	 *
 	 * @param int $i Server index (does not support DB_MASTER/DB_REPLICA)
 	 * @param string|bool $domain Domain ID, or false for the current domain