Merge pull request #641 from ceh/lock-docs

docs: describe child process handling on Windows for lock command

command/lock.go

@@ -43,12 +43,13 @@ Usage: consul lock [options] prefix child...
 
   Acquires a lock or semaphore at a given path, and invokes a child
   process when successful. The child process can assume the lock is
-  held while it executes. If the lock is lost or communication is disrupted
-  the child process will be sent a SIGTERM signal and given time to
-  gracefully exit. After the grace period expires the process will
-  be hard terminated.
-  On Windows agents, the process is always hard terminated, even on
-  the first attempt.
+  held while it executes. If the lock is lost or communication is
+  disrupted the child process will be sent a SIGTERM signal and given
+  time to gracefully exit. After the grace period expires the process
+  will be hard terminated.
+  For Consul agents on Windows, the child process is always hard 
+  terminated with a SIGKILL, since Windows has no POSIX compatible
+  notion for SIGTERM.
 
   When -n=1, only a single lock holder or leader exists providing
   mutual exclusion. Setting a higher value switches to a semaphore
@@ -288,7 +289,7 @@ func (c *LockCommand) startChild(script string, doneCh chan struct{}) error {
 // killChild is used to forcefully kill the child, first using SIGTERM
 // to allow for a graceful cleanup and then using SIGKILL for a hard
 // termination.
-// On Windows, the child is always hard terminated with SIGKILL, even
+// On Windows, the child is always hard terminated with a SIGKILL, even
 // on the first attempt.
 func (c *LockCommand) killChild(childDone chan struct{}) error {
 	// Get the child process

command/util_windows.go

@@ -8,7 +8,8 @@ import (
 )
 
 // signalPid sends a sig signal to the process with process id pid.
-// Interrupts et al is not implemented on Windows. Always send a SIGKILL.
+// Since interrupts et al is not implemented on Windows, signalPid
+// always sends a SIGKILL signal irrespective of the sig value.
 func signalPid(pid int, sig syscall.Signal) error {
 	p, err := os.FindProcess(pid)
 	if err != nil {

website/source/docs/commands/lock.html.markdown

@@ -13,9 +13,9 @@ Command: `consul lock`
 The `lock` command provides a mechanism for simple distributed locking.
 A lock (or semaphore) is created at a given prefix in the Key/Value store,
 and only when held, is a child process invoked. If the lock is lost or
-communication disrupted, the child process is terminated.A
+communication is disrupted, the child process is terminated.
 
-The number of lock holder is configurable with the `-n` flag. By default,
+The number of lock holders is configurable with the `-n` flag. By default,
 a single holder is allowed, and a lock is used for mutual exclusion. This
 uses the [leader election algorithm](/docs/guides/leader-election.html).
 
@@ -39,9 +39,11 @@ The only required options are the key prefix and the command to execute.
 The prefix must be writable. The child is invoked only when the lock is held,
 and the `CONSUL_LOCK_HELD` environment variable will be set to `true`.
 
-If the lock is lost, communication disrupted, or the parent process interrupted,
-the child process will receive a `SIGTERM`. After a grace period, a `SIGKILL`
-will be used to force termination.
+If the lock is lost, communication is disrupted, or the parent process
+interrupted, the child process will receive a `SIGTERM`. After a grace period,
+a `SIGKILL` will be used to force termination.  
+For Consul agents on Windows, the child process is always terminated with a
+`SIGKILL`, since Windows has no POSIX compatible notion for `SIGTERM`.
 
 The list of available flags are: