From 2a80aacb861b68c7e13dfbe126a8ce31d0c4b592 Mon Sep 17 00:00:00 2001 From: Emil Hessman Date: Sun, 25 Jan 2015 11:42:26 +0100 Subject: [PATCH] docs: describe child process handling on Windows for lock command Add website documentation for how the lock command handles child process termination on Windows. --- command/lock.go | 15 ++++++++------- command/util_windows.go | 3 ++- website/source/docs/commands/lock.html.markdown | 12 +++++++----- 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/command/lock.go b/command/lock.go index a6ae7c34f..51b5e2d16 100644 --- a/command/lock.go +++ b/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 diff --git a/command/util_windows.go b/command/util_windows.go index ecdea4e02..6a26306c4 100644 --- a/command/util_windows.go +++ b/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 { diff --git a/website/source/docs/commands/lock.html.markdown b/website/source/docs/commands/lock.html.markdown index d30e15f69..9e341cc42 100644 --- a/website/source/docs/commands/lock.html.markdown +++ b/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: