SyncMutexLock(), SyncMutexLock

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.

Note: Don't use the SyncMutexLock() or SyncMutexLock_r() kernel call directly; instead, use the POSIX functions for mutexes (see pthread_mutex_lock()).

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 QNX Neutrino 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.

Note: 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:

EFAULT

A fault occurred when the kernel tried to access the buffers you provided.

EINVAL

One of the following occurred:

The synchronization ID specified in sync doesn't exist.
(QNX Neutrino 7.0.1 or later) 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:

QNX Neutrino

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

SyncMutexLock(), SyncMutexLock_r()