From 36f025f8c979d06e87150f88be4838ab9bbb9de7 Mon Sep 17 00:00:00 2001
From: Aaron Schulz <aschulz@wikimedia.org>
Date: Wed, 18 Nov 2015 18:23:03 -0800
Subject: [PATCH] Improve docs for lag related DB functions

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

Change-Id: I40a1cb2da2f23815b9da8f79195df45c5e510585
---
 includes/db/Database.php          | 26 ++------------------------
 includes/db/DatabaseMysqlBase.php |  7 -------
 includes/db/IDatabase.php         |  4 ++--
 3 files changed, 4 insertions(+), 33 deletions(-)

diff --git a/includes/db/Database.php b/includes/db/Database.php
index 05dc3d309b..c0cf067009 100644
--- 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 38aae58645..1d9246df73 100644
--- 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 19eb12628b..4674c17bed 100644
--- 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();
-- 
2.20.1