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.
DISTRIBUTION
The latest version is available from CPAN and from http://www.veripool.org/.
Copyright 1999-2017 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>