NAME

Cache::Memcached::Semaphore - a simple pure-perl library for cross-machine semaphores using memcached.

SYNOPSIS

        use Cache::Memcached;
        use Cache::Memcached::Semaphore;
        
        my $memd = new Cache::Memcached {
                'servers' => [ "10.0.0.15:11211", "10.0.0.15:11212",
                                                "10.0.0.17:11211", [ "10.0.0.17:11211", 3 ] ],
        };
        
        # OO interface
        # acquire semaphore
        my $lock = Cache::Memcached::Semaphore(
                memd => $memd, 
                name => "semaphore1",
        );
        # release semaphore
        $lock = undef;

        # acquire semaphore which will stay 10 secs after deleting object
        my $lock2 = Cache::Memcached::Semaphore(
                memd => $memd, 
                name => "semaphore2",
                timeout => 10,
        );
        
        # Functional interface
        # acquire semaphore which will stay 10 secs after deleting object
        my $lock3 = acquire(
                memd => $memd, 
                name => "semaphore3",
                timeout => 10,
        );
        
        # try to acquire semaphore during 10 seconds
        my $lock4 = wait_acquire(
                memd => $memd, 
                name => "semaphore4",
                max_wait        => 10,
                poll_time       => 0.1,
        );

DESCRIPTION

This module uses Cache::Memcached perl API to maintain semaphores across a number of servers. It relies upon return value of memcached API add function (true in case of previously non-existent value, false in case value already exists).

Tested with memcached v 1.1.12, Cache::Memcached 1.15+ on FreeBSD 6.0-RELEASE, 6.1-STABLE, 6.1-RELEASE, 6.2-PRERELEASE.

CONSTRUCTOR

new

Takes a hash of named options. The main keys are memd which is a reference to a memcached API object (actually, it can be any blessed reference with the same interface as Cache::Memcached) and name - the name for the semaphore.

Use timeout to set the time in seconds, for which acquiring the semaphore will be impossible after releasing it.

The constructor return a blessed reference to Cache::Memcached::Semaphore object in case of success, otherwise undef.

The semaphore is released automatically when the variable holding the reference to the object leaves the scope or is explicitly set to any other value (in the object's destructor).

FUNCTIONAL INTERFACE

acquire

Takes the same parameters as the constructor and returns blessed object reference in case of success, otherwise undef.

wait_acquire

Takes the same options as above plus extra two: max_wait and poll_time. The function tries to acquire the semaphore, in case of failure it waits poll_time seconds (may be fractions of seconds) and tries again. If the function succeeds to acquire the semafore within max_wait seconds, it returns a blessed object reference. Otherwise it returns undef.

BUGS

None known yet

TODO

Forced lock acquiring

Semaphore time-to-live

Deadlock resolving

AUTHOR

Sergei A. Fedorov <zmij@cpan.org>

I will be happy to have your feedback about the module.

COPYRIGHT

This module is Copyright (c) 2006 Sergei A. Fedorov. All rights reserved.

You may distribute under the terms of either the GNU General Public License or the Artistic License, as specified in the Perl README file.

WARRANTY

This is free software. IT COMES WITHOUT WARRANTY OF ANY KIND.