pthread_mutex_init()--Initialize Mutex

 #include <pthread.h>
 int pthread_mutex_init(pthread_mutex_t *mutex,  
			const pthread_mutexattr_t *attr);   

 pthread_mutex_t  mutex = PTHREAD_MUTEX_INITIALIZER;  

The pthread_mutex_init() function initializes a mutex with the specified attributes for use. The new mutex may be used immediately for serializing critical resources. If attr is specified as NULL, all attributes are set to the default mutex attributes for the newly created mutex.

With these declarations and initialization:

pthread_mutex_t       mutex2;
pthread_mutex_t       mutex3;
pthread_mutexattr_t   mta;
pthread_mutexattr_init(&mta);

The following three mutex initialization mechanisms have equivalent function.

pthread_mutex_t       mutex1 = PTHREAD_MUTEX_INITIALIZER;
pthread_mutex_init(&mutex2, NULL);
pthread_mutex_init(&mutex3, &mta);

All three mutexes are created with the default mutex attributes.

Every mutex must eventually be destroyed with pthread_mutex_destroy(). The machine eventually detects the error if a mutex is not destroyed. Large numbers of these entries can affect system performance. Always use pthread_mutex_destroy() before freeing or reusing mutex storage.

Once a mutex is created, it cannot be validly copied or moved to a new location. If the mutex is copied or moved to a new location, the new object is not valid and should not be used. Any attempt to use the invalid object will produce unpredictable results.

Note: Mutex initialization using the PTHREAD_MUTEX_INITIALIZER does not immediately initialize the mutex. Instead, on first use, the pthread_mutex_lock() or pthread_mutex_trylock() functions branch into a slow path and cause the initialization of the mutex. Because a mutex is not just a simple memory object and requires that some resources be allocated by the system, an attempt to call pthread_mutex_destroy() or pthread_mutex_unlock() on a mutex that was statically initialized using PTHREAD_MUTEX_INITIALIZER and was not yet locked causes an EINVAL error.

Authorities and Locks

None.

Parameters

mutex

(Input) The address of the variable to contain a mutex object.

attr

(Input) The address of the variable containing the mutex attributes object.

Return Value

0

pthread_mutex_init() was successful.

value

pthread_mutex_init() was not successful. value is set to indicate the error condition.

Error Conditions

If pthread_mutex_init() was not successful, the error condition returned usually indicates one of the following errors. Under some conditions, the value returned could indicate an error other than those listed here.

[EINVAL]

The value specified for the argument is not correct.

[ENOMEM]

The system cannot allocate the resources required to create the mutex.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_mutex_destroy()--Destroy Mutex
  
  
• pthread_mutex_lock()--Lock Mutex
  
  
• pthread_mutex_trylock()--Lock Mutex with No Wait
  
  
• pthread_mutex_unlock()--Unlock Mutex

Example

Note: By using the code examples, you agree to the terms of the Code license and disclaimer information.

#define _MULTI_THREADED
#include <pthread.h>
#include <stdio.h>
#include "check.h"

pthread_mutex_t    mutex = PTHREAD_MUTEX_INITIALIZER;
pthread_mutex_t    mutex2;
pthread_mutex_t    mutex3;

int main(int argc, char **argv)
{
  int                   rc=0;
  pthread_mutexattr_t   mta;

  printf("Enter Testcase - %s\n", argv[0]);

  printf("Create a default mutex attribute\n");
  rc = pthread_mutexattr_init(&mta);
  checkResults("pthread_mutexattr_init\n", rc);

  printf("Create the mutexes using the default mutex attributes\n");

  printf("First mutex created via static PTHREAD_MUTEX_INITIALIZER\n");

  printf("Create the mutex using the NULL attributes (default)\n");
  rc = pthread_mutex_init(&mutex3, NULL);
  checkResults("pthread_mutex_init(NULL)\n", rc);

  printf("Create the mutex using a mutex attributes object\n");
  rc = pthread_mutex_init(&mutex2, &mta);
  checkResults("pthread_mutex_init(mta)\n", rc);

  printf("- At this point, all mutexes can be used with their\n");
  printf("- default attributes from any threads that want to\n");
  printf("- use them\n");

  printf("Destroy all mutexes\n");
  pthread_mutex_destroy(&mutex);
  pthread_mutex_destroy(&mutex2);
  pthread_mutex_destroy(&mutex3);

  printf("Main completed\n");
  return 0;
}

Output:

Enter Testcase - QP0WTEST/TPMTXINI0
Create a default mutex attribute
Create the mutexes using the default mutex attributes
First mutex created via static PTHREAD_MUTEX_INITIALIZER
Create the mutex using the NULL attributes (default)
Create the mutex using a mutex attributes object
- At this point, all mutexes can be used with their
- default attributes from any threads that want to
- use them
Destroy all mutexes
Main completed

[ Back to top | Pthread APIs | APIs by category ]