Exceptions.h

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#ifndef _Stroika_Foundation_Execution_Exceptions_h_
#define _Stroika_Foundation_Execution_Exceptions_h_ 1
 
#include "Stroika/Foundation/StroikaPreComp.h"
 
#include <cerrno>
#include <exception>
#include <mutex>
#include <optional>
#include <stdexcept>
#include <string>
#include <system_error>
 
#include "Stroika/Foundation/Characters/String.h"
 
#include "Stroika/Foundation/Execution/Activity.h"
#include "Stroika/Foundation/Execution/Throw.h"
 
/**
 *  \note Code-Status:  <a href="Code-Status.md#Beta">Beta</a>
 *
 *  \note \em Design Note
 *      (essentially) All exceptions thrown by Stroika (except where needed by quirks of underlying library
 *      integrated with) inherit from std::exception, or are Stroika::Foundation::Execution::SilentException.
 *
 *      This means that any code which wishes to report an exception can catch these two types, and use
 *      the 'what()' method to report the text of the exception message.
 *
 *      Sadly, there is no documentation (I'm aware of) or specification of the character set/code page reported
 *      back by the what () on an exception. It tends to be ascii. Stroika guarantees that all exceptions it throws
 *      will use the current SDK characters (@see SDKString). But - its best to use Characters::ToString () on the
 *      caught exception, since this uses ExceptionStringHelper to properly handle characters the SDK character set might not
 *      allow representing some unicode characters.
 *
 *  TODO:
 *      @todo   COULD MAYBE add 'suppress-activities' object you can declare and while it exists (it sets private thread local storage flag)
 *              activities are not merged into message. But this can be done other ways too and doesn't address other stages of message
 *              formation so I'm not sure that's worth while.
 */
 
namespace Stroika::Foundation::Execution {
 
    /**
     *  The type of 'errno' variable.
     *
     *  \note   POSIX and C99 just say to assume its an int and doesn't define errno_t.
     *          But I find this type usage clearer.
     */
#if qCompilerAndStdLib_Supports_errno_t
    using errno_t = ::errno_t;
#else
    using errno_t = int;
#endif
 
    /**
     *  This is a base class for Execution::Exception<> template, which gets mixed with the std c++ exception class, to mix
     *  in Stroika string support.
     *
     *  This probably should NOT be used directly.
     */
    class ExceptionStringHelper {
    public:
        /**
         *  \brief   activities default to NULLOPT - meaning "not specified" - which is different from "specified,
         *           and there were none".
         *
         *  Nothing is captured at construction. @see Throw () fills them in at the point of throw, but only for
         *  an exception which has not specified them - so an exception built once and thrown many times (e.g. a
         *  `static const`) reports the context of each throw rather than freezing the first one.
         *
         *  Pass them explicitly here, or @see ImbueActivities (), if you are not going through Throw ().
         */
        ExceptionStringHelper () = delete;
        ExceptionStringHelper (const ExceptionStringHelper& src);
        ExceptionStringHelper (const Characters::String& reasonForError, const optional<Containers::Stack<Activity<>>>& activities = nullopt);
 
    public:
        /**
         *  Return error message without added 'activities'.
         */
        nonvirtual Characters::String GetBasicErrorMessage () const;
 
    public:
        /**
         *  Return error message with added 'activities'
         */
        nonvirtual Characters::String GetFullErrorMessage () const;
 
    public:
        /**
         *  Return the activity stack from when the exception was thrown. NOTE - see @Activity<>. This has little
         *  todo with the thread runtime stack. It refers to a logical stack of declared Activity<> objects.
         */
        nonvirtual optional<Containers::Stack<Activity<>>> GetActivities () const;
 
    public:
        /**
         *  \brief   Set, replace, or clear the activity stack. Any already-computed message text is
         *           discarded, since it depends on these.
         *
         *  Takes an optional for symmetry with the constructor and @see GetActivities (), so that every
         *  state is reachable. Passing nullopt returns the exception to "not specified", after which
         *  @see Throw () will stamp in the context of the throw - which is what you want when forwarding
         *  an exception you did not construct.
         *
         *  \note   ***This invalidates any pointer previously returned by what ().*** That is allowed, and is
         *          why this is deliberately a NON-const member: the standard guarantees what ()'s result only
         *          "until the exception object is destroyed, or until a non-const member function on the
         *          exception object is called". Do not hold a what () pointer across a call to this.
         *
         *          @see Throw () - which imbues a COPY it is about to throw, so nobody can be holding a
         *          what () pointer into it - is the normal caller, and is unaffected.
         *
         *  \note   Replacing is allowed on purpose: a caller doing this explicitly knows what it wants.
         *          @see Throw () is the one that will not overwrite - it imbues only when GetActivities () is
         *          nullopt, so deliberately-specified context always survives being thrown.
         */
        nonvirtual void ImbueActivities (const optional<Containers::Stack<Activity<>>>& activities);
 
    public:
        /**
         * Only implemented for
         *      o   wstring
         *      o   String
         *
         * This returns the message callers should display to represent the error (e.g. in exception::c_str ()).
         * For now, it returns GetFullErrorMessage () - but may someday change.
         */
        template <typename T>
        nonvirtual T As () const;
 
    protected:
        /**
         *  In order for subclasses to support the c++ exception::c_str () API, we need to convert
         *  the string/message to an SDKChar string, and have that lifetime be very long. So we store it
         *  in a std::string. And this function returns the pointer to that string. This object is
         *  immutable, so that the lifetime of the underlying return const char* is as long as this object.
         */
        nonvirtual const char* _PeekAtNarrowSDKString () const;
 
    private:
        /**
         *  Builds fFullErrorMessage_/fSDKCharString_ if not already built. Cheap and safe to call repeatedly,
         *  and safe to call concurrently (an exception object can be shared via exception_ptr).
         *
         *  \note   These CANNOT be computed at construction: activities may be supplied afterwards by
         *          @see ImbueActivities (), and the full message merges them in. Computing eagerly would mean
         *          either baking in the wrong context or recomputing.
         *
         *  \note   noexcept because its callers are - notably what (). If formatting fails (allocation), the
         *          cache is left empty rather than propagating.
         */
        nonvirtual void EnsureBuilt_ () const noexcept;
 
    private:
        optional<Containers::Stack<Activity<>>> fActivities_;
        Characters::String                      fRawErrorMessage_;
        mutable mutex                           fBuildMutex_;
        mutable bool                            fBuilt_{false};
        mutable Characters::String              fFullErrorMessage_;
        mutable string                          fSDKCharString_;
    };
    template <>
    wstring ExceptionStringHelper::As () const;
    template <>
    Characters::String ExceptionStringHelper::As () const;
 
    /**
     *  \brief Exception<> is a replacement (subclass) for any std c++ exception class (e.g. the default 'std::exception'), 
     *         which adds UNICODE String support.
     *
     *  Stroika's Exception<> class is fully interoperable with the normal C++ exception classes, but its use offers two
     *  benefits:
     *      o   It guarantees that UNICODE messages (including things like filenames) are properly preserved in the exception
     *          message, even if the system default code page (locale) does not allow representing those characters.
     *
     *      o   It integrates neatly with the Stroika 'Activity' mechanism, whereby you declare current 'activities' on the stack
     *          and these are automatically integrated into exceptions thrown with Execution::Throw (), to provide clearer messages (e.g. instead of
     *          getting the error message 
     *              o   "(errno: 13)" OR 
     *              o   "Permission denied"
     *          Stroika returns something like:
     *              o   "Permission denied {errno: 13} while binding to INADDR_ANY:80, while constructing static content webserver."
     *
     *          @see Activity<>
     *          @see DeclareActivity
     *
     *  \par Example Usage
     *      \code
     *          static constexpr Activity   kBuildingThingy_ {"building thingy"sv };
     *          try {
     *              DeclareActivity declareActivity { &kBuildingThingy_ };
     *              doBuildThing  ();   // Execution::Throw () any Exception<>
     *          }
     *          catch (...) {
     *              String exceptionMsg = Characters::ToString (current_exception ());
     *              Assert (exceptionMsg.Contains (kBuildingThingy_.AsString ()));       // exception e while building thingy...
     *          }
     *      \endcode
     *
     *  \note Satisfies:
     *      o   Exception<std::exception>{msg}          - default-constructible
     *      o   Exception<std::bad_alloc>{msg}          - default-constructible
     *      o   Exception<std::runtime_error>{msg}      - requires a what_arg
     *      o   Exception<std::logic_error>{msg}        - requires a what_arg
     *      o   Exception<std::out_of_range>{msg}       - requires a what_arg
     *
     *  \note   Deliberately NOT std::system_error: it needs an error_code, not a string, so it satisfies
     *          neither constraint and must use the protected delegating ctor below - @see
     *          SystemErrorException. (No static_assert for this one, because it is not portable: libstdc++
     *          declares `system_error (error_code = error_code ())`, so THERE it is default-constructible
     *          and this ctor does match, yielding a useless empty code. MSVC has no such default. Do not
     *          rely on either behaviour.)
     */
    template <derived_from<exception> BASE_EXCEPTION = exception>
    class Exception : public ExceptionStringHelper, public BASE_EXCEPTION {
    private:
        using inherited = BASE_EXCEPTION;
 
    public:
        /**
         *  \brief construct with just a message - BASE_EXCEPTION gets whatever it minimally needs.
         *
         *  Two overloads with mutually exclusive constraints, because the std exception types split into two
         *  groups and NEITHER spelling covers both: some are default-constructible, and some instead require
         *  a what_arg (and have no default ctor). The latter get "" - they need *some* string and do not care
         *  which, since @see what () is overridden to return the Stroika message regardless.
         */
        Exception ()                 = delete;
        Exception (const Exception&) = default;
        Exception (const Characters::String& reasonForError)
            requires (default_initializable<BASE_EXCEPTION>);
        Exception (const Characters::String& reasonForError)
            requires (not default_initializable<BASE_EXCEPTION> and constructible_from<BASE_EXCEPTION, const char*>);
 
    protected:
        /**
         * For BASE_EXCEPTION classes with constructors OTHER than just 'message' - you cannot use a 'using X = Exception(x)' but a subclass
         * which uses this delegating method.
         */
        template <typename... BASE_EXCEPTION_ARGS>
        explicit Exception (const Characters::String& reasonForError, BASE_EXCEPTION_ARGS... baseExceptionArgs);
 
    public:
        /**
         *  Provide a 'c string' variant of the exception message. Convert the UNICODE
         *  string argument to a narrow-string (multibyte) in the current locale encoding.
         */
        virtual const char* what () const noexcept override;
    };
 
#if qCompilerAndStdLib_CTADIgnoresConstructorRequiresClause_Buggy
    /**
     *  \brief explicit deduction guide so 'Exception{msg}' (no explicit template argument) deduces
     *         Exception<exception>, rather than being ambiguous.
     *
     *  Without this, CTAD on 'Exception{msg}' has to choose between the two implicitly-generated guides
     *  for the two constructors above, which differ only in their requires-clause (mutually exclusive, but
     *  only once BASE_EXCEPTION is known - a chicken-and-egg problem for a purely argument-driven deduction).
     *  This explicit guide is a non-template exact match, so ordinary overload resolution picks it over
     *  either implicit (function-template) guide outright, without needing to evaluate their constraints.
     *
     *  @see qCompilerAndStdLib_CTADIgnoresConstructorRequiresClause_Buggy
     */
    Exception (const Characters::String&) -> Exception<exception>;
#endif
 
    static_assert (constructible_from<Exception<exception>, Characters::String>);                // see Satisfies
    static_assert (constructible_from<Exception<bad_alloc>, Characters::String>);                // ""
    static_assert (constructible_from<Execution::Exception<runtime_error>, Characters::String>); // ""
    static_assert (constructible_from<Exception<logic_error>, Characters::String>);              // ""
    static_assert (constructible_from<Exception<out_of_range>, Characters::String>);             // ""
 
    /**
     *  \brief NestedException contains a new higher level error message (typically based on argument basedOnException)
     *         and preserves the original exception (which you can use to get its message, with Characters::ToString (fBasedOnException)
     * 
     *  This also can be used to wrap third-party libraries exceptions, which don't know about 'DeclareActivity' - and incorporating
     *  that into an error message.
     */
    class NestedException : public Execution::Exception<runtime_error> {
    public:
        /**
         */
        NestedException ()                       = delete;
        NestedException (const NestedException&) = default;
        NestedException (const exception_ptr& basedOnException);
        NestedException (const Characters::String& msg, const exception_ptr& basedOnException);
 
    public:
        const exception_ptr fBasedOnException;
    };
 
    /**
     *  Simple wrapper on std::system_error, but adding support for Stroika String, and other utility methods.
     *
     *  \note see https://en.cppreference.com/w/cpp/error/errc for a mapping of errc conditions and ERRNO values.
     *
     *  \note   **Catch `system_error`, not `SystemErrorException`.** Catching the base costs you nothing -
     *          Characters::ToString () still recovers the UNICODE message and the Activity stack (@see Exception<>) -
     *          and it additionally covers what this type does NOT: errors from non-Stroika code (which throws plain
     *          system_error), and Stroika errors built over OTHER system_error subclasses, such as
     *          IO::FileSystem::Exception (an @see Exception<filesystem_error>).
     *
     *  \note   The reverse applies when THROWING: prefer SystemErrorException over a plain std::system_error.
     *          It preserves the UNICODE message, and carries the Activity stack that @see Throw () stamps in
     *          (@see Exception<>); a plain system_error can hold neither, and the catcher cannot recover what
     *          was never there. And since SystemErrorException IS a system_error, throwing the
     *          richer type costs nothing. In short: catch broadly (system_error), throw richly
     *          (SystemErrorException, or let @see ThrowError () build it for you).
     *
     *  \note   ***Changed in Stroika v3.0d25*** - this is no longer a template; spell it without the `<>`.
     *          It exists only to add error_code-shaped constructors to Exception<system_error>, and those
     *          constructors are meaningful ONLY for system_error - no other standard system_error subclass has
     *          a constructor taking a bare error_code (filesystem_error, for one, requires a what_arg). The old
     *          `SystemErrorException<BASE_EXCEPTION>` therefore offered a generality it could not deliver.
     *          To mix Stroika's string/Activity support into a DIFFERENT system_error subclass, derive from
     *          @see Exception<THAT_TYPE> directly - which is what IO::FileSystem::Exception now does.
     *
     *  \par Example Usage
     *      \code
     *          try {
     *              ThrowPOSIXErrNo (make_error_code (errc::bad_address).value ());
     *          }
     *          catch (const std::system_error& e) {
     *              EXPECT_TRUE (e.code ().value () == make_error_code (errc::bad_address).value ());
     *              EXPECT_TRUE (e.code ().category () == system_category () or e.code ().category () == generic_category ());
     *              Assert (Characters::ToString (e).Contains ("bad address {errno: 14}"));
     *          }
     *      \endcode
     *
     *  Note this preserves UNICODE characters in messages, even if not using UNICODE code page/locale
     *  \par Example Usage
     *      \code
     *          try {
     *          const Characters::String kMsgWithUnicode_ = L"zß水𝄋"; // this works even if using a code page / locale which doesn't support UNICODE/Chinese
     *          try {
     *              Execution::Throw (SystemErrorException (make_error_code (errc::bad_address), kMsgWithUnicode_));
     *          }
     *          catch (const std::system_error& e) {
     *              Assert (Characters::ToString (e).Contains (kMsgWithUnicode_));  // message also includes the number for bad_address
     *          }
     *      \endcode
     *
     *  \par Example Usage
     *      \code
     *          try {
     *              s.JoinMulticastGroup (UPnP::SSDP::V4::kSocketAddress.GetInternetAddress ());
     *          }
     *          catch (const std::system_error& e) {
     *              if (Execution::IsA (e, errc::no_such_device)) {
     *                  // This can happen on Linux when you start before you have a network connection - no problem - just keep trying
     *                  DbgTrace ("Got exception (errno: ENODEV) - while joining multicast group, so try again");
     *                  Execution::Sleep (1);
     *                  goto Again;
     *              }
     *              else {
     *                  Execution::ReThrow ();
     *              }
     *          }
     *      \endcode
     *
     *  \note   The constructors which take no message build one from the error_code, via its category. For a
     *          few codes whose platform wording is poor or actively misleading, Stroika substitutes a clearer
     *          string instead - notably errc::timed_out, which glibc renders "Connection timed out" even for a
     *          mutex or event wait. @see ThrowError for the full rule and rationale.
     *
     *  \note   ***Considered and declined 2026-09-22: removing this type altogether.*** The argument was that it
     *          is a footgun - someone can catch it, and thereby silently miss every error Stroika raises over a
     *          DIFFERENT system_error subclass - and that anything it does could be had from Exception<system_error>
     *          directly.
     *
     *          The first half is true, which is why the advice above exists. The second is not: these constructors
     *          synthesize the message from the error_code (@see Private_::SystemErrorExceptionPrivate_), including
     *          the substitutions described below, and that machinery is private. Removing the class would push
     *          message synthesis onto every throw site, or replace it with a factory function that is the same
     *          thing without a name - neither simpler.
     *
     *          In practice the exposure is small: @see ThrowError () is the normal path and builds this for you,
     *          and direct construction is rare. So the type stays, and the rule stays: throw richly, catch broadly.
     *
     *  @see also GetAssociatedErrorCode ()
     */
    class SystemErrorException : public Exception<system_error> {
    private:
        using inherited = Exception<system_error>;
 
    public:
        /**
         */
        SystemErrorException (error_code errCode);
        SystemErrorException (error_code errCode, const Characters::String& message);
        SystemErrorException (int ev, const error_category& ecat);
        SystemErrorException (int ev, const error_category& ecat, const Characters::String& message);
    };
 
    /**
     *  \brief treats argument errNo as a `POSIX errno` value, and calls ThrowError () with an error_code constructed from it
     *
     *  \pre errNo != 0
     *
     *  \note   Since this calls @see ThrowError - it will throw a @see SystemErrorException (or a derived type) or bad_alloc.
     *
     *  \note   On a POSIX system, this amounts to a call to ThrowSystemErrNo.
     *          But even on a non-POSIX system, many APIs map their error numbers to POSIX error numbers so this can make sense to use.
     *          Also, on POSIX systems, its legal to call this with POSIX compatible extended (and therefore not POSIX) erorr nubmbers.
     *          In other words, you can call this with anything (except 0) you read out of errno on a POSIX system.
     *
     *  \note  From http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/n4659.pdf  -
     *          "If the argument ev corresponds to a POSIX errno value posv, the function
     *          shall return error_- condition(posv, generic_category()). Otherwise, the function"
     *
     *  \note this function takes errno as a default value because you almost always want to call it with the value from errno.
     *
     *  See:
     *      @see ThrowSystemErrNo ();
     */
    [[noreturn]] void ThrowPOSIXErrNo (errno_t errNo = errno);
 
    /**
     *  Look at the argument value and if < 0,ThrowPOSIXErrNo (), and otherwise return it.
     *
     *  \note   Many POSIX - APIs - return a number which is zero if good, or -1 (or sometimes defined negative) if errno is set and there is an error.
     *          This function is useful for wrapping calls to those style functions. It checks if the argument result is negative (so -1 covers that) and
     *          throws and a POSIX (generic_error) SystemErrorException.
     */
    template <typename INT_TYPE>
    INT_TYPE ThrowPOSIXErrNoIfNegative (INT_TYPE returnCode);
 
    /**
     *  \brief treats argument sysErr as a platform-defined error number, and calls ThrowError () with an error_code constructed from it.
     *
     *  \pre sysErr != 0
     *
     *  \note   Since this calls @see ThrowError - it will throw a @see SystemErrorException (or a derived type) or bad_alloc.
     *
     *  \note   stdc++ uses 'int' for the type of this error number, but Windows generally defines the type to be
     *          DWORD.
     *
     *  \par Which error_category it uses
     *      o   POSIX:   std::system_category ()
     *      o   Windows: Platform::Windows::Win32_error_category () - the same value and name () ("system")
     *          as std::system_category (), but it maps more codes onto the portable errc conditions
     *          (@see Platform::Windows::Win32_error_category)
     *
     *      So test what you catch with IsA (e, errc::...), or on Windows Platform::Windows::IsWin32Error
     *      (e.code (), ERROR_X) - never by comparing with error_code{n, system_category ()}.
     *
     *  \note   This follows the rule the standard library sets for its own errors ([value.error.codes],
     *          http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2017/n4659.pdf): "That object's category()
     *          member shall return std::system_category() for errors originating from the operating system,
     *          or a reference to an implementation-defined error_category object for errors originating
     *          elsewhere." Windows is the deliberate exception - why: https://github.com/SophistSolutions/Stroika/issues/1192
     *
     *  \par Example Usage
     *      \code
     *          #if qStroika_Platform_POSIX
     *              ThrowSystemErrNo (errno);
     *          #elif qStroika_Platform_Windows
     *              ThrowSystemErrNo (::GetLastError ());      // works with this type of error # - GetLastError () is default if no arg provided
     *              ThrowSystemErrNo (::WSAGetLastError ());   // or this
     *          #endif
     *      \endcode
     *
     *  See:
     *      @see ThrowPOSIXErrNo ();
     *
     *  \note   zero arg versions only defined for POSIX and Windows platforms, and there the default is the obvious value for each
     *          platform - errno and GetLastError(). It is still an assertion (require) error to call these when errno / GetLastError () would return 0.
     */
    [[noreturn]] void ThrowSystemErrNo (int sysErr);
#if qStroika_Platform_POSIX or qStroika_Platform_Windows
    [[noreturn]] void ThrowSystemErrNo (); ///< \brief ThrowSystemErrNo (errno) on POSIX, ThrowSystemErrNo (::GetLastError ()) on Windows
#endif
 
    /**
     *  \brief throw a SystemErrorException with the given error_code - or std::bad_alloc for errc::not_enough_memory, the one type promotion documented below.
     *
     *  \par This throws EITHER a SystemErrorException (a subclass of system_error), OR std::bad_alloc.
     *
     *  Use this - rather than constructing and throwing a SystemErrorException directly - whenever you have an
     *  error_code from ANY error_category: the OS, or a third party library which defines its own category
     *  (libcurl, getaddrinfo/DNS, HRESULT, ...). It is what gives callers one portable story about how errors
     *  surface, independent of where they came from.
     *
     *  \pre ec != error_code{}
     *
     *  \par What a caller must catch
     *      This throws EITHER something derived from std::system_error, OR std::bad_alloc. There is no third
     *      possibility. So a caller which wants to handle everything needs:
     *
     *      \code
     *          try {
     *              ...
     *          }
     *          catch (const system_error& e) {
     *              // everything except memory exhaustion; always test the CONDITION, not the value
     *              if (Execution::IsA (e, errc::timed_out)) { ... }
     *              DbgTrace ("{}"_f, Characters::ToString (e)); // NB: ToString (e), NOT e.what () - see below
     *          }
     *          catch (const bad_alloc&) {
     *              // memory exhaustion ONLY - see below for why this is separate
     *          }
     *      \endcode
     *
     *  \note   **Catch std::system_error, NOT SystemErrorException** - even though today ThrowError () only
     *          ever throws the latter. Catching the base additionally covers errors from non-Stroika code (which
     *          throws plain system_error), and Stroika errors built over other system_error subclasses -
     *          IO::FileSystem::Exception is an Exception<filesystem_error>, and so is NOT a SystemErrorException.
     *          @see the note on SystemErrorException itself, which gives the same advice.
     *
     *          (For reference, the C++ standard defines exactly two subclasses of system_error:
     *          std::ios_base::failure and std::filesystem::filesystem_error. std::future_error is NOT one of
     *          them - it derives from logic_error - and neither are C++20's chrono local-time exceptions.)
     *
     *  \note   **Catching the base costs you nothing - as long as you read the message with
     *          Characters::ToString (e) rather than e.what ().** ToString () does a dynamic_cast to
     *          Execution::ExceptionStringHelper (@see Characters::ToStringDefaults::ToString), and a
     *          dynamic_cast cross-casts, so it finds the Stroika half through ANY base reference -
     *          system_error, or even std::exception. What it returns is As<String> (), which is
     *          GetFullErrorMessage (), so you get the full UNICODE text **with the Activity stack already
     *          merged in** - exactly what you would have got by catching the derived type.
     *
     *          e.what () is the lossy path: it is narrow SDK-charset, so characters the SDK code page cannot
     *          represent do not survive. That is the whole reason Exception<> exists (@see Exception<>).
     *
     *          If you want the activities structurally rather than as message text, dynamic_cast to
     *          Execution::ExceptionStringHelper yourself and call GetActivities ().
     *
     *      The bad_alloc case is the ONLY reason two handlers are needed, and it is deliberate: bad_alloc does
     *      not derive from system_error, because allocation failure is the one error C++ has always expected you
     *      to catch by its own standard type. Folding it in as just another error_code would be more uniform but
     *      would fight decades of convention, so it is called out separately instead.
     *
     *  \par The one type promotion
     *      The rule is deliberately narrow: **promote only to a type the C++ standard itself already defines for
     *      that condition.** That yields exactly one entry:
     *
     *      | condition                 | thrown type      | still a SystemErrorException? |
     *      |---------------------------|------------------|-------------------------------|
     *      | `errc::not_enough_memory` | `std::bad_alloc` | **no**                        |
     *
     *      Every other error_code - errc::timed_out included - throws a plain SystemErrorException: test a
     *      timeout with `Execution::IsA (e, errc::timed_out)`.
     *
     *  \par What is preserved, and what is not
     *      **ThrowError () preserves what the error MEANS. It does not promise to preserve how that meaning is
     *      REPRESENTED.** Where the two conflict it normalizes - sometimes lossily - so the error can be tested
     *      portably. In order of how much is given up:
     *
     *      o   Usually nothing: the error_code is passed through untouched, and only the thrown type is chosen
     *          from it. `e.code ().category ()` still names where the error came from, which is what makes
     *          library-specific diagnosis possible.
     *      o   Windows codes keep their raw value: the conditions MSVC's system_category leaves out (a WinHTTP
     *          timeout, a refused connection, ...) come from @see Platform::Windows::Win32_error_category, which
     *          ThrowSystemErrNo () tags them with - so nothing needs rewriting (as WAIT_TIMEOUT and
     *          ERROR_INTERNET_TIMEOUT once were).
     *      o   `errc::not_enough_memory` becomes `std::bad_alloc`, giving up the error_code entirely - bad_alloc
     *          has no code () - because that is the type C++ has always expected you to catch for allocation
     *          failure. This is also why it needs its own catch handler, and why GetAssociatedErrorCode ()
     *          returns nullopt for it. It gives up the caller's message and the Activity stack too; that is
     *          deliberate, and the note below says why.
     *
     *  \note   **Why the bad_alloc case alone is allowed to be this lossy.** Everywhere else, Stroika works hard
     *          to carry a UNICODE message and the Activity context (@see Exception<>). Here it deliberately
     *          does not, and the reason is that the enrichment would need the very resource that just ran out:
     *          building a message and copying an activity stack means several allocations, performed while
     *          reporting that an allocation failed. Under genuine memory pressure that can throw from inside
     *          the throw, turning a clean bad_alloc into something far harder to diagnose. std::bad_alloc is
     *          specified to be cheap to create for exactly this reason, and wrapping it would throw that away.
     *
     *          Little is lost in practice. @see Throw () already traces the message and the activities at the
     *          throw point, which is where anyone diagnosing this would look; and an out-of-memory failure is
     *          rarely recoverable, so rich structured context buys less here than anywhere else.
     *
     *          Considered and rejected 2026-09-09: making this throw an Exception<bad_alloc> so the message and
     *          activities survive. It works, and `catch (const bad_alloc&)` would keep matching - but it trades
     *          a reliable failure for a richer one that is least reliable exactly when it matters. Revisit only
     *          with a concrete case where the lost context actually mattered.
     *
     *      So: **test what the error means** - `e.code () == errc::whatever`, or `catch (const bad_alloc&)` -
     *      and none of this normalization is visible to you. Test how it is represented -
     *      `e.code ().value () == SOME_PLATFORM_CONSTANT` - and it is.
     *      @see ThrowTranslatedExceptionIfNeeded_ in Exceptions.cpp for the mechanism.
     *
     *      **If you do not want any of that** - if you want the exception object you constructed delivered to
     *      the catcher unchanged - then say so by using @see Throw () instead. That is the whole distinction
     *      between the two: ThrowError () normalizes, possibly lossily, in exchange for portability; Throw ()
     *      is literal.
     *
     *      The narrow rule is what stops the table being arbitrary. The obvious question about any such table is
     *      "why this condition and not permission_denied, or connection_refused?" - and the answer is that C++
     *      defines std::bad_alloc and defines no counterpart for the others. Nothing is invented.
     *
     *  \par How Stroika treats errc::timed_out, and what its default message says
     *      **Stroika treats errc::timed_out as the generic "the time limit for this operation expired"
     *      condition** - nothing connection-specific. Every Stroika timeout answers to it: a Synchronized<>
     *      lock acquisition, Thread::WaitForDone (), a WaitableEvent, a socket read, a libcurl transfer. That
     *      uniformity is what makes `Execution::IsA (e, errc::timed_out)` the one portable timeout test.
     *
     *      That is the condition's actual meaning, not a Stroika invention. POSIX specifies ETIMEDOUT - which
     *      std::errc::timed_out names - as the result of pthread_mutex_timedlock (), pthread_cond_timedwait (),
     *      sem_timedwait () and mq_timedreceive (), none of which involve a connection.
     *
     *      \note ***Changed in Stroika v3.0d25*** - the DEFAULT message now reflects that. glibc renders
     *            ETIMEDOUT as "Connection timed out" (a BSD-sockets legacy - ETIMEDOUT began life as a
     *            connect () error), while MSVC renders it "timed out": so before v3.0d25 the very same lock
     *            timeout was described differently on each platform, and misleadingly on one. Stroika now
     *            substitutes **"Operation timed out"** when it builds a default message for errc::timed_out in
     *            `generic_category ()` - which is exactly the case where STROIKA decided something timed out,
     *            since make_error_code () always yields that category. A timeout reported by the OS arrives in
     *            `system_category ()` (@see ThrowPOSIXErrNo) and keeps the platform's own wording, which is
     *            accurate there. A message you pass explicitly is never touched.
     *
     *            Nothing portable is being overridden: the standard specifies error_category::message () only
     *            as "a string that describes the error condition", so the text is implementation-defined and
     *            the two platforms already disagreed. @see SystemErrorException, whose constructor is where a
     *            default message actually gets built.
     *
     *  \par Relationship to ThrowPOSIXErrNo () and ThrowSystemErrNo ()
     *      All three funnel through here and behave identically once they do. They differ ONLY in which
     *      error_category the raw number gets tagged with - that is, in how the error_code is built:
     *
     *      | function               | category used                                             |
     *      |------------------------|-----------------------------------------------------------|
     *      | `ThrowError (ec)`      | whatever category you put in the error_code               |
     *      | `ThrowSystemErrNo (n)` | `system_category ()` (on Windows `Platform::Windows::Win32_error_category ()`) |
     *      | `ThrowPOSIXErrNo (n)`  | `system_category ()` on POSIX, else `generic_category ()` |
     *
     *      So on a POSIX system ThrowPOSIXErrNo and ThrowSystemErrNo are the same call - errno IS the
     *      platform's native error space there, so one subsumes the other. They diverge only on Windows,
     *      where errno and GetLastError () are distinct numbering spaces and must not be tagged with the
     *      same category. Pick whichever names where your number actually came from.
     *
     *      **The category is not just a label.** It supplies default_error_condition () and equivalent (), which
     *      is what every `e.code () == errc::something` test - and the bad_alloc promotion above - is matched
     *      against. So tagging a number with the wrong category does not merely mislabel the error, it silently
     *      changes which conditions the error appears to satisfy. WAIT_TIMEOUT in a Win32 category compares
     *      equal to errc::timed_out; the same number tagged with generic_category () is interpreted as an errno
     *      instead, and matches something else or nothing at all. That - not tidiness - is why these two
     *      functions must stay separate on Windows. (And it is why Win32 codes get Stroika's
     *      Win32_error_category () rather than plain system_category (), whose mapping misses, for example,
     *      ERROR_WINHTTP_TIMEOUT.)
     *
     *  \note   Matching is driven by the CONDITION, not the raw value, so any category which maps its own
     *          numbering onto std::errc (as the LibCurl and DNS categories both do) participates automatically.
     *          That is precisely what error_category::default_error_condition is for - a category author gets
     *          this simply by writing a correct mapping.
     *
     *  \par Example Usage
     *      \code
     *          // wrapping a third party library which has its own error_category
     *          if (status != kThirdPartyOK) [[unlikely]] {
     *              ThrowError (error_code{status, ThirdParty_error_category ()});
     *          }
     *      \endcode
     *
     *  \par Raising a portable condition directly - the std::errc overload
     *      When the error did not come from anywhere with its own numbering - Stroika itself has decided the
     *      operation timed out, say - there is no category to name, and `ThrowError (errc::timed_out)` says so
     *      directly:
     *
     *      \code
     *          ThrowError (errc::timed_out, "Timeout Expired"sv);                      // instead of
     *          ThrowError (make_error_code (errc::timed_out), "Timeout Expired"sv);
     *      \endcode
     *
     *      This is exactly `ThrowError (make_error_code (ec))` and nothing else. It is unambiguous with the
     *      error_code overloads because `is_error_code_enum_v<errc>` is **false** - std::errc has no implicit
     *      conversion to error_code - so overload resolution cannot pick the wrong one.
     *
     *  \note   Use the error_code overload whenever you HAVE a category. std::errc names a *condition*, and
     *          make_error_code () resolves it to `generic_category ()` - it asserts the error originated as a
     *          POSIX errno. That is true when Stroika raises the error itself; it is NOT true of an error handed
     *          back by the OS or a third-party library, and flattening one of those to an errc discards where it
     *          came from. Since `e.code () == errc::whatever` matches either way, nothing is gained by
     *          discarding the category.
     *
     *  See:
     *      @see ThrowPOSIXErrNo ();
     *      @see ThrowSystemErrNo ();
     */
    [[noreturn]] void ThrowError (error_code ec);
    [[noreturn]] void ThrowError (error_code ec, const Characters::String& message);
    [[noreturn]] void ThrowError (errc ec);
    [[noreturn]] void ThrowError (errc ec, const Characters::String& message);
 
    /**
     *  \brief Handle UNIX EINTR system call behavior - fairly transparently - just effectively removes them from the set of errors that can be returned
     *
     *  Run the given (argument) call. After each call, invoke Thread::CheckForInterruption ().
     *  If the call returns < 0 and errno == EINTR, repeat the call.
     *  If the result was < 0, but errno != EINTR, then ThrowErrNoIfNegative ();
     *  Then return the result.
     *
     *  \note The only HITCH with respect to automatically handling interruptability is that that its handled by 'restarting' the argument 'call'
     *        That means if it was partially completed, the provider of 'call' must accommodate that fact (use mutable lambda).
     *
     *  This behavior is meant to work with the frequent POSIX API semantics of a return value of < 0
     *  implying an error, and < 0 but errno == EINTR means retry the call. This API also provides a
     *  cancelation point - so it makes otherwise blocking calls (like select, or read) work well with thread
     *  interruption.
     *
     *  \note   ***Cancelation Point***
     */
    template <typename CALL>
    auto Handle_ErrNoResultInterruption (CALL call) -> decltype (call ());
 
    /**
     *  Check the argument 'return value' from some function, and if its null, throw a SystemError exception with
     *  the current errno value.
     *
     *  \note rarely useful, but some POSIX APIs such as getcwd() do return null on error.
     */
    void ThrowPOSIXErrNoIfNull (void* returnValue);
 
    /**
     *  This checks if the given exception_ptr is of a type that contains an error code, and if so
     *  it extracts the error code, and returns it (else nullopt).
     *
     *  \par Example Usage
     *      \code
     *          try {
     *              /// do something that throws
     *          }
     *          catch (...) {
     *              if (auto err = GetAssociatedErrorCode (current_exception ())) {
     *                  if (*err == errc::no_such_device) {
     *                      // This can happen on Linux when you start before you have a network connection - no problem - just keep trying
     *                      DbgTrace ("Got exception (errno: ENODEV) - while joining multicast group, so try again");
     *                      Execution::Sleep (1);
     *                      goto Again;
     *                  }
     *                  else {
     *                      Execution::ReThrow ();
     *                  }
     *              }
     *          }
     *      \endcode
     */
    optional<error_code> GetAssociatedErrorCode (const exception_ptr& e) noexcept;
 
    /**
     *  \brief Does this error MEAN the given condition - regardless of how it happens to be represented?
     *
     *  This is the recommended way to test an error in Stroika code. It is `e.code () == cond` with the
     *  question asked once, correctly, and with overloads for the things you actually hold - including
     *  exception_ptr, which the standard gives you no way to interrogate without rethrowing.
     *
     *  \note basically same as e.code () == cond, but safer (less error prone and not MATCHES on differnt error_category, etc)
     * 
     *  \par Example Usage
     *      \code
     *          try {
     *              t.WaitForDone (1s);
     *          }
     *          catch (const system_error& e) {
     *              if (Execution::IsA (e, errc::timed_out)) {
     *                  ...
     *              }
     *          }
     *      \endcode
     *
     *  \note   ***Why this exists, and why it takes an error_condition***
     *
     *          std::error_code and std::error_condition look interchangeable and are not. A CODE is a
     *          concrete value in some category - `errno`, a Win32 error, a libcurl status. A CONDITION is
     *          the portable meaning those map onto. Comparing a code to a condition asks what the error
     *          MEANS and works whatever category it arrived in. Comparing `e.code ().value ()` to a number
     *          asks how it is REPRESENTED, and is right only if you guessed the category correctly - it
     *          compiles, it looks reasonable, and it is usually wrong.
     *
     *          That trap is inherited from the c++ standard and Stroika cannot remove it. What it can do is
     *          make the recommended form incapable of expressing it: the second parameter is an
     *          error_condition BY VALUE, so `IsA (e, errc::timed_out)` converts implicitly and compiles,
     *          while `IsA (e, ERROR_FILE_NOT_FOUND)` and `IsA (e, someErrorCode)` do not compile at all.
     *
     *          `e.code () == errc::X` remains perfectly correct, and existing code using it is fine.
     *
     *  \note   On Windows, IsA () also answers for a Win32 code that arrived in std::system_category () (from the
     *          standard library, say) as if it were in Platform::Windows::Win32_error_category () - so it gets the
     *          conditions Microsoft's mapping leaves out. A raw `e.code () == errc::X` does not get that for such a
     *          code; IsA () is the one portable test.
     *
     *  \note   The exception_ptr and exception overloads answer false for anything that carries no error
     *          code, which includes a null exception_ptr. They never throw.
     *
     *  @see GetAssociatedErrorCode
     *  @see Tests/37, Test5_error_code_condition_compares_ - which demonstrates the trap directly.
     */
    bool IsA (const error_code& ec, error_condition cond) noexcept;
    bool IsA (const system_error& e, error_condition cond) noexcept;  ///< \brief Does this error MEAN the given condition?
    bool IsA (const exception& e, error_condition cond) noexcept;     ///< \brief ...and false if it carries no error code at all
    bool IsA (const exception_ptr& e, error_condition cond) noexcept; ///< \brief ...without having to rethrow it to find out
 
    /**
     *  Wrap the the argument function (typically a lambda) in an OPTIONAL of the argument type, and return nullopt - dropping the exception
     *  on the floor.
     * 
     *  @todo When we support std c++23, do likewise for expected!!!
     */
    template <typename F>
    inline auto TranslateExceptionToOptional (F&& f) -> optional<remove_cvref_t<invoke_result_t<F>>>;
 
}
 
#if qStroika_Platform_Windows
namespace Stroika::Foundation::Execution::Platform::Windows {
 
    /**
     *  \brief The error_category Stroika tags Win32 error numbers (GetLastError ()) with: std::system_category (), plus the
     *         portable conditions Microsoft's leaves out.
     *
     *  MSVC's system_category maps a Win32 code onto a portable condition with one flat, one-to-one table, which knows
     *  nothing of the WinINet / WinHTTP range (so ERROR_WINHTTP_TIMEOUT is not errc::timed_out) and misses winerror.h's
     *  own connection errors (ERROR_CONNECTION_REFUSED, ...) although it maps their Winsock twins. Its message () also
     *  says "unknown error" for codes whose text lives in a module (wininet.dll / winhttp.dll). This category answers
     *  those, and delegates everything else - name () included - to std::system_category ().
     *
     *  Mapping a numbering onto conditions is what an error_category is FOR, so this keeps the raw code (unlike
     *  rewriting it at throw time), and both `e.code () == errc::X` and IsA () work. It maps a code onto MORE than one
     *  condition where the meaning is ambiguous (via equivalent ()), since Win32 codes do not divide as neatly as
     *  POSIX errno does. @see https://github.com/SophistSolutions/Stroika/issues/1192 for the alternatives considered.
     *
     *  \note   A Win32 error_code in std::system_category () - from the standard library or another library - is
     *          still a different code from the same number in this category. Execution::IsA () treats it as this
     *          category, so test with IsA (), or with IsWin32Error () for an exact code - not `ec == error_code{...}`.
     *
     *  This object lives forever (like other error categories).
     */
    const error_category& Win32_error_category () noexcept;
 
    /**
     *  \brief Is ec the given Win32 error number - in Win32_error_category () or std::system_category ()?
     *
     *  Use this instead of `ec == error_code{ERROR_X, system_category ()}`, which no longer matches errors Stroika throws
     *  (@see Win32_error_category).
     */
    bool IsWin32Error (const error_code& ec, int win32Err) noexcept;
 
}
#endif
 
/*
 ********************************************************************************
 ***************************** Implementation Details ***************************
 ********************************************************************************
 */
#include "Exceptions.inl"
 
#endif /*_Stroika_Foundation_Execution_Exceptions_h_*/