Cow.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) 2026 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/chemical/wrapper/AtomicCow.h"
#include "bio/physical/common/Class.h"
#include "bio/common/Cast.h"
 
namespace bio {
 
template < typename T >
class Cow :
    public chemical::AtomicCow
{
public:
    Cow(
        Pointer< chemical::Atom > source,
        chemical::AtomicNumber bondId,
        Pointer< physical::Wave > bondedSnapshot
    )
        :
        chemical::AtomicCow(source, bondId, bondedSnapshot)
    {
    }
 
    Pointer< T > Moo()
    {
        Pointer< physical::Wave > bonded = WriteBonded();
        if (!bonded)
        {
            return NULL;
        }
        return ForceCast< physical::Class< T >* >(bonded.Get())->GetWaveObject();
    }
 
    // operator-> ALWAYS shares: it returns a Pointer<const T>, so cow->ConstMethod() is
    // pointer-identical and zero-copy, while cow->NonConstMethod() is a compile error naming
    // the fix ("...on a const T*"). Mutation is therefore explicit and can never silently
    // bleed across clones -- take it via .Moo() (cow.Moo()->Mut()) or by extracting a
    // mutable Pointer<T> (Pointer<T> p = cow, which detaches below). This is the only
    // overload, so a non-const handle binds it too (a const member is callable on a
    // non-const object) -- reads share regardless of the handle's const-ness.
    Pointer< const T > operator->() const
    {
        return View();
    }
 
    // Extraction signals intent by target const-ness: a Pointer<const T> target SHARES (read);
    // a Pointer<T> target copy-on-write DETACHES (write -- a private, uniquely-owned T).
    operator Pointer< const T >() const
    {
        return View();
    }
 
    operator Pointer< T >()
    {
        return Moo();
    }
 
#if BIO_CPP_VERSION >= 11
    // Per-method dispatch for a held handle that interleaves reads and writes:
    // cow(&T::m, args...) reads m's const-ness off the member-pointer TYPE and routes
    // share-vs-detach -- the one place a method's const-ness is visible at compile time
    // (operator-> cannot see it; see the class TODO). A const m shares, a non-const m
    // detaches via Moo(). Args bind to m's exact parameter types, so call-site conversions
    // happen as usual. C++11+ only (variadic templates); cpp98 uses operator-> and Moo().
    template < typename ReturnType, typename... Args >
    ReturnType operator()(ReturnType (T::* method)(Args...) const, Args... args) const
    {
        return (View() ->* method)(args...);
    }
 
    template < typename ReturnType, typename... Args >
    ReturnType operator()(ReturnType (T::* method)(Args...), Args... args)
    {
        return (Moo() ->* method)(args...);
    }
#endif
 
private:
    // The internal SHARE path behind operator->, the Pointer<const T> conversion, and the const
    // dispatch overload. NOT public: reads already go through those (cow->ConstMethod(),
    // Pointer<const X> p = cow), so an explicit View() would only re-expose -- and invite -- the
    // share path the public surface is built to make implicit. Mutation stays explicit via
    // the public Moo(); the asymmetry is the point (reads default, writes deliberate).
    Pointer< const T > View() const
    {
        Pointer< const physical::Wave > bonded = ReadBonded();
        if (!bonded)
        {
            return NULL;
        }
        return ForceCast< const physical::Class< T >* >(bonded.Get())->GetWaveObject();
    }
};
 
} // namespace bio