rtems/score/chain.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreChain
0007  *
0008  * @brief This header file provides interfaces of the
0009  *   @ref RTEMSScoreChain which are used by the implementation and the API.
0010  */
0011
0012 /*
0013  *  Copyright (c) 2010 embedded brains GmbH & Co. KG
0014  *
0015  *  COPYRIGHT (c) 1989-2006.
0016  *  On-Line Applications Research Corporation (OAR).
0017  *
0018  * Redistribution and use in source and binary forms, with or without
0019  * modification, are permitted provided that the following conditions
0020  * are met:
0021  * 1. Redistributions of source code must retain the above copyright
0022  *    notice, this list of conditions and the following disclaimer.
0023  * 2. Redistributions in binary form must reproduce the above copyright
0024  *    notice, this list of conditions and the following disclaimer in the
0025  *    documentation and/or other materials provided with the distribution.
0026  *
0027  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0028  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0029  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0030  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0031  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0032  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0033  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0034  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0035  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0036  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0037  * POSSIBILITY OF SUCH DAMAGE.
0038  */
0039
0040 #ifndef _RTEMS_SCORE_CHAIN_H
0041 #define _RTEMS_SCORE_CHAIN_H
0042
0043 #ifdef __cplusplus
0044 extern "C" {
0045 #endif
0046
0047 /**
0048  * @defgroup RTEMSScoreChain Chain Handler
0049  *
0050  * @ingroup RTEMSScore
0051  *
0052  * @brief This group contains the Chain Handler implementation.
0053  *
0054  * The Chain Handler is used to manage sets of entities.  This handler
0055  * provides two data structures.  The Chain Node data structure is included
0056  * as the first part of every data structure that will be placed on
0057  * a chain.  The second data structure is Chain Control which is used
0058  * to manage a set of Chain Nodes.
0059  *
0060  * @{
0061  */
0062
0063 /**
0064  *  @brief This structure represents a chain node.
0065  *
0066  *  This is used to manage each element (node) which is placed
0067  *  on a chain.
0068  *
0069  *  @note Typically, a more complicated structure will use the
0070  *        chain package.  The more complicated structure will
0071  *        include a chain node as the first element in its
0072  *        control structure.  It will then call the chain package
0073  *        with a pointer to that node element.  The node pointer
0074  *        and the higher level structure start at the same address
0075  *        so the user can cast the pointers back and forth.
0076  *
0077  */
0078 typedef struct Chain_Node {
0079   /** This points to the node after this one on this chain. */
0080   struct Chain_Node *next;
0081   /** This points to the node immediate prior to this one on this chain. */
0082   struct Chain_Node *previous;
0083 } Chain_Node;
0084
0085 /**
0086  * @brief This union represents a chain control block.
0087  *
0088  * This is used to manage a chain.  A chain consists of a doubly
0089  * linked list of zero or more nodes.
0090  *
0091  * @note This implementation does not require special checks for
0092  *   manipulating the first and last elements on the chain.
0093  *   To accomplish this the @a Chain_Control structure is
0094  *   treated as two overlapping @ref Chain_Node structures.
0095  */
0096 typedef union {
0097   struct {
0098     Chain_Node Node;
0099     Chain_Node *fill;
0100   } Head;
0101
0102   struct {
0103     Chain_Node *fill;
0104     Chain_Node Node;
0105   } Tail;
0106 } Chain_Control;
0107
0108 /** @} */
0109
0110 #ifdef __cplusplus
0111 }
0112 #endif
0113
0114 #endif
0115 /* end of include file */