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

	PR 1673/cpukit
	* sapi/src/chainappendnotify.c, sapi/src/chaingetnotify.c,
	sapi/src/chaingetwait.c, sapi/src/chainprependnotify.c: New files.
	* sapi/Makefile.am: Reflect changes above.
	* sapi/include/rtems/chain.h: Declare
	rtems_chain_append_with_notification(),
	rtems_chain_prepend_with_notification(),
	rtems_chain_get_with_notification(), and rtems_chain_get_with_wait().
	* sapi/inline/rtems/chain.inl: Define
	rtems_chain_append_with_empty_check(),
	rtems_chain_prepend_with_empty_check(), and
	rtems_chain_get_with_empty_check().

1 files changed, 87 insertions, 12 deletions

diff --git a/cpukit/sapi/include/rtems/chain.h b/cpukit/sapi/include/rtems/chain.h
index 01b335d666..a80bb9c1e2 100644
--- a/cpukit/sapi/include/rtems/chain.h
+++ b/cpukit/sapi/include/rtems/chain.h
@@ -1,14 +1,14 @@
 /**
- * @file rtems/chain.h
+ * @file
  *
- *  This include file contains all the constants and structures associated
- *  with the Chain API in RTEMS. The chain is a double linked list that
- *  is part of the Super Core. This is the published interface to that
- *  code.
+ * @ingroup ClassicChains
  *
+ * @brief Chain API.
  */
 
 /*
+ *  Copyright (c) 2010 embedded brains GmbH.
+ *
  *  COPYRIGHT (c) 1989-2008.
  *  On-Line Applications Research Corporation (OAR).
  *
@@ -24,23 +24,24 @@
 
 #include <rtems/system.h>
 #include <rtems/score/chain.h>
+#include <rtems/rtems/event.h>
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 /**
- * @typedef rtems_chain_node
+ * @defgroup ClassicChains Chains
+ *
+ * @ingroup ClassicRTEMS
+ *
+ * @brief Chain API.
  *
- * A node that can be manipulated in the chain.
+ * @{
  */
+
 typedef Chain_Node rtems_chain_node;
 
-/**
- * @typedef rtems_chain_control
- *
- * The chain's control anchors the chain.
- */
 typedef Chain_Control rtems_chain_control;
 
 /**
@@ -55,8 +56,82 @@ typedef Chain_Control rtems_chain_control;
 #define RTEMS_CHAIN_DEFINE_EMPTY(name) \
   CHAIN_DEFINE_EMPTY(name)
 
+/** @} */
+
 #include <rtems/chain.inl>
 
+/**
+ * @addtogroup ClassicChains
+ *
+ * @{
+ */
+
+/**
+ * @brief Appends the @a node to the @a chain and sends the @a events to the
+ * @a task if the @a chain was empty before the append.
+ *
+ * @see rtems_chain_append_with_empty_check() and rtems_event_send().
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID No such task.
+ */
+rtems_status_code rtems_chain_append_with_notification(
+  rtems_chain_control *chain,
+  rtems_chain_node *node,
+  rtems_id task,
+  rtems_event_set events
+);
+
+/**
+ * @brief Prepends the @a node to the @a chain and sends the @a events to the
+ * @a task if the @a chain was empty before the prepend.
+ *
+ * @see rtems_chain_prepend_with_empty_check() and rtems_event_send().
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID No such task.
+ */
+rtems_status_code rtems_chain_prepend_with_notification(
+  rtems_chain_control *chain,
+  rtems_chain_node *node,
+  rtems_id task,
+  rtems_event_set events
+);
+
+/**
+ * @brief Gets the first @a node of the @a chain and sends the @a events to the
+ * @a task if the @a chain is empty after the get.
+ *
+ * @see rtems_chain_get_with_empty_check() and rtems_event_send().
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_INVALID_ID No such task.
+ */
+rtems_status_code rtems_chain_get_with_notification(
+  rtems_chain_control *chain,
+  rtems_id task,
+  rtems_event_set events,
+  rtems_chain_node **node
+);
+
+/**
+ * @brief Gets the first @a node of the @a chain and sends the @a events to the
+ * @a task if the @a chain is empty afterwards.
+ *
+ * @see rtems_chain_get() and rtems_event_receive().
+ *
+ * @retval RTEMS_SUCCESSFUL Successful operation.
+ * @retval RTEMS_TIMEOUT Timeout.
+ */
+rtems_status_code rtems_chain_get_with_wait(
+  rtems_chain_control *chain,
+  rtems_event_set events,
+  rtems_interval timeout,
+  rtems_chain_node **node
+);
+
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif