Sys::RunAlone::Flexible2 - Make sure only one invocation of a script is active at a time
This document describes version 0.001 of Sys::RunAlone::Flexible2 (from Perl distribution Sys-RunAlone-Flexible2), released on 2019-09-03.
Use like you would use Sys::RunAlone:
use Sys::RunAlone::Flexible2; # code of which there may only be on instance running on system use Sys::RunAlone::Flexible2 silent => 1; # be silent if other running instance detected use Sys::RunAlone::Flexible2 retry => 50; # retry execution 50 times with wait time of 1 second in between use Sys::RunAlone::Flexible2 retry => '55,60'; # retry execution 55 times with wait time of 60 seconds in between use Sys::RunAlone::Flexible2 'silent'; # obsolete form of silent => 1
Use in run-time:
require Sys::RunAlone::Flexible2; Sys::RunAlone::Flexible2->import(retry => "55,60"); # then, somewhere in your program sub run { Sys::RunAlone::Flexible2::lock(); }
Sys::RunAlone::Flexible2 is a fork of Sys::RunAlone 0.13. It's also a temporary version for Sys::RunAlone::Flexible. It's just like Sys::RunAlone but it can be used at run-time too. The main logic is moved from INIT block to the lock subroutine which you can invoke at run-time. But, if you "use Sys::RunAlone::Flexible2" at compile-time like you would normally use Sys::RunAlone, the lock() subroutine will still be invoked at INIT phase.
Aside from that, when script does not contain __DATA__ or __END__, S:R:F2 opens a filehandle to the script (which is basically the same thing as DATA). Or, if you happen to use this module in a one-liner, S:R:F2 will open a filehandle to this module. So you don't have to put __DATA__ in your script.
The rest of the documentation is Sys::RunAlone's.
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.
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).
DATA
NOTE: the __END__ tag is always found in the main package namespace. However, the __DATA__ tag is always found in the namespace declared by the script. This might very well be different when writing a modulino.
__END__
main
__DATA__
At compile/INIT time (or when you run "lock"), it is checked when 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 flocked, 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.
flock
silent =
use
SILENT_SYS_RUNALONE
If there is a DATA handle, and it could be flocked, execution continues without any further interference.
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:
retry =
RETRY_SYS_RUNALONE
use Sys::RunAlone retry => 55; # retry 55 times, with 1 second intervals
Specify the number of times to retry, with 1 second intervals.
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.
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
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'
Fcntl (any)
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.
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.
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.
Elizabeth Mattijsen
Copyright (c) 2005, 2006, 2008, 2009, 2011, 2012 Elizabeth Mattijsen <liz@dijkmat.nl>. Copyright (c) 2017 Ben Tilly <btilly@gmail.com>. Copyright (c) 2019 Jim Bacon <boftx@cpan.org>. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
There are no methods.
Please visit the project's homepage at https://metacpan.org/release/Sys-RunAlone-Flexible2.
Source repository is at https://github.com/perlancar/perl-Sys-RunAlone-Flexible2.
Please report any bugs or feature requests on the bugtracker website https://rt.cpan.org/Public/Dist/Display.html?Name=Sys-RunAlone-Flexible2
When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.
Sys::RunAlone.
perlancar <perlancar@cpan.org>
This software is copyright (c) 2019 by perlancar@cpan.org.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.
To install Sys::RunAlone::Flexible2, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Sys::RunAlone::Flexible2
CPAN shell
perl -MCPAN -e shell install Sys::RunAlone::Flexible2
For more information on module installation, please visit the detailed CPAN module installation guide.