Lock a mutex synchronization object
#include <sys/neutrino.h> int SyncMutexLock( sync_t * sync ); int SyncMutexLock_r( sync_t * sync );
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
The SyncMutexLock() and SyncMutexLock_r() kernel calls try to lock the mutex synchronization object sync. If the mutex isn't currently locked, the call returns immediately with the object locked. The mutex is considered unlocked if the owner field of sync is zero. Otherwise, the owner field of sync is treated as the thread ID of the current owner of the mutex.
These functions are similar, except for the way they indicate errors. See the Returns section for details.
The POSIX functions pthread_mutex_lock(), and pthread_mutex_unlock(), are faster, since they can potentially avoid a kernel call. |
If the mutex is already locked, the calling thread blocks on sync until it's unlocked by the owner. If more than one thread is blocked on sync they're queued in priority order.
If the priority of the blocking thread is higher than the thread that owns the mutex, the owner's priority is boosted to match that of the caller. In other words, the owner inherits the caller's priority if it's higher. If the owner's priority is boosted, it returns to its previous value before any boosts when the mutex is unlocked. Note that the owner may be boosted more than once as higher priority threads block on sync.
If a thread is boosted via this mechanism and subsequently changes its own priority, that priority takes immediate effect and also becomes the value it's returned to after it releases the mutex.
Waiting for a mutex isn't a cancellation point. If a signal is delivered to the thread while waiting for the mutex, the signal handler runs and, upon return from the handler, the thread resumes waiting for the mutex as if it wasn't interrupted.
Avoid timeouts on mutexes. Mutexes should be locked for brief periods of time, eliminating the need for a timeout. |
The sync argument must have been initialized by a call to SyncTypeCreate() or have been statically initialized by the manifest PTHREAD_MUTEX_INITIALIZER.
The only difference between these functions is the way they indicate errors:
Safety: | |
---|---|
Cancellation point | No |
Interrupt handler | No |
Signal handler | Yes |
Thread | Yes |
pthread_mutex_lock(), pthread_mutex_unlock(), SyncTypeCreate(), SyncDestroy(), SyncMutexUnlock()