1package Sys::RunAlways;
2
3# version info
4$VERSION= '0.06';
5
6# be as strict and verbose as possible
7use strict;
8use warnings;
9
10# make sure we know how to lock
11use Fcntl ':flock';
12
13# process local storage
14my $silent;
15
16# satisfy -require-
171;
18
19#-------------------------------------------------------------------------------
20#
21# Standard Perl functionality
22#
23#-------------------------------------------------------------------------------
24# import
25#
26#  IN: 1 class (not used)
27#      2 .. N options (default: none)
28
29sub import {
30    my ( undef, %args )= @_;
31
32    # obtain parameters
33    $silent= delete $args{silent};
34
35    # sanity check
36    if ( my @huh= sort keys %args ) {
37        die "Don't know what to do with: @huh";
38    }
39
40    return;
41} #import
42
43#-------------------------------------------------------------------------------
44
45INIT {
46    # no warnings here
47    no warnings;
48
49    # no data handle, we're screwed
50    print( STDERR "Add __END__ to end of script '$0' to be able use the features of Sys::RunAlways\n" ),exit 2
51     if tell( *main::DATA ) == -1;
52
53    # we're still running
54    exit 0 if !flock main::DATA,LOCK_EX | LOCK_NB;
55
56    # tell the world if necessary
57    printf STDERR "'%s' has been started at %s\n", $0, scalar time
58      if !$silent;
59} #INIT
60
61#-------------------------------------------------------------------------------
62
63__END__
64
65=head1 NAME
66
67Sys::RunAlways - make sure there is always one invocation of a script active
68
69=head1 SYNOPSIS
70
71 use Sys::RunAlways;
72 # code of which there must always be on instance running on system
73
74 use Sys::RunAlways silent => 1;  # don't tell the world we're starting
75 # code of which there must always be on instance running on system
76
77=head1 DESCRIPTION
78
79Provide a simple way to make sure the script from which this module is
80loaded, is always running on the server.
81
82=head1 VERSION
83
84This documentation describes version 0.06.
85
86=head1 METHODS
87
88There are no methods.
89
90=head1 THEORY OF OPERATION
91
92The functionality of this module depends on the availability of the DATA
93handle in the script from which this module is called (more specifically:
94in the "main" namespace).
95
96At INIT time, it is checked whethere there is a DATA handle: if not, it
97exits with an error message on STDERR and an exit value of 2.
98
99If the DATA handle is available, and it cannot be C<flock>ed, it exits
100silently with an exit value of 0.
101
102If there is a DATA handle, and it could be C<flock>ed, a message is put on
103STDERR and execution continues without any further interference.  Optionally,
104the message on STDERR can be prevented by specifying the "silent" parameter
105in the C<use> statement with a true value, like:
106
107  use Sys::RunAlways silent => 1;
108
109=head1 REQUIRED MODULES
110
111 Fcntl (any)
112
113=head1 CAVEATS
114
115=head2 symlinks
116
117Execution of scripts that are (sym)linked to another script, will all be seen
118as execution of the same script, even though the error message will only show
119the specified script name.  This could be considered a bug or a feature.
120
121=head2 changing a running script
122
123If you change the script while it is running, the script will effectively
124lose its lock on the file.  Causing any subsequent run of the same script
125to be successful, causing two instances of the same script to run at the
126same time (which is what you wanted to prevent by using Sys::RunAlone in
127the first place).  Therefore, make sure that no instances of the script are
128running (and won't be started by cronjobs while making changes) if you really
129want to be 100% sure that only one instance of the script is running at the
130same time.
131
132=head1 ACKNOWLEDGEMENTS
133
134Inspired by Randal Schwartz's mention of using the DATA handle as a semaphore
135on the London PM mailing list.
136
137=head1 SEE ALSO
138
139L<Sys::RunAlone>.
140
141=head1 AUTHOR
142
143 Elizabeth Mattijsen
144
145maintained by LNATION, <thisusedtobeanemail@gmail.com>
146
147=head1 COPYRIGHT
148
149Copyright (c) 2005, 2006, 2012 Elizabeth Mattijsen <liz@dijkmat.nl>. All rights
150reserved.  This program is free software; you can redistribute it and/or
151modify it under the same terms as Perl itself.
152
153=cut
154