lockerd
lockersh
pidstat
pidstatd
pidwatch
uriexec
IPC::Locker
IPC::Locker::Server
IPC::PidStat
IPC::PidStat::PidServer

lockerd

NAME

lockerd - Distributed lock handler for Perl IPC::Locker

SYNOPSIS

lockerd [ --help ] [ --port=port ] [ --path=fifo_path ] [ --version ]

DESCRIPTION

Lockerd will start a daemon to watch for and service connects by the Perl IPC::Locker package.

ARGUMENTS

--help: Displays this message and program version and exits.
--nofork: Keep the daemon in the foreground for debugging.
--port: Specifies the port number to be used.
--path: Specifies that UNIX FIFO will be used for communications with clients and the path to the FIFO.
--version: Displays program version and exits.

PERFORMANCE

Lockerd has tested to perform well handling above 3,000 lock or unlock requests per second on a 2GHz AMD Operton server.

DISTRIBUTION

The latest version is available from CPAN and from http://www.veripool.org/.

Copyright 1999-2012 by Wilson Snyder. This package is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License Version 3 or the Perl Artistic License Version 2.0.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>

lockersh

NAME

lockersh - Run a command under a global lock

SYNOPSIS

  lockersh [--dhost <host> --port <port>] --lock <name> [args....]

DESCRIPTION

Obtain a global IPC::Locker lock with the passed name.

When the lock is granted, run the arguments as a command in the foreground. When the foreground process exits, release the lock, and return the executed command's exit status.

This makes it very easy to insure only one copy of a program executes across a clump:

   lockersh --lock one_sleep_runs sleep 10

ARGUMENTS

--dhost host: Hostname of lockerd server. Defaults to IPCLOCKER_HOST environment variable.
--help: Displays this message and program version and exits.
--lock lockname: Name for the lock. This argument may be passed multiple times or with a colon separator to allow one of multiple possible locks to be selected.
--locklist: Suppress normal operation, and instead print a list of all outstanding locks and their owners.
--port port: Port of pidstatd server on remote host. Defaults IPCLOCKER_PORT environment variable.
--timeout: Set number of seconds before wait for license will timeout. Defaults to wait forever.
--verbose: Print 'waiting for lock' and similar messages.
--version: Displays program version and exits.

ENVIRONMENT

IPCLOCKER_HOST: Hostname of lockerd server, or colon separated list including backup servers. Defaults to localhost.
IPCLOCKER_PORT: Port number of lockerd server. Defaults to 1751.

pidstat

NAME

pidstat - Check the existence of a process on a remote machine

SYNOPSIS

pidstat [ --help ] [ --host=host ] [ --port=port ] [ --silent ] [ --version ] [ --debug ] [ exists remotepids ]

DESCRIPTION

Pidstat will contact the PID stat daemon (pidstatd, in the IPC::Locker distribution on CPAN) and perform the requested command(s).

COMMANDS

exists remotepids

Check the existence of a set of process IDs (potentially) on remote hosts.

Takes a list of remote process IDs. These process IDs are understood to be on the host specified by "--host" (default is "localhost"). Alternatively, the host may be overridden by specifying the process IDs in the form <hostname>:<pid>.

The exit value is 0 if all the requested process IDs exist. The exit value is 1 if any of the requested process IDs did not exist, or 2 if any hosts did not have a running daemon. This is roughly the same as "kill -0 <pid>".

The following works well for shell scripts.

 if pidstat exists 3459 host1:4220 host2:9821
 then
    print "All processes are up"
 else
    print "One of the processes is down"
 fi

ARGUMENTS

--help: Displays this message and program version and exits.
--host: Specifies host name to check for a process.
--port: Specifies the port number to contact the "pidstatd" on. (default 1752)
--silent: Do not print out a line per process checked.
--debug: Turns on the debug flag for diagnostic output.
--version: Displays program version and exits.

pidstatd

NAME

pidstatd - Determine if process ID is running for Perl IPC::Locker

SYNOPSIS

pidstatd [ --help ] [ --port=port ] [ --version ]

DESCRIPTION

Pidstatd will start a UDP daemon. The daemon responds to requests that contain a PID with a packet indicating the PID and if the PID currently exists.

The Perl IPC::Locker package optionally uses this daemon to break locks for PIDs that no longer exists.

ARGUMENTS

--help: Displays this message and program version and exits.
--nofork: For debugging, prevents the daemon from creating additional processes and from going into the background. This allows messages to appear on stdout, and ctrl-C to stop the daemon.
--port: Specifies the port number to be used.
--version: Displays program version and exits.

PERFORMANCE

As pidstatd is a UDP daemon, some requests may be dropped by the operating system, but this assists in graceful degradation under heavy loads. Pidstatd has been tested to perform well handling to above 13,000 requests per second on a 2GHz AMD Operton server.

pidwatch

NAME

pidwatch - Run a command and if another PID exits, kill the command

SYNOPSIS

  pidwatch [--cd I<cd>] --host <host> --pid <pid>  args[....]
  pidwatch [--cd I<cd>] --host <host> --pid <pid> --foreground <pid>

DESCRIPTION

Chdir to the specified directory, if specified and possible, then run the arguments as a command in the foreground. When the foreground process exits, return its exit status. This is basically the same as running the command directly.

In the background, watch the specified pid on the specified host. If pidstatd is running on the specified host, and the specified pid goes away, kill the foreground command.

Alternatively pass the PID of any process with --foreground. When the foreground process exits, the background job exits; if the specified watched PID exits, the foreground pid is killed.

Common usage is to kill remote rsh children when a parent is kill -9ed. An example Perl application would invoke:

    system("rsh \$remote_host pidwatch"
           ." --cd \$ENV{PWD} --host \$ENV{HOST} --pid \$\$"
           ."\$remote_command...");

Another usage is as a "barrier" to start the new step in a script when another process completes. Just use a sleep with a appropriate timeout value:

    pidwatch --host HOST --pid PID sleep 9999999
    echo PID has completed, do whatever is next

ARGUMENTS

<parameters>: All non switch arguments after the switches are passed to /bin/sh as a -c argument. Thus passing "a && b" to pidwatch will result in pidwatch executing "/bin/sh -c 'a && b'".
--cd dir: Directory to chdir to.
--help: Displays this message and program version and exits.
--host host: Hostname to check for specified pid on. pidstatd must be running on that host to have this program be useful.
--killer program: Program to use instead of kill when it's time to terminate the pid. Will be passed arguments as if it was /bin/kill (program signame pid).
--foreground pid: Process ID to be killed when watched process exits. Used to watch a preexisting PID, instead of launching commands under a shell.
--pid pid: Process ID to watch. When this pid exits, the program will kill the foreground process.
--port port: Port of pidstatd server on remote host.
--signal signame: Signal number/name to send to process on remote PIDs death. Defaults to -HUP.
--version: Displays program version and exits.

uriexec

NAME

uriexec - Decode and execute the given URI-encoded command

SYNOPSIS

  uriexec [--cd I<cd>] echo %24HOME

DESCRIPTION

Run the specified command (optionally from the specified directory). Each URL-encoded character (%xx) is translated prior to executing the command with exec().

Uriexec solves the classic problem of having to figure out how to quote shell metacharacters to pass commands across multiple shells and ssh processes. Simply call "uriexec" on a string created with URI::Escape::uri_escape, and it will end up executing on the final machine with proper quoting.

ARGUMENTS

--cd dir: Directory to cd to before the exec of the given command, URI-encoded.
--shell shell: Name of the shell and additional parameters to prefix, URI-encoded. Defaults to "/bin/sh -c".
--show: Instead of executing the command, print the decoding of the command to aid in user debug. This also supports decoding nested uriexec calls, however they are not always perfect so the output from this option is only for users, not scripts.
--version: Displays program version and exits.

IPC::Locker

NAME

IPC::Locker - Distributed lock handler

SYNOPSIS

  use IPC::Locker;

  my $lock = IPC::Locker->lock(lock=>'one_per_machine',
                               host=>'example.std.com',
                               port=>223);

  if ($lock->lock()) { something; }
  if ($lock->locked()) { something; }

  $lock->unlock();

DESCRIPTION

IPC::Locker will query a remote lockerd server to obtain a lock around a critical section. When the critical section completes, the lock may be returned.

This is useful for distributed utilities which run on many machines, and cannot use file locks or other such mechanisms due to NFS or lack of common file systems.

Multiple locks may be requested, in which case the first lock to be free will be used. Lock requests are serviced in a first-in-first-out order, and the locker can optionally free locks for any processes that cease to exist.

new ([parameter=>value ...]);: Create a lock structure.
lock ([parameter=>value ...]);: Try to obtain the lock, return the lock object if successful, else undef.
locked (): Return true if the lock has been obtained.
lock_name (): Return the name of the lock.
unlock (): Remove the given lock. This will be called automatically when the object is destroyed.
ping (): A simplified version of ping_status; polls the server to see if it is up. Returns true if up, otherwise undef.
ping_status (): Polls the server to see if it is up. Returns hash reference with {ok} indicating if up, and {status} with status information. If called without an object, defaults to call new() with connect_tries=>1, under the assumption that a quick go/nogo response is desired.
break_lock (): Remove current locker for the given lock.
owner ([parameter=>value ...]);: Returns a string of who has the lock or undef if not currently locked. Note that this information is not atomic, and may change asynchronously; do not use this to tell if the lock will be available, to do that, try to obtain the lock and then release it if you got it.

PARAMETERS

block: Boolean flag, true indicates wait for the lock when calling lock() and die if an error occurs. False indicates to just return false. Defaults to true.
connect_tries: If none of the lockerd hosts are available or other network errors are encountered, perform this number of retries, with a random connect_delay to connect_delay*2 interval between them before signalling an error.
connect_delay: The minimum seconds to wait between each of the connect_tries, and one-half of the maximum random wait. Defaults to 30 seconds.
destroy_unlock: Boolean flag, true indicates destruction of the lock variable should unlock the lock, only if the current process id matches the pid passed to the constructor. Set to false if destruction should not close the lock, such as when other children destroying the lock variable should not unlock the lock.
family: The family of transport to use, either INET or UNIX. Defaults to INET.
host: The name of the host containing the lock server. It may also be an array of hostnames, where if the first one is down, subsequent ones will be tried. Defaults to value of IPCLOCKER_HOST or localhost.
port: The port number (INET) or name (UNIX) of the lock server. Defaults to IPCLOCKER_PORT environment variable, else 'lockerd' looked up via /etc/services, else 1751.
lock: The name of the lock. This may also be a reference to an array of lock names, and the first free lock will be returned.
lock_list: Return a list of lock and lock owner pairs. (You can assign this to a hash for easier parsing.)
pid: The process ID that owns the lock, defaults to the current process id.
print_broke: A function to print a message when the lock is broken. The only argument is self. Defaults to print a message if verbose is set.
print_down: A function to print a message when the lock server is unavailable. The first argument is self. Defaults to a croak message.
print_obtained: A function to print a message when the lock is obtained after a delay. The only argument is self. Defaults to print a message if verbose is set.
print_retry: A function to print a message when the lock server is unavailable, and is about to be retried. The first argument is self. Defaults to a print message.
print_waiting: A function to print a message when the lock is busy and needs to be waited for. The first argument is self, second the name of the lock. Defaults to print a message if verbose is set.
timeout: The maximum time in seconds that the lock may be held before being forced open, passed to the server when the lock is created. Thus if the requester dies, the lock will be released after that amount of time. Zero disables the timeout. Defaults to 30 minutes.
user: Name to request the lock under, defaults to host_pid_user
autounlock: True to cause the server to automatically timeout a lock if the locking process has died. For the process to be detected, it must be on the same host as either the locker client (the host making the lock call), or the locker server. Defaults false.
verbose: True to print messages when waiting for locks. Defaults false.

ENVIRONMENT

IPCLOCKER_HOST: Hostname of lockerd server, or colon separated list including backup servers. Defaults to localhost.
IPCLOCKER_PORT: The port number (INET) or name (UNIX) of the lock server. Defaults to 'lockerd' looked up via /etc/services, else 1751.

IPC::Locker::Server

NAME

IPC::Locker::Server - Distributed lock handler server

SYNOPSIS

  use IPC::Locker::Server;

  IPC::Locker::Server->new(port=>1234)->start_server;

  # Or more typically via the command line
  lockerd

DESCRIPTION

IPC::Locker::Server provides the server for the IPC::Locker package.

new ([parameter=>value ...]);: Creates a server object.
start_server ([parameter=>value ...]);: Starts the server. Does not return.

PARAMETERS

family: The family of transport to use, either INET or UNIX. Defaults to INET.
port: The port number (INET) or name (UNIX) of the lock server. Defaults to 'lockerd' looked up via /etc/services, else 1751.

IPC::PidStat

NAME

IPC::PidStat - Process ID existence test

SYNOPSIS

  use IPC::PidStat;

  my $exister = new IPC::PidStat(
    port=>1234,
    );
  $exister->pid_request(host=>'foo', pid=>$pid)
  while (1) {  # Poll receiving callbacks
     my ($epid, $eexists, $ehostname) = $exister->recv_stat();
     print "Pid $epid ",($eexists?'exists':'dead'),"\n" if $ehostname;
  }

DESCRIPTION

IPC::PidStat allows remote requests to be made to the pidstatd, to determine if a PID is running on the daemon's machine.

PidStat uses UDP, and as such results are fast but may be unreliable. Furthermore, the pidstatd may not even be running on the remote machine, so responses should never be required before an application program makes progress.

METHODS

new ([parameter=>value ...]);

Creates a new object for later use. See the PARAMETERS section.

pid_request (host=>$host, pid=>$pid);

Sends a request to the specified host's server to see if the specified PID exists.

The optional parameters return_exist=>0, return_doesnt=>0 and return_unknown=>0 improve performance by suppressing return messages if the specified pid exists, doesn't exist, or has unknown state respectively. Pidstatd versions before 1.480 ignore this flag, so the return code from recv_stat should not assume the undesired return types will be suppressed.

pid_request_recv (host=>$host, pid=>$pid);

Calls pid_request and returns the recv_stat reply. If the response fails to return in one second, it is retried up to 5 times, then undef is returned.

recv_stat()

Blocks waiting for any return from the server. Returns undef if none is found, or a 2 element array with the PID and existence flag. Generally this would be called inside a IO::Poll loop.

STATIC METHODS

local_pid_doesnt_exist(<pid>): Static call, not a method call. Return 0 if a pid exists, 1 if not. Return undef if it can't be determined.
local_pid_exists(<pid>): Static call, not a method call. Return 1 if a pid exists, 0 if not. Return undef if it can't be determined.

PARAMETERS

port: The port number (INET) of the pidstatd server. Defaults to 'pidstatd' looked up via /etc/services, else 1752.

IPC::PidStat::PidServer

NAME

IPC::PidStat::PidServer - Process ID existence server

SYNOPSIS

  use IPC::PidStat::PidServer;

  IPC::PidStat::PidServer->new(port=>1234)->start_server;

  # Or more typically via the command line
  pidstatd

DESCRIPTION

IPC::PidStat::PidServer responds to UDP requests that contain a PID with a packet indicating the PID and if the PID currently exists.

The Perl IPC::Locker package optionally uses this daemon to break locks for PIDs that no longer exists.

new ([parameter=>value ...]);: Creates a server object.
start_server ([parameter=>value ...]);: Starts the server. Does not return.

PARAMETERS

port: The port number (INET) or name (UNIX) of the lock server. Defaults to 'pidstatd' looked up via /etc/services, else 1752.

IPC::Locker

Wiki

lockerd

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

PERFORMANCE

DISTRIBUTION

AUTHORS

SEE ALSO

lockersh

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

ENVIRONMENT

SEE ALSO

pidstat

NAME

SYNOPSIS

DESCRIPTION

COMMANDS

ARGUMENTS

SEE ALSO

pidstatd

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

PERFORMANCE

SEE ALSO

pidwatch

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

SEE ALSO

uriexec

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

SEE ALSO

IPC::Locker

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

ENVIRONMENT

SEE ALSO

IPC::Locker::Server

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

SEE ALSO

IPC::PidStat

NAME

SYNOPSIS

DESCRIPTION

METHODS

STATIC METHODS

PARAMETERS

SEE ALSO

IPC::PidStat::PidServer

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

SEE ALSO