pthread_mutex_unlock()--Unlock Mutex

 #include <pthread.h>
 int pthread_mutex_unlock(pthread_mutex_t *mutex); 

The pthread_mutex_unlock() function unlocks the mutex specified. If the calling thread does not currently hold the mutex (via a previous call to pthread_mutex_lock(), pthread_mutex_trylock(), or pthread_mutex_timedlock_np()) the unlock request fails with the EPERM error.

Mutex initialization using the PTHREAD_MUTEX_INITIALIZER does not immediately initialize the mutex. Instead, on first use, pthread_mutex_timedlock_np() or pthread_mutex_lock() or pthread_mutex_trylock() branches into a slow path and causes 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.

Mutex Types

A normal mutex cannot be locked repeatedly by the owner. Attempts by a thread to relock an already held mutex, or to lock a mutex that was held by another thread when that thread terminated, cause a deadlock condition.

A recursive mutex can be locked repeatedly by the owner. The mutex does not become unlocked until the owner has called pthread_mutex_unlock() for each successful lock request that it has outstanding on the mutex.

An errorcheck mutex checks for deadlock conditions that occur when a thread relocks an already held mutex. If a thread attempts to relock a mutex that it already holds, the lock request fails with the EDEADLK error.

An ownerterm mutex is an IBM^® i extension to the errorcheck mutex type. An ownerterm mutex checks for deadlock conditions that occur when a thread relocks an already held mutex. If a thread attempts to relock a mutex that it already holds, the lock request fails with the EDEADLK error. An ownerterm mutex also checks for deadlock conditions that occur when a thread attempts to lock a mutex that was held by another thread when that thread terminated (an orphaned mutex). If a thread attempts to lock an orphaned mutex, the lock request fails with the EOWNERTERM error.

When a thread terminates while holding a mutex lock on a normal or errorcheck mutex, other threads that wait for that mutex will block forever. The pthreads run-time simulates the deadlock that has occurred in your application. When you are attempting to debug these deadlock scenarios, the CL command WRKJOB, option 20, shows the thread as in a condition wait. Displaying the call stack shows that the function deadlockOnOrphanedMutex is in the call stack.

When a thread attempts to acquire a normal mutex that it already holds, the thread will block forever. The pthreads run-time simulates the deadlock that has occurred in your application. When you are attempting to debug these deadlock scenarios, the CL command WRKJOB, option 20, shows the thread as in a condition wait. Displaying the call stack shows that the function deadlockOnAlreadyHeldMutex is in the call stack.

To change these behaviors, use an errorcheck or ownerterm mutex type.

Authorities and Locks

For successful completion, the mutex lock must be held before you call pthread_mutex_unlock().

Parameters

mutex

(Input) Address of the mutex to unlock

Return Value

0

pthread_mutex_unlock() was successful.

value

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

Error Conditions

If pthread_mutex_unlock() 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.

[EPERM]

The mutex is not currently held by the caller.

Related Information

• The <pthread.h> header file. See Header files for Pthread functions.
  
  
• pthread_mutex_destroy()--Destroy Mutex
  
  
• pthread_mutex_init()--Initialize Mutex
  
  
• pthread_mutex_lock()--Lock Mutex
  
  
• pthread_mutex_timedlock_np()--Lock Mutex with Time-Out
  
  
• pthread_mutex_trylock()--Lock Mutex with No Wait

Example

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

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

pthread_mutex_t    mutex = PTHREAD_MUTEX_INITIALIZER;

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

  printf("Entering testcase\n");

  printf("Lock the mutex\n");
  rc = pthread_mutex_lock(&mutex);
  checkResults("pthread_mutex_lock()\n", rc);

  /* All other threads will be blocked from the resource here */
 
  printf("Unlock the mutex\n");
  rc = pthread_mutex_unlock(&mutex);
  checkResults("pthread_mutex_unlock()\n", rc);

  printf("Destroy the mutex\n");
  rc = pthread_mutex_destroy(&mutex);
  checkResults("pthread_mutex_destroy()\n", rc);
  
  printf("Main completed\n");
  return 0;
}

Output:

Entering testcase
Lock the mutex
Unlock the mutex
Destroy the mutex
Main completed

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