SyncMutexLock(), SyncMutexLock_r()
Lock a mutex synchronization object
Synopsis:
#include <sys/neutrino.h>
int SyncMutexLock( sync_t * sync );
int SyncMutexLock_r( sync_t * sync );
Arguments:
- sync
- A pointer to the synchronization object for the mutex that you want to lock.
Library:
libc
Use the -l c option to qcc to link against this library. This library is usually included automatically.
Description:
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.
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.
For more information, see
Mutexes: mutual exclusion locks
in the IDE Microkernel chapter of the
System Architecture guide.
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.
The sync argument must have been initialized by a call to SyncTypeCreate() or have been statically initialized by the manifest PTHREAD_MUTEX_INITIALIZER.
Blocking states
- STATE_MUTEX
- The calling thread blocks waiting for the synchronization object to be unlocked.
Returns:
The only difference between these functions is the way they indicate errors:
- SyncMutexLock()
- If an error occurs, the function returns -1 and sets errno. Any other value returned indicates success.
- SyncMutexLock_r()
- Returns EOK on success. This function does NOT set errno. If an error occurs, this function returns any value listed in the Errors section.
Errors:
- EFAULT
- A fault occurred when the kernel tried to access the buffers you provided.
- EINVAL
- One of the following occurred:
- The mutex was created with a protocol attribute of PTHREAD_PRIO_PROTECT, and the calling thread's priority is higher than the mutex's current priority ceiling.
- The synchronization ID specified in sync doesn't exist.
- You're using safe shared mutexes (see the -s option for procnto), and you tried to lock a PTHREAD_PRIO_INHERIT mutex whose owner isn't known to the kernel and that the locking thread claims is from a different process.
- EOWNERDEAD
- The owner of the lock died while holding it.
- ETIMEDOUT
- A kernel timeout unblocked the call. See TimerTimeout().
Classification:
Safety: | |
---|---|
Cancellation point | No |
Signal handler | Yes |
Thread | Yes |