#!/usr/bin/env perl
# @(#)$Id: munchies_lock 1300 2012-04-03 19:45:20Z pjf $

use strict;
use warnings;

use English qw(-no_match_vars);
use File::Spec::Functions;
use FindBin qw( $Bin );

BEGIN {
   my $path = catfile( $Bin, q(munchies_localenv) );

   do $path or die $EVAL_ERROR || "Path $path not done\n";
}

use version; our $VERSION = qv( sprintf '0.6.%d', q$Rev: 1300 $ =~ /\d+/gmx );

use App::Munchies::CLI;

my $prog = App::Munchies::CLI->new( appclass => q(App::Munchies),
                                    arglist  => q(k=s p=s t=s) );

$prog->method( q(lock_).$prog->method ); $prog->quiet( 1 );

exit $prog->run;

__END__

=pod

=head1 NAME

munchies_lock - Provide set/reset locking semantics

=head1 SYNOPSIS

=over 3

=item B<munchies_lock> B<-c list>

List the contents of the lock table

=item B<munchies_lock> B<-c reset> B<-k> I<key>

Reset the lock for key

=item B<munchies_lock> B<-c set> B<-k> I<key> B<-p> I<pid> [B<-t> I<timeout>]

Set the lock for key. Caller must provide it's PID. Timeout defaults to five
minutes

=item B<munchies_lock> B<-H>|B<-h>

Display man page/usage string

=back

=head1 VERSION

0.6.$Rev: 1300 $

=head1 DESCRIPTION

This program exposes the subroutines in the IPC::SRLock module

Use one of three mechanisms to provide set/reset locking semantics. On Unix
systems where the SysV IPC works use semaphores and shared memory. On Cygwin
use flock(3m). There is also an implementation using I<libmemcached>

Perl's portable flock(3m) mechanism to single thread access to the
lock table. The lock table is a text file in XML format. Successful
lock setting results in a line entry being written to the lock
table. Other processes wishing to set the lock will suspend until the
lock is released or times out. When released or timed out the line
entry is removed from the lock table. The I<key> can be any string (no
commas), the I<pid> should be the PID of the lock setting process,
i.e. ${$} in Shell. The timeout defaults to five minutes.

=head1 REQUIRED ARGUMENTS

=over 3

=item B<-c> I<subroutine>

One of list, reset, or set

=back

=head1 OPTIONS

=over 3

=item B<-D>

Turn debugging on

=item B<-n>

Do not prompt for debugging

=back

=head1 DIAGNOSTICS

Prints errors to stderr

=head1 EXIT STATUS

Returns zero on success, non zero on failure

=head1 CONFIGURATION

Uses the constructor's I<appclass> attribute to locate a configuration file

Locking mechanisms are selected in the OS dependant configuration
file. Setting lock_type in the global config to ipc selects the SysV
IPC method.

=over 3

=item F<var/tmp/ipc_srlock.lck>

The one true lock file

=item F<var/tmp/ipc_srlock.shm>

The lock table

=back

=head1 INCOMPATIBILITIES

None

=head1 DEPENDENCIES

=over 3

=item L<App::Munchies::CLI>

=back

=head1 BUGS AND LIMITATIONS

Send reports to Support at RoxSoft.co.uk

=head1 AUTHOR

Peter Flanigan

=head1 LICENSE AND COPYRIGHT

Copyright (c) 2012 Peter Flanigan

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

=cut

# Local Variables:
# mode: perl
# tab-width: 3
# End:
