rdbms: improve ILoadBalancer comments about reuseConnection()

[lhc/web/wiklou.git] / includes / libs / rdbms / loadbalancer / ILoadBalancer.php

diff --git a/includes/libs/rdbms/loadbalancer/ILoadBalancer.php b/includes/libs/rdbms/loadbalancer/ILoadBalancer.php
index b565b3b..088c3f2 100644 (file)
--- a/includes/libs/rdbms/loadbalancer/ILoadBalancer.php
+++ b/includes/libs/rdbms/loadbalancer/ILoadBalancer.php
@@ -87,9 +87,6 @@ interface ILoadBalancer {
        /** @var int DB handle should have DBO_TRX disabled and the caller will leave it as such */
        const CONN_TRX_AUTO = 1;
 
-       /** Disable writing for the given connection. Used internally. Do not use with DB_MASTER! */
-       const CONN_NO_WRITE = 2;
-
        /**
         * Construct a manager of IDatabase connection objects
         *
@@ -173,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
         */
@@ -257,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
@@ -312,25 +319,6 @@ interface ILoadBalancer {
         */
        public function getServerType( $i );
 
-       /**
-        * Return the server info structure for a given index, or false if the index is invalid.
-        * @param int $i
-        * @return array|bool
-        *
-        * @deprecated Since 1.30, no alternative
-        */
-       public function getServerInfo( $i );
-
-       /**
-        * Sets the server info structure for the given index. Entry at index $i
-        * is created if it doesn't exist
-        * @param int $i
-        * @param array $serverInfo
-        *
-        * @deprecated Since 1.30, construct new object
-        */
-       public function setServerInfo( $i, array $serverInfo );
-
        /**
         * Get the current master position for chronology control purposes
         * @return DBMasterPos|bool Returns false if not applicable