HIROSE Masaaki > IPC-Lock-WithTTL-0.01 > IPC::Lock::WithTTL

Download:
IPC-Lock-WithTTL-0.01.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

NAME ^

IPC::Lock::WithTTL - run only one process up to given timeout

SYNOPSIS ^

    use IPC::Lock::WithTTL;
    
    my $lock = IPC::Lock::WithTTL->new(
        file          => '/tmp/lockme',
        ttl           => 5,
        kill_old_proc => 0,
       );
    
    my($r, $hb) = $lock->acquire;
    
    if ($r) {
        infof("Got lock! yay!!");
    } else {
        critf("Cannot get lock. Try after at %d", $hb->{expiration});
        exit 1;
    }
    
    $lock->release;

DESCRIPTION ^

IPC::Lock::WithTTL provides inter process locking feature. This locking has timeout feature, so we can use following cases:

    * Once send an alert email, don't send same kind of alert email within 10 minutes.
    * We want to prevent the situation that script for failover some system is invoked more than one processes at same time and invoked many times in short time.

DETAIL ^

SEQUENCE

    1. flock a heartbeat file (specified by file param in new) with LOCK_EX
       return if failed to flock.
    2. read a heartbeat file and examine PID and expiration (describe later)
       return if I should not go ahead.
    3. update a heartbeat file with my PID and new expiration.
    4. ACQUIRED LOCK
    5. unlock a lock file.
    6. process main logic.
    7. RELEASE LOCK with calling $lock->release method.
       In that method update a heartbeat file with PID=0 and new expiration.

DETAIL OF EXAMINATION OF PID AND EXPIRATION

Format of a heartbeat file (lock file) is:

    PID EXPIRATION

Next action table by PID and expiration

    PID       expired?  Next action      Description
    =========================================================================
    not mine  yes       acquired lock*1  Another process is running or
    - - - - - - - - - - - - - - - - - -  exited abnormally (without leseasing
    not mine  no        return           lock).
    -------------------------------------------------------------------------
    mine      yes       acquired lock    Previously myself acquired lock but
    - - - - - - - - - - - - - - - - - -  does not release lock.
    mine      no        acquired lock
    -------------------------------------------------------------------------
    0         yes       acquired lock    Previously someone acquired and
    - - - - - - - - - - - - - - - - - -  released lock successfully.
    0         no        return
    -------------------------------------------------------------------------
    
    *1 try to kill another process if you enable kill_old_proc option in new().

METHODS ^

new($args:Hash)
    file => Str (required)
      File path of heartbeat file. IPC::Lock::WithTTL also flock this file.
    
    ttl  => Int (default is 0)
      TTL to exipire. expiration time set to now + TTL.
    
    kill_old_proc => Boolean (default is 0)
      Try to kill old process which might exit abnormally.
acquire(ttl => $TTL:Int)

Try to acquire lock. ttl option set TTL to expire (override ttl in new())

This method returns scalar or list by context.

    Scalar context
    =========================================================================
      Acquired lock successfully
        1
      -----------------------------------------------------------------------
      Failed to acquire lock
        0
    
    List context
    =========================================================================
      Acquired lock successfully
        (1, { pid => PID, expiration => time_to_expire })
        PID is mine. expiration is setted by me.
      -----------------------------------------------------------------------
      Failed to acquire lock
        (0, { pid => PID, expiration => time_to_expire })
        PID is another process. expiration is setted by another process.
release()

Update a heartbeat file (PID=0 and new expiration) and release lock.

AUTHOR ^

HIROSE Masaaki <hirose31 _at_ gmail.com>

REPOSITORY ^

https://github.com/hirose31/IPC-Lock-WithTTL

  git clone git://github.com/hirose31/IPC-Lock-WithTTL.git

patches and collaborators are welcome.

SEE ALSO ^

IPC::Lock

LICENSE ^

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: