tools: add comments about the global lockdev-dct-lvmlockd-AJ

State the reason that the global lock is
needed in each place it is taken.

18 files changed, 53 insertions, 12 deletions

diff --git a/tools/lvchange.c b/tools/lvchange.c
index 57b96bb5c..75925d307 100644
--- a/tools/lvchange.c
+++ b/tools/lvchange.c
@@ -1284,6 +1284,10 @@ int lvchange(struct cmd_context *cmd, int argc, char **argv)
 	if (arg_count(cmd, activate_ARG) || arg_count(cmd, refresh_ARG))
 		cmd->lockd_vg_default_sh = 1;
 
+	/*
+	 * Needed for a current listing of the global VG namespace.
+	 * (All VGs must be searched and read to match tags.)
+	 */
 	if (arg_tag_count(argc, argv) && !lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/lvscan.c b/tools/lvscan.c
index 4042204fb..389d960d1 100644
--- a/tools/lvscan.c
+++ b/tools/lvscan.c
@@ -98,6 +98,7 @@ int lvscan(struct cmd_context *cmd, int argc, char **argv)
 		return EINVALID_CMD_LINE;
 	}
 
+	/* Needed for a current listing of the global VG namespace. */
 	if (!lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/pvchange.c b/tools/pvchange.c
index 1b5e2a43f..19f993690 100644
--- a/tools/pvchange.c
+++ b/tools/pvchange.c
@@ -82,7 +82,11 @@ static int _pvchange_single(struct cmd_context *cmd, struct volume_group *vg,
 		}
 	}
 
-	/* Convert sh to ex.  gl only needed for orphans. */
+	/*
+	 * Needed to change a property on an orphan PV.
+	 * i.e. the global lock is only needed for orphans.
+	 * Convert sh to ex.
+	 */
 	if (is_orphan(pv) && !lockd_gl(cmd, "ex", 0))
 		return_ECMD_FAILED;
 
@@ -195,6 +199,7 @@ int pvchange(struct cmd_context *cmd, int argc, char **argv)
 		goto out;
 	}
 
+	/* Needed for a current listing of the global VG namespace. */
 	if (!lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/pvcreate.c b/tools/pvcreate.c
index 8b4730103..1f45ad91d 100644
--- a/tools/pvcreate.c
+++ b/tools/pvcreate.c
@@ -96,6 +96,7 @@ int pvcreate(struct cmd_context *cmd, int argc, char **argv)
 	int ret = ECMD_PROCESSED;
 	struct pvcreate_params pp;
 
+	/* Needed to change the set of orphan PVs. */
 	if (!lockd_gl(cmd, "ex", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/pvdisplay.c b/tools/pvdisplay.c
index b72651e04..abcf5dd60 100644
--- a/tools/pvdisplay.c
+++ b/tools/pvdisplay.c
@@ -107,6 +107,7 @@ int pvdisplay(struct cmd_context *cmd, int argc, char **argv)
 		}
 	}
 
+	/* Needed for a current listing of the global VG namespace. */
 	if (!lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/pvremove.c b/tools/pvremove.c
index 1baf1ac5e..e6ae86641 100644
--- a/tools/pvremove.c
+++ b/tools/pvremove.c
@@ -32,6 +32,7 @@ int pvremove(struct cmd_context *cmd, int argc, char **argv)
 
 	dm_list_init(&pv_names);
 
+	/* Needed to change the set of orphan PVs. */
 	if (!lockd_gl(cmd, "ex", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/pvresize.c b/tools/pvresize.c
index a86ddd4da..375c9a631 100644
--- a/tools/pvresize.c
+++ b/tools/pvresize.c
@@ -36,7 +36,11 @@ static int _pvresize_single(struct cmd_context *cmd,
 	}
 	params->total++;
 
-	/* Convert sh to ex.  gl is only needed for orphans. */
+	/*
+	 * Needed to change a property on an orphan PV.
+	 * i.e. the global lock is only needed for orphans.
+	 * Convert sh to ex.
+	 */
 	if (is_orphan(pv) && !lockd_gl(cmd, "ex", 0))
 		return_ECMD_FAILED;
 
@@ -80,6 +84,7 @@ int pvresize(struct cmd_context *cmd, int argc, char **argv)
 
 	handle->custom_handle = &params;
 
+	/* Needed for a current listing of the global VG namespace. */
 	if (!lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/pvscan.c b/tools/pvscan.c
index 7f6c34de8..144023ce6 100644
--- a/tools/pvscan.c
+++ b/tools/pvscan.c
@@ -370,6 +370,7 @@ int pvscan(struct cmd_context *cmd, int argc, char **argv)
 		return ECMD_FAILED;
 	}
 
+	/* Needed for a current listing of the global VG namespace. */
 	if (!lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/reporter.c b/tools/reporter.c
index 4db40b552..4437675b2 100644
--- a/tools/reporter.c
+++ b/tools/reporter.c
@@ -629,6 +629,10 @@ static int _report(struct cmd_context *cmd, int argc, char **argv,
 	/* Check PV specifics and do extra changes/actions if needed. */
 	_check_pv_list(cmd, argc, argv, &report_type, &args_are_pvs);
 
+	/*
+	 * Needed for a current listing of the global VG namespace.
+	 * (And all VGs must be searched and read to match tags.)
+	 */
 	if ((!argc || arg_tag_count(argc, argv)) && !lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/vgchange.c b/tools/vgchange.c
index a609cf60f..7912cfcc8 100644
--- a/tools/vgchange.c
+++ b/tools/vgchange.c
@@ -1021,10 +1021,12 @@ static int lockd_vgchange(struct cmd_context *cmd, int argc, char **argv)
 
 	if (!argc || arg_tag_count(argc, argv) || arg_is_set(cmd, lockstart_ARG)) {
 		/*
-		 * The first two standard conditions want the current
-		 * list of all vg names.  The lockstart condition takes
-		 * the gl to serialize with any other host that tries to
-		 * remove the VG while this tries to start it.
+		 * Needed for a current listing of the global VG namespace.
+		 * (And all VGs must be searched and read to match tags.)
+		 *
+		 * The lockstart condition takes the global lock to serialize
+		 * with any other host that tries to remove the VG while this
+		 * tries to start it.
 		 */
 		if (!lockd_gl(cmd, "sh", 0))
 			return_ECMD_FAILED;
@@ -1033,12 +1035,14 @@ static int lockd_vgchange(struct cmd_context *cmd, int argc, char **argv)
 		   arg_is_set(cmd, uuid_ARG) ||
 		   arg_is_set(cmd, locktype_ARG)) {
 		/*
-		 * VG names, uuids and system_ids are the three things that
-		 * other hosts cache related to local vg's, so we use the
-		 * name-change counter in the global lock to indicate that
-		 * one of these global VG identifiers has changed so other
-		 * hosts will update these cached values in VG's that they
-		 * otherwise ignore (because they have foreign system_ids).
+		 * This is a special case where taking the global lock is
+		 * helpful to detect changes to local VGs from other hosts.  VG
+		 * names, uuids and system_ids are the three things that other
+		 * hosts cache related to local VGs, so we use the VG namespace
+		 * change detection of the global lock to indicate that one of
+		 * these global VG properties has changed so other hosts will
+		 * update these cached values in VGs that they otherwise ignore
+		 * (because they have foreign system_ids).
 		 */
 		if (!lockd_gl(cmd, "ex", LDGL_UPDATE_NAMES))
 			return_ECMD_FAILED;
diff --git a/tools/vgcreate.c b/tools/vgcreate.c
index a3a9b6eea..1f5eb38ec 100644
--- a/tools/vgcreate.c
+++ b/tools/vgcreate.c
@@ -50,6 +50,10 @@ int vgcreate(struct cmd_context *cmd, int argc, char **argv)
 	if (!vgcreate_params_validate(cmd, &vp_new))
 	    return EINVALID_CMD_LINE;
 
+	/*
+	 * Needed to change the global VG namespace,
+	 * and to change the set of orphan PVs.
+	 */
 	if (!lockd_gl_create(cmd, "ex", vp_new.lock_type))
 		return ECMD_FAILED;
 
diff --git a/tools/vgextend.c b/tools/vgextend.c
index c7da8bc6c..581c21127 100644
--- a/tools/vgextend.c
+++ b/tools/vgextend.c
@@ -165,6 +165,7 @@ int vgextend(struct cmd_context *cmd, int argc, char **argv)
 	 */
 	cmd->handles_missing_pvs = 1;
 
+	/* Needed to change the set of orphan PVs. */
 	if (!lockd_gl(cmd, "ex", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/vgmerge.c b/tools/vgmerge.c
index e6e20278c..c5ac33299 100644
--- a/tools/vgmerge.c
+++ b/tools/vgmerge.c
@@ -201,6 +201,7 @@ int vgmerge(struct cmd_context *cmd, int argc, char **argv)
 		return EINVALID_CMD_LINE;
 	}
 
+	/* Needed change the global VG namespace. */
 	if (!lockd_gl(cmd, "ex", LDGL_UPDATE_NAMES))
 		return ECMD_FAILED;
 
diff --git a/tools/vgreduce.c b/tools/vgreduce.c
index 7ab2dca93..693f538ae 100644
--- a/tools/vgreduce.c
+++ b/tools/vgreduce.c
@@ -196,6 +196,7 @@ int vgreduce(struct cmd_context *cmd, int argc, char **argv)
 	init_ignore_suspended_devices(1);
 	cmd->handles_missing_pvs = 1;
 
+	/* Needed to change the set of orphan PVs. */
 	if (!lockd_gl(cmd, "ex", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/vgremove.c b/tools/vgremove.c
index e6df559a0..7c1f0ee4e 100644
--- a/tools/vgremove.c
+++ b/tools/vgremove.c
@@ -94,6 +94,10 @@ int vgremove(struct cmd_context *cmd, int argc, char **argv)
 		return EINVALID_CMD_LINE;
 	}
 
+	/*
+	 * Needed to change the global VG namespace,
+	 * and to change the set of orphan PVs.
+	 */
 	if (!lockd_gl(cmd, "ex", LDGL_UPDATE_NAMES))
 		return ECMD_FAILED;
 
diff --git a/tools/vgrename.c b/tools/vgrename.c
index 2cef1fc72..188061be6 100644
--- a/tools/vgrename.c
+++ b/tools/vgrename.c
@@ -219,6 +219,7 @@ int vgrename(struct cmd_context *cmd, int argc, char **argv)
 		return EINVALID_CMD_LINE;
 	}
 
+	/* Needed change the global VG namespace. */
 	if (!lockd_gl(cmd, "ex", LDGL_UPDATE_NAMES))
 		return_ECMD_FAILED;
 
diff --git a/tools/vgscan.c b/tools/vgscan.c
index c70a3f07e..b9e2f0f78 100644
--- a/tools/vgscan.c
+++ b/tools/vgscan.c
@@ -42,6 +42,7 @@ int vgscan(struct cmd_context *cmd, int argc, char **argv)
 		return ECMD_FAILED;
 	}
 
+	/* Needed for a current listing of the global VG namespace. */
 	if (!lockd_gl(cmd, "sh", 0))
 		return_ECMD_FAILED;
 
diff --git a/tools/vgsplit.c b/tools/vgsplit.c
index e04bf232b..7605bc4b0 100644
--- a/tools/vgsplit.c
+++ b/tools/vgsplit.c
@@ -499,6 +499,7 @@ int vgsplit(struct cmd_context *cmd, int argc, char **argv)
 		return ECMD_FAILED;
 	}
 
+	/* Needed change the global VG namespace. */
 	if (!lockd_gl(cmd, "ex", LDGL_UPDATE_NAMES))
 		return_ECMD_FAILED;