table of contents
LOCKS(3) | 3 (libbash locks library manual) | LOCKS(3) |
NAME¶
locks
— libbash
library that implements locking (directory based).
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¶
dirInitLock ⟨object⟩ [⟨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:
dirTryLock ⟨object⟩¶
Try to lock the lock object. The function always returns immediately.
Parameters:
- ⟨object⟩
- The object that the lock is set on.
Return Value:
dirLock ⟨object⟩¶
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:
dirUnlock ⟨dir⟩¶
Unlock the lock object.
Parameters:
- ⟨object⟩
- The object that the lock is set on.
Return Value:
dirDestroyLock ⟨object⟩¶
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:
EXAMPLES¶
Creating an abstract lock named mylock, with 0.1 second spintime:
AUTHORS¶
Hai Zaar
⟨haizaar@haizaar.com⟩
Gil Ran ⟨gil@ran4.net⟩
SEE ALSO¶
Linux |