UnorderedStructureDetail.h

Go to the documentation of this file.

/*
 * This file is a part of the Biology project by eons LLC.
 * Biology (aka Develop Biology) is a framework for approaching software
 * development from a natural sciences perspective.
 *
 * Copyright (C) 2024 Séon O'Shannon & eons LLC
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Affero General Public License as
 * published by the Free Software Foundation, either version 3 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Affero General Public License for more details.
 *
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 
#pragma once
 
#include "bio/common/type/NormalizeTypeName.h"
#include "bio/common/type/TypeName.h"
#include "bio/common/wrapper/Pointer.h"
#include "bio/common/thread/SafelyAccess.h"
#include "bio/chemical/bonding/Atom.h"
#include "bio/chemical/bonding/Bond.h"
#include "bio/chemical/relativity/PeriodicTable.h"
#include "bio/chemical/relativity/WaveTypeId.h"
#include "bio/chemical/structure/motif/AbstractMotif.h"
#include "bio/physical/wave/Wave.h"
 
#include <cstddef>
#include <vector>
 
namespace bio {
namespace chemical {
 
class UnorderedStructureInterface;
 
namespace structure {
 
template < typename T >
struct LinearMotifContentTypeId
{
    typedef typename type::RemovePointer< T >::Type Pointee;
    typedef Pointer< Pointee > WrappedPointer;
 
    static AtomicNumber Get()
    {
        return TypeId< WrappedPointer >();
    }
};
 
inline void TryAddWaveCollectVisitor(const Bond& bond, void* ctx)
{
    std::vector< Pointer< physical::Wave > >* candidates =
        static_cast< std::vector< Pointer< physical::Wave > >* >(ctx);
    Pointer< physical::Wave > bonded = const_cast< Bond& >(bond).GetBonded();
    if (!bonded)
    {
        return;
    }
    candidates->push_back(bonded);
}
 
inline bool TryAddWaveToAnyMotif(
    Pointer< physical::Wave > host,
    Pointer< physical::Wave > payload
)
{
    if (!host || !payload)
    {
        return false;
    }
    Pointer< Atom > hostAtom = host->AsAtom();
    if (!hostAtom)
    {
        return false;
    }
    // RFC §5 step 3: snapshot bonded Wave* under hostAtom's shared lock,
    // then do the motif-accept dance outside the lock. The motif accept
    // calls back into add-implementation paths that may acquire other
    // Atom locks (the target's mBonds), so we must NOT be holding
    // hostAtom's lock during that call.
    std::vector< Pointer< physical::Wave > > candidates;
    hostAtom->ForEachBond(&TryAddWaveCollectVisitor, &candidates);
 
    for (std::size_t i = 0; i < candidates.size(); ++i)
    {
        Pointer< physical::Wave > bonded = candidates[i];
        // No-RTTI Wave* -> AbstractMotif* cross-cast. The codebase forbids
        // dynamic_cast (PeriodicTable is the type-info substitute); the
        // canonical alternative is the Atom bond mechanism — every
        // UnorderedMotif registers a Quantum<AbstractMotif> bond on its
        // own Atom that exposes its AbstractMotif subobject with the
        // correct multi-inheritance offset (see
        // UnorderedMotif::RegisterAsAbstractMotifBond). Atom::As<>'s
        // AsBondedQuantum path returns NULL when no such bond exists,
        // so this safely yields NULL for non-motif bonded waves.
        Pointer< Atom > bondedAtom = bonded->AsAtom();
        if (!bondedAtom)
        {
            continue;
        }
        Pointer< AbstractMotif > motif = bondedAtom->As< AbstractMotif >();
        if (!motif)
        {
            continue;
        }
        Pointer< physical::Wave > clone = payload->Clone();
        if (!clone)
        {
            continue;
        }
        if (motif->AddWaveByContentType(clone))
        {
            return true;
        }
        Delete(clone);
    }
    return false;
}
 
inline bool TryShareWaveWithAnyMotif(
    Pointer< physical::Wave > host,
    Pointer< physical::Wave > payload
)
{
    if (!host || !payload)
    {
        return false;
    }
    Pointer< Atom > hostAtom = host->AsAtom();
    if (!hostAtom)
    {
        return false;
    }
    // RFC §5 step 3: snapshot under shared, share-add outside the lock.
    // See TryAddWaveToAnyMotif for the lock-discipline rationale.
    std::vector< Pointer< physical::Wave > > candidates;
    hostAtom->ForEachBond(&TryAddWaveCollectVisitor, &candidates);
 
    for (std::size_t i = 0; i < candidates.size(); ++i)
    {
        Pointer< physical::Wave > bonded = candidates[i];
        Pointer< Atom > bondedAtom = bonded->AsAtom();
        if (!bondedAtom)
        {
            continue;
        }
        Pointer< AbstractMotif > motif = bondedAtom->As< AbstractMotif >();
        if (!motif)
        {
            continue;
        }
        if (motif->AddSharedWaveByContentType(payload))
        {
            return true;
        }
    }
    return false;
}
 
template < typename MOTIF >
bool IsBondedMotifType(Pointer< const physical::Wave > bonded)
{
    BIO_SANITIZE(bonded, , return false)
    // Fast path: cached typeId on Wave matches MOTIF's. Lock-free,
    // O(1), and crucially avoids the bonded->Spin() recursion loop
        // where Molecule::Spin -> GetAll<Surface> -> ResolveLinearMotif ->
    // IsBondedMotifType → bonded->Spin() (back into Molecule::Spin).
    if (WaveHasExactTypeId< MOTIF >(bonded))
    {
        return true;
    }
    // Slow path: legacy Symmetry-name comparison. Required when (a)
    // BIO_MEMORY_OPTIMIZE_LEVEL > 0 disables the typeId cache, or (b)
    // bonded is a subclass of MOTIF rather than an exact match.
    Pointer< const physical::Symmetry > symmetry = bonded->GetSymmetry();
    if (!symmetry)
    {
        // Deferred Symmetry: explicitly skip Spin() here — same recursion
        // concern as above. The exact-match case was covered by the
        // typeId fast-path; subclass-match for never-Spun objects would
        // have to materialise via Spin first if a caller depends on it.
        return false;
    }
    static const Name expected(type::TypeName< MOTIF >());
    const String normalizedExpected = type::NormalizeTypeName(expected);
    const String normalizedActual = type::NormalizeTypeName(symmetry->GetName());
    return normalizedActual == normalizedExpected;
}
 
struct MotifCandidate
{
    AtomicNumber id;
    Pointer< physical::Wave > bonded;
    MotifCandidate() : id(0), bonded(NULL) {}
    MotifCandidate(AtomicNumber i, Pointer< physical::Wave > b) : id(i), bonded(b) {}
};
 
inline void MotifCandidateCollectVisitor(const Bond& bond, void* ctx)
{
    std::vector< MotifCandidate >* out =
        static_cast< std::vector< MotifCandidate >* >(ctx);
    Pointer< physical::Wave > bonded = const_cast< Bond& >(bond).GetBonded();
    if (!bonded)
    {
        return;
    }
    out->push_back(MotifCandidate(bond.GetId(), bonded));
}
 
template < typename T >
Pointer< UnorderedMotif< T > > ResolveUnorderedMotif(Pointer< UnorderedStructureInterface > self)
{
    if (!self)
    {
        return NULL;
    }
    const AtomicNumber expectedBondId = Atom::GetBondId< UnorderedMotif< T > >();
 
    // Fast path: GetBondPosition + GetBonded each take a shared lock
    // internally; we don't nest. GetBonded(position) returns NULL on
    // !IsAllocated or empty bond, replacing the legacy explicit checks.
    // Because GetBondPosition< UnorderedMotif<T> >() resolves through
    // the slot whose Id equals expectedBondId, the legacy
    // "bond->GetId() == expectedBondId || IsBondedMotifType(...)"
    // short-circuit is always satisfied on this path.
    // RFC §5 step 3.
    Valence position = self->template GetBondPosition< UnorderedMotif< T > >();
    if (position)
    {
        Pointer< physical::Wave > bonded = self->GetBonded(position);
        if (bonded)
        {
            Pointer< physical::Class< UnorderedMotif< T > > > bondedClass =
                ForceCast< Pointer< physical::Class< UnorderedMotif< T > > > >(bonded);
            if (bondedClass)
            {
                return bondedClass->GetWaveObject();
            }
        }
    }
 
    // Slow path: snapshot all (id, bonded) pairs under shared, then
    // scan in reverse order to match the legacy End->Begin walk.
    std::vector< MotifCandidate > candidates;
    self->ForEachBond(&MotifCandidateCollectVisitor, &candidates);
    for (std::size_t i = candidates.size(); i; --i)
    {
        const MotifCandidate& cand = candidates[i - 1];
        if (cand.id != expectedBondId)
        {
            continue;
        }
        Pointer< physical::Class< UnorderedMotif< T > > > bondedClass =
            ForceCast< Pointer< physical::Class< UnorderedMotif< T > > > >(cand.bonded);
        if (!bondedClass)
        {
            continue;
        }
        return bondedClass->GetWaveObject();
    }
    return NULL;
}
 
template < typename T >
Pointer< const UnorderedMotif< T > > ResolveUnorderedMotif(Pointer< const UnorderedStructureInterface > self)
{
    if (!self)
    {
        return NULL;
    }
    const AtomicNumber expectedBondId = Atom::GetBondId< UnorderedMotif< T > >();
 
    // Fast path — see non-const sibling for RFC §5 step 3 notes.
    Valence position = self->template GetBondPosition< UnorderedMotif< T > >();
    if (position)
    {
        Pointer< const physical::Wave > bonded = self->GetBonded(position);
        if (bonded)
        {
            Pointer< const physical::Class< UnorderedMotif< T > > > bondedClass =
                ForceCast< Pointer< const physical::Class< UnorderedMotif< T > > > >(bonded);
            if (bondedClass)
            {
                return bondedClass->GetWaveObject();
            }
        }
    }
 
    // Slow path — snapshot then walk reverse for End->Begin parity.
    std::vector< MotifCandidate > candidates;
    self->ForEachBond(&MotifCandidateCollectVisitor, &candidates);
    for (std::size_t i = candidates.size(); i; --i)
    {
        const MotifCandidate& cand = candidates[i - 1];
        if (cand.id != expectedBondId)
        {
            continue;
        }
        Pointer< const physical::Class< UnorderedMotif< T > > > bondedClass =
            ForceCast< Pointer< const physical::Class< UnorderedMotif< T > > > >(cand.bonded);
        if (!bondedClass)
        {
            continue;
        }
        return bondedClass->GetWaveObject();
    }
    return NULL;
}
 
template < typename T >
Pointer< LinearMotif< T > > ResolveLinearMotif(Pointer< UnorderedStructureInterface > self)
{
    if (!self)
    {
        return NULL;
    }
    const AtomicNumber expectedBondId = Atom::GetBondId< LinearMotif< T > >();
    const AtomicNumber expectedId = LinearMotifContentTypeId< T >::Get();
 
    // Fast path — see ResolveUnorderedMotif for RFC §5 step 3 notes.
    Valence position = self->template GetBondPosition< LinearMotif< T > >();
    if (position)
    {
        Pointer< physical::Wave > bonded = self->GetBonded(position);
        if (bonded && IsBondedMotifType< LinearMotif< T > >(bonded))
        {
            Pointer< physical::Class< LinearMotif< T > > > bondedClass =
                ForceCast< Pointer< physical::Class< LinearMotif< T > > > >(bonded);
            if (bondedClass)
            {
                Pointer< LinearMotif< T > > motif = bondedClass->GetWaveObject();
                if (motif && motif->mContentId == expectedId)
                {
                    return motif;
                }
            }
        }
    }
 
    // Slow path — snapshot then walk reverse for End->Begin parity.
    std::vector< MotifCandidate > candidates;
    self->ForEachBond(&MotifCandidateCollectVisitor, &candidates);
    for (std::size_t i = candidates.size(); i; --i)
    {
        const MotifCandidate& cand = candidates[i - 1];
        if (cand.id != expectedBondId)
        {
            continue;
        }
        Pointer< physical::Class< LinearMotif< T > > > bondedClass =
            ForceCast< Pointer< physical::Class< LinearMotif< T > > > >(cand.bonded);
        if (!bondedClass)
        {
            continue;
        }
        Pointer< LinearMotif< T > > motif = bondedClass->GetWaveObject();
        if (motif && motif->mContentId == expectedId)
        {
            return motif;
        }
    }
    return NULL;
}
 
template < typename T >
Pointer< const LinearMotif< T > > ResolveLinearMotif(Pointer< const UnorderedStructureInterface > self)
{
    if (!self)
    {
        return NULL;
    }
    const AtomicNumber expectedBondId = Atom::GetBondId< LinearMotif< T > >();
    const AtomicNumber expectedId = LinearMotifContentTypeId< T >::Get();
 
    // Fast path — see ResolveUnorderedMotif for RFC §5 step 3 notes.
    Valence position = self->template GetBondPosition< LinearMotif< T > >();
    if (position)
    {
        Pointer< const physical::Wave > bonded = self->GetBonded(position);
        if (bonded && IsBondedMotifType< LinearMotif< T > >(bonded))
        {
            Pointer< const physical::Class< LinearMotif< T > > > bondedClass =
                ForceCast< Pointer< const physical::Class< LinearMotif< T > > > >(bonded);
            if (bondedClass)
            {
                Pointer< const LinearMotif< T > > motif = bondedClass->GetWaveObject();
                if (motif && motif->mContentId == expectedId)
                {
                    return motif;
                }
            }
        }
    }
 
    // Slow path — snapshot then walk reverse for End->Begin parity.
    std::vector< MotifCandidate > candidates;
    self->ForEachBond(&MotifCandidateCollectVisitor, &candidates);
    for (std::size_t i = candidates.size(); i; --i)
    {
        const MotifCandidate& cand = candidates[i - 1];
        if (cand.id != expectedBondId)
        {
            continue;
        }
        Pointer< const physical::Class< LinearMotif< T > > > bondedClass =
            ForceCast< Pointer< const physical::Class< LinearMotif< T > > > >(cand.bonded);
        if (!bondedClass)
        {
            continue;
        }
        Pointer< const LinearMotif< T > > motif = bondedClass->GetWaveObject();
        if (motif && motif->mContentId == expectedId)
        {
            return motif;
        }
    }
    return NULL;
}
 
template < typename T, bool kIsPointer >
struct LinearMotifDispatch
{
    static T Add(Pointer< UnorderedStructureInterface > self, const T t)
    {
        Pointer< UnorderedMotif< T > > implementer = ResolveUnorderedMotif< T >(self);
        BIO_SANITIZE_AT_SAFETY_LEVEL_1(implementer,
            return implementer->AddImplementation(t),
            return 0
        )
    }
 
    static Code Remove(Pointer< UnorderedStructureInterface > self, const T t)
    {
        Pointer< UnorderedMotif< T > > implementer = ResolveUnorderedMotif< T >(self);
        BIO_SANITIZE_AT_SAFETY_LEVEL_1(implementer,
            return implementer->RemoveImplementation(t),
            return code::BadArgument1()
        )
    }
 
    static Index GetCount(Pointer< const UnorderedStructureInterface > self)
    {
        Pointer< const LinearMotif< T > > linear = ResolveLinearMotif< T >(self);
        if (linear)
        {
            return linear->GetCountImplementation();
        }
        Pointer< const UnorderedMotif< T > > implementer = ResolveUnorderedMotif< T >(self);
        BIO_SANITIZE_AT_SAFETY_LEVEL_1(implementer,
            return implementer->GetCountImplementation(),
            return 0
        )
    }
 
    static Pointer< Container > GetAll(Pointer< UnorderedStructureInterface > self)
    {
        Pointer< LinearMotif< T > > linear = ResolveLinearMotif< T >(self);
        if (linear)
        {
            return linear->GetAllImplementation();
        }
        Pointer< UnorderedMotif< T > > implementer = ResolveUnorderedMotif< T >(self);
        BIO_SANITIZE_AT_SAFETY_LEVEL_1(implementer,
            return implementer->GetAllImplementation(),
            return 0
        )
    }
 
    static Pointer< const Container > GetAll(Pointer< const UnorderedStructureInterface > self)
    {
        Pointer< const LinearMotif< T > > linear = ResolveLinearMotif< T >(self);
        if (linear)
        {
            return linear->GetAllImplementation();
        }
        Pointer< const UnorderedMotif< T > > implementer = ResolveUnorderedMotif< T >(self);
        BIO_SANITIZE_AT_SAFETY_LEVEL_1(implementer,
            return implementer->GetAllImplementation(),
            return 0
        )
    }
 
    static bool Has(Pointer< const UnorderedStructureInterface > self, T content)
    {
        Pointer< const UnorderedMotif< T > > implementer = ResolveUnorderedMotif< T >(self);
        BIO_SANITIZE_AT_SAFETY_LEVEL_1(implementer,
            return implementer->HasImplementation(content),
            return false
        )
    }
};
 
template < typename T, bool kUseWrappedMotif >
struct WrappedLinearMotifDispatch
{
    static T Add(Pointer< UnorderedStructureInterface >, const T)
    {
        return 0;
    }
 
    static Code Remove(Pointer< UnorderedStructureInterface >, const T)
    {
        return code::BadArgument1();
    }
 
    static Index GetCount(Pointer< const UnorderedStructureInterface >)
    {
        return 0;
    }
 
    static Pointer< Container > GetAll(Pointer< UnorderedStructureInterface >)
    {
        return 0;
    }
 
    static Pointer< const Container > GetAll(Pointer< const UnorderedStructureInterface >)
    {
        return 0;
    }
 
    static bool Has(Pointer< const UnorderedStructureInterface >, T)
    {
        return false;
    }
};
 
template < typename T >
struct WrappedLinearMotifDispatch< T, true >
{
    typedef typename type::RemovePointer< T >::Type Pointee;
    typedef Pointer< Pointee > Wrapped;
 
    static T Add(Pointer< UnorderedStructureInterface > self, const T t)
    {
        Pointer< LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            Wrapped added = implementer->AddImplementation(t);
            return added.Get();
        }
        return 0;
    }
 
    static Code Remove(Pointer< UnorderedStructureInterface > self, const T t)
    {
        Pointer< LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->RemoveImplementation(t);
        }
        return code::BadArgument1();
    }
 
    static Index GetCount(Pointer< const UnorderedStructureInterface > self)
    {
        Pointer< const LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->GetCountImplementation();
        }
        return 0;
    }
 
    static Pointer< Container > GetAll(Pointer< UnorderedStructureInterface > self)
    {
        Pointer< LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->GetAllImplementation();
        }
        return 0;
    }
 
    static Pointer< const Container > GetAll(Pointer< const UnorderedStructureInterface > self)
    {
        Pointer< const LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->GetAllImplementation();
        }
        return 0;
    }
 
    static bool Has(Pointer< const UnorderedStructureInterface > self, T content)
    {
        Pointer< const LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->HasImplementation(content);
        }
        return false;
    }
};
 
template < typename T >
struct LinearMotifDispatch< T, true >
{
    typedef typename type::RemovePointer< T >::Type Pointee;
 
    static T Add(Pointer< UnorderedStructureInterface > self, const T t)
    {
        Pointer< LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->AddImplementation(t);
        }
        T wrappedAdded = WrappedLinearMotifDispatch<
            T,
            !type::IsPointerWrapper< T >::sValue
        >::Add(self, t);
        if (wrappedAdded)
        {
            return wrappedAdded;
        }
        return LinearMotifDispatch< T, false >::Add(self, t);
    }
 
    static Code Remove(Pointer< UnorderedStructureInterface > self, const T t)
    {
        Pointer< LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->RemoveImplementation(t);
        }
        Code wrapped = WrappedLinearMotifDispatch<
            T,
            !type::IsPointerWrapper< T >::sValue
        >::Remove(self, t);
        if (wrapped != code::BadArgument1())
        {
            return wrapped;
        }
        return LinearMotifDispatch< T, false >::Remove(self, t);
    }
 
    static Index GetCount(Pointer< const UnorderedStructureInterface > self)
    {
        Pointer< const LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->GetCountImplementation();
        }
        Index wrapped = WrappedLinearMotifDispatch<
            T,
            !type::IsPointerWrapper< T >::sValue
        >::GetCount(self);
        if (wrapped)
        {
            return wrapped;
        }
        return LinearMotifDispatch< T, false >::GetCount(self);
    }
 
    static Pointer< Container > GetAll(Pointer< UnorderedStructureInterface > self)
    {
        Pointer< LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->GetAllImplementation();
        }
        Pointer< Container > wrapped = WrappedLinearMotifDispatch<
            T,
            !type::IsPointerWrapper< T >::sValue
        >::GetAll(self);
        if (wrapped)
        {
            return wrapped;
        }
        return LinearMotifDispatch< T, false >::GetAll(self);
    }
 
    static Pointer< const Container > GetAll(Pointer< const UnorderedStructureInterface > self)
    {
        Pointer< const LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->GetAllImplementation();
        }
        Pointer< const Container > wrapped = WrappedLinearMotifDispatch<
            T,
            !type::IsPointerWrapper< T >::sValue
        >::GetAll(self);
        if (wrapped)
        {
            return wrapped;
        }
        return LinearMotifDispatch< T, false >::GetAll(self);
    }
 
    static bool Has(Pointer< const UnorderedStructureInterface > self, T content)
    {
        Pointer< const LinearMotif< Pointee > > implementer = ResolveLinearMotif< Pointee >(self);
        if (implementer)
        {
            return implementer->HasImplementation(content);
        }
        bool wrapped = WrappedLinearMotifDispatch<
            T,
            !type::IsPointerWrapper< T >::sValue
        >::Has(self, content);
        if (wrapped)
        {
            return true;
        }
        return LinearMotifDispatch< T, false >::Has(self, content);
    }
};
 
} //structure namespace
} //chemical namespace
} //bio namespace