RIOT-OS/RIOT
RIOT-OS/RIOT
1
0
Fork 0
mirror of https://github.com/RIOT-OS/RIOT.git synced 2024-12-29 04:50:03 +01:00
Code Releases Activity
aaa9512d50
RIOT/sys/posix/pthread/include/pthread_mutex_attr.h

223 lines
8.8 KiB
C
Raw Blame History

/*
* Copyright (C) 2014 Freie Universität Berlin
*
* This file is subject to the terms and conditions of the GNU Lesser
* General Public License v2.1. See the file LICENSE in the top level
* directory for more details.
*/
/**
* @ingroup pthread
* @{
* @file
* @brief Attributes for pthread mutexes.
* @note Do not include this header file directly, but pthread.h.
*/
#ifndef PTHREAD_MUTEX_ATTR_H
#define PTHREAD_MUTEX_ATTR_H
#include <errno.h>
#ifdef __cplusplus
extern "C" {
#endif
/**
* @def PTHREAD_MUTEX_NORMAL
* @brief A non-error correcting mutex (default).
*/
/**
* @def PTHREAD_MUTEX_RECURSIVE
* @brief A mutex that allows recursive locking.
* @note Not implemented, yet.
*/
/**
* @def PTHREAD_MUTEX_ERRORCHECK
* @brief A mutex that fails with `EDEADLK` if recursive locking was detected.
* @note Not implemented, yet.
*/
/**
* @def PTHREAD_MUTEX_DEFAULT
* @brief The default mutex kind for RIOT.
* @note Not implemented, yet.
*/
#define PTHREAD_MUTEX_NORMAL 0
#define PTHREAD_MUTEX_RECURSIVE 1
#define PTHREAD_MUTEX_ERRORCHECK 2
#define PTHREAD_MUTEX_DEFAULT PTHREAD_MUTEX_NORMAL
/**
* @def PTHREAD_PRIO_NONE
* @brief No priority inheritance.
* @details Prone to inversed priorities.
* The default mutex protocol.
*/
/**
* @def PTHREAD_PRIO_INHERIT
* @brief If a thread attempts to acquire a held lock,
* the holding thread gets its dynamic priority increased up to
* the priority of the blocked thread
* @note Not implemented, yet.
*/
#define PTHREAD_PRIO_NONE 0
#define PTHREAD_PRIO_INHERIT 1
/**
* @def PTHREAD_PRIO_PROTECT
* @brief Not implemented, yet.
*/
/**
* @def PTHREAD_MUTEX_STALLED
* @brief Mutexes aren't automatically released on the end of a thread.
* @see #pthread_cleanup_push() for an option to unlock mutexes on the end of a thread.
* @note This is the default.
*/
/**
* @def PTHREAD_MUTEX_ROBUST
* @brief Mutexes that are held at the exit of a thread get released automatically.
* @note Not implemented, yet.
*/
#define PTHREAD_PRIO_PROTECT 2
#define PTHREAD_MUTEX_STALLED 0
#define PTHREAD_MUTEX_ROBUST 1
/**
* @brief This type is unused right now, and only exists for POSIX compatibility.
*/
typedef struct
{
int pshared; /**< Whether to share the mutex with child processes. */
int kind; /**< Type of the mutex. */
int protocol; /**< Priority inheritance of the mutex. */
int robustness; /**< What to do if a thread terminates while it holds a mutex. */
} pthread_mutexattr_t;
/**
* @brief Initialize a pthread_mutexattr_t
* @details A zeroed out datum is initialized
* @note This function is not implemented, yet.
* @param[out] attr Datum to initialize.
* @returns `0` on success.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_init(pthread_mutexattr_t *attr);
/**
* @brief Destroys a pthread_mutexattr_t
* @details There is no need to ever call this function.
* This function is a no-op.
* @note This function is not implemented, yet.
* @param[in,out] attr Datum to destroy.
* @returns `0` on success.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_destroy(pthread_mutexattr_t *attr);
/**
* @brief Queries the attribute set whether to share the mutex with child processes.
* @note Since RIOT does not implement processes, this value is unused.
* @param[in] attr Attribute set to query.
* @param[out] pshared Either #PTHREAD_PROCESS_SHARED or #PTHREAD_PROCESS_PRIVATE.
* @returns `0` on success.
* `EINVAL` if `attr` or `pshared` are `NULL`.
*/
int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, int *pshared);
/**
* @brief Set whether to share the mutex with child processes.
* @note Since RIOT does not implement processes, this value is unused.
* @param[in,out] attr Attribute set to change.
* @param[in] pshared Either #PTHREAD_PROCESS_SHARED or #PTHREAD_PROCESS_PRIVATE.
* @returns `0` on success.
* `EINVAL` if `pshared` is neither #PTHREAD_PROCESS_SHARED nor #PTHREAD_PROCESS_PRIVATE.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, int pshared);
/**
* @brief Query the type of the mutex to create.
* @note This implementation only supports PTHREAD_MUTEX_NORMAL mutexes.
* @param[in] attr Attribute set to query.
* @param[out] kind Either #PTHREAD_MUTEX_NORMAL or #PTHREAD_MUTEX_RECURSIVE or #PTHREAD_MUTEX_ERRORCHECK.
* @returns `0` on success.
* `EINVAL` if `attr` or `kind` are `NULL`.
*/
int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, int *kind);
/**
* @brief Sets the type of the mutex to create.
* @note This implementation only supports `PTHREAD_MUTEX_NORMAL` mutexes.
* @param[in,out] attr Attribute set to change.
* @param[in] kind Either #PTHREAD_MUTEX_NORMAL or #PTHREAD_MUTEX_RECURSIVE or #PTHREAD_MUTEX_ERRORCHECK.
* @returns `0` on success.
* `EINVAL` if the value of `kind` is unsupported.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int kind);
/**
* @brief Query the priority inheritance of the mutex to create.
* @note This implementation only supports `PTHREAD_PRIO_NONE` mutexes.
* @param[in] attr Attribute set to query
* @param[out] protocol Either #PTHREAD_PRIO_NONE or #PTHREAD_PRIO_INHERIT or #PTHREAD_PRIO_PROTECT.
* @returns `0` on success.
* `EINVAL` if `attr` or `protocol` are `NULL`.
*/
int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, int *protocol);
/**
* @brief Sets the priority inheritance of the mutex to create.
* @note This implementation only supports `PTHREAD_PRIO_NONE` mutexes.
* @param[in,out] attr Attribute set to change.
* @param[in] protocol Either #PTHREAD_PRIO_NONE or #PTHREAD_PRIO_INHERIT or #PTHREAD_PRIO_PROTECT.
* @returns `0` on success.
* `EINVAL` if the value of `protocol` is unsupported.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, int protocol);
/* Return in *PRIOCEILING the mutex prioceiling attribute in *ATTR. */
int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr, int *prioceiling);
/* Set the mutex prioceiling attribute in *ATTR to PRIOCEILING. */
int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, int prioceiling);
/**
* @brief Query the attribute set whether to create a robut mutex.
* @details A "robust" mutex releases gets released automagically if the threads exits while it hold the mutex.
* If the thread is cancellable, only rubust mutex should be held.
* @note This implementation does not support robust mutexes, yet.
* As it doesn't implement cancellation points, yet, this should not pose a problem.
* @param[in] attr Attribute set to query.
* @param[out] robustness Either #PTHREAD_MUTEX_STALLED or #PTHREAD_MUTEX_ROBUST.
* @returns `0` on success.
* `EINVAL` if the value of `protocol` is unsupported.
* `EINVAL` if `attr` or `robustness` is `NULL`.
*/
int pthread_mutexattr_getrobust(const pthread_mutexattr_t *attr, int *robustness);
/**
* @brief Set whether the mutex to create should be robust.
* @details A "robust" mutex releases gets released automagically if the threads exits while it hold the mutex.
* If the thread is cancellable, only rubust mutex should be held.
* @note This implementation does not support robust mutexes, yet.
* As it doesn't implement cancellation points, yet, this should not pose a problem.
* @param[in,out] attr Attribute set to change.
* @param[in] robustness Either #PTHREAD_MUTEX_STALLED or #PTHREAD_MUTEX_ROBUST.
* @returns `0` on success.
* `EINVAL` if the value of `robustness` is unsupported.
* `EINVAL` if `attr == NULL`.
*/
int pthread_mutexattr_setrobust(pthread_mutexattr_t *attr, int robustness);
#ifdef __cplusplus
}
#endif
#endif /* PTHREAD_MUTEX_ATTR_H */
/**
* @}
*/
View Git Blame Copy Permalink