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.

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.

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:

EAGAIN: On the first use of a statically initialized sync, all kernel synchronization objects were in use.
EFAULT: A fault occurred when the kernel tried to access the buffers you provided.
EINVAL: The synchronization ID specified in sync doesn't exist.
ETIMEDOUT: A kernel timeout unblocked the call. See TimerTimeout().

Classification:

QNX Neutrino

Safety:
Cancellation point	No
Interrupt handler	No
Signal handler	Yes
Thread	Yes