forked from Imagelibrary/rtems
doxygen: score: adjust doc in priorityimpl.h to doxygen guidelines
Update #3706.
This commit is contained in:
Andreas Dachsberger
committed by
Sebastian Huber
Sebastian Huber
parent
1d6e6b1feb
commit
35a07c4682
@@ -1,3 +1,11 @@
|
||||
/**
|
||||
* @file
|
||||
*
|
||||
* @ingroup RTEMSScorePriority
|
||||
*
|
||||
* @brief Priority Handler API Implementation.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Copyright (c) 2016 embedded brains GmbH. All rights reserved.
|
||||
*
|
||||
@@ -22,6 +30,17 @@
|
||||
extern "C" {
|
||||
#endif /* __cplusplus */
|
||||
|
||||
/**
|
||||
* @addtogroup RTEMSScorePriority
|
||||
*
|
||||
* @{
|
||||
*/
|
||||
|
||||
/**
|
||||
* @brief Initializes the priority actions empty.
|
||||
*
|
||||
* @param[out] actions The actions to be initialized empty.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_empty(
|
||||
Priority_Actions *actions
|
||||
)
|
||||
@@ -29,6 +48,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_empty(
|
||||
actions->actions = NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Initializes the priority actions with the given information.
|
||||
*
|
||||
* @param[out] actions The actions to be initialized.
|
||||
* @param aggregation The aggregation for the @a actions to be initialized.
|
||||
* @param node The action node for the @a actions to be initialized.
|
||||
* @param type The action type for the @a actions to be initialized.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_one(
|
||||
Priority_Actions *actions,
|
||||
Priority_Aggregation *aggregation,
|
||||
@@ -45,6 +72,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Actions_initialize_one(
|
||||
actions->actions = aggregation;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Checks if the priority actions is empty.
|
||||
*
|
||||
* @param actions The priority actions to check if it is empty.
|
||||
*
|
||||
* @retval true The priority actions @a actions is empty.
|
||||
* @retval false The priority actions @a actions is empty.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_empty(
|
||||
const Priority_Actions *actions
|
||||
)
|
||||
@@ -52,6 +87,14 @@ RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_empty(
|
||||
return actions->actions == NULL;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Checks if the priority actions is valid.
|
||||
*
|
||||
* @param aggregation The aggregation of the priority action.
|
||||
*
|
||||
* @retval true The @a aggregation is valid.
|
||||
* @retval false The @a aggregation is not valid.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_valid(
|
||||
const Priority_Aggregation *aggregation
|
||||
)
|
||||
@@ -64,6 +107,13 @@ RTEMS_INLINE_ROUTINE bool _Priority_Actions_is_valid(
|
||||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Moves the priority actions' actions.
|
||||
*
|
||||
* @param[in, out] actions The priority actions to move the actions away from.
|
||||
*
|
||||
* @return The former actions of @a actions that were moved.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Actions_move(
|
||||
Priority_Actions *actions
|
||||
)
|
||||
@@ -76,6 +126,12 @@ RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Actions_move(
|
||||
return aggregation;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Adds actions to the priority actions' actions.
|
||||
*
|
||||
* @param[in, out] actions The priority actions to add actions to.
|
||||
* @param[out] aggregation The actions to add to @a actions.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Actions_add(
|
||||
Priority_Actions *actions,
|
||||
Priority_Aggregation *aggregation
|
||||
@@ -91,6 +147,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Actions_add(
|
||||
actions->actions = aggregation;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Initializes the priority node to the given priority.
|
||||
*
|
||||
* @param[out] node The priority node to be initialized.
|
||||
* @param priority The priority to initialize @a node to.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Node_initialize(
|
||||
Priority_Node *node,
|
||||
Priority_Control priority
|
||||
@@ -100,6 +162,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Node_initialize(
|
||||
_RBTree_Initialize_node( &node->Node.RBTree );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Sets the priority of the priority node to the given priority.
|
||||
*
|
||||
* @param[out] node The priority node to set the priority of.
|
||||
* @param priority The new priority for @a node.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Node_set_priority(
|
||||
Priority_Node *node,
|
||||
Priority_Control priority
|
||||
@@ -108,6 +176,11 @@ RTEMS_INLINE_ROUTINE void _Priority_Node_set_priority(
|
||||
node->priority = priority;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Sets the priority node inactive.
|
||||
*
|
||||
* @param[in, out] node The priority node to set inactive.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Node_set_inactive(
|
||||
Priority_Node *node
|
||||
)
|
||||
@@ -115,6 +188,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Node_set_inactive(
|
||||
_RBTree_Set_off_tree( &node->Node.RBTree );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Checks if the priority node is active.
|
||||
*
|
||||
* @param node The priority node that shall be verified if it is active.
|
||||
*
|
||||
* @retval true The priority node is active.
|
||||
* @retval false The priority node is inactive.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE bool _Priority_Node_is_active(
|
||||
const Priority_Node *node
|
||||
)
|
||||
@@ -122,6 +203,11 @@ RTEMS_INLINE_ROUTINE bool _Priority_Node_is_active(
|
||||
return !_RBTree_Is_node_off_tree( &node->Node.RBTree );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Initializes the priority aggregation empty.
|
||||
*
|
||||
* @param[out] aggregation The priority aggregaton to initialize empty.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Initialize_empty(
|
||||
Priority_Aggregation *aggregation
|
||||
)
|
||||
@@ -137,6 +223,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Initialize_empty(
|
||||
_RBTree_Initialize_empty( &aggregation->Contributors );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Initializes the priority aggregation with the given information.
|
||||
*
|
||||
* @param[out] aggregation The priority aggregaton to initialize.
|
||||
* @param node The priority node to initialize @a aggregation with.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Initialize_one(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node
|
||||
@@ -153,6 +245,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Initialize_one(
|
||||
_RBTree_Initialize_one( &aggregation->Contributors, &node->Node.RBTree );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Checks if the priority aggregation is empty.
|
||||
*
|
||||
* @param aggregation The priority aggregation that shall be verified if it is empty.
|
||||
*
|
||||
* @retval true The priority aggregation is empty.
|
||||
* @retval false The priority aggregation is not empty.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE bool _Priority_Is_empty(
|
||||
const Priority_Aggregation *aggregation
|
||||
)
|
||||
@@ -160,6 +260,13 @@ RTEMS_INLINE_ROUTINE bool _Priority_Is_empty(
|
||||
return _RBTree_Is_empty( &aggregation->Contributors );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Gets the priority aggregation's priority.
|
||||
*
|
||||
* @param aggregation The priority aggregation to get the priority from.
|
||||
*
|
||||
* @return The priority of @a aggregation.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE Priority_Control _Priority_Get_priority(
|
||||
const Priority_Aggregation *aggregation
|
||||
)
|
||||
@@ -167,6 +274,13 @@ RTEMS_INLINE_ROUTINE Priority_Control _Priority_Get_priority(
|
||||
return aggregation->Node.priority;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Gets the priority aggregation's scheduler.
|
||||
*
|
||||
* @param aggregation The priority aggregation to get the scheduler from.
|
||||
*
|
||||
* @return The scheduler of @a aggregation.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE const Scheduler_Control *_Priority_Get_scheduler(
|
||||
const Priority_Aggregation *aggregation
|
||||
)
|
||||
@@ -178,6 +292,13 @@ RTEMS_INLINE_ROUTINE const Scheduler_Control *_Priority_Get_scheduler(
|
||||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Gets the minimum node of the priority aggregation
|
||||
*
|
||||
* @param aggregation The priority aggregation to get the minimum node from.
|
||||
*
|
||||
* @return The minimum node of @a aggregation
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE Priority_Node *_Priority_Get_minimum_node(
|
||||
const Priority_Aggregation *aggregation
|
||||
)
|
||||
@@ -185,6 +306,12 @@ RTEMS_INLINE_ROUTINE Priority_Node *_Priority_Get_minimum_node(
|
||||
return (Priority_Node *) _RBTree_Minimum( &aggregation->Contributors );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Sets the action node of the priority aggregation.
|
||||
*
|
||||
* @param[out] aggregation The priority aggregation to set the action node of.
|
||||
* @param node The new priority node for @a aggregation.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Set_action_node(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node
|
||||
@@ -193,6 +320,12 @@ RTEMS_INLINE_ROUTINE void _Priority_Set_action_node(
|
||||
aggregation->Action.node = node;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Sets the action type of the priority aggregation.
|
||||
*
|
||||
* @param[out] aggregation The priority aggregation to set the action type of.
|
||||
* @param type The new action type for @a aggregation.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Set_action_type(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Action_type type
|
||||
@@ -201,6 +334,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Set_action_type(
|
||||
aggregation->Action.type = type;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Sets the action type and action node of the priority aggregation.
|
||||
*
|
||||
* @param[out] aggregation The priority aggregation to set the action type
|
||||
* and action node of.
|
||||
* @param node The new action node for @a aggregation.
|
||||
* @param type The new action type for @a aggregation.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Set_action(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node,
|
||||
@@ -211,6 +352,14 @@ RTEMS_INLINE_ROUTINE void _Priority_Set_action(
|
||||
aggregation->Action.type = type;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Gets the next action of the priority aggregation.
|
||||
*
|
||||
* @param aggregation The priority aggregation to get the next action of.
|
||||
*
|
||||
* @retval next_action The next action of @a aggregation if RTEMS_SMP is defined.
|
||||
* @retval NULL RTEMS_SMP is not defined.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Get_next_action(
|
||||
const Priority_Aggregation *aggregation
|
||||
)
|
||||
@@ -223,6 +372,15 @@ RTEMS_INLINE_ROUTINE Priority_Aggregation *_Priority_Get_next_action(
|
||||
#endif
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Compares two priorities.
|
||||
*
|
||||
* @param left The priority control on the left hand side of the comparison.
|
||||
* @param right THe RBTree_Node to get the priority for the comparison from.
|
||||
*
|
||||
* @retval true The priority on the left hand side of the comparison is smaller.
|
||||
* @retval false The priority on the left hand side of the comparison is greater of equal.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE bool _Priority_Less(
|
||||
const void *left,
|
||||
const RBTree_Node *right
|
||||
@@ -237,6 +395,19 @@ RTEMS_INLINE_ROUTINE bool _Priority_Less(
|
||||
return *the_left < the_right->priority;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Inserts the node with the given priority into the
|
||||
* priority aggregation's contributors.
|
||||
*
|
||||
* This method does not handle the case that @a node was the minimal node.
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to insert the node in its contributors.
|
||||
* @param[in] node The node to insert in the contributors.
|
||||
* @param priority The priority control for the inserted node.
|
||||
*
|
||||
* @retval true The inserted node with its priority is the minimum of the RBTree.
|
||||
* @retval false The inserted node with its priority is not the minimum of the RBTree.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE bool _Priority_Plain_insert(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node,
|
||||
@@ -251,6 +422,14 @@ RTEMS_INLINE_ROUTINE bool _Priority_Plain_insert(
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Extracts the priority node from the aggregation.
|
||||
*
|
||||
* This method does not handle the case that @a node was the minimal node.
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to extract the node from.
|
||||
* @param node The node to be extracted.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Plain_extract(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node
|
||||
@@ -259,6 +438,15 @@ RTEMS_INLINE_ROUTINE void _Priority_Plain_extract(
|
||||
_RBTree_Extract( &aggregation->Contributors, &node->Node.RBTree );
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Updates the priority of the node in the aggregation.
|
||||
*
|
||||
* It first extracts the node and inserts it again, with the new @a node priority as key.
|
||||
* This method does not handle the case that @a node was the minimal node.
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to change the node in.
|
||||
* @param node The node that has a new priority and will be reinserted in the aggregation.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Plain_changed(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node
|
||||
@@ -287,6 +475,16 @@ typedef void ( *Priority_Remove_handler )(
|
||||
void *arg
|
||||
);
|
||||
|
||||
/**
|
||||
* @brief Does nothing.
|
||||
*
|
||||
* This method does nothing.
|
||||
*
|
||||
* @param aggregation Is ignored by the method.
|
||||
* @param prepend_it Is ignored by the method.
|
||||
* @param actions Is ignored by the method.
|
||||
* @param arg Is ignored by the method.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Change_nothing(
|
||||
Priority_Aggregation *aggregation,
|
||||
bool prepend_it,
|
||||
@@ -300,6 +498,15 @@ RTEMS_INLINE_ROUTINE void _Priority_Change_nothing(
|
||||
(void) arg;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Does nothing.
|
||||
*
|
||||
* This method does nothing.
|
||||
*
|
||||
* @param aggregation Is ignored by the method.
|
||||
* @param actions Is ignored by the method.
|
||||
* @param arg Is ignored by the method.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Remove_nothing(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Actions *actions,
|
||||
@@ -311,6 +518,19 @@ RTEMS_INLINE_ROUTINE void _Priority_Remove_nothing(
|
||||
(void) arg;
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Inserts the node in a nonempty aggregation and handles change if
|
||||
* the node is the new minimum.
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to insert the node into.
|
||||
* @param node The node to be inserted. The node's priority is used as a key.
|
||||
* @param actions Parameter for @a change that is used if the node is the new
|
||||
* minimum.
|
||||
* @param change The priority change handler that is called in the case that
|
||||
* the new node is the minimum of the aggregation.
|
||||
* @param arg Arguments for @a change that is used if the node is the new
|
||||
* minimum.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Non_empty_insert(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node,
|
||||
@@ -330,6 +550,18 @@ RTEMS_INLINE_ROUTINE void _Priority_Non_empty_insert(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to insert the node in.
|
||||
* @param node The node to be inserted. The node's priority is used as key.
|
||||
* @param actions Priority actions for the case that the aggregation was empty before
|
||||
* the insert or the node is the new minimum.
|
||||
* @param add Is called in the case that @a aggregation was empty before the insert.
|
||||
* @param change Is called in the case that @a aggregation was nonempty before the
|
||||
* insert and @a node is the new minimum of the aggregation.
|
||||
* @param arg The arguments for @a change.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Insert(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node,
|
||||
@@ -347,6 +579,23 @@ RTEMS_INLINE_ROUTINE void _Priority_Insert(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Extracts the node from the aggregation.
|
||||
*
|
||||
* This method extracts the node from the aggregation and handles the
|
||||
* cases that @a aggregation is empty after the extraction, or that
|
||||
* @a node was the minimal node in @a aggregation by calling remove (if
|
||||
* empty) or change (if @a node was the minimal node).
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to extract the @a node from.
|
||||
* @param node The node to extract from @a aggregation.
|
||||
* @param actions The actions for the cases that the aggregation is empty
|
||||
* after the extraction, or the minimal node was extracted.
|
||||
* @param remove Is called in the case that the aggregation is empty after
|
||||
* the extraction.
|
||||
* @param change Is called in the case that the minimal node was extracted.
|
||||
* @param arg The arguments for @a remove and @a change.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Extract(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node,
|
||||
@@ -372,6 +621,19 @@ RTEMS_INLINE_ROUTINE void _Priority_Extract(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Extracts the node from the aggregation.
|
||||
*
|
||||
* This method extracts the node from the aggregation and handles the
|
||||
* case that @a node was the minimal node in @a aggregation by calling
|
||||
* change (if @a node was the minimal node).
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to extract the @a node from.
|
||||
* @param node The node to extract from @a aggregation.
|
||||
* @param actions The actions for the case that the minimal node was extracted.
|
||||
* @param change Is called in the case that the minimal node was extracted.
|
||||
* @param arg The arguments for @a change.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Extract_non_empty(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node,
|
||||
@@ -393,6 +655,21 @@ RTEMS_INLINE_ROUTINE void _Priority_Extract_non_empty(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Updates the priority of the node in the aggregation.
|
||||
*
|
||||
* This method handles the case that @a node was the minimal node in
|
||||
* @a aggregation.
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to change the node in.
|
||||
* @param node The node that has a new priority and will be reinserted in the aggregation.
|
||||
* @param prepend_it Indicates whether @a change should prepend if the minimal priority is
|
||||
* incorrectly set after the change.
|
||||
* @param actions The actions for the case that the minimal priority is incorrectly set
|
||||
* after the change.
|
||||
* @param change Is called if the minimal priority is incorrectly set after the change.
|
||||
* @param arg The arguments for @a change.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Changed(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *node,
|
||||
@@ -414,6 +691,16 @@ RTEMS_INLINE_ROUTINE void _Priority_Changed(
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* @brief Replaces one node by another.
|
||||
*
|
||||
* The new node has the priority of the old node.
|
||||
*
|
||||
* @param[in, out] aggregation The aggregation to replace @a victim by @a replacement in.
|
||||
* @param victim The node that will be replaced.
|
||||
* @param[out] replacement The node that replaces @a victim. It obtains its priority
|
||||
* from @a victim.
|
||||
*/
|
||||
RTEMS_INLINE_ROUTINE void _Priority_Replace(
|
||||
Priority_Aggregation *aggregation,
|
||||
Priority_Node *victim,
|
||||
@@ -428,6 +715,8 @@ RTEMS_INLINE_ROUTINE void _Priority_Replace(
|
||||
);
|
||||
}
|
||||
|
||||
/** @} */
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif /* __cplusplus */
|
||||
|
||||
Reference in New Issue
Block a user