Improve docs for lag related DB functions

* They can return false if replication is stopped.
* Also remove redundant related doc blocks.

Change-Id: I40a1cb2da2f23815b9da8f79195df45c5e510585

diff --git a/includes/db/Database.php b/includes/db/Database.php
index 05dc3d3..c0cf067 100644 (file)
--- a/includes/db/Database.php
+++ b/includes/db/Database.php
@@ -3773,19 +3773,6 @@ abstract class DatabaseBase implements IDatabase {
                return true;
        }
 
-       /**
-        * Get the slave lag when the current transaction started
-        * or a general lag estimate if not transaction is active
-        *
-        * This is useful when transactions might use snapshot isolation
-        * (e.g. REPEATABLE-READ in innodb), so the "real" lag of that data
-        * is this lag plus transaction duration. If they don't, it is still
-        * safe to be pessimistic. In AUTO-COMMIT mode, this still gives an
-        * indication of the staleness of subsequent reads.
-        *
-        * @return array ('lag': seconds, 'since': UNIX timestamp of BEGIN)
-        * @since 1.27
-        */
        public function getSessionLagStatus() {
                return $this->getTransactionLagStatus() ?: $this->getApproximateLagStatus();
        }
@@ -3798,7 +3785,7 @@ abstract class DatabaseBase implements IDatabase {
         * is this lag plus transaction duration. If they don't, it is still
         * safe to be pessimistic. This returns null if there is no transaction.
         *
-        * @return array|null ('lag': seconds, 'since': UNIX timestamp of BEGIN)
+        * @return array|null ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN)
         * @since 1.27
         */
        public function getTransactionLagStatus() {
@@ -3810,7 +3797,7 @@ abstract class DatabaseBase implements IDatabase {
        /**
         * Get a slave lag estimate for this server
         *
-        * @return array ('lag': seconds, 'since': UNIX timestamp of estimate)
+        * @return array ('lag': seconds or false on error, 'since': UNIX timestamp of estimate)
         * @since 1.27
         */
        public function getApproximateLagStatus() {
@@ -3851,15 +3838,6 @@ abstract class DatabaseBase implements IDatabase {
                return $res;
        }
 
-       /**
-        * Get slave lag. Currently supported only by MySQL.
-        *
-        * Note that this function will generate a fatal error on many
-        * installations. Most callers should use LoadBalancer::safeGetLag()
-        * instead.
-        *
-        * @return int Database replication lag in seconds
-        */
        public function getLag() {
                return 0;
        }

diff --git a/includes/db/DatabaseMysqlBase.php b/includes/db/DatabaseMysqlBase.php
index 38aae58..1d9246d 100644 (file)
--- a/includes/db/DatabaseMysqlBase.php
+++ b/includes/db/DatabaseMysqlBase.php
@@ -620,13 +620,6 @@ abstract class DatabaseMysqlBase extends Database {
         */
        abstract protected function mysqlPing();
 
-       /**
-        * Returns slave lag.
-        *
-        * This will do a SHOW SLAVE STATUS
-        *
-        * @return int
-        */
        function getLag() {
                if ( $this->lagDetectionMethod === 'pt-heartbeat' ) {
                        return $this->getLagFromPtHeartbeat();

diff --git a/includes/db/IDatabase.php b/includes/db/IDatabase.php
index 19eb126..4674c17 100644 (file)
--- a/includes/db/IDatabase.php
+++ b/includes/db/IDatabase.php
@@ -1369,7 +1369,7 @@ interface IDatabase {
         * installations. Most callers should use LoadBalancer::safeGetLag()
         * instead.
         *
-        * @return int Database replication lag in seconds
+        * @return int|bool Database replication lag in seconds or false on error
         */
        public function getLag();
 
@@ -1383,7 +1383,7 @@ interface IDatabase {
         * safe to be pessimistic. In AUTO-COMMIT mode, this still gives an
         * indication of the staleness of subsequent reads.
         *
-        * @return array ('lag': seconds, 'since': UNIX timestamp of BEGIN)
+        * @return array ('lag': seconds or false on error, 'since': UNIX timestamp of BEGIN)
         * @since 1.27
         */
        public function getSessionLagStatus();