Locks are objects that can be used to guarantee exclusive access to some resource. More...
Functions | |
| void | BZ_LockInit (BZ_LOCK *lock) |
| Initialises a lock before use. | |
| int | BZ_LockObtain (BZ_LOCK *lock) |
| Obtain a lock. | |
| int | BZ_LockRelease (BZ_LOCK *lock) |
| Release a lock. | |
| int | BZ_LockAttempt (BZ_LOCK *lock) |
| Attempt to obtain a lock. | |
Locks are objects that can be used to guarantee exclusive access to some resource.
A lock is either free or it has an owner. When you want to use a the shared resource, you obtain the lock. If the lock is owned by an other thread, you will be suspended until that thread finishes with the resource and releases the lock. At that moment you became the owner of the lock and you are free to use the resource, all other threads will be suspended on the lock. When you finished with the resource, you have to release a lock, thus granting access to the resource to other threads.
When multiple threads are waiting for a lock, then the order of them getting the lock when it becomes available depends on the scheduling policy of the kernel. In priority scheduling mode the highest priority waiting process will get the lock, in round-robin mode any one of the waiting threads can get it. In effect when the lock is released they all become runable and the first one scheduled by the kernel gets the lock, all the others go back to wait.
The locking code is very short but rather unsophisticated. If you use a lot of locks and many threads suspended on locks, then you will burn CPU cycles unnecessarily. Do not use locks as general purpose synchronisation mechanism. Use then only as intended, providin a mutually exclusive access to a shared resource.
| int BZ_LockAttempt | ( | BZ_LOCK * | lock | ) |
Attempt to obtain a lock.
This function tries to obtain the lock, but does not wait if it is not available. It does not suspend the caller.
| lock | Pointer to the lock |
| 0 | The lock is already owned by the caller | |
| 1 | The lock was free and now is owned by the caller | |
| BZ_IN_USE | The lock is owned by an other thread |
| void BZ_LockInit | ( | BZ_LOCK * | lock | ) |
Initialises a lock before use.
Before you can use a lock, you must initialise it. After this function the lock will be ready to use. The function does not suspend the caller.
| lock | Pointer to the lock to initialise |
| int BZ_LockObtain | ( | BZ_LOCK * | lock | ) |
Obtain a lock.
If the lock is available, then the function takes it and returns immediately. Otherwise, it will suspend the caller until the lock becomes free. If the lock is already owned by the caller, then the function returns immediately.
| lock | Pointer to the lock |
| 0 | The lock is already owned by the caller | |
| 1 | The lock was free and now is owned by the caller |
| int BZ_LockRelease | ( | BZ_LOCK * | lock | ) |
Release a lock.
The caller, who must be the current owner of the lock, releases the lock. This call does not suspend the caller.
| lock | Pointer to the lock |
| BZ_NOT_OWNER | The caller did not own the lock | |
| 0 | The lock was released. |
1.6.3