diff options
Diffstat (limited to 'cpukit/score/include/rtems/score/threadq.h')
| -rw-r--r-- | cpukit/score/include/rtems/score/threadq.h | 412 |
1 files changed, 63 insertions, 349 deletions
diff --git a/cpukit/score/include/rtems/score/threadq.h b/cpukit/score/include/rtems/score/threadq.h index 3fec37953c..5879576bcf 100644 --- a/cpukit/score/include/rtems/score/threadq.h +++ b/cpukit/score/include/rtems/score/threadq.h @@ -1,14 +1,14 @@ /** - * @file rtems/score/threadq.h + * @file * - * Constants and Structures Associated with the Manipulation of Objects + * @brief Constants and Structures Needed to Declare a Thread Queue * - * This include file contains all the constants and structures associated - * with the manipulation of objects. + * This include file contains all the constants and structures + * needed to declare a thread queue. */ /* - * COPYRIGHT (c) 1989-2009. + * COPYRIGHT (c) 1989-2008. * On-Line Applications Research Corporation (OAR). * * The license and distribution terms for this file may be @@ -19,363 +19,77 @@ #ifndef _RTEMS_SCORE_THREADQ_H #define _RTEMS_SCORE_THREADQ_H -#include <rtems/score/tqdata.h> - -#include <rtems/score/object.h> -#include <rtems/score/thread.h> -#include <rtems/score/watchdog.h> +#include <rtems/score/chain.h> +#include <rtems/score/states.h> +#include <rtems/score/threadsync.h> #ifdef __cplusplus extern "C" { #endif /** - * @defgroup ScoreThreadQ Thread Queue Handler + * @defgroup ScoreThreadQueue Thread Queue Handler * * @ingroup Score * - * This handler encapsulates functionality related to managing sets of threads - * blocked waiting for resources. + * This handler defines the data shared between the thread and thread + * queue handlers. Having this handler define these data structure + * avoids potentially circular references. */ /**@{*/ /** - * Constant for indefinite wait. - */ -#define THREAD_QUEUE_WAIT_FOREVER WATCHDOG_NO_TIMEOUT - -/** - * The following type defines the callout used when a remote task - * is extracted from a local thread queue. - */ -typedef void ( *Thread_queue_Flush_callout )( - Thread_Control * - ); - -/** - * The following type defines the callout used for timeout processing - * methods. - */ -typedef void ( *Thread_queue_Timeout_callout )( - Objects_Id, - void * - ); - -/** - * @brief Gets a pointer to a thread waiting on the_thread_queue. - * - * This function returns a pointer to a thread waiting on - * the_thread_queue. The selection of this thread is based on - * the discipline of the_thread_queue. If no threads are waiting - * on the_thread_queue, then NULL is returned. - */ -Thread_Control *_Thread_queue_Dequeue( - Thread_queue_Control *the_thread_queue -); - -/** - * @brief Enqueues the currently executing thread on the_thread_queue. - * - * This routine enqueues the currently executing thread on - * the_thread_queue with an optional timeout. - */ -#define _Thread_queue_Enqueue( _the_thread_queue, _timeout ) \ - _Thread_queue_Enqueue_with_handler( \ - _the_thread_queue, \ - _timeout, \ - _Thread_queue_Timeout ) - -/** - * @brief Blocks a thread and places it on a thread. - * - * This routine blocks a thread, places it on a thread, and optionally - * starts a timeout timer. - * - * @param[in] the_thread_queue pointer to threadq - * @param[in] timeout interval to wait - * - * - INTERRUPT LATENCY: - * + single case - */ -void _Thread_queue_Enqueue_with_handler( - Thread_queue_Control* the_thread_queue, - Watchdog_Interval timeout, - Thread_queue_Timeout_callout handler -); - -/** - * @brief Invoked when a thread changes priority and is blocked. - * - * This routine is invoked when a thread changes priority and is - * blocked on a thread queue. If the queue is priority ordered, - * the_thread is removed from the_thread_queue and reinserted using - * its new priority. This method has no impact on the state of the_thread - * or of any timeouts associated with this blocking. - * - * @param[in] the_thread_queue pointer to a threadq header - * @param[in] the_thread pointer to a thread control block - */ -void _Thread_queue_Requeue( - Thread_queue_Control *the_thread_queue, - Thread_Control *the_thread -); - -/** - * @brief Extracts thread from thread queue. - * - * This routine removes @a the_thread from @a the_thread_queue - * and cancels any timeouts associated with this blocking. - * - * @param[in] the_thread_queue is the pointer to the ThreadQ header - * @param[in] the_thread is the pointer to a thread control block that is to be removed - */ -void _Thread_queue_Extract( - Thread_queue_Control *the_thread_queue, - Thread_Control *the_thread -); - -/** - * @brief Extracts the_thread from the_thread_queue. - * - * This routine extracts the_thread from the_thread_queue - * and ensures that if there is a proxy for this task on - * another node, it is also dealt with. - */ -bool _Thread_queue_Extract_with_proxy( - Thread_Control *the_thread -); - -/** - * @brief Gets a pointer to the "first" thread on the_thread_queue. - * - * This function returns a pointer to the "first" thread - * on the_thread_queue. The "first" thread is selected - * based on the discipline of the_thread_queue. - * - * @param[in] the_thread_queue pointer to thread queue - * - * @retval first thread or NULL - */ -Thread_Control *_Thread_queue_First( - Thread_queue_Control *the_thread_queue -); - -/** - * @brief Unblocks all threads blocked on the_thread_queue. - * - * This routine unblocks all threads blocked on the_thread_queue - * and cancels any associated timeouts. - * - * @param[in] the_thread_queue is the pointer to a threadq header - * @param[in] remote_extract_callout points to a method to invoke to - * invoke when a remote thread is unblocked - * @param[in] status is the status which will be returned to - * all unblocked threads - */ -void _Thread_queue_Flush( - Thread_queue_Control *the_thread_queue, - Thread_queue_Flush_callout remote_extract_callout, - uint32_t status -); - -/** - * @brief Initialize the_thread_queue. - * - * This routine initializes the_thread_queue based on the - * discipline indicated in attribute_set. The state set on - * threads which block on the_thread_queue is state. - * - * @param[in] the_thread_queue is the pointer to a threadq header - * @param[in] the_discipline is the queueing discipline - * @param[in] state is the state of waiting threads - * @param[in] timeout_status is the return on a timeout - */ -void _Thread_queue_Initialize( - Thread_queue_Control *the_thread_queue, - Thread_queue_Disciplines the_discipline, - States_Control state, - uint32_t timeout_status -); - -/** - * @brief Removes a thread from the specified PRIORITY based - * threadq, unblocks it, and cancels its timeout timer. - * - * This routine removes a thread from the specified PRIORITY based - * threadq, unblocks it, and cancels its timeout timer. - * - * - INTERRUPT LATENCY: - * + single case - * - * @param[in] the_thread_queue is a pointer to a thread queue - * - * @retval thread dequeued - * @retval NULL if no thread are waiting on the_thread_queue - */ -Thread_Control *_Thread_queue_Dequeue_priority( - Thread_queue_Control *the_thread_queue -); - -/** - * @brief Enqueues the currently executing thread on the_thread_queue. - * - * This routine enqueues the currently executing thread on - * the_thread_queue with an optional timeout using the - * priority discipline. - * - * @param[in] the_thread_queue is the pointer to threadq - * @param[in] the_thread is the thread to insert - * @param[in] level_p is a pointer to an interrupt level to be returned - * - * @retval This methods returns an indication of the blocking state as - * well as filling in *@ level_p with the previous interrupt level. - * - * - INTERRUPT LATENCY: - * + forward less than - * + forward equal - */ -Thread_blocking_operation_States _Thread_queue_Enqueue_priority ( - Thread_queue_Control *the_thread_queue, - Thread_Control *the_thread, - ISR_Level *level_p -); - -/** - * @brief Removes the_thread and cancels related timeouts. - * - * This routine removes the_thread from the_thread_queue - * and cancels any timeouts associated with this blocking. - * @param[in] the_thread_queue pointer to a threadq header - * @param[in] the_thread pointer to a thread control block - * @param[in] requeuing true if requeuing and should not alter - * timeout or state - * - INTERRUPT LATENCY: - * + EXTRACT_PRIORITY - */ -void _Thread_queue_Extract_priority_helper( - Thread_queue_Control *the_thread_queue, - Thread_Control *the_thread, - bool requeuing -); - -/** - * @brief Wraps the underlying call and hides the requeuing argument. - * - * This macro wraps the underlying call and hides the requeuing argument. - */ - -#define _Thread_queue_Extract_priority( _the_thread_queue, _the_thread ) \ - _Thread_queue_Extract_priority_helper( _the_thread_queue, _the_thread, false ) -/** - * @brief Get highest priority thread on the_thread_queue. - * - * This function returns a pointer to the "first" thread - * on @a the_thread_queue. The "first" thread is the highest - * priority thread waiting on @a the_thread_queue. - * - * @param[in] the_thread_queue is the pointer to the thread queue - * @retval first thread or NULL - */ -Thread_Control *_Thread_queue_First_priority( - Thread_queue_Control *the_thread_queue -); - -/** - * @brief Gets a pointer to the thread which has been waiting the longest. - * - * This function returns a pointer to the thread which has - * been waiting the longest on the_thread_queue. If no - * threads are waiting on the_thread_queue, then NULL is returned. - * - * @param[in] the_thread_queue is the pointer to threadq - * - * @retval thread dequeued or NULL - * - * - INTERRUPT LATENCY: - * + check sync - * + FIFO - */ -Thread_Control *_Thread_queue_Dequeue_fifo( - Thread_queue_Control *the_thread_queue -); - -/** - * @brief Enqueues the currently executing thread on the_thread_queue. - * - * This routine enqueues the currently executing thread on - * the_thread_queue with an optional timeout using the - * FIFO discipline. - * - * @param[in] the_thread_queue pointer to threadq - * @param[in] the_thread pointer to the thread to block - * @param[in] level_p interrupt level in case the operation blocks actually - * - * - INTERRUPT LATENCY: - * + single case - */ -Thread_blocking_operation_States _Thread_queue_Enqueue_fifo ( - Thread_queue_Control *the_thread_queue, - Thread_Control *the_thread, - ISR_Level *level_p -); - -/** - * @brief Removes the_thread from the_thread_queue and cancels any timeouts. - * - * This routine removes the_thread from the_thread_queue - * and cancels any timeouts associated with this blocking. - */ -void _Thread_queue_Extract_fifo( - Thread_queue_Control *the_thread_queue, - Thread_Control *the_thread -); - -/** - * @brief Gets a pointer to the "first" thread on the_thread_queue. - * - * This function returns a pointer to the "first" thread - * on the_thread_queue. The first thread is the thread - * which has been waiting longest on the_thread_queue. - * - * @param[in] the_thread_queue is the pointer to threadq - * - * @retval first thread or NULL - */ -Thread_Control *_Thread_queue_First_fifo( - Thread_queue_Control *the_thread_queue -); - -/** - * @brief Thread queue timeout. - * - * This routine is invoked when a task's request has not - * been satisfied after the timeout interval specified to - * enqueue. The task represented by ID will be unblocked and - * its status code will be set in it's control block to indicate - * that a timeout has occurred. - * - * @param[in] id thread id - */ -void _Thread_queue_Timeout ( - Objects_Id id, - void *ignored -); - -/** - * @brief Process thread queue timeout. - * - * This is a shared helper routine which makes it easier to have multiple - * object class specific timeout routines. - * - * @param[in] the_thread is the thread to extract - * - * @note This method assumes thread dispatching is disabled - * and is expected to be called via the processing of - * a clock tick. - */ -void _Thread_queue_Process_timeout( - Thread_Control *the_thread -); + * The following enumerated type details all of the disciplines + * supported by the Thread Queue Handler. + */ +typedef enum { + THREAD_QUEUE_DISCIPLINE_FIFO, /* FIFO queue discipline */ + THREAD_QUEUE_DISCIPLINE_PRIORITY /* PRIORITY queue discipline */ +} Thread_queue_Disciplines; + +/** + * This is one of the constants used to manage the priority queues. + * + * There are four chains used to maintain a priority -- each chain + * manages a distinct set of task priorities. The number of chains + * is determined by TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS. + * The following set must be consistent. + * + * The set below configures 4 headers -- each contains 64 priorities. + * Header x manages priority range (x*64) through ((x*64)+63). If + * the priority is more than half way through the priority range it + * is in, then the search is performed from the rear of the chain. + * This halves the search time to find the insertion point. + */ +#define TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS 4 + +/** + * This is the structure used to manage sets of tasks which are blocked + * waiting to acquire a resource. + */ +typedef struct { + /** This union contains the data structures used to manage the blocked + * set of tasks which varies based upon the discipline. + */ + union { + /** This is the FIFO discipline list. */ + Chain_Control Fifo; + /** This is the set of lists for priority discipline waiting. */ + Chain_Control Priority[TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS]; + } Queues; + /** This field is used to manage the critical section. */ + Thread_blocking_operation_States sync_state; + /** This field indicates the thread queue's blocking discipline. */ + Thread_queue_Disciplines discipline; + /** This indicates the blocking state for threads waiting on this + * thread queue. + */ + States_Control state; + /** This is the status value returned to threads which timeout while + * waiting on this thread queue. + */ + uint32_t timeout_status; +} Thread_queue_Control; /**@}*/ |