view release on metacpan or  search on metacpan

lib/BrLock.pm  view on Meta::CPAN

#!/usr/bin/perl -w
#!/usr/local/bin/perl -w

package BrLock; 

=head1 NAME 

BrLock - Distributed Lock with minimal messages exchanges 
over a reliable network. 

=head1 SYNOPSIS

 BrLock->new('cfg_file', # configuration file, (see DESCRIPTION).
            '127.0.0.1', # this node's ip.
  	    3001);       # port to be bound to this node.

 BrLock->br_lock(); 
 # enter critical region
 BrLock->br_unlock(); 

=head1 DESCRIPTION

BrLock features a distributed lock, using the algorithm
Carvalho and Roucariol, On mutual exclusion in computer networks,
ACM Communications, Feb83.

The algorithm features minimal messages for acquiring the next lock,
but with the trade-off of network being reliable enough to ensure that
all nodes are alive. In fact, one node won't be able to acquire the
next lock if it can't communicate to all other nodes (unless the node
which was the last one to acquire the lock).

If this is a hard constraint for you, you may want to use IPC::Lock.

The list containing all nodes that may apply for this lock must be
described in the configuration file passed as parameters to the 
environment builder (see SYNOPSIS). The file must be as this:

 0 0
 0.0.0.0 0
 x.x.x.x  port
 y.y.y.y  port
 ...

The first line must have two zeros, and the second  must have the 
0.0.0.0 ip and the 0 port (deprecated parameters, see TODO). The 
next lines must have a node ip and a node port. All nodes must use
the same configuration file, so a node will read its own 
parameters. 

A valid cfg_file for BrLock->new('cfg_file', '127.0.0.1', 3001), 
for an environment with 3 nodes, is: 
 0 0
 0.0.0.0 0
 127.0.0.1 3002
 127.0.0.1 3001
 127.0.0.1 3003

Note the networking setup will be made by this module. So, after
calling Br->new, the node will be listening at 127.0.0.1:3001 in
the above example. 


=head1 TODO

=over

=item * Accept entire configuration as parameters thus not requiring 
a configuration file. 

=item * Switch to PerlOO, so multiple locks can be used at once. 

=back

=head1 AUTHORS

Ribamar Santarosa <ribamar@gmail.com>

Tarcisio Genaro <cuervojonas@gmail.com>

=head1 SEE ALSO

<IPC::Lock>

=cut