[rtems commit] sapi: Add rtems_chain_get_first_unprotected()

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    aa473025f70d144ef9b50e833e7d9b91aad134f9
Changeset: http://git.rtems.org/rtems/commit/?id=aa473025f70d144ef9b50e833e7d9b91aad134f9

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Tue Nov  3 11:10:21 2015 +0100

sapi: Add rtems_chain_get_first_unprotected()

Close #2459.

---

 cpukit/sapi/include/rtems/chain.h | 10 ++++++++++
 doc/user/chains.t                 | 33 +++++++++++++++++++++++++++++++++
 testsuites/sptests/spchain/init.c |  7 +++++++
 3 files changed, 50 insertions(+)

diff --git a/cpukit/sapi/include/rtems/chain.h b/cpukit/sapi/include/rtems/chain.h
index 8da355d..4d586ff 100644
--- a/cpukit/sapi/include/rtems/chain.h
+++ b/cpukit/sapi/include/rtems/chain.h
@@ -624,6 +624,16 @@ RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get_unprotected(
 }
 
 /**
+ * @brief See _Chain_Get_first_unprotected().
+ */
+RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get_first_unprotected(
+  rtems_chain_control *the_chain
+)
+{
+  return _Chain_Get_first_unprotected( the_chain );
+}
+
+/**
  * @brief Insert a node on a chain
  *
  * This routine inserts @a the_node on a chain immediately following
diff --git a/doc/user/chains.t b/doc/user/chains.t
index e5dffc2..79e5984 100644
--- a/doc/user/chains.t
+++ b/doc/user/chains.t
@@ -35,6 +35,7 @@ provided by RTEMS is:
 @item @code{@value{DIRPREFIX}chain_extract_unprotected} - Extract the node from the chain (unprotected)
 @item @code{@value{DIRPREFIX}chain_get} - Return the first node on the chain
 @item @code{@value{DIRPREFIX}chain_get_unprotected} - Return the first node on the chain (unprotected)
+ at item @code{@value{DIRPREFIX}chain_get_first_unprotected} - Get the first node on the chain (unprotected)
 @item @code{@value{DIRPREFIX}chain_insert} - Insert the node into the chain
 @item @code{@value{DIRPREFIX}chain_insert_unprotected} - Insert the node into the chain (unprotected)
 @item @code{@value{DIRPREFIX}chain_append} - Append the node to chain
@@ -661,6 +662,38 @@ interrupts.
 @c
 @c
 @page
+ at subsection Get the First Node (unprotected)
+
+ at cindex chain get first node
+
+ at subheading CALLING SEQUENCE:
+
+ at ifset is-C
+ at findex @value{DIRPREFIX}chain_get_first_unprotected
+ at example
+ at value{DIRPREFIX}chain_node *@value{DIRPREFIX}chain_get_first_unprotected(
+  @value{DIRPREFIX}chain_control *the_chain
+);
+ at end example
+ at end ifset
+
+ at subheading RETURNS:
+
+A pointer to the former first node is returned.
+
+ at subheading DESCRIPTION:
+
+Removes the first node from the chain and returns a pointer to it.  In case the
+chain was empty, then the results are unpredictable.
+
+ at subheading NOTES:
+
+The function does nothing to ensure the atomicity of the operation.
+
+ at c
+ at c
+ at c
+ at page
 @subsection Insert a Node
 
 @cindex chain insert a node
diff --git a/testsuites/sptests/spchain/init.c b/testsuites/sptests/spchain/init.c
index ca2e135..476629b 100644
--- a/testsuites/sptests/spchain/init.c
+++ b/testsuites/sptests/spchain/init.c
@@ -117,6 +117,13 @@ static void test_chain_first_and_last(void)
   puts( "INIT - Verify rtems_chain_is_last" );
   cnode = rtems_chain_last(&chain);
   rtems_test_assert( rtems_chain_is_last( cnode ) );
+
+  cnode = rtems_chain_get_first_unprotected( &chain );
+  rtems_test_assert( cnode == &node1 );
+  cnode = rtems_chain_first( &chain );
+  rtems_test_assert( cnode == &node2 );
+  cnode = rtems_chain_last( &chain );
+  rtems_test_assert( cnode == &node2 );
 }
 
 static void test_chain_with_notification(void)