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

FreeBSD Manual Pages

  
 
  

home | help
Sys::RunAlone(3)      User Contributed Perl Documentation     Sys::RunAlone(3)

NAME
       Sys::RunAlone - make sure only one invocation of	a script is active at
       a time

SYNOPSIS
	use Sys::RunAlone;
	# code of which	there may only be on instance running on system

	use Sys::RunAlone silent => 1;
	# be silent if other running instance detected

	use Sys::RunAlone retry	=> 50;
	# retry	execution 50 times with	wait time of 1 second in between

	use Sys::RunAlone retry	=> '55,60';
	# retry	execution 55 times with	wait time of 60	seconds	in between

	use Sys::RunAlone 'silent';
	# obsolete form	of silent => 1

DESCRIPTION
       Provide a simple	way to make sure the script from which this module is
       loaded, is only running once on the server.  Optionally allow for
       retrying	execution until	the other instance of the script has finished.

VERSION
       This documentation describes version 0.12.

METHODS
       There are no methods.

THEORY OF OPERATION
       The functionality of this module	depends	on the availability of the
       DATA handle in the script from which this module	is called (more
       specifically: in	the "main" namespace).

       At INIT time, it	is checked whethere there is a DATA handle: if not, it
       exits with an error message on STDERR and an exit value of 2.

       If the DATA handle is available,	and it cannot be "flock"ed, it exits
       with an error message on	STDERR and an exit value of 1.	The error
       message will be surpressed when "silent =" 1> was specified in the
       "use" statement.	 This can be overridden	with the environment variable
       "SILENT_SYS_RUNALONE".

       If there	is a DATA handle, and it could be "flock"ed, execution
       continues without any further interference.

TRYING MORE THAN ONCE
       Optionally, it is possibly to specify a number of retries to be done if
       the first "flock" fails.	 This can be done by either specifying the
       retry value in the "use"	statement as e.g. "retry =" 55>, or with the
       environment variable "RETRY_SYS_RUNALONE".  There are two forms of the
       retry value:

       times
	    use	Sys::RunAlone retry => 55;  # retry 55 times, with 1 second intervals

	   Specify the number of times to retry, with 1	second intervals.

       times,seconds
	    use	Sys::RunAlone retry => '55,60';	# retry	55 times, with 60 second intervals

	   Specify both	the number of retries as well as the number of seconds
	   interval between tries.

       This is particularly useful for minutely	and hourly scripts that	run a
       long and	sometimes run into the next period.  Instead of	then not doing
       anything	for the	next period, it	will start processing again as soon as
       it is possible.	This makes the chance of catching up so	that the
       period after the	next period everything is in sync again.

OVERRIDING CHECK
       In some cases, the same script may need to be run simultaneously	with
       another incarnation (but	possibly with different	parameters).  In order
       to simplify this	type of	usage, it is possible to specify the
       environment variable "SKIP_SYS_RUNALONE"	with a true value.

	SKIP_SYS_RUNALONE=1 yourscript.pl

       will run	the script always.

	SKIP_SYS_RUNALONE=2 yourscript.pl

       will actually be	verbose	about this and say:

	Skipping Sys::RunAlone check for 'yourscript.pl'

REQUIRED MODULES
	Fcntl (any)

CAVEATS
   symlinks
       Execution of scripts that are (sym)linked to another script, will all
       be seen as execution of the same	script,	even though the	error message
       will only show the specified script name.  This could be	considered a
       bug or a	feature.

   changing a running script
       If you change the script	while it is running, the script	will
       effectively lose	its lock on the	file.  Causing any subsequent run of
       the same	script to be successful, causing two instances of the same
       script to run at	the same time (which is	what you wanted	to prevent by
       using Sys::RunAlone in the first	place).	 Therefore, make sure that no
       instances of the	script are running (and	won't be started by cronjobs
       while making changes) if	you really want	to be 100% sure	that only one
       instance	of the script is running at the	same time.

ACKNOWLEDGEMENTS
       Inspired	by Randal Schwartz's mention of	using the DATA handle as a
       semaphore on the	London PM mailing list.

       Booking.com for using this heavily in production	and allowing me	to
       improve this module.

SEE ALSO
       Sys::RunAlways.

AUTHOR
	Elizabeth Mattijsen

COPYRIGHT
       Copyright (c) 2005, 2006, 2008, 2009, 2011, 2012	Elizabeth Mattijsen
       <liz@dijkmat.nl>.  Copyright (c)	2017 Ben Tilly <btilly@gmail.com>.
       All rights reserved.  This program is free software; you	can
       redistribute it and/or modify it	under the same terms as	Perl itself.

perl v5.32.1			  2017-09-21		      Sys::RunAlone(3)

NAME | SYNOPSIS | DESCRIPTION | VERSION | METHODS | THEORY OF OPERATION | TRYING MORE THAN ONCE | OVERRIDING CHECK | REQUIRED MODULES | CAVEATS | ACKNOWLEDGEMENTS | SEE ALSO | AUTHOR | COPYRIGHT

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

home | help