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

VERSION
   This document describes version 0.004 of Sys::RunAlone::Flexible (from
   Perl distribution Sys-RunAlone-Flexible), released on 2019-09-03.

SYNOPSIS
   Use like you would use Sys::RunAlone:

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

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

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

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

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

   Use in run-time:

    require Sys::RunAlone::Flexible;
    Sys::RunAlone::Flexible->import(retry => "55,60");

    # then, somewhere in your program
    sub run {
        Sys::RunAlone::Flexible::lock();
    }

DESCRIPTION
   Sys::RunAlone::Flexible is a fork of Sys::RunAlone 0.13. 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::Flexible" at compile-time like
   you would normally use Sys::RunAlone, the lock() subroutine will still
   be invoked at INIT phase.

   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.

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).

   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.

   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 "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.

SYS::RUNALONE 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.

SYS::RUNALONE AUTHOR
    Elizabeth Mattijsen

SYS::RUNALONE COPYRIGHT
   Copyright (c) 2005, 2006, 2008, 2009, 2011, 2012 Elizabeth Mattijsen
   <[email protected]>. Copyright (c) 2017 Ben Tilly <[email protected]>.
   Copyright (c) 2019 Jim Bacon <[email protected]>. All rights reserved. This
   program is free software; you can redistribute it and/or modify it under
   the same terms as Perl itself.

FUNCTIONS
 lock
METHODS
   There are no methods.

HOMEPAGE
   Please visit the project's homepage at
   <https://metacpan.org/release/Sys-RunAlone-Flexible>.

SOURCE
   Source repository is at
   <https://github.com/perlancar/perl-Sys-RunAlone-Flexible>.

BUGS
   Please report any bugs or feature requests on the bugtracker website
   <https://rt.cpan.org/Public/Dist/Display.html?Name=Sys-RunAlone-Flexible
   >

   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.

SEE ALSO
   Sys::RunAlone.

AUTHOR
   perlancar <[email protected]>

COPYRIGHT AND LICENSE
   This software is copyright (c) 2019 by [email protected].

   This is free software; you can redistribute it and/or modify it under
   the same terms as the Perl 5 programming language system itself.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.