NAME

GT::Lock - a small autonomous locking module.

SYNOPSIS

    use GT::Lock qw/lock unlock LOCK_TRY LOCK_FORCE/;
    # attempt to lock foobar for 10 seconds
    if (lock 'foobar', 10, LOCK_TRY) {
        # do some code that needs to be locked
        unlock 'foobar';
    }
    else {
        # oops out lock failed
        die "Lock failed: $GT::Lock::error\n";
    }


DESCRIPTION

GT::Lock is a very simple module to impliment autonomous named locking. Locking can be used for many things but is most commonly used to lock files for IO to them.

Nothing is exported by default. You may request the lock, unlock routines be exported. You can also get the two constants for lock types exported: LOCK_TRY and LOCK_FORCE.

lock - Lock a name.

    lock NAME [, TIMOUT, TYPE, AGE ]

This method is used to create a lock. Its arguments are the name you wish to give the lock, the timeout in seconds for the lock to happen, the type of lock, and the maximum lock age (in seconds). The types are LOCK_FORCE and LOCK_TRY. If LOCK_FORCE is given a lock always succeeds, e.g. if the lock times out the lock is removed and your lock succeeds. Try attempts to get the lock and returns false if the lock can not be had in the specified TIMEOUT. If TIMEOUT is zero this method will attempt to lock forever. TIMEOUT defaults to 10 seconds. The AGE parameter can be used to ensure that stale locks are not preserved - if the lock already exists and is older than AGE seconds, it will be removed before attempting to get the lock. Omitting it uses the default value, undef, which does not attempt to remove stale locks.

unlock - unlock a name.

    unlock NAME

This method is used to unlock a name. It's argument is the name of the lock to unlock. Returns true on success and false on errors and sets the error in $GT::Lock::error.


DEPENDANCIES

the GT::Lock manpage depends on the GT::TempFile manpage, bases, and constants.


COPYRIGHT

Copyright (c) 2005 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/


VERSION

Revision: $Id: Lock.pm,v 1.7 2007/02/11 21:56:56 sbeck Exp $