package Semfile;

use strict;
use FileHandle;
use Carp;
 
# copied (and documented) by Dave Graff from 
# The Perl Journal, issue #23 (Vol.6 No.1):
# "Resource Locking with Semaphore Files"
# by Sean M. Burke.
# (removed obsolete url for that article -- see update below)

# Create and manage semaphore files, which will guarantee that
# simultaneous processes competing for a single resource do not
# collide when using that resource.

# The semaphore (locked) file has no content -- it is simply the
# thing to check, and lock if it's available, before using/altering
# the actual shared resource.

sub new {
    my $class = shift(@_);
    my $filespec = shift(@_) or Carp::croak("What filespec?");

    my $fh = new FileHandle;
    $fh->open( ">$filespec" )
        or Carp::croak("Can't open semaphore file $filespec: $!");
    chmod 0664, $filespec;      # make it ug+rw
    use Fcntl 'LOCK_EX';
    flock $fh, LOCK_EX;
    return bless {'fh' => $fh}, ref($class) || $class;
}

sub release {
    undef $_[0]{'fh'};
}
1; # End of module

##</code><code>##

use Semfile;
...
# All instances of this process (and any other perl process that 
# uses the same shared resource) will use the same semaphore file:

my $lock = Semfile->new( "my_semafore.filename" );

# When that call returns, I have the lock; I'll hold it
# till I finish doing sensitive tasks, like:
#  - read the shared resource
#  - alter and save the value of that resource
#  - confirm that I haven't botched it
# then:

$lock->release;