rtems/score/freechainimpl.h

0001 /* SPDX-License-Identifier: BSD-2-Clause */
0002
0003 /**
0004  * @file
0005  *
0006  * @ingroup RTEMSScoreFreechain
0007  *
0008  * @brief This header file provides interfaces of the
0009  *   @ref RTEMSScoreBarrier which are only used by the implementation.
0010  */
0011
0012 /*
0013  * Copyright (c) 2013 Gedare Bloom.
0014  *
0015  * Redistribution and use in source and binary forms, with or without
0016  * modification, are permitted provided that the following conditions
0017  * are met:
0018  * 1. Redistributions of source code must retain the above copyright
0019  *    notice, this list of conditions and the following disclaimer.
0020  * 2. Redistributions in binary form must reproduce the above copyright
0021  *    notice, this list of conditions and the following disclaimer in the
0022  *    documentation and/or other materials provided with the distribution.
0023  *
0024  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
0025  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
0026  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
0027  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
0028  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
0029  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
0030  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
0031  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
0032  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
0033  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
0034  * POSSIBILITY OF SUCH DAMAGE.
0035  */
0036
0037 #ifndef _RTEMS_SCORE_FREECHAINIMPL_H
0038 #define _RTEMS_SCORE_FREECHAINIMPL_H
0039
0040 #include <rtems/score/freechain.h>
0041 #include <rtems/score/basedefs.h>
0042 #include <rtems/score/chainimpl.h>
0043
0044 #ifdef __cplusplus
0045 extern "C" {
0046 #endif
0047
0048 /**
0049  * @addtogroup RTEMSScoreFreechain
0050  *
0051  * @{
0052  */
0053
0054 /**
0055  * @brief Allocator function.
0056  */
0057 typedef void *( *Freechain_Allocator )( size_t size );
0058
0059 /**
0060  * @brief Initializes a freechain.
0061  *
0062  * This routine initializes the freechain control structure to manage a chain
0063  * of nodes.  In the case the freechain is empty the extend handler is called to
0064  * get more nodes.
0065  *
0066  * @param[out] freechain The freechain control to initialize.
0067  * @param[out] initial_nodes Array with the initial nodes.
0068  * @param number_nodes The initial number of nodes.
0069  * @param node_size The node size.
0070  */
0071 static inline void _Freechain_Initialize(
0072   Freechain_Control   *freechain,
0073   void                *initial_nodes,
0074   size_t               number_nodes,
0075   size_t               node_size
0076 )
0077 {
0078   _Chain_Initialize(
0079     &freechain->Free,
0080     initial_nodes,
0081     number_nodes,
0082     node_size
0083   );
0084 }
0085
0086 /**
0087  * @brief Return true if the freechain is empty, otherwise false
0088  *
0089  * @param freechain The freechain control.
0090  */
0091 static inline bool _Freechain_Is_empty(
0092   const Freechain_Control *freechain
0093 )
0094 {
0095   return _Chain_Is_empty( &freechain->Free );
0096 }
0097
0098 /**
0099  * @brief Pops a node from the freechain.
0100  *
0101  * The freechain shall not be empty.
0102  *
0103  * @param freechain The freechain control.
0104  */
0105 static inline void *_Freechain_Pop( Freechain_Control *freechain )
0106 {
0107   return _Chain_Get_first_unprotected( &freechain->Free );
0108 }
0109
0110 /**
0111  * @brief Pushes a node back to the freechain.
0112  *
0113  * @param freechain The freechain control.
0114  * @param node The node to push back.  The node shall not be @c NULL.
0115  */
0116 void static inline _Freechain_Push(
0117   Freechain_Control *freechain,
0118   void              *node
0119 )
0120 {
0121   _Chain_Initialize_node( node );
0122   _Chain_Prepend_unprotected( &freechain->Free, node );
0123 }
0124
0125 /**
0126  * @brief Extend the freechain with new nodes.
0127  *
0128  * @param freechain The freechain control.
0129  * @param allocator The allocator function.
0130  * @param number_nodes_to_extend The number of nodes to extend.
0131  * @param node_size The node size.
0132  *
0133  * @retval NULL The extend operation failed.
0134  * @retval nodes Pointer to the new nodes.
0135  */
0136 void *_Freechain_Extend(
0137   Freechain_Control   *freechain,
0138   Freechain_Allocator  allocator,
0139   size_t               number_nodes_to_extend,
0140   size_t               node_size
0141 );
0142
0143 /**
0144  * @brief Gets a node from the freechain.
0145  *
0146  * @param[in, out] freechain The freechain control.
0147  * @param allocator The allocator function.
0148  * @param number_nodes_to_extend The number of nodes in the case an extend is
0149  *   necessary due to an empty freechain.
0150  * @param[in] node_size The node size.
0151  *
0152  * @retval NULL The freechain is empty and the extend operation failed.
0153  * @retval pointer Pointer to a node.  The node ownership passes to the
0154  * caller.
0155  */
0156 void *_Freechain_Get(
0157   Freechain_Control   *freechain,
0158   Freechain_Allocator  allocator,
0159   size_t               number_nodes_to_extend,
0160   size_t               node_size
0161 );
0162
0163 /**
0164  * @brief Puts a node back onto the freechain.
0165  *
0166  * @param[in, out] freechain The freechain control.
0167  * @param[out] node The node to put back.  The node may be @c NULL, in this case
0168  *   the function does nothing.
0169  */
0170 void _Freechain_Put(
0171   Freechain_Control *freechain,
0172   void              *node
0173 );
0174
0175 /** @} */
0176
0177 #ifdef __cplusplus
0178 }
0179 #endif
0180
0181 #endif
0182 /* end of include file */