[rtems commit] doxygen: score: adjust doc in priorityimpl.h to doxygen guidelines
Sebastian Huber
sebh at rtems.org
Mon May 13 05:52:28 UTC 2019
Module: rtems
Branch: master
Commit: 35a07c468246a26d459b2be7d9b6b6d83026e1ac
Changeset: http://git.rtems.org/rtems/commit/?id=35a07c468246a26d459b2be7d9b6b6d83026e1ac
Author: Andreas Dachsberger <andreas.dachsberger at embedded-brains.de>
Date: Thu Apr 11 08:17:17 2019 +0200
doxygen: score: adjust doc in priorityimpl.h to doxygen guidelines
Update #3706.
---
cpukit/include/rtems/score/priorityimpl.h | 289 ++++++++++++++++++++++++++++++
1 file changed, 289 insertions(+)
diff --git a/cpukit/include/rtems/score/priorityimpl.h b/cpukit/include/rtems/score/priorityimpl.h
index 3380983..b33419a 100644
--- a/cpukit/include/rtems/score/priorityimpl.h
+++ b/cpukit/include/rtems/score/priorityimpl.h
@@ -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 */
More information about the vc
mailing list