View on
MetaCPAN
Sergei A. Fedorov > Cache-Memcached-Semaphore-0.3 > Cache::Memcached::Semaphore

Download:
Cache/Memcached/Cache-Memcached-Semaphore-0.3.tar.gz

Dependencies

Annotate this POD

CPAN RT

New  1
Open  0
View/Report Bugs
Module Version: 0.3   Source  

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.

syntax highlighting: