Man Linux: Main Page and Category List

NAME

     locks - libbash library that implements locking (directory based).

     This library is not throughoutly tested - use with caution!

SYNOPSIS

     dirInitLock      〈object〉 [〈spin〉]
     dirTryLock       〈object〉
     dirLock          〈object〉
     dirUnlock        〈object〉
     dirDestroyLock   〈object〉

DESCRIPTION

   General
     locks is a collection of functions that implement locking (mutex like) in
     bash scripting language.  The whole idea is based on the fact that
     directory creation/removal is an atomic process.  The creation of this
     library was inspired by studying CVS locks management.

     Same lock object can by used by several processes to serialize access to
     some shared resource.  (Well, yeah, this what locks were invented for...)
     To actually do this, processes just need to access lock object by the
     same name.

   Functions list:
          dirInitLock      Initialize a lock object for your proccess

          dirTryLock       Try to lock the lock object - give up if its
                           already locked

          dirLock          Lock the lock object - will block until object is
                           unlocked

          dirUnlock        Unlock the lock object

          dirDestroyLock   Destroy the lock object - free resources

     Detailed interface description follows.

FUNCTIONS DESCRIPTIONS

   dirInitLockobject〉 [〈spin〉]
     Initialize a lock object for your process.  Only after a lock is
     initialized, your proccess will be able to use it.  Notice: This action
     does not lock the object.

     The lock can be set on two types of objects. The first is an existing
     directory.  In this case, Aq dir must be a path (relative or full). The
     path must contain a ‘/’.  The second is an abstract object used as a
     lock. In this case, the name of the lock will not contain any ‘/’.  This
     can be used to create locks without creating real directories for them.
     Notice: Do not call your lock object ‘.lock’.

     Parameters:

       〈object〉
         The name of the lock object (either existing directory or abstract
         name)

       〈spin〉
         The time (in seconds) that the funtion dirLock will wait between two
         runs of dirTryLock.  This parameter is optional, and its value
         generally should be less then 1.  If ommited, a default value (0.01)
         is set.

     Return Value:

       One of the following:
       0    The action finished successfully.
       1    The action failed. You do not have permissions to preform it.
       3    The directory path could not be resolved. Possibly parameter  does
            contain ‘/’, but refers to directory that does not exist.

   dirTryLockobject〉
     Try to lock the lock object. The function always returns immediately.

     Parameters:

       〈object〉
         The object that the lock is set on.

     Return Value:

       One of the following:
       0    The action finished successfully.
       1    The action failed. The object is already locked.
       2    The action failed. Your proccess did not initialize a lock for the
            object.
       3    The directory path could not be resolved.

   dirLockobject〉
     Lock given lock object.  If the object is already locked - the function
     will block untill the object is unlocked.  After each try (dirTryLock)
     the function will sleep for spin seconds (spin is defined using
     dirInitLock ).

     Parameters:

       〈object〉
         The directory that the lock is set on.

     Return Value:

       One of the following:
       0    The action finished successfully.
       2    The action failed. Your proccess did not initialize a lock for the
            directory.
       3    The directory path could not be resolved.

   dirUnlockdir〉
     Unlock the lock object.

     Parameters:

       〈object〉
         The object that the lock is set on.

     Return Value:

       One of the following:
       0    The action finished successfully.
       2    The action failed. Your proccess did not initialize the lock.
       3    The directory path could not be resolved.

   dirDestroyLockobject〉
     Destroys the lock object.  After this action the proccess will no longer
     be able to use the lock object.  To use  the object after this action is
     done, one must initialize the lock, using dirInitLock.

     Parameters:

       〈object〉
         The directory that the lock is set on.

     Return Value:

       One of the following:
       0    The action finished successfully.
       1    The action failed. The directory is locked by your  own  proccess.
            Unlock it first.
       2    The action failed. Your proccess did not initialize the lock.
       3    The directory path could not be resolved.

EXAMPLES

     Creating an abstract lock named mylock, with 0.1 second spintime:
           $ dirInitLock mylock 0.1 # $?=0
     Locking it:
           $ dirLock mylock # $?=0
     Trying once to lock it again:
           $ dirTryLock mylock # $?=1
     Trying to lock it again:
           $ dirLock mylock # Will wait forever
     Unlocking:
           $ dirUnlock mylock # $?=0
     Destroying the lock:
           $ dirDestroyLock mylock # $?=0
     Trying to lock again:
           $ dirLock mylock # $?=2
     Creating a lock on the directory ./mydir, with default spin time:
           $ dirInitLock ./mydir # $?=0

AUTHORS

     Hai Zaar 〈haizaar@haizaar.com〉
     Gil Ran 〈gil@ran4.net

SEE ALSO

     ldbash(1), libbash(1)