Warning: main(/www/www/htdocs/style/globals.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_mutex_lock.html on line 1

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/globals.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_mutex_lock.html on line 1

Warning: main(/www/www/htdocs/style/header.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_mutex_lock.html on line 8

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/header.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_mutex_lock.html on line 8

pthread_mutex_lock()

Lock a mutex

Synopsis:

#include <pthread.h>

int pthread_mutex_lock( pthread_mutex_t* mutex );

Arguments:

mutex
A pointer to the pthread_mutex_t object 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 pthread_mutex_lock() function locks the mutex object referenced by mutex. If the mutex is already locked, then the calling thread blocks until it has acquired the mutex. When the function returns, the mutex object is locked and owned by the calling thread.

By default, if a thread with a higher priority than the mutex owner attempts to lock a mutex, then the effective priority of the current owner is increased to that of the higher-priority blocked thread waiting for the mutex. The owner returns to its real priority when it unlocks the mutex. For more information, see Mutexes: mutual exclusion locks in the QNX Neutrino Microkernel chapter of the System Architecture guide.

If the mutex allows recursive behavior, a call to pthread_mutex_lock() while you own the mutex succeeds. You can allow recursive behavior by:

If the mutex is recursive, you must call pthread_mutex_unlock() for each corresponding call to lock the mutex. The default POSIX behavior doesn't allow recursive mutexes, and returns EDEADLK.

If a signal is delivered to a thread that's waiting for a mutex, the thread resumes waiting for the mutex on returning from the signal handler.

Returns:

EOK
Success.
EAGAIN
Insufficient system resources available to lock the mutex.
EDEADLK
The calling thread already owns mutex, and the mutex doesn't allow recursive behavior.
EFAULT
A fault occurred when the kernel tried to access the buffers you provided.
EINVAL
Invalid mutex mutex.
ETIMEDOUT
A kernel timeout unblocked the call.

Examples:

This example shows how you can use a mutex to synchronize access to a shared variable. In this example, function1() and function2() both attempt to access and modify the global variable count. Either thread could be interrupted between modifying count and assigning its value to the local tmp variable. Locking mutex prevents this from happening; if one thread has mutex locked, the other thread waits until it's unlocked, before continuing.

#include <stdio.h>
#include <pthread.h>

pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER;
int count = 0;

void* function1( void* arg )
{
    int tmp = 0;

    while( 1 ) {
        pthread_mutex_lock( &mutex );
        tmp = count++;
        pthread_mutex_unlock( &mutex );
        printf( "Count is %d\n", tmp );

        /* snooze for 1 second */
        sleep( 1 );
    }

    return 0;
}

void* function2( void* arg )
{
    int tmp = 0;

    while( 1 ) {
        pthread_mutex_lock( &mutex );
        tmp = count--;
        pthread_mutex_unlock( &mutex );
        printf( "** Count is %d\n", tmp );

        /* snooze for 2 seconds */
        sleep( 2 );
    }

    return 0;
}

int main( void )
{
    pthread_create( NULL, NULL, &function1, NULL );
    pthread_create( NULL, NULL, &function2, NULL );

    /* Let the threads run for 60 seconds. */
    sleep( 60 );

    return 0;
}

Classification:

POSIX 1003.1 THR

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

See also:

pthread_mutex_init(), pthread_mutexattr_setrecursive(), pthread_mutex_timedlock(), pthread_mutex_trylock(), pthread_mutex_unlock(), SyncMutexLock()

Mutexes: mutual exclusion locks in the QNX Neutrino Microkernel chapter of the System Architecture guide

Processes and Threads chapter of Getting Started with QNX Neutrino


Warning: main(/www/www/htdocs/style/footer.php) [function.main]: failed to open stream: No such file or directory in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_mutex_lock.html on line 271

Warning: main() [function.include]: Failed opening '/www/www/htdocs/style/footer.php' for inclusion (include_path='.:/www/www/common:/www/www/php/lib/php') in /www/www/docs/6.4.1/neutrino/lib_ref/p/pthread_mutex_lock.html on line 271