mtx_destroy, mtx_init, mtx_lock, mtx_timedlock, mtx_trylock, and mtx_unlock Subroutine

Purpose

The mtx_destroy subroutine releases any resources that are used by the mtx mutex variable.

The mtx_init subroutine creates a mtx mutex variable that has the properties specified by the type parameter.

The mtx_lock and mtx_unlock subroutine locks and unlocks the mtx mutex variable.

The mtx_timedlock subroutine locks the mtx mutex variable for the time that is specified by the tsun parameter.

The mtx_trylock subroutine tries to lock the mtx mutex variable, if available.

Library

Standard C library (libc.a)

Syntax

#include <threads.h>
void mtx_destroy (mtx_t * mtx);

int mtx_init (mtx_t * mtx, int type);

int mtx_lock (mtx_t * mtx);

int mtx_init (mtx_t * mtx, int type);

int mtx_timedlock (mtx_t * restrict mtx, const struct timespec * restrict  ts);

int mtx_trylock (mtx_t * mtx);

Description

The mtx_destroy subroutine releases any resources that are used by the mutex variable specified by the mtx parameter.

The mtx_destroy subroutine requires that threads are not blocked while waiting for the mutex variable specified by the mtx parameter.

The mtx_init subroutine creates a mutex object that has the type parameter, which can accept any one of the following values:
  • mtx_plain for a simple nonrecursive mutex
  • mtx_timed for a nonrecursive mutex that supports timeout
  • mtx_plain or mtx_recursive for a simple recursive mutex
  • mtx_timed or mtx_recursive for a recursive mutex that supports timeout
If the mtx_init subroutine is successful, it sets the mutex variable specified by the mtx parameter to a value that uniquely identifies the newly created mutex.

The mtx_lock subroutine locks the mutex variable specified by the mtx parameter. If the mutex variable is nonrecursive, it is not locked by the calling thread.

The mtx_timedlock subroutine tries to lock the mutex variable specified by the mtx parameter or till the TIME_UTC based calendar time is pointed to by the value that is specified in the ts parameter. The specified mutex variable supports timeout operation.

The mtx_trylock subroutine tries to lock the mutex variable specified by the mtx parameter. If the mutex is already locked, the function returns without blocking the mutex variable.

Previous calls to the mtx_unlock subroutine on the same mutex synchronizes the operations while using any of the subroutines, such as the mtx_lock, mtx_trylock or mtx_timedlock subroutines.

The mtx_unlock subroutine unlocks the mutex variable specified by the mtx parameter. The mutex specified by the mtx parameter is locked by the calling thread.

Parameters

Item Description
mtx Specifies the mutex variable to be created and locked. It also specifies the mutex variable for which the resources are to be released based on the type of the subroutine in which the parameter is referenced.
type Specifies the properties of the mutex variable and contains the combination of any of the following values: mtx_plain, mtx_timed, or mtx_recursive.
ts Specifies the maximum time for the mtx_timedlock subroutine to block the mutex variable.

Return Values

The mtx_destroy subroutine returns no value.

The mtx_init, mtx_lock and mtx_unlock subroutines return the value of thrd_success on success, and returns the value of thrd_error if the request cannot be processed.

The mtx_timedlock subroutine returns the value of thrd_success on success.

The mtx_timedlock subroutine returns the value of thrd_timedout if the specified time is reached without acquiring the requested resource.

The mtx_timedlock subroutine returns the value of thrd_error if the request cannot be processed.

The mtx_trylock subroutine returns the value of thrd_success on success, it returns the value of thrd_busy if the requested resource is already in use, and it returns the value of thrd_error if the request cannot be processed.

Files

The threads.h file defines standard macros, data types, and subroutines.