ProcessRunner.h

/*
 * Copyright(c) Sophist Solutions, Inc. 1990-2026.  All rights reserved
 */
#ifndef _Stroika_Foundation_Execution_ProcessRunner_h_
#define _Stroika_Foundation_Execution_ProcessRunner_h_ 1
 
#include "Stroika/Foundation/StroikaPreComp.h"
 
#include <filesystem>
#include <optional>
 
#include "Stroika/Foundation/Characters/CodeCvt.h"
#include "Stroika/Foundation/Characters/String.h"
#include "Stroika/Foundation/Common/Common.h"
#include "Stroika/Foundation/Containers/Mapping.h"
#include "Stroika/Foundation/Containers/Sequence.h"
#include "Stroika/Foundation/Debug/AssertExternallySynchronizedChecker.h"
#include "Stroika/Foundation/Execution/CommandLine.h"
#include "Stroika/Foundation/Execution/Process.h"
#include "Stroika/Foundation/Execution/Signals.h"
#include "Stroika/Foundation/Memory/BLOB.h"
#include "Stroika/Foundation/Streams/InputStream.h"
#include "Stroika/Foundation/Streams/OutputStream.h"
 
// DEPRECATED - only while we have deprecated apis for use of progressmontior in this class
#include "Stroika/Foundation/Execution/ProgressMonitor.h"
 
/**
 *  TODO:
 *      @todo   After we lose DEPRECATED APIS (STREAM STUFF) - Run and RunInBackground can become const methods
 * 
 *      @todo   Redo POSIX impl using vfork () or http://linux.die.net/man/3/posix_spawn
 *
 *      @todo   Fix POSIX version to use vfork() instead of fork () - but carefully! Must setup data just so.
 *
 *      @todo   Fix POSIX version to properly handle reading and writing streams at the same time to avoid deadlock
 *              in finite kernel buffer sizes.
 *
 *      @todo   Fix POSIX version to use pipe2 and close appropriate open file descriptors (and other 'clean invoke' stuff.
 *
 *      @todo   Redo DWORD   waitResult  =   ::WaitForMultipleObjects()... logic to wait on thread and each read/write socket
 *              with select() AND somehow maybe eventually wait on streams (so we don't have to pre-read it all)
 *
 *      @todo   Make sure it handles well without blocking
 *              (tricks I had todo in HF - forcing extra reads so writes wouldn't block).
 *              Currently structured to work off a single runnable, which implies works off a single thread. That implies
 *              it must use select() - probably a good idea anyhow - on each socket used for operations (windows and POSIX).
 *
 *              So data pusher/buffer loop does select on external streams to see if data available.
 *
 *              This implies I must also be able to do the moral equivalent of selects on my BinaryInput/Output streams? Maybe,
 *              unless I do all the buffering... But at least for the stdin stream - I need to be able to check if/when there
 *              is new data available!!! TRICKY
 *
 *      @todo   Decide on/document semantics if there is a change in setting STDIN/SETDOUT etc while a runner exists?
 *              If error - always detectable?
 *
 *              And related - what if we create a runner, and then destroy the object? How to assure runner fully
 *              destroyed? Blocking/waiting or error or detached state?
 *
 *      @todo   Add optional hook to be run (at least for POSIX) inside the FORKED process, before the exec.
 *              Can be used to reset signals, and/or close file descriptors. Maybe have optional
 *              flag to auto-do this stuff and or have a preset value hook proc do do most standard things.
 *
 *  Design Goals:
 *      o   Be able to run simple processes and capture output with little overhead, and very easy to do
 *          (like perl backticks).
 *
 *      o   Be able to support pipes between processes (either within the shell, or between Stroika threads)
 *
 *      o   Support large data and blocking issues properly - automating avoidance of pipe full bugs
 *          which block processes
 *
 *      o   Efficient/Low performance overhead
 *
 *      o   For POSIX - simple to cleanly cleanup open sockets/resources (not needed on windows)
 *
 *      o   Separate threading implementation from API, so easy to externally specify the thread
 *          stuff  runs on (e.g. so you can use thread pools to run the processes).
 *
 *      o   Work with stroika streams so its easy to have user-defined producers and consumers, and
 *          easy to hook together TextStreams (wrappers) - for format conversion/piping.
 *
 *  \em Design Overview
 *      o
 *
 */
 
namespace Stroika::Foundation::Execution {
 
    using Characters::String;
    using Containers::Mapping;
    using Containers::Sequence;
 
    /**
     *  \brief Run an external command, with stdin/stdout/stderr as strings or as streams - like perl backticks
     *
     *  There are two ways to run, and the difference is all you really need to know:
     *
     *      o   Run () is synchronous. It returns the output, and THROWS on any failure - including the
     *          process merely exiting non-zero. Nothing to check; if it returns, it worked.
     *      o   RunInBackground () hands back a BackgroundProcess you wait on and interrogate - exit status,
     *          signal, child pid - so you can treat a failed run as data instead of as an exception.
     *
     *  Run () behaves as if it were RunInBackground (), then waiting, then
     *  ProcessResultType::ThrowIfFailed ().
     *
     *  \note   ProcessRunner searches the PATH for the given executable: it need not be a full or even relative to
     *          cwd path.
     *
     *  \par Example Usage - Run (), the simple case
     *      \code
     *          String name = get<0> (ProcessRunner{"uname"}.Run (String {})).Trim ();
     *
     *          ProcessRunner pr{"echo hi mom"};
     *          auto [stdOutStr, stdErrStr] = pr.Run ("");     // throws if echo fails or exits non-zero
     *          EXPECT_EQ (stdOutStr.Trim (), "hi mom");
     *      \endcode
     *
     *  \par Example Usage - RunInBackground (), when the exit status is data rather than an error
     *      \code
     *          ProcessRunner::BackgroundProcess bp = ProcessRunner{"grep pattern somefile"}.RunInBackground ();
     *          bp.WaitForDone ();
     *          // grep exits 1 for 'no match', which is an answer and not a failure
     *          optional<ProcessRunner::ProcessResultType> r = bp.GetProcessResult ();
     *          bool matched = r and r->fExitStatus == 0;
     *      \endcode
     *
     *  \note   Historical note: the idea came from KDJ - do something like python/perl subprocess handling,
     *          as a simple portable wrapper.
     */
    class ProcessRunner {
    public:
        static constexpr CommandLine::WrapInShell kDefaultShell =
#if qStroika_Platform_Windows
            CommandLine::WrapInShell::eWindowsCMD
#else
            CommandLine::WrapInShell::eBash
#endif
            ;
 
    public:
        /**
         */
        struct Options {
            /**
             *  \brief pwd/cwd of the created process
             *      defaults to 'missing'. If missing, then WellKnownDirectories::GetTemporary () is 
             *      used (since this is a generally safe place to run an executable); use filesystem::current_path () if that is the intention.
             */
            optional<filesystem::path> fWorkingDirectory;
 
            /**
             *  If provided, child executed with this replacing its 'environment'; Variant 'Sequence<path>' means just the PATH part replaced.
             *  If Mapping<String,...> converted to SDKString codepage, and if SDKString provided, used as-is.
             */
            optional<variant<Sequence<filesystem::path>, Mapping<String, String>, Mapping<Characters::SDKString, Characters::SDKString>>> fEnvironment;
 
            /**
             *  If true, then any nullptr input / output pipes are replaced with /dev/null (or equivalent)
             *  And any 'terminal' associated with the calling process is eliminated from the child
             *  process.
             * 
             *  Case POSIX:
             *      This also detaches from the terminal driver, to avoid spurious SIGHUP
             *      and SIGTTIN and SIGTTOU (setsid);
             * 
             *  Case Windoze:
             *      From: https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
             *      DETACHED_PROCESS - the new process does not inherit its parent's console
             *      This flag is ignored if the application is not a console application, or if it is used with either CREATE_NEW_CONSOLE or DETACHED_PROCESS
             * 
             *  \note replaces the Stroika v2.1 DetachedProcessRunner API
             * 
             *  \note as of Stroika v3.0d23, Run () API is not compatible with fDetached=true - use RunInBackground () API instead.
             *        This restriction may be lifted in a future release (if I can figure out what it means cleanly).
             */
            bool fDetached{false};
 
#if qStroika_Platform_POSIX
            /**
             *  \brief set umask of child process
             * 
             *  mostly harmless, not clearly needed, but suggested in http://codingfreak.blogspot.com/2012/03/daemon-izing-process-in-linux.html
             */
            optional<mode_t> fChildUMask{027};
#endif
 
#if qStroika_Platform_Windows
            /**
             *  From: https://learn.microsoft.com/en-us/windows/win32/procthread/process-creation-flags
             *  CONSOLE handle from this app not passed to child process. Obviates fDetachConsole.
             */
            bool fCreateNoWindow : 1 {true};
 
#endif
        };
 
    public:
        ProcessRunner ()                     = delete;
        ProcessRunner (const ProcessRunner&) = delete;
        /**
         * \brief Construct ProcessRunner with a CommandLine to run (doesn't actually RUN til you call Run or RunInBackground).
         * 
         *  \note overload with executable allows specifying an alternate executable to run, even though args[0] will be what is reported
         *        to that application (a somewhat common trick in unix-land).
         * 
         *  \note overload with String commandLine:
         *        Simple commands are run directly, and strings with apparent shell-isms, like pipes and quotes etc, are run through kDefaultShell.
         *        This overload is handy, but easy to explicitly control shell used with CommandLine argument instead.
         */
#if qCompilerAndStdLib_default_member_initializer_needed_within_enclosing_class_Buggy
        ProcessRunner (const filesystem::path& executable, const CommandLine& args, const Options& o);
        ProcessRunner (const CommandLine& args, const Options& o);   ///< \brief Run args, whose args[0] is the executable
        ProcessRunner (const String& commandLine, const Options& o); ///< \brief Run directly if simple, else through kDefaultShell
        ProcessRunner (const filesystem::path& executable, const CommandLine& args); ///< \brief Same, with Options{}
        ProcessRunner (const CommandLine& args);                                     ///< \brief Same, with Options{}
        ProcessRunner (const String& commandLine);                                   ///< \brief Same, with Options{}
#else
        ProcessRunner (const filesystem::path& executable, const CommandLine& args, const Options& o = {});
        ProcessRunner (const CommandLine& args, const Options& o = {});   ///< \brief Run args, whose args[0] is the executable
        ProcessRunner (const String& commandLine, const Options& o = {}); ///< \brief Run directly if simple, else through kDefaultShell
#endif
 
    public:
        nonvirtual ProcessRunner& operator= (const ProcessRunner&) = delete;
 
    public:
#if qStroika_Platform_POSIX
        using ExitStatusType = uint8_t;
#elif qStroika_Platform_Windows
        using ExitStatusType = DWORD;
#else
        using ExitStatusType = int;
#endif
 
    public:
        class Exception;
 
    public:
        /**
         */
        nonvirtual CommandLine GetCommandLine () const;
        nonvirtual void        SetCommandLine (const CommandLine& args);
 
    public:
        /**
         */
        nonvirtual Options GetOptions () const;
        nonvirtual void    SetOptions (const Options& o);
 
    public:
        /**
         *  Zero means success. Run() returns optional<ProcessResultType> by reference, and that
         *  value is only provided if the child process exited. If exited, we return the exit
         *  status and signal number (if any) - see waitpid - http://pubs.opengroup.org/onlinepubs/9699919799/functions/wait.html
         */
        struct [[nodiscard]] ProcessResultType {
            optional<ExitStatusType> fExitStatus;
            optional<SignalID>       fTerminatedByUncaughtSignalNumber;
 
            nonvirtual void ThrowIfFailed ();
 
            /**
             *  Purely for debugging / diagnostic purposes. Don't count on this format.
             */
            nonvirtual String ToString () const;
        };
 
    public:
        /**
         *  \brief Run () options for mapping Strings - what code page converters to use.
         * 
         *      \note defaults now are UTF-8, but don't count on this if you care about the encoding used (subject to change).
         */
        struct StringOptions {
            /**
             *  Input refers to the input of the sub-process being run. So this conversion is applied before sending the data to
             *  that process.
             */
            optional<Characters::CodeCvt<>> fInputCodeCvt;
 
            /**
             *  Output refers to the output of the sub-process being run. So this conversion is applied to the data retrieved
             *  from that process.
             */
            optional<Characters::CodeCvt<>> fOutputCodeCvt;
        };
 
    public:
        /**
         *  \brief Run the command synchronously, returning its output, and THROW on any failure
         *
         *      o   STRING overload: pass stdin as a string, get back {stdout, stderr}. Run () with no
         *          argument means Run (""). The simplest form.
         *      o   STREAMS overload: pass binary streams instead. Any of the three left nullptr is
         *          redirected to /dev/null.
         *
         *  \note Exceptions - failure is ONLY reported by throwing ProcessRunner::Exception, whether that is
         *        something going wrong before the process starts, a non-zero exit (Exception::fExitStatus),
         *        or death by an uncaught signal (Exception::fTermSignal). The string overload also captures
         *        the child's stderr into Exception::fStderrFragment, usually the only thing that says WHY.
         *        To read an exit status instead of catching it, use RunInBackground ().
         *
         *  \note if this is called with a timeout, and it times out, the child is killed immediately upon timeout.
         *        To avoid this behavior, use RunInBackground
         *
         *  \par Example Usage (using strings in/out)
         *      \code
         *          String name = get<0> (ProcessRunner{"uname"}.Run (String {})).Trim ();
         *      \endcode
         *
         *  \par Example Usage (using binary streams)
         *      \code
         *          ProcessRunner                    pr{"cat"};
         *          Memory::BLOB                     kData_{ Memory::BLOB::FromRaw ("this is a test") };
         *          Streams::MemoryStream::Ptr<byte> processStdIn = Streams::MemoryStream::New<byte> (kData_);
         *          Streams::MemoryStream::Ptr<byte> processStdOut = Streams::MemoryStream::New<byte> ();
         *          pr.Run (processStdIn, processStdOut);
         *          EXPECT_EQ (processStdOut.ReadAll (), kData_);
         *      \endcode
         *
         *  @see RunInBackground
         */
        nonvirtual void Run (const Streams::InputStream::Ptr<byte>& in, const Streams::OutputStream::Ptr<byte>& out = nullptr,
                             const Streams::OutputStream::Ptr<byte>& error = nullptr, Time::DurationSeconds timeout = Time::kInfinity);
        nonvirtual tuple<Characters::String, Characters::String> Run (const Characters::String& cmdStdInValue = ""sv,
                                                                      const StringOptions&      stringOpts    = {},
                                                                      Time::DurationSeconds     timeout       = Time::kInfinity);
 
    public:
        class BackgroundProcess;
 
    public:
        /**
         *  \brief Run the given external command/process (set by constructor) - with the given arguments in the background,
         *         and return a handle to the results.
         * 
         *  This function is generally quick, and non-blocking - just creates a thread todo the work.
         *
         *  \note it is perfectly legal to launch a subprocess, and not track it in any way, just ignoring (not saving)
         *        the BackgroundProcess object.
         * 
         *  \note if options.fDetached is true, as of Stroika v3.0d23, then we REQUIRE (in==nullptr, out==nullptr, and err==nullptr)
         *        and this means no data is written to the detached process, and no data is read from it.
         *
         *  @see Run
         */
        nonvirtual BackgroundProcess RunInBackground (const Streams::InputStream::Ptr<byte>&  in    = nullptr,
                                                      const Streams::OutputStream::Ptr<byte>& out   = nullptr,
                                                      const Streams::OutputStream::Ptr<byte>& error = nullptr);
 
    private:
        /**
         * @brief like CreateDetailedRunnable_, but doesnt track pid or result - just creates runnable to execute
         */
        nonvirtual function<void ()> CreateSimpleRunnable_ ();
 
    private:
        /**
         * Capture the process results and running PID. NOTE - this uses Synchronized, since its generally looked at and set from
         * two different threads.
         */
        struct DetailedRunnableRep_ {
            Synchronized<optional<ProcessResultType>> fProcessResult;
            Synchronized<optional<pid_t>>             fRunningPID;
        };
 
    private:
        /**
         * @brief DOESNT run anything - but creates a function object that when run will do the work of running the process, and returns a shared DetailedRunnableRep_ to track the progress of the runnable when run
         * 
         *  Note that 'in' will be sent to the stdin of the subprocess, 'out' will be read from the
         *  stdout of the subprocess and error will be read from the stderr of the subprocess.
         *
         *  Each of these CAN be null, and will if so, that will be interpreted as an empty stream
         *  (for in/stdin), and for out/error, just means the results will be redirected to /dev/null.
         * 
         *  Note the runnable holds onto shared_ptr<DetailedRunnableRep_> so it doesn't NEED to be by the caller - just hold
         *  onto it if you want to see the results.
         */
        nonvirtual tuple<function<void ()>, shared_ptr<DetailedRunnableRep_>> CreateDetailedRunnable_ ();
 
    private:
#if qStroika_Platform_POSIX
        static void Process_Runner_POSIX_ (const shared_ptr<DetailedRunnableRep_>&            runneeDetails,
                                           [[maybe_unused]] const optional<filesystem::path>& executable, const CommandLine& cmdLine,
                                           const ProcessRunner::Options& options, const Streams::InputStream::Ptr<byte>& in,
                                           const Streams::OutputStream::Ptr<byte>& out, const Streams::OutputStream::Ptr<byte>& err);
#elif qStroika_Platform_Windows
        static void Process_Runner_Windows_ (const shared_ptr<DetailedRunnableRep_>& runneeDetails,
                                             const optional<filesystem::path>& executable, const CommandLine& cmdLine,
                                             const ProcessRunner::Options& options, const Streams::InputStream::Ptr<byte>& in,
                                             const Streams::OutputStream::Ptr<byte>& out, const Streams::OutputStream::Ptr<byte>& err);
#endif
 
    private:
        optional<filesystem::path>                  fExecutable_; // if omitted, derived from fArgs[0]
        CommandLine                                 fArgs_;
        Options                                     fOptions_;
        Streams::InputStream::Ptr<byte>             fStdIn_;  // just while we support deprecated API
        Streams::OutputStream::Ptr<byte>            fStdOut_; // ""
        Streams::OutputStream::Ptr<byte>            fStdErr_; // ""
        Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE Debug::AssertExternallySynchronizedChecker fThisAssertExternallySynchronized_;
 
    public:
        [[deprecated ("Since Stroika v3.0d12 - pass stdin/stdout/stderr to ProcessRunner Run() method (if needed)")]] ProcessRunner (
            const filesystem::path& executable, const CommandLine& args, const Streams::InputStream::Ptr<byte>& in,
            const Streams::OutputStream::Ptr<byte>& out = nullptr, const Streams::OutputStream::Ptr<byte>& error = nullptr);
        [[deprecated ("Since Stroika v3.0d12 - pass stdin/stdout/stderr to ProcessRunner Run() method (if needed)")]] ProcessRunner (
            const CommandLine& args, const Streams::InputStream::Ptr<byte>& in, const Streams::OutputStream::Ptr<byte>& out = nullptr,
            const Streams::OutputStream::Ptr<byte>& error = nullptr);
        [[deprecated ("Since Stroika v3.0d12 - pass stdin/stdout/stderr to ProcessRunner Run() method (if needed)")]] ProcessRunner (
            const String& commandLine, const Streams::InputStream::Ptr<byte>& in, const Streams::OutputStream::Ptr<byte>& out = nullptr,
            const Streams::OutputStream::Ptr<byte>& error = nullptr)
            : ProcessRunner{commandLine}
        {
            this->fStdIn_  = in;
            this->fStdOut_ = out;
            this->fStdErr_ = error;
        }
 
        [[deprecated ("Since Stroika v3.0d12 - use other overloads for ProcessRunner")]] ProcessRunner (
            const filesystem::path& executable, const Containers::Sequence<String>& args, const Streams::InputStream::Ptr<byte>& in = nullptr,
            const Streams::OutputStream::Ptr<byte>& out = nullptr, const Streams::OutputStream::Ptr<byte>& error = nullptr)
            : ProcessRunner{executable, CommandLine{args}}
        {
            this->fStdIn_  = in;
            this->fStdOut_ = out;
            this->fStdErr_ = error;
        }
 
        [[deprecated ("Since Stroika v3.0d12 - pass in/out/error streams(can be nullptr) to Run method instead of CTOR")]] void
        Run (optional<ProcessResultType>* processResult, ProgressMonitor::Updater progress = nullptr, Time::DurationSeconds timeout = Time::kInfinity);
 
        [[deprecated ("Since Stroika v3.0d12 pass in/out/error(can be nullptr) in RunInbackground() method")]] BackgroundProcess
        RunInBackground (ProgressMonitor::Updater progress);
 
        [[deprecated ("Since Stroika v3.0d23d")]] BackgroundProcess RunInBackground (const Streams::InputStream::Ptr<byte>&    in,
                                                                                     const Streams::OutputStream::Ptr<byte>&   out,
                                                                                     const Streams::OutputStream::Ptr<byte>&   error,
                                                                                     [[maybe_unused]] ProgressMonitor::Updater progress);
 
    public:
        //DEPRECATED
        [[deprecated ("Since Stroika v3.0d23d")]] void Run (const Streams::InputStream::Ptr<byte>& in, const Streams::OutputStream::Ptr<byte>& out,
                                                            const Streams::OutputStream::Ptr<byte>& error, ProgressMonitor::Updater progress,
                                                            Time::DurationSeconds timeout = Time::kInfinity);
        [[deprecated ("Since Stroika v3.0d23d")]] tuple<Characters::String, Characters::String>
        Run (const Characters::String& cmdStdInValue, const StringOptions& stringOpts, ProgressMonitor::Updater progress,
             Time::DurationSeconds timeout = Time::kInfinity);
 
    public:
        /**
         */
        [[deprecated ("Since Stroika v3.0d12 - use GetOptions().fWorkingDirectory")]] optional<filesystem::path> GetWorkingDirectory () const;
        [[deprecated ("Since Stroika v3.0d12 - use SetOptions({.fWorkingDirectory})")]] void SetWorkingDirectory (const optional<filesystem::path>& d);
 
    public:
        /**
         *  If empty, stdin will not be empty (redirected from /dev/null).
         *
         *  Otherwise, the stream will be 'read' by the ProcessRunner and 'fed' downstream to
         *  the running subprocess.
         */
        [[deprecated ("Since Stroika v3.0d12 - pass in/out/error streams(can be nullptr) to Run method instead of CTOR")]] Streams::InputStream::Ptr<byte>
        GetStdIn () const;
        [[deprecated ("Since Stroika v3.0d12 - pass in/out/error streams(can be nullptr) to Run method instead of CTOR")]] void
        SetStdIn (const Streams::InputStream::Ptr<byte>& in);
 
    public:
        /**
         *  If empty, stdout will not be captured (redirected to /dev/null)
         */
        [[deprecated ("Since Stroika v3.0d12 - pass in/out/error streams(can be nullptr) to Run method instead of CTOR")]] Streams::OutputStream::Ptr<byte>
        GetStdOut () const;
        [[deprecated ("Since Stroika v3.0d12 - pass in/out/error streams(can be nullptr) to Run method instead of CTOR")]] void
        SetStdOut (const Streams::OutputStream::Ptr<byte>& out);
 
    public:
        /**
         *  If empty, stderr will not be captured (redirected to /dev/null)
         */
        [[deprecated ("Since Stroika v3.0d12 - pass in/out/error streams(can be nullptr) to Run method instead of CTOR")]] Streams::OutputStream::Ptr<byte>
        GetStdErr () const;
        [[deprecated ("Since Stroika v3.0d12 - pass in/out/error streams(can be nullptr) to Run method instead of CTOR")]] void
        SetStdErr (const Streams::OutputStream::Ptr<byte>& err);
    };
 
    /**
     *  Exceptions generated by ProcessRunner are typically of this sort.
     */
    class ProcessRunner::Exception : public Execution::Exception<runtime_error> {
    private:
        using inherited = Execution::Exception<runtime_error>;
 
    public:
        /**
         */
        Exception (const String& failureMessage, const optional<String>& stderrFragment = nullopt,
                   const optional<ExitStatusType>& wExitStatus = nullopt, const optional<SignalID>& wTermSig = nullopt);
 
    public:
        /**
         *  High level summary - not including stuff like exit status, stderr results etc
         */
        const String fFailureMessage;
 
    public:
        const optional<String> fStderrFragment;
 
    public:
        const optional<ExitStatusType> fExitStatus;
 
    public:
        const optional<SignalID> fTermSignal;
 
    private:
        static String mkMsg_ (const String& errorMessage, const optional<String>& stderrSubset, const optional<ExitStatusType>& wExitStatus,
                              const optional<SignalID>& wTermSig);
    };
 
    /**
     *  Support more controlled running of sub-process, where wait timeouts don't necessarily kill the child process.
     * 
     *  \note it is perfectly legal to launch a subprocess, and not track it in any way, just ignoring (not saving)
     *        the BackgroundProcess object.
     */
    class ProcessRunner::BackgroundProcess {
    private:
        BackgroundProcess ();
 
    public:
        BackgroundProcess (const BackgroundProcess&) = default;
 
    public:
        /**
         * Return missing if process still running, and if completed, return the results.
         */
        nonvirtual optional<ProcessResultType> GetProcessResult () const;
 
    public:
        /**
         *  \brief maybe missing if process not yet (or ever successfully) launched. Child process may have
         *         already exited by the time this is returned.
         */
        optional<pid_t> GetChildProcessID () const;
 
    public:
        /**
         *  \brief wait until GetChildProcessID () returns a valid answer, or until the process failed to start
         *         (in which case calls PropagateIfException).
         */
        nonvirtual void WaitForStarted (Time::DurationSeconds timeout = Time::kInfinity) const;
 
    public:
        /**
         *
         *  @see Join ()
         *  @see JoinUntil ()
         */
        nonvirtual void WaitForDone (Time::DurationSeconds timeout = Time::kInfinity) const;
 
    public:
        /**
         *  \brief Join () does WaitForDone () and throw exception if there was any error (see PropagateIfException).
         *
         *  \note   Aliases - this used to be called WaitForDoneAndPropagateErrors; but used the name Join () to mimic the name used with Threads - NOT
         *          because that's used in the implementation, but because its essentially logically the same thing.
         *
         *  @see JoinUntil ()
         *  @see WaitForDone ()
         */
        nonvirtual void Join (Time::DurationSeconds timeout = Time::kInfinity) const;
 
    public:
        /**
         *  \brief WaitForDoneUntil () and throw exception if there was any error (see PropagateIfException).
         *
         *  @see Join ()
         *  @see WaitForDone ()
         */
        nonvirtual void JoinUntil (Time::TimePointSeconds timeoutAt) const;
 
    public:
        /**
         *  If the process has completed with an error, throw exception reflecting that failure.
         *
         *  \note if the process has not completed, this likely does nothing.
         */
        nonvirtual void PropagateIfException () const;
 
    public:
        /**
         *   If the process is still running, terminate it.
         */
        nonvirtual void Terminate ();
 
    public:
        /**
         *  Purely for debugging / diagnostic purposes. Don't count on this format.
         */
        nonvirtual String ToString () const;
 
    private:
        struct Rep_ {
            virtual ~Rep_ () = default;
            Thread::CleanupPtr               fProcessRunner{Thread::CleanupPtr::eAbortBeforeWaiting};
            shared_ptr<DetailedRunnableRep_> fDetailedRunnableRep_;
        };
        shared_ptr<Rep_>                            fRep_;
        Stroika_ATTRIBUTE_NO_UNIQUE_ADDRESS_VCFORCE Debug::AssertExternallySynchronizedChecker fThisAssertExternallySynchronized_;
 
    private:
        friend class ProcessRunner;
    };
 
}
 
/*
 ********************************************************************************
 ***************************** Implementation Details ***************************
 ********************************************************************************
 */
#include "ProcessRunner.inl"
 
#endif /*_Stroika_Foundation_Execution_ProcessRunner_h_*/