2010-08-23 Sebastian Huber <sebastian.huber@embedded-brains.de>

	PR 1673/cpukit
	* score/src/chainappendempty.c, score/src/chaingetempty.c,
	score/src/chainprependempty.c: New files.
	* score/Makefile.am: Reflect changes above.
	* score/include/rtems/score/chain.h: Declare
	_Chain_Append_with_empty_check(), _Chain_Prepend_with_empty_check(),
	and _Chain_Get_with_empty_check().
	* score/inline/rtems/score/chain.inl: Define
	_Chain_Append_with_empty_check_unprotected(),
	_Chain_Prepend_with_empty_check_unprotected(), and
	_Chain_Get_with_empty_check_unprotected().

1 files changed, 68 insertions, 3 deletions

diff --git a/cpukit/score/include/rtems/score/chain.h b/cpukit/score/include/rtems/score/chain.h
index 3d18adf64f..4d298b3cd2 100644
--- a/cpukit/score/include/rtems/score/chain.h
+++ b/cpukit/score/include/rtems/score/chain.h
@@ -1,11 +1,14 @@
 /**
- *  @file  rtems/score/chain.h
+ * @file
  *
- *  This include file contains all the constants and structures associated
- *  with the Doubly-Linked Chain Handler.
+ * @ingroup ScoreChain
+ *
+ * @brief Chain Handler API.
  */
 
 /*
+ *  Copyright (c) 2010 embedded brains GmbH.
+ *
  *  COPYRIGHT (c) 1989-2006.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -22,6 +25,8 @@
 /**
  *  @defgroup ScoreChain Chain Handler
  *
+ *  @ingroup Score
+ *
  *  The Chain Handler is used to manage sets of entities.  This handler
  *  provides two data structures.  The Chain Node data structure is included
  *  as the first part of every data structure that will be placed on
@@ -185,6 +190,66 @@ void _Chain_Append(
   Chain_Node    *the_node
 );
 
+/**
+ * @brief Append a node and check if the chain was empty before.
+ *
+ * This routine appends the_node onto the end of the_chain.
+ *
+ * @param[in] the_chain is the chain to be operated upon.
+ * @param[in] the_node is the node to be appended.
+ *
+ * @note It disables interrupts to ensure the atomicity of the append
+ * operation.
+ *
+ * @retval true The chain was empty before.
+ * @retval false The chain contained at least one node before.
+ */
+bool _Chain_Append_with_empty_check(
+  Chain_Control *the_chain,
+  Chain_Node    *the_node
+);
+
+/**
+ * @brief Prepend a node and check if the chain was empty before.
+ *
+ * This routine prepends the_node onto the front of the_chain.
+ *
+ * @param[in] the_chain is the chain to be operated upon.
+ * @param[in] the_node is the node to be prepended.
+ *
+ * @note It disables interrupts to ensure the atomicity of the append
+ * operation.
+ *
+ * @retval true The chain was empty before.
+ * @retval false The chain contained at least one node before.
+ */
+bool _Chain_Prepend_with_empty_check(
+  Chain_Control *the_chain,
+  Chain_Node    *the_node
+);
+
+/**
+ * @brief Get the first node and check if the chain is empty afterwards.
+ *
+ * This function removes the first node from the_chain and returns
+ * a pointer to that node in @a the_node.  If the_chain is empty, then NULL is
+ * returned.
+ *
+ * @param[in] the_chain is the chain to attempt to get the first node from.
+ * @param[out] the_node is the first node on the chain or NULL if the chain is
+ * empty.
+ *
+ * @note It disables interrupts to ensure the atomicity of the append
+ * operation.
+ *
+ * @retval true The chain is empty now.
+ * @retval false The chain contains at least one node now.
+ */
+bool _Chain_Get_with_empty_check(
+  Chain_Control *the_chain,
+  Chain_Node **the_node
+);
+
 #ifndef __RTEMS_APPLICATION__
 #include <rtems/score/chain.inl>
 #endif