diff options
Diffstat (limited to 'cpukit/posix/include/rtems/posix/pthread.h')
| -rw-r--r-- | cpukit/posix/include/rtems/posix/pthread.h | 135 |
1 files changed, 69 insertions, 66 deletions
diff --git a/cpukit/posix/include/rtems/posix/pthread.h b/cpukit/posix/include/rtems/posix/pthread.h index 5932d45a39..5250b70d0f 100644 --- a/cpukit/posix/include/rtems/posix/pthread.h +++ b/cpukit/posix/include/rtems/posix/pthread.h @@ -1,5 +1,7 @@ /** - * @file rtems/posix/pthread.h + * @file + * + * @brief POSIX Threads Private Support * * This include file contains all the private support information for * POSIX threads. @@ -21,12 +23,6 @@ #include <rtems/posix/config.h> #include <rtems/posix/threadsup.h> -/** - * @defgroup POSIX_PTHREADS Private Threads - * - * @ingroup POSIX - */ -/**@{*/ #ifdef __cplusplus extern "C" { #endif @@ -34,80 +30,82 @@ extern "C" { /** * @defgroup POSIX_PTHREAD POSIX Threads Support * - * @ingroup POSIX + * @ingroup POSIXAPI * * @brief Private Support Information for POSIX Threads + * */ +/**@{**/ /** - * The following sets the minimum stack size for POSIX threads. + * The following sets the minimum stack size for POSIX threads. */ #define PTHREAD_MINIMUM_STACK_SIZE (_Stack_Minimum() * 2) /** - * The following defines the information control block used to manage - * this class of objects. + * The following defines the information control block used to manage + * this class of objects. */ POSIX_EXTERN Objects_Information _POSIX_Threads_Information; /** - * This variable contains the default POSIX Thread attributes. + * This variable contains the default POSIX Thread attributes. */ extern const pthread_attr_t _POSIX_Threads_Default_attributes; /** - * When the user configures a set of POSIX API initialization threads, - * This variable will point to the method used to initialize them. + * When the user configures a set of POSIX API initialization threads, + * This variable will point to the method used to initialize them. * - * @note It is instantiated and initialized by confdefs.h based upon - * application requirements. + * NOTE: It is instantiated and initialized by confdefs.h based upon + * application requirements. */ extern void (*_POSIX_Threads_Initialize_user_threads_p)(void); /** - * @brief _POSIX_Threads_Manager_initialization + * @brief POSIX threads manager initialization. * - * This routine performs the initialization necessary for this manager. + * This routine performs the initialization necessary for this manager. */ void _POSIX_Threads_Manager_initialization(void); /** - * @brief _POSIX_Threads_Allocate + * @brief Allocate POSIX thread control block. * - * This function allocates a pthread control block from - * the inactive chain of free pthread control blocks. + * This function allocates a pthread control block from + * the inactive chain of free pthread control blocks. * - * @return This method returns a newly allocated thread. + * @return This method returns a newly allocated thread. */ RTEMS_INLINE_ROUTINE Thread_Control *_POSIX_Threads_Allocate( void ); /** - * @brief _POSIX_Threads_Free + * @brief Free POSIX control block. * - * This routine frees a pthread control block to the - * inactive chain of free pthread control blocks. + * This routine frees a pthread control block to the + * inactive chain of free pthread control blocks. * - * @param[in] the_pthread is the thread to free + * @param[in] the_pthread is a pointer to the thread to free. */ RTEMS_INLINE_ROUTINE void _POSIX_Threads_Free( Thread_Control *the_pthread ); /** - * @brief _POSIX_Threads_Get + * @brief Map POSIX thread IDs to control blocks. * - * This function maps pthread IDs to pthread control blocks. - * If ID corresponds to a local pthread, then it returns - * the_pthread control pointer which maps to ID and location - * is set to OBJECTS_LOCAL. if the pthread ID is global and - * resides on a remote node, then location is set to OBJECTS_REMOTE, - * and the_pthread is undefined. Otherwise, location is set - * to OBJECTS_ERROR and the_pthread is undefined. + * This function maps pthread IDs to pthread control blocks. + * If ID corresponds to a local pthread, then it returns + * the_pthread control pointer which maps to ID and location + * is set to OBJECTS_LOCAL. if the pthread ID is global and + * resides on a remote node, then location is set to OBJECTS_REMOTE, + * and the_pthread is undefined. Otherwise, location is set + * to OBJECTS_ERROR and the_pthread is undefined. * - * @param[in] id is the id to lookup - * @param[in] location points to the returned location value + * @param[in] id is the id to lookup + * @param[in] location points to the returned location value * - * @return This methods returns a pointer to the corresponding Thread_Control. + * @return This methods returns a pointer to the corresponding Thread_Control. */ RTEMS_INLINE_ROUTINE Thread_Control *_POSIX_Threads_Get( pthread_t id, @@ -115,43 +113,45 @@ RTEMS_INLINE_ROUTINE Thread_Control *_POSIX_Threads_Get( ); /** - * @brief _POSIX_Threads_Is_null + * @brief Check if a POSIX thread control block is NULL. * - * This function returns TRUE if the_pthread is NULL and FALSE otherwise. + * This function returns @c TRUE if the_pthread is @c NULL and @c FALSE + * otherwise. * - * @param[in] the_pthread is the thread pointer to check. + * @param[in] the_pthread is a pointer to the POSIX thread control block + * to check. * - * @return This method returns true if the thread pointer is null. + * @retval TRUE The thread control block is @c NULL. + * @retval FALSE The thread control block is not @c NULL. */ RTEMS_INLINE_ROUTINE bool _POSIX_Threads_Is_null( Thread_Control *the_pthread ); /** - * @brief _POSIX_Threads_Sporadic_budget_callout + * @brief POSIX threads sporadic budget callout. * - * This routine handles the sporadic scheduling algorithm. + * This routine handles the sporadic scheduling algorithm. * - * @param[in] the_thread is the thread whose budget has been exceeded. + * @param[in] the_thread is a pointer to the thread whose budget + * has been exceeded. */ void _POSIX_Threads_Sporadic_budget_callout( Thread_Control *the_thread ); /** - * _POSIX_Threads_Sporadic_budget_TSR + * This routine supports the sporadic scheduling algorithm. It + * is scheduled to be executed at the end of each replenishment + * period. In sporadic scheduling a thread will execute at a + * high priority for a user specified amount of CPU time. When + * it exceeds that amount of CPU time, its priority is automatically + * lowered. This TSR is executed when it is time to replenish + * the thread's processor budget and raise its priority. * - * This routine supports the sporadic scheduling algorithm. It - * is scheduled to be executed at the end of each replenishment - * period. In sporadic scheduling a thread will execute at a - * high priority for a user specified amount of CPU time. When - * it exceeds that amount of CPU time, its priority is automatically - * lowered. This TSR is executed when it is time to replenish - * the thread's processor budget and raise its priority. - * - * @param[in] id is ignored - * @param[in] argument is a pointer to the Thread_Control structure - * for the thread being replenished. + * @param[in] id is ignored + * @param[in] argument is a pointer to the Thread_Control structure + * for the thread being replenished. */ void _POSIX_Threads_Sporadic_budget_TSR( Objects_Id id, @@ -159,17 +159,18 @@ void _POSIX_Threads_Sporadic_budget_TSR( ); /** - * @brief Translate sched_param into SuperCore Terms + * @brief Translate sched_param into SuperCore terms. * - * This method translates the POSIX API sched_param into the corresponding - * SuperCore settings. + * This method translates the POSIX API sched_param into the corresponding + * SuperCore settings. * - * @param[in] policy is the POSIX scheduling policy - * @param[in] param points to the scheduling parameter structure - * @param[in] budget_algorithm points to the output CPU Budget algorithm - * @param[in] budget_callout points to the output CPU Callout + * @param[in] policy is the POSIX scheduling policy + * @param[in] param points to the scheduling parameter structure + * @param[in] budget_algorithm points to the output CPU Budget algorithm + * @param[in] budget_callout points to the output CPU Callout * - * @return This method returns 0 on success or a POSIX error code. + * @retval 0 Indicates success. + * @retval error_code POSIX error code indicating failure. */ int _POSIX_Thread_Translate_sched_param( int policy, @@ -179,7 +180,7 @@ int _POSIX_Thread_Translate_sched_param( ); /** - * @brief POSIX Threads Initialize User Threads Body + * @brief POSIX threads initialize user threads body. * * This routine creates and starts all configured user * initialization threads. @@ -188,9 +189,11 @@ extern void _POSIX_Threads_Initialize_user_threads_body(void); #include <rtems/posix/pthread.inl> +/** @} */ + #ifdef __cplusplus } #endif -/**@}*/ + #endif /* end of include file */ |