Declares the C APIs of mutex, which are used to provide mutually exclusive access between concurrent tasks and protect shared resources from race conditions.
File to include: <ffrt/mutex.h>
Library: libffrt.z.so
System capability: SystemCapability.Resourceschedule.Ffrt.Core
Since: 10
Related module: FFRT
| Name | Description |
|---|---|
| FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr) | Initializes the mutex attribute. After successful initialization, the mutex attribute is set to the default value. When the mutex attribute is no longer used, it must be destroyed by ffrt_mutexattr_destroy. |
| FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type) | Sets the type of the mutex attribute. The type can be ffrt_mutex_normal (normal mutex) or ffrt_mutex_recursive (recursive mutex, which allows the same task to acquire the lock multiple times). |
| FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type) | Gets the type of the mutex attribute. After the call succeeds, the type value is returned through the output parameter type. |
| FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr) | Destroys the mutex attribute. The mutex attribute must have been initialized by ffrt_mutexattr_init. |
| FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr) | Initializes the mutex. When the mutex is no longer used, it must be destroyed by ffrt_mutex_destroy. Pass the configured mutex attribute through attr, or pass a null pointer to use the default value. |
| FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex) | Locks the mutex. If the mutex is already held by another thread, the current thread is blocked until the mutex becomes available. On success, the calling thread holds the mutex until it is released by ffrt_mutex_unlock. |
| FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex) | Unlocks the mutex. The calling thread must hold the mutex, and the lock must have been acquired by ffrt_mutex_lock or ffrt_mutex_trylock. |
| FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex) | Tries to lock the mutex. This API is a non-blocking operation: if the mutex is already held by another thread, an error code is returned immediately. On success, the calling thread holds the mutex until it is released by ffrt_mutex_unlock. |
| FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex) | Destroys the mutex. After the call succeeds, the resources occupied by the mutex are released, and the mutex object can no longer be used. The mutex must have been initialized by ffrt_mutex_init, and it must not be held by any thread when this API is called. |
FFRT_C_API int ffrt_mutexattr_init(ffrt_mutexattr_t* attr)
Description
Initializes a mutex attribute. After the initialization succeeds, the mutex attribute is set to the default value. When the mutex attribute is no longer used, it must be destroyed by ffrt_mutexattr_destroy.
Since: 12
Parameters
| Name | Description |
|---|---|
| ffrt_mutexattr_t* attr | Pointer to the mutex attribute. |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success if the mutex attribute is initialized successfully; otherwise returns ffrt_error_inval. |
FFRT_C_API int ffrt_mutexattr_settype(ffrt_mutexattr_t* attr, int type)
Description
Sets the type of a mutex attribute. The type can be ffrt_mutex_normal (a normal mutex) or ffrt_mutex_recursive (a recursive mutex that allows the same task to acquire the lock multiple times).
Since: 12
Parameters
| Name | Description |
|---|---|
| ffrt_mutexattr_t* attr | Pointer to the mutex attribute. |
| int type | Mutex type, which can be ffrt_mutex_normal, ffrt_mutex_recursive, or ffrt_mutex_default (equivalent to ffrt_mutex_normal). |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success if the mutex attribute type is set successfully; returns ffrt_error_inval if attr is a null pointer, or the mutex attribute type is neither ffrt_mutex_normal nor ffrt_mutex_recursive. |
Reference
FFRT_C_API int ffrt_mutexattr_gettype(ffrt_mutexattr_t* attr, int* type)
Description
Gets the type of a mutex attribute. When the call succeeds, the type value is returned through the output parameter type.
Since: 12
Parameters
| Name | Description |
|---|---|
| ffrt_mutexattr_t* attr | Pointer to the mutex attribute. |
| int* type | Pointer to the mutex type, used to receive the obtained type value (ffrt_mutex_normal or ffrt_mutex_recursive). |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success when the mutex attribute type is obtained successfully; returns ffrt_error_inval if attr or type is a null pointer. |
FFRT_C_API int ffrt_mutexattr_destroy(ffrt_mutexattr_t* attr)
Description
Destroys a mutex attribute. The mutex attribute must have been initialized by ffrt_mutexattr_init.
Since: 12
Parameters
| Name | Description |
|---|---|
| ffrt_mutexattr_t* attr | Pointer to the mutex attribute. |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success if the mutex attribute is destroyed successfully; otherwise returns ffrt_error_inval. |
FFRT_C_API int ffrt_mutex_init(ffrt_mutex_t* mutex, const ffrt_mutexattr_t* attr)
Description
Initializes a mutex. When the mutex is no longer used, it must be destroyed by ffrt_mutex_destroy. Pass a configured mutex attribute through attr, or pass a null pointer to use the default value.
Since: 10
Parameters
| Name | Description |
|---|---|
| ffrt_mutex_t* mutex | Pointer to the mutex. |
| const ffrt_mutexattr_t* attr | Pointer to the mutex attribute, or pass a null pointer to use the default value. |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | ffrt_success is returned when the mutex is initialized successfully; ffrt_error_inval is returned when mutex is null, or when attr is not null but does not specify a valid mutex type. |
FFRT_C_API int ffrt_mutex_lock(ffrt_mutex_t* mutex)
Description
Locks a mutex. If the mutex is already held by another thread, the current thread is blocked until the mutex becomes available. On success, the calling thread holds the mutex until it is released by ffrt_mutex_unlock.
Since: 10
Parameters
| Name | Description |
|---|---|
| ffrt_mutex_t* mutex | Pointer to the mutex. |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success if the mutex is locked successfully; otherwise returns ffrt_error_inval. |
Reference
FFRT_C_API int ffrt_mutex_unlock(ffrt_mutex_t* mutex)
Description
Unlocks a mutex. The calling thread must hold the mutex, and the lock must have been acquired by ffrt_mutex_lock or ffrt_mutex_trylock.
Since: 10
Parameters
| Name | Description |
|---|---|
| ffrt_mutex_t* mutex | Pointer to the mutex. |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success if the mutex is unlocked successfully; otherwise returns ffrt_error_inval. |
FFRT_C_API int ffrt_mutex_trylock(ffrt_mutex_t* mutex)
Description
Attempts to lock the mutex. This API is a non-blocking operation: if the mutex is already held by another thread, an error code is returned immediately. On success, the calling thread holds the mutex until it is released through ffrt_mutex_unlock.
Since: 10
Parameters
| Name | Description |
|---|---|
| ffrt_mutex_t* mutex | Pointer to the mutex. |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success when the mutex is locked successfully; otherwise returns ffrt_error_inval or ffrt_error_busy. |
Reference
FFRT_C_API int ffrt_mutex_destroy(ffrt_mutex_t* mutex)
Description
Destroys a mutex. After the call succeeds, the resources occupied by the mutex are released, and the mutex object can no longer be used. The mutex must have been initialized through ffrt_mutex_init, and it must not be held by any thread when this API is called.
Since: 10
Parameters
| Name | Description |
|---|---|
| ffrt_mutex_t* mutex | Pointer to the mutex. |
Returns
| Type | Description |
|---|---|
| FFRT_C_API int | Returns ffrt_success if the mutex is destroyed successfully; otherwise returns ffrt_error_inval. |