Program Listing for File Frame.h#
↰ Return to documentation for file (include/Karana/Frame/Frame.h)
/*
* Copyright (c) 2024-2026 Karana Dynamics Pty Ltd. All rights reserved.
*
* NOTICE TO USER:
*
* This source code and/or documentation (the "Licensed Materials") is
* the confidential and proprietary information of Karana Dynamics Inc.
* Use of these Licensed Materials is governed by the terms and conditions
* of a separate software license agreement between Karana Dynamics and the
* Licensee ("License Agreement"). Unless expressly permitted under that
* agreement, any reproduction, modification, distribution, or disclosure
* of the Licensed Materials, in whole or in part, to any third party
* without the prior written consent of Karana Dynamics is strictly prohibited.
*
* THE LICENSED MATERIALS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND.
* KARANA DYNAMICS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
* BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY, NON-INFRINGEMENT, AND
* FITNESS FOR A PARTICULAR PURPOSE.
*
* IN NO EVENT SHALL KARANA DYNAMICS BE LIABLE FOR ANY DAMAGES WHATSOEVER,
* INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, DATA, OR USE, EVEN IF
* ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, WHETHER IN CONTRACT, TORT,
* OR OTHERWISE ARISING OUT OF OR IN CONNECTION WITH THE LICENSED MATERIALS.
*
* U.S. Government End Users: The Licensed Materials are a "commercial item"
* as defined at 48 C.F.R. 2.101, and are provided to the U.S. Government
* only as a commercial end item under the terms of this license.
*
* Any use of the Licensed Materials in individual or commercial software must
* include, in the user documentation and internal source code comments,
* this Notice, Disclaimer, and U.S. Government Use Provision.
*/
/**
* @file
* @brief Contains the declarations for the Frame class.
*/
#pragma once
#include "Karana/KCore/LockingBase.h"
#include "Karana/KCore/RegistryList.h"
#include <string>
namespace Karana::Frame {
namespace kc = Karana::Core;
class FrameContainer;
class EdgeFrameToFrame;
class ChainedFrameToFrame;
class OrientedChainedFrameToFrame;
/**
* @class Frame
* @brief The class for a frame in the frames tree
*
* See \sref{frames_layer_sec} for more discussion on
* the frames layer.
*
*/
class Frame : public Karana::Core::LockingBase {
friend FrameContainer;
// For access to _edge and _children
friend EdgeFrameToFrame;
public:
/**
* @brief Creates a new frame with the given name.
* @param name - The name of the frame to create.
* @param fc - The parent frames container
* @return The created frame.
*/
static kc::ks_ptr<Frame> create(std::string_view name, kc::ks_ptr<FrameContainer> fc);
/**
* @brief Discard the Frame. Used when you want to specifically call Frame's discard method
* rather than virtual dispatching to the most derived class's _discard method.
* @param frame - The pointer to the frame to discard.
*/
void discard(kc::ks_ptr<Frame> &frame);
/**
* @brief Destructor for the Frame class.
*/
virtual ~Frame();
/**
* @brief Get the parent frame.
* @return The parent frame.
*/
const kc::ks_ptr<Frame> &parent() const;
/**
* @brief Get the edge associated with this frame.
* @return The edge f2f.
*/
const kc::ks_ptr<EdgeFrameToFrame> &edge() const;
// std::iterator<kc::ks_ptr<Frame>> childIterator();
/**
* @brief Get the reference to the container of the frame.
* @return The reference to the container of the frame.
*/
FrameContainer &container() const;
/**
* @brief Get the shared pointer for the container of the frame.
* @return The shared pointer for the container of the frame.
*/
const kc::ks_ptr<FrameContainer> &containerPtr() const;
/**
* @brief Create a chained f2f between this frame and the target frame. This frame will be
* the o-frame and the target frame will become the p-frame.
* @param frame The target frame. This will be the p-frame in the chained frame to frame.
* @return The ChainedFrameToFrame connecting this frame (o-frame)
* and the target frame (p-frame).
*/
const kc::ks_ptr<ChainedFrameToFrame> &frameToFrame(const kc::ks_ptr<Frame> &frame) const;
/**
* @brief Create a chained f2f between this frame and the target frame. This frame will be
* the o-frame and the target frame will become the p-frame.
* @param frame The target frame. This will be the p-frame in the chained frame to frame.
* @return The ChainedFrameToFrame connecting this frame (o-frame)
* and the target frame (p-frame).
*/
const kc::ks_ptr<ChainedFrameToFrame> &frameToFrameRef(const Frame &frame) const;
/**
* @brief Create an oriented chained f2f between this frame and the target frame. This frame
* will be the o-frame and the target frame will become the p-frame.
*
* Note that it up to the user to ensure that the pframe is a true
* descendant of the oframe. If not, there will be errors when
* trying to use this oriented chain.
*
* @param frame The target frame. This will be the p-frame in the chained frame to frame.
* @return The OrientedChainedFrameToFrame connecting this frame (o-frame)
* and the target frame (p-frame).
*/
const kc::ks_ptr<OrientedChainedFrameToFrame> &
orientedFrameToFrame(const kc::ks_ptr<Frame> &frame) const;
/**
* @brief Create an oriented chained f2f between this frame and the target frame. This frame
* will be the o-frame and the target frame will become the p-frame.
*
* Note that it up to the user to ensure that the pframe is a true
* descendant of the oframe. If not, there will be errors when
* trying to use this oriented chain.
*
* @param frame The target frame. This will be the p-frame in the chained frame to frame.
* @return The OrientedChainedFrameToFrame connecting this frame (o-frame)
* and the target frame (p-frame).
*/
const kc::ks_ptr<OrientedChainedFrameToFrame> &
orientedFrameToFrameRef(const Frame &frame) const;
/**
* @brief Check if this frame is an ancestor of another frame.
* @param other The other frame to check against.
* @param strict if false, a frame can be its own ancestor
* @return True if this frame is an ancestor of the other frame, false otherwise.
*/
bool isAncestorOf(const Frame &other, bool strict) const;
/**
* @brief Get the ancestor of this frame and another frame.
* @param other The other frame.
* @return The common ancestor.
*/
const kc::ks_ptr<Frame> &getAncestor(const Frame &other) const;
public:
/**
* @brief Frame constructor. The constructor is not meant to be called directly.
* Please use the create(...) method instead to create an instance.
*
* @param name The name of the frame.
* @param frame_container The container of the frame.
*/
Frame(std::string_view name, kc::ks_ptr<FrameContainer> frame_container);
/**
* @brief Return inform about the Frame
* @param prefix the prefix for each output line
* @param options to tailor the dump output
* @return the informational string
*/
std::string dumpString(std::string_view prefix = "",
const Base::DumpOptions *options = nullptr) const override;
/** A struct with options to tailor the content from a dumpFrameTree()
call */
struct DumpFrameTreeOptions {
bool type_string = true; ///< include the frame's typeString info
bool edge_type = false; ///< include the frame's edge's typeString info
bool healthy_status = false; ///< include the frame's healthy status
bool ref_count = false; ///< include the frame's reference count
bool edge_ref_count = false; ///< include the frame's edge's reference count
bool id = false; ///< include the frame's tree id
};
/** Display the frame tree. The contents of the options struct can be
used to control the content and verbosity of the displayed
output.
* @param prefix the prefix for each output line
* @param options output content options
*/
void dumpFrameTree(std::string_view prefix = "",
const DumpFrameTreeOptions options =
DumpFrameTreeOptions(true, false, false, false, false, false)) const;
protected:
/**
* @brief Discard the provided frame.
* @param base - Base pointer to the frame to discard.
*/
void _discard(kc::ks_ptr<Base> &base) override;
private:
// FrameContainer *_frame_container; ///< Pointer to the frame container.
kc::ks_ptr<FrameContainer> _frame_container; ///< Pointer to the frame container.
kc::ks_ptr<EdgeFrameToFrame> _edge; ///< The EdgeFrameToFrame.
kc::RegistryList<Frame> _children; ///< List of child frames.
};
} // namespace Karana::Frame