NAME

Lock::Socket - application lock/mutex module based on sockets

VERSION

0.0.2 (2014-09-13) development release.

SYNOPSIS

### Function API
use Lock::Socket qw/lock_socket try_lock_socket/;

# Raises exception if cannot lock
my $lock = lock_socket(15151);

# Or just return undef
my $lock2 = try_lock_socket(15151) or
    die "handle your own error";


### Object API
use Lock::Socket;

# Create a socket
my $sock = Lock::Socket->new(port => 15151);

# Lock or raise an exception
$sock->lock;

# Can check its status in case you forgot
my $status = $sock->is_locked; # 1 (or 0)

# Re-locking changes nothing
$sock->lock;

# New lock on same port fails
my $sock2 = Lock::Socket->new(port => 15151);
eval { $sock2->lock }; # exception

# But trying to get a lock is ok
my $status = $sock2->try_lock;       # 0
my $same_status = $sock2->is_locked; # 0

# If you need the underlying filehandle
my $fh = $sock->fh;

# You can manually unlock
$sock->unlock;
# ... or unlocking is automatic on scope exit
undef $sock;

DESCRIPTION

Lock::Socket provides cooperative inter-process locking for applications that need to ensure that only one process is running at a time. This module works by binding to a socket on a loopback (127/8) address/port combination, which the operating system conveniently restricts to a single process.

Both lock_socket and try_lock_socket take a mandatory port number and an optional IP address as arguments, and return a Lock::Socket object. Objects are instantiated manually as follows:

Lock::Socket->new(
    port => $PORT, # required
    addr => $ADDR, # defaults to 127.X.Y.1
);

On most systems the port number needs to be greater than 1024 unless you are running as root. If addr is not given then it is calculated as follows, which provides automatic per-user namespacing up to a maximum user ID of 65536:

Octet   Value
------  ------------------------------
1       127
2       First byte of user ID
3       Second byte of user ID
4       1

The calculated address can be read back from $sock->addr. If you want a system-wide namespace you can manually specify the address as well as the required port number.

As soon as the Lock::Socket object goes out of scope the port is closed and the lock can be obtained by someone else.

If you want to keep holding onto a lock socket after a call to exec (perhaps after forking) read about the $^F variable in perlvar, as you will probably have to set it to ensure the socket is not closed:

use List::Util qw/max/;
$^F = max($^F, $sock->fh->fileno);

SEE ALSO

There are many other locking modules available on CPAN, but most of them use some kind of file or flock-based locking.

BUGS

At the moment all of the tests fail on FreeBSD systems. Anyone with a clue or a box to test with please get in touch.

AUTHOR

Mark Lawrence <nomad@null.net>. This module was inspired by the solo.pl script by Andres Erbsen.

COPYRIGHT AND LICENSE

Copyright (C) 2014 Mark Lawrence <nomad@null.net>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.