AuroraRuntime/Include/Aurora/Processes/IProcess.hpp

/***
    Copyright (C) 2021 J Reece Wilson (a/k/a "Reece"). All rights reserved.

    File: IProcess.hpp
    Date: 2021-6-9
    Author: Reece
***/
#pragma once

namespace Aurora::Threading
{
    struct IWaitable;
}

namespace Aurora::Processes
{
    struct IProcess
    {
        /**
         * @brief High performance thread primitive to synchronize against the process
         * @deprecated - but not really. You should rethink your code design if you're 
         *               using this over the loop source. Won't remove. Has legitmate 
         *               use cases. You could use this lock state as 'has terminated'
         * @return 
        */
        virtual AuSPtr<Threading::IWaitable> AsWaitable() = 0;

        /**
         * @brief Kernel synchronization primitive to synchronize against the process
         * 
        */
        virtual AuSPtr<IO::Loop::ILoopSource> AsLoopSource() = 0;
        
        /**
         * @brief returns the exit code of the process should we outlive them
         * @return 
        */
        virtual AuSInt GetExitCode() = 0;

        /**
         * @brief returns *something* about the process. you should not use this
         * @return 
        */
        virtual AuUInt GetProcessId() = 0;

        /**
         * @brief Creates the process, for the first and only time, given the input
         *        StartupParmaters provided to the relevant Spawn function
         * @return 
        */
        virtual bool Start() = 0;
        
        /**
         * @brief Forcefully terminates the process
         * @return 
        */
        virtual bool Terminate() = 0;

        /**
         * WARNING: this function **MAY** block for quite some time.  
         * @brief Sends SIGTERM, Close all Windows under watchdog, and/or conhost 
                  terminate key sequence to the process
         * @return whether or not the thread is still alive at the end of the kill 
         *         attempt.
        */
        virtual bool TryKill()   = 0;
        
        /**
         * @brief Reads asynchronously or synchronously (@param nonblock) destination span length from the stream 
         *        If the destination pointer is null, the AuMemoryStreamWrite output variable with be assigned to the available bytes for possible sync or async read
         * @param stream        Specifies the standard C stream for stdin/out UNIX style IPC
         * @param destination   Memory span of output bytes, should the intention be to _read_ from the stream specified by the stream EStandardHandle. 
         *                      If the input span is null, outVariable is assigned the available bytes in the IPC buffer
         * @param nonblock 
         * @return 
        */
        virtual bool Read(EStandardHandle stream, const Memory::MemoryViewStreamWrite &destination, bool nonblock = true) = 0;

        /**
         * @brief Synchronously writes `source` bytes to the processes stdin stream
         * @param source 
         * @return 
        */
        virtual bool Write(const Memory::MemoryViewStreamRead &source) = 0;

        /**
         * @brief Returns an asynchronous file stream transaction of pipe pair: stdout, stdin
         * @return
        */
        virtual AuSPtr<IO::IAsyncTransaction> NewAsyncTransaction() = 0;

        /**
         * @brief Returns an asynchronous file stream transaction of pipe pair: stderr, INVALID
         * @return
        */
        virtual AuSPtr<IO::IAsyncTransaction> NewErrorStreamAsyncTransaction() = 0;
    };
}