/*
 * (c) Copyright, Real-Time Innovations, 2002-2026.
 * All rights reserved.
 * No duplications, whole or partial, manual or electronic, may be made
 * without express written permission.  Any such copies, or
 * revisions thereof, must display this notice unaltered.
 * This code contains trade secrets of Real-Time Innovations, Inc.
 */
#ifndef reda_inlineTree_h
#define reda_inlineTree_h

#include "log/log_makeheader.h"
#include "osapi/osapi_type.h"
#include "reda/reda_dll.h"
#include "reda/reda_inlineList.h"

#ifdef __cplusplus
extern "C" {
#endif

struct REDAInlineTree;

/* Doxygen file & module documentation ==================================*/
/*e \file
 *  @brief Defines the REDAInlineTree
 */

/*e \defgroup REDAInlineTreeClass REDAInlineTree
 * \ingroup REDAModule
 *
 * @brief A simple complete tree representation. The tree itself is composed of
 * tree nodes that are children sub-trees of the parent node. Nodes are
 * in-line (same convention than REDAInlineList) so memory allocation is not
 * needed to insert/remove nodes.
 *
 * The InlineTree class provides simple access to nodes by navigation from one
 * after another. Custom search algorithms must be provided by client code.
 *
 * @mtsafety The inlineTree does NOT allow concurrent modifications:
 * multiple threads cannot add/remove nodes concurrently.  The users of
 * the inlineTree should make sure this won't happen.
 *
 * @see REDAInlineList
 */
struct REDAInlineTree {
    struct REDAInlineListNode _node;

    /*i @brief back pointer to the parent tree. */
    struct REDAInlineTree *_parent;
    /*i @brief List of child nodes or sub-trees */
    struct REDAInlineList _children;
};

/*e \ingroup REDAInlineTreeClass
 * \brief All nodes wishing to be linked in inline list must "derive" from this
 * logical parent class.
 */

/*e \ingroup REDAInlineTreeClass
 * @brief Get the first child node or sub-tree.
 *
 * @post Tree in same state as in precondition
 *
 * @param self \b In. Tree to look under.
 *
 * @return The first child node in the tree. NULL if children list empty.
 *
 * @exception RTI_LOG_PRECONDITION_FAILURE
 *
 * @mtsafety Safe if list is not concurrently modified.  Otherwise, such as
 * when a new node is added to the front, or when the first node is removed
 * from the list, the caller will get the "first" node EITHER before OR after
 * the modification.
 *
 * @see REDAInlineTree_addChildEA REDAInlineTree_removeChildEA
 */
extern REDADllExport struct REDAInlineTree *REDAInlineTree_getFirstChild(
        const struct REDAInlineTree *self);

/*e \ingroup REDAInlineTreeClass
 * @brief Get the next node or sub-tree to the specified node.
 *
 * @post tree in same state as in precondition
 *
 * @param l \b In. Tree node to get the next sibling from.
 *
 * @return The next sibling node or NULL if no more siblings.
 *
 * @exception RTI_LOG_PRECONDITION_FAILURE
 *
 * @mtsafety Safe if list is not concurrently modified.  Otherwise, such as
 * when a new node is added to the front, or when the last node is removed
 * from the list, the caller will get the "last" node EITHER before OR after
 * the modification.
 *
 * @see REDAInlineTree_addChildEA REDAInlineTree_removeChildEA
 */
extern REDADllExport struct REDAInlineTree *REDAInlineTree_getNextSibling(
        const struct REDAInlineTree *self);

/*e \ingroup REDAInlineTreeClass
 * @brief Get the parent node or sub-tree owner.
 *
 * @post Tree in same state as in precondition
 *
 * @param self \b In. Tree to look over.
 *
 * @return The parent node or NULL if this node is the top node.
 *
 * @exception RTI_LOG_PRECONDITION_FAILURE
 *
 * @mtsafety Safe if list is not concurrently modified.  Otherwise, such as
 * when a new node is added to the front, or when the first node is removed
 * from the list, the caller will get the "first" node EITHER before OR after
 * the modification.
 *
 * @see REDAInlineTree_addChildEA REDAInlineTree_removeChildEA
 */
extern REDADllExport struct REDAInlineTree *REDAInlineTree_getParent(
        const struct REDAInlineTree *self);

/*e \ingroup REDAInlineTreeClass
 * @brief Check if node is a top node.
 *
 * A top node is such with no parent.
 *
 * @pre valid tree and a valid node. The implementation does NOT traverse
 * through the tree to verify the attribute of the node. Instead, it relies on
 * internal state flags set previously based on proper calls to
 * REDAInlineTree_init, REDAInlineTree_addChildEA, REDAInlineList_removeNodeEA.
 *
 * @post tree in same state as in precondition
 *
 * @exception RTI_LOG_PRECONDITION_FAILURE
 *
 * @mtsafety generally unsafe, except for the previously discussed in inline
 * tree MT safety section.
 *
 * @see REDAInlineTree
 */
extern REDADllExport RTIBool REDAInlineTree_isTop(struct REDAInlineTree *self);

/*e \ingroup REDAInlineTreeClass
 * @brief Check if node is a leaf node.
 *
 * A leaf node is such with no children.
 *
 * @pre valid tree and a valid node. The implementation does NOT traverse
 * through the tree to verify the attribute of the node. Instead, it relies on
 * internal state flags set previously based on proper calls to
 * REDAInlineTree_init, REDAInlineTree_addChildEA, REDAInlineList_removeNodeEA.
 *
 * @post tree in same state as in precondition
 *
 * @exception RTI_LOG_PRECONDITION_FAILURE
 *
 * @mtsafety generally unsafe, except for the previously discussed in inline
 * tree MT safety section.
 *
 * @see REDAInlineTree
 */
extern REDADllExport RTIBool REDAInlineTree_isLeaf(struct REDAInlineTree *self);

/*e \ingroup REDAInlineTreeClass
 * @brief Insert a tree node as child of this tree.
 *
 * This tree node will become the parent of the inserted one and hence it will
 * not be leaf. The inserted node may or may not be leaf depending on its
 * content.
 *
 * @pre valid tree and a free tree node. A free tree node must have no parent
 * but may have children.
 * @post The tree node is added next to the last child node.
 *
 * @param node \b In. Node to add.
 *
 * @exception RTI_LOG_PRECONDITION_FAILURE
 *
 * @mtsafety generally unsafe, except for the previously discussed in inline
 * tree MT safety section.
 *
 * @see REDAInlineTree
 */
extern REDADllExport void REDAInlineTree_addChildEA(
        struct REDAInlineTree *self,
        struct REDAInlineTree *node);

/*e \ingroup REDAInlineListClass
 * @brief Take node off the tree.
 *
 * @pre a valid tree node as child in the specified, valid tree.
 * @post node is removed from the tree and can be added to another list.
 *
 * @param node \b In. Node to remove.
 *
 * @mtsafety generally unsafe, except for the previously discussed in inline
 * tree MT safety section.
 *
 * @see REDAInlineTree
 */
extern REDADllExport void REDAInlineTree_removeChildEA(
        struct REDAInlineTree *self,
        struct REDAInlineTree *node);

/*e \ingroup REDAInlineListClass
 *
 * @brief Returns the number of child nodes in this tree.
 *
 * If the node is leaf, the number of children nodes will be zero.
 *
 * @pre valid tree.
 * @post Tree in same state as in precondition.
 *
 * @return number of child nodes in this tree.
 *
 * @mtsafety safe unless add or remove is performed concurrently.
 */
extern REDADllExport int REDAInlineTree_getChildCount(
        const struct REDAInlineTree *self);

/*e \ingroup REDAInlineListNodeClass
 * @brief Initializes the tee.
 *
 * @post a free tree with empty content
 *
 * @mtsafety Safe if node is not read or modified concurrently, such as in
 * removeNodeEA() or addChildEA().
 */
extern REDADllExport void REDAInlineTree_init(struct REDAInlineTree *self);

#ifdef __cplusplus
} /* extern "C" */
#endif

#endif /* reda_inlineTree_h */