PointerSafety.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/common/macro/Macros.h"
 
//@formatter:off
#if defined(BIO_POINTER_SAFETY) && BIO_CPP_VERSION >= 11
    #include <unordered_set>
    #include <mutex>
    #include <cstdio>
    #include <cstdlib>
    #include <type_traits>
#endif
//@formatter:on
 
namespace bio {
namespace pointer_safety {
 
//@formatter:off
#if defined(BIO_POINTER_SAFETY) && BIO_CPP_VERSION >= 11
//@formatter:on
 
namespace detail {
 
struct RetiredPointer
{
    RetiredPointer(
        const void* address,
        const void* type
    )
        :
        mAddress(address),
        mType(type)
    {
    }
 
    bool operator==(const RetiredPointer& other) const
    {
        return mAddress == other.mAddress && mType == other.mType;
    }
 
    const void* mAddress;
    const void* mType;
};
 
struct RetiredPointerHash
{
    ::std::size_t operator()(const RetiredPointer& key) const
    {
        const ::std::size_t addressHash = ::std::hash< const void* >()(key.mAddress);
        const ::std::size_t typeHash = ::std::hash< const void* >()(key.mType);
        return addressHash ^ (typeHash + 0x9e3779b97f4a7c15ULL + (addressHash << 6) + (addressHash >> 2));
    }
};
 
struct PointerSafetyRegistry
{
    ::std::unordered_set< RetiredPointer, RetiredPointerHash > mRetired;
    ::std::mutex mLock;
};
 
template < typename T >
inline const void* TypeToken()
{
    typedef typename ::std::remove_cv< T >::type BareT;
    static const char sToken = 0;
    (void)sizeof(BareT*);
    return &sToken;
}
 
template < typename T >
inline RetiredPointer Key(
    const void* p
)
{
    return RetiredPointer(p, TypeToken< T >());
}
 
inline RetiredPointer UntypedKey(
    const void* p
)
{
    return Key< void >(p);
}
 
inline PointerSafetyRegistry& Registry()
{
    static PointerSafetyRegistry* sRegistry = new PointerSafetyRegistry();
    return *sRegistry;
}
 
[[noreturn]] inline void OnRetiredDeref(const void* p, const char* file, int line)
{
    ::std::fprintf(stderr,
        "BIO_POINTER_SAFETY: dereference of retired (freed) pointer %p at %s:%d\n",
        p, file, line);
    ::std::abort();
}
 
} // namespace detail
 
template < typename T >
inline void MarkLive(const void* p)
{
    if (!p) { return; }
    detail::PointerSafetyRegistry& reg = detail::Registry();
    ::std::lock_guard< ::std::mutex > guard(reg.mLock);
    reg.mRetired.erase(detail::Key< T >(p));
    reg.mRetired.erase(detail::UntypedKey(p));
}
 
inline void MarkLive(const void* p)
{
    MarkLive< void >(p);
}
 
template < typename T >
inline void MarkRetired(const void* p)
{
    if (!p) { return; }
    detail::PointerSafetyRegistry& reg = detail::Registry();
    ::std::lock_guard< ::std::mutex > guard(reg.mLock);
    reg.mRetired.insert(detail::Key< T >(p));
}
 
inline void MarkRetired(const void* p)
{
    MarkRetired< void >(p);
}
 
template < typename T >
inline bool IsLive(const void* p)
{
    if (!p) { return true; }
    detail::PointerSafetyRegistry& reg = detail::Registry();
    ::std::lock_guard< ::std::mutex > guard(reg.mLock);
    if (reg.mRetired.find(detail::Key< T >(p)) != reg.mRetired.end())
    {
        return false;
    }
    const detail::RetiredPointer untyped = detail::UntypedKey(p);
    if (untyped.mType != detail::TypeToken< T >()
        && reg.mRetired.find(untyped) != reg.mRetired.end())
    {
        return false;
    }
    return true;
}
 
inline bool IsLive(const void* p)
{
    return IsLive< void >(p);
}
 
template < typename T >
inline void AssertLive(
    const void* p,
    const char* file,
    int line
)
{
    if (!IsLive< T >(p))
    {
        detail::OnRetiredDeref(p, file, line);
    }
}
 
inline void AssertLive(
    const void* p,
    const char* file,
    int line
)
{
    if (!IsLive(p))
    {
        detail::OnRetiredDeref(p, file, line);
    }
}
 
//@formatter:off
#else // feature off (prod) or cpp98: every entry point is a removed no-op.
//@formatter:on
 
template < typename T >
inline void MarkLive(const void*) {}
inline void MarkLive(const void*) {}
template < typename T >
inline void MarkRetired(const void*) {}
inline void MarkRetired(const void*) {}
template < typename T >
inline bool IsLive(const void*) { return true; }
inline bool IsLive(const void*) { return true; }
template < typename T >
inline void AssertLive(const void*, const char*, int) {}
inline void AssertLive(const void*, const char*, int) {}
 
//@formatter:off
#endif
//@formatter:on
 
} // namespace pointer_safety
} // namespace bio
 
//@formatter:off
#if defined(BIO_POINTER_SAFETY) && BIO_CPP_VERSION >= 11
    // Deref guard used inside Pointer< T >::operator-> / operator*. Aborts on a deref of
    // a retired (freed) address whenever BIO_POINTER_SAFETY is on -- NOT NDEBUG-gated, so
    // a Release+BIO_POINTER_SAFETY build catches too. No-op (references nothing) when off.
    #define BIO_POINTER_SAFETY_CHECK(ptr) \
        do { ::bio::pointer_safety::AssertLive((const void*)(ptr), __FILE__, __LINE__); } while (0)
#else
    #define BIO_POINTER_SAFETY_CHECK(ptr) ((void)0)
#endif
//@formatter:on