File threading.h

Threading abstraction layer.

Defines

MBEDTLS_ERR_THREADING_USAGE_ERROR

Detected error in mutex or condition variable usage.

Note that depending on the platform, many usage errors of synchronization primitives have undefined behavior. But where it is practical to detect usage errors at runtime, mutex and condition primitives can return this error code.

MBEDTLS_ERR_THREADING_MUTEX_ERROR

A historical alias for MBEDTLS_ERR_THREADING_USAGE_ERROR.

Typedefs

typedef pthread_mutex_t mbedtls_platform_mutex_t
typedef pthread_cond_t mbedtls_platform_condition_variable_t
typedef struct mbedtls_threading_mutex_t mbedtls_threading_mutex_t
typedef struct mbedtls_threading_condition_variable_t mbedtls_threading_condition_variable_t

Functions

void mbedtls_threading_set_alt(int (*mutex_init)(mbedtls_platform_mutex_t*), void (*mutex_destroy)(mbedtls_platform_mutex_t*), int (*mutex_lock)(mbedtls_platform_mutex_t*), int (*mutex_unlock)(mbedtls_platform_mutex_t*), int (*cond_init)(mbedtls_platform_condition_variable_t*), void (*cond_destroy)(mbedtls_platform_condition_variable_t*), int (*cond_signal)(mbedtls_platform_condition_variable_t*), int (*cond_broadcast)(mbedtls_platform_condition_variable_t*), int (*cond_wait)(mbedtls_platform_condition_variable_t*, mbedtls_platform_mutex_t*))

Set your alternate threading implementation function pointers and initialize global mutexes. If used, this function must be called once in the main thread before any other Mbed TLS function is called, and mbedtls_threading_free_alt() must be called once in the main thread after all other Mbed TLS functions.

Note

Functions should return MBEDTLS_ERR_THREADING_USAGE_ERROR if a mutex usage error is detected. However, it is acceptable for usage errors to result in undefined behavior (including deadlocks and crashes) if detecting usage errors is not practical on your platform.

Note

The library will always unlock a mutex from the same thread that locked it, and will never lock a mutex in a thread that has already locked it.

Note

Spurious wakeups on condition variables are permitted.

Parameters:

  • mutex_init –

    The mutex init function implementation.

    The behavior is undefined if the mutex is already initialized and has not been destroyed, or if this function is called concurrently from multiple threads.

  • mutex_destroy –

    The mutex destroy function implementation.

    This function must free any resources associated with the mutex object.

    The behavior is undefined if the mutex was not initialized, if it has already been destroyed, if it is currently locked, or if this function is called concurrently from multiple threads.

  • mutex_lock –

    The mutex lock function implementation.

    The behavior is undefined if the mutex was not initialized, if it has already been destroyed, or if it is currently locked by the calling thread.

  • mutex_unlock –

    The mutex unlock function implementation.

    The behavior is undefined if the mutex is not currently locked by the calling thread.

  • cond_init –

    The condition variable initialization implementation.

    The behavior is undefined if the variable is already initialized, if it has been destroyed, or if this function is called concurrently from multiple threads.

  • cond_destroy –

    The condition variable destroy implementation.

    This function must free any resources associated with the condition variable object.

    The behavior is undefined if the condition variable was not initialized, if it has already been destroyed, if a thread is waiting on it, or if this function is called concurrently from multiple threads.

  • cond_signal –

    The condition variable signal implementation.

    The behavior is undefined if the condition variable was not initialized or if it has already been destroyed.

  • cond_broadcast –

    The condition variable broadcast implementation.

    The behavior is undefined if the condition variable was not initialized or if it has already been destroyed.

  • cond_wait –

    The condition variable wait implementation.

    The behavior is undefined if the mutex and the condition variable have not both been initialized, if one of them has already been destroyed, or if the mutex is not currently locked by the calling thread.

void mbedtls_threading_free_alt(void)

Free global mutexes.

void mbedtls_mutex_init(mbedtls_threading_mutex_t *mutex)

Initialize a mutex (mutual exclusion lock).

You must call this function on a mutex object before using it for any purpose.

Note

This function may fail internally, but for historical reasons, it does not return a value. If the mutex initialization fails internally, mbedtls_mutex_free() will still work normally, and all other mutex functions will fail safely with a nonzero return code.

Note

The behavior is undefined if:

  • mutex is already initialized;

  • this function is called concurrently on the same object from multiple threads.

Parameters:

mutex – The mutex to initialize.

void mbedtls_mutex_free(mbedtls_threading_mutex_t *mutex)

Destroy a mutex.

After this function returns, you may call mbedtls_mutex_init() again on mutex.

Note

The behavior is undefined if:

  • any function is called concurrently on the same object from another thread;

  • mbedtls_mutex_init() has never been called on the object, and it is not all-bits-zero or {0};

  • mutex is locked.

Note

This function does nothing if:

  • mutex is all-bits-zero or {0}.

  • The last function called on mutex is mbedtls_mutex_free() (i.e. a double free is safe).

Parameters:

mutex – The mutex to destroy.

int mbedtls_mutex_lock(mbedtls_threading_mutex_t *mutex)

Lock a mutex.

It must not be already locked by the calling thread (mutexes are not recursive).

Note

The behavior is undefined if:

Parameters:

mutex – The mutex to lock.

Return values:

  • 0 – Success.

  • MBEDTLS_ERR_THREADING_USAGE_ERROR – mbedtls_mutex_init() failed, or a mutex usage error was detected. Note that depending on the platform, a mutex usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.

  • PSA_ERROR_INSUFFICIENT_MEMORY – There were insufficient resources to initialize or lock the mutex.

  • PSA_ERROR_BAD_STATE – The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

int mbedtls_mutex_unlock(mbedtls_threading_mutex_t *mutex)

Unlock a mutex.

It must be currently locked by the calling thread.

Note

The behavior is undefined if:

Parameters:

mutex – The mutex to unlock.

Return values:

  • 0 – Success.

  • MBEDTLS_ERR_THREADING_USAGE_ERROR – mbedtls_mutex_init() failed, or a mutex usage error was detected. Note that depending on the platform, a mutex usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.

  • PSA_ERROR_BAD_STATE – The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

int mbedtls_condition_variable_init(mbedtls_threading_condition_variable_t *cond)

Initialize a condition variable.

Note

The behavior is undefined if:

  • cond is already initialized;

  • this function is called concurrently on the same object from multiple threads.

Parameters:

cond – The condition variable to initialize.

Return values:

  • 0 – Success.

  • MBEDTLS_ERR_THREADING_USAGE_ERROR – The condition variable is already initialized (on platforms where this can be detected), or an unpecified error occurred.

  • PSA_ERROR_INSUFFICIENT_MEMORY – There were insufficient resources to initialize the object.

  • PSA_ERROR_BAD_STATE – The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

void mbedtls_condition_variable_free(mbedtls_threading_condition_variable_t *cond)

Destroy a condition variable.

After this function returns, you may call mbedtls_condition_variable_init() again on cond.

Note

The behavior is undefined if:

Parameters:

cond – The condition variable to destroy.

int mbedtls_condition_variable_signal(mbedtls_threading_condition_variable_t *cond)

Wake up one thread that is waiting on the given condition variable.

Do nothing, successfully, if no thread is waiting.

Note

The behavior is undefined if:

Parameters:

cond – The condition variable to signal.

Return values:

  • 0 – Success.

  • MBEDTLS_ERR_THREADING_USAGE_ERROR – A usage error was detected. Note that depending on the platform, a condition variable usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.

  • PSA_ERROR_BAD_STATE – The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

int mbedtls_condition_variable_broadcast(mbedtls_threading_condition_variable_t *cond)

Wake up all threads that are waiting on the given condition variable.

Note

The behavior is undefined if:

Parameters:

cond – The condition variable to signal.

Return values:

  • 0 – Success.

  • MBEDTLS_ERR_THREADING_USAGE_ERROR – A usage error was detected. Note that depending on the platform, a condition variable usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.

  • PSA_ERROR_BAD_STATE – The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

int mbedtls_condition_variable_wait(mbedtls_threading_condition_variable_t *cond, mbedtls_threading_mutex_t *mutex)

Wait for a wakeup signal on a condition variable.

On entry, this function atomically unlocks mutex and blocks until another thread calls mbedtls_condition_variable_signal() or mbedtls_condition_variable_broadcast() on cond.

Before returning, this function locks mutex.

Note

On some platforms, it is possible for this function to stop blocking even if no signal is raised on cond (spurious wakeup).

Note

The behavior is undefined if:

Parameters:

  • cond – The condition variable to wait on.

  • mutex – The mutex to unlock and re-lock. It must currently be locked by the calling thread.

Return values:

  • 0 – Success.

  • MBEDTLS_ERR_THREADING_USAGE_ERROR – A usage error was detected. Note that depending on the platform, a condition variable usage error may result in a deadlock, a crash or other undesirable behavior instead of returning an error.

  • PSA_ERROR_BAD_STATE – The compilation option MBEDTLS_THREADING_ALT is enabled, and mbedtls_threading_set_alt() has not been called.

Variables

mbedtls_threading_mutex_t mbedtls_threading_readdir_mutex
struct mbedtls_threading_mutex_t
#include <threading.h>

Public Members

mbedtls_platform_mutex_t private_mutex
char private_initialized
char private_state
struct mbedtls_threading_condition_variable_t
#include <threading.h>

Public Members

mbedtls_platform_condition_variable_t private_cond