#include <Linkable.hh>

Detailed Description

* Created by Douglas S. Leonard on 6/10/25. All rights Reserved
* See related files for license, if any is provided.
*
* A transitive view of another Linkable<T> or, as a root link, an owning T copy or non-owning T* view. Data access is value semantics, immutability control (of the links).
* Every link can be set only once, but once linked the view transitively controls the linked Linkable, including its link command, so it's possible
* to call Link more than once from a single Linkable but not to relink or to acquire more than one concrete resource.

* Links can be thought of as a view linking toward a single root (downlink) source. The root may be in an unlinked state, or may
* have a non-owning or owning shared pointer to data. Links to other links are always effectively non-owning. While the data itself is internally linked via shared
* via shared pointer, the link stack itself becomes invalid if another link is deleted, making it unsafe to operate on at that point. It's better
* to think of links like raw pointers in this regard. Multiple links can be made from other linkables to a single source or source link. Every individual link can only only be set once.

* If the root itself is not linked, all objects on the tree will behave as not linked, because
* there is still no source, and any object in the tree can call link to link the root to another link
* or to a source. Once the root is linked to a source, all objects in the tree are linked to a source and cannot be
* be relinked. Other objects can be still be linked to linkables in the tree, and then having a source, will also be fully linked.

*
* Copy and assignment work on the contents, not the internal pointer.
* It provides value-like semantics even for heap/pointer objects, and
* with const Linkable, you can only Link once, but it doesn't have to be in an initializer!
*
* Makes relinking more deliberate, even in ctor initializers.
*
* Const refers to pointer. It does NOT protect the contents of the object.
* Use ex: Linkable<const int> to make CONTENTS const.
* This is consistent with shared pointer behavior, but note operator= here acts on contents,
* and CAN modify them unless T itself is a const type.
*
* Gaurantees:
* -Will NEVER modify the shared_ptr itself without an explicit Link(..) call or SET_LINK parameter
* -Will never CREATE a shared_ptr that ties to an exisiting shared_ptr without the same.
* because the copy ctor creates a new ptr from a deep copy.
* -No concern for accidentally re-initializing to something that can be changed elsewhere (bugs!).
* -copy ctor and assignment semantics both follow value semantics, behaving like a T
* more than like a shred pointer.
* Just use it like a T, EXCEPT when you explicitly link.
*
* Heap Object (pointers) Safety:
* For heap objects O you usually want a Linkable<O> NOT a Linkable<O*>
* The Linkable O is internally an O* and can be initialized from an O* but
* because it acts like an O, you cannot modify the stored pointer.
* Unless you re-link (impossible with const) you will always access the memory.
*
*

The documentation for this class was generated from the following file:

include/Linkable.hh