edited function descriptions

Author: Liudmila Mantrova

doc/functions.md

@@ -2,47 +2,47 @@
 
 ## Cluster information functions
 
-* `mtm.get_nodes_state()` — Shows the status of nodes in the cluster. 
-    * id, integer - node ID.
-    * enabled, bool - shows whether node was excluded from cluster. Node can only be disabled due to missing responses to heartbeats during `heartbeat_recv_timeout`. When node will start responding to hearbeats it will be recovered and turned back to enabled state. Automatic recovery only possible when replication slot is active. Otherwise see section [manual node recovery].
-    * connected, bool - shows that node connected to our walsender.
-    * slot_active, bool - node has active replication slot. For a disabled node slot will be active until `max_recovery_lag` will be reached.
-    * stopped, bool - shows whether replication to this node was stopped by `mtm.stop_node()` function. Stopped node acts as a disabled one, but will not be automatically recovered. Call `mtm.recover_node()` to enable it again.
-    * catchUp - during recovery shows that node recovered till `min_recovery_lag`.
-    * slotLag - amount of WALs that replication slot holds for disabled/stoped node. Slot will be dropped whne slotLag reaches `max_recovery_lag`.
-    * avgTransDelay - average delay to transaction commit imposed by this node, usecs.
-    * lastStatusChange - last time when node changed it's status (enabled/disabled).
-    * oldestSnapshot - oldest global snapshot existing on this node.
-    * SenderPid - pid of WALSender.
-    * SenderStartTime - time when WALSender was started.
-    * ReceiverPid - pid of WALReceiver.
-    * ReceiverStartTime - time when WALReceiver was started.
-    * connStr - connection string to this node.
-    * connectivityMask - bitmask representing connectivity to neighbor nodes. Each bit means connection to node.
-    * nHeartbeats - number of hearbeat responses received from that node.
-
-* `mtm.collect_cluster_state()` - Collects output of `mtm.get_cluster_state()` from all available nodes. Note: for this function to work pg_hba should also allow ordinary connections (in addition to replication) to node with specified connstring.
-
-* `mtm.get_cluster_state()` - Get info about interanal state of multimaster extension. 
-    * status - Node status. Can be "Initialization", "Offline", "Connected", "Online", "Recovery", "Recovered", "InMinor", "OutOfService".
-    * disabledNodeMask - bitmask of disabled nodes.
-    * disconnectedNodeMask - bitmask of disconnected nodes.
-    * catchUpNodeMask - bitmask of nodes that completed their recovery.
-    * liveNodes - number of enabled nodes.
-    * allNodes - number of all nodes added to cluster. Decisions about majority of alive nodes based on that parameter.
-    * nActiveQueries - number of queries being currently processed on this node.
-    * nPendingQueries - number of queries avaiting their turn on this node.
-    * queueSize - size of pending queue in bytes.
-    * transCount - total amount of replicated transactions processed by this node.
-    * timeShift - global snapshot shit due to unsynchronized clocks on nodes, usec.
-    * recoverySlot - during recovery procedure node grabs changes from this node.
-    * xidHashSize - size of xid2state hash.
-    * gidHashSize - size of gid2state hash.
-    * oldestXid - oldest xid on this node.
-    * configChanges - number of state changes (enabled/disabled) since last reboot.
-    * stalledNodeMask - bitmask of nodes for which replication slot was dropped.
-    * stoppedNodeMask - bitmask of nodes that were stopped by `mtm.stop_node()`.
-    * lastStatusChange - timestamp when last state change happend.
+* `mtm.get_nodes_state()` — Shows the status of nodes in the cluster. Returns a tuple of the following values:
+    * id, integer - Node ID.
+    * enabled, bool - Shows whether the node is excluded from the cluster. The node can only be disabled if responses to heartbeats are not received within the `heartbeat_recv_timeout` time interval. When the node starts responding to heartbeats, `multimaster` can automatically restore the node and switch it back to the enabled state. Automatic recovery is only possible if the replication slot is still active. Otherwise, you can restore the node manually.
+    * connected, bool - Shows whether the node is connected to the WAL sender.
+    * slot_active, bool - Shows whether the node has an active replication slot. For a disabled node, the slot remains active until the `max_recovery_lag` value is reached.
+    * stopped, bool - Shows whether replication to this node was stopped by the `mtm.stop_node()` function. A stopped node acts as a disabled one, but cannot be automatically recovered. Call `mtm.recover_node()` to re-enable such a node.
+    * catchUp - During the node recovery, shows whether the data is recovered up to the `min_recovery_lag` value.
+    * slotLag - Size of the WAL data that the replication slot holds for a disabled/stopped node. The slot is dropped when `slotLag` reaches the `max_recovery_lag` value.
+    * avgTransDelay - An average commit delay caused by this node, in microseconds.
+    * lastStatusChange - Last time when the node changed its status (enabled/disabled).
+    * oldestSnapshot - The oldest global snapshot existing on this node.
+    * SenderPid - Process ID of the WAL sender.
+    * SenderStartTime - WAL sender start time.
+    * ReceiverPid - Process ID of the WAL receiver.
+    * ReceiverStartTime - WAL receiver start time.
+    * connStr - Connection string to this node.
+    * connectivityMask - Bitmask representing connectivity to neighbor nodes. Each bit represents a connection to node.
+    * nHeartbeats - Number of heartbeat responses received from this node.
+
+* `mtm.collect_cluster_state()` - Collects the data returned by the `mtm.get_cluster_state()` function from all available nodes. For this function to work, in addition to replication connections, pg_hba.conf must allow ordinary connections to the node with the specified connection string.
+
+* `mtm.get_cluster_state()` - Shows the status of the multimaster extension. Returns a tuple of the following values:
+    * status - Node status. Possible values are: "Initialization", "Offline", "Connected", "Online", "Recovery", "Recovered", "InMinor", "OutOfService". The <literal>inMinor</literal> status indicates that the corresponding node got disconnected from the majority of the cluster nodes. Even though the node is active, it will not accept write transactions until it is reconnected to the cluster.
+    * disabledNodeMask - Bitmask of disabled nodes.
+    * disconnectedNodeMask - Bitmask of disconnected nodes.
+    * catchUpNodeMask - Bitmask of nodes that completed the recovery.
+    * liveNodes - Number of enabled nodes.
+    * allNodes - Number of nodes in the cluster. The majority of alive nodes is calculated based on this parameter.
+    * nActiveQueries - Number of queries being currently processed on this node.
+    * nPendingQueries - Number of queries waiting for execution on this node.
+    * queueSize - Size of the pending query queue, in bytes.
+    * transCount - The total number of replicated transactions processed by this node.
+    * timeShift - Global snapshot shift caused by unsynchronized clocks on nodes, in microseconds.
+    * recoverySlot - The node from which a failed node gets data updates during automatic recovery.
+    * xidHashSize - Size of xid2state hash.
+    * gidHashSize - Size of gid2state hash.
+    * oldestXid - The oldest transaction ID on this node.
+    * configChanges - Number of state changes (enabled/disabled) since the last reboot.
+    * stalledNodeMask - Bitmask of nodes for which replication slots were dropped.
+    * stoppedNodeMask - Bitmask of nodes that were stopped by `mtm.stop_node()`.
+    * lastStatusChange - Timestamp of the last state change.
 
 
 ## Node management functions