Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
IPC::Locker(3)	      User Contributed Perl Documentation	IPC::Locker(3)

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>

SEE ALSO
       lockerd,	IPC::Locker::Server

       IPC::PidStat, pidstat, pidstatd,	pidwatch

perl v5.24.1			  2017-04-26			IPC::Locker(3)

NAME | SYNOPSIS | DESCRIPTION | PARAMETERS | ENVIRONMENT | DISTRIBUTION | AUTHORS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=IPC::Locker&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help