Async.h

// Copyright (c) Stefano Cristiano
// SPDX-License-Identifier: MIT
#pragma once
 
#include "../Containers/IntrusiveDoubleLinkedList.h"
#include "../FileSystem/FileSystemOperations.h" // FileSystemCopyFlags
#include "../Foundation/Function.h"
#include "../Foundation/OpaqueObject.h"
#include "../Foundation/Span.h"
#include "../Threading/Atomic.h"
#include "../Threading/ThreadPool.h"
#include "../Time/Time.h"
 
// Descriptors
#include "../File/FileDescriptor.h"
#include "../Process/ProcessDescriptor.h"
#include "../Socket/SocketDescriptor.h"
 
namespace SC
{
struct ThreadPool;
struct ThreadPoolTask;
struct EventObject;
} // namespace SC
 
namespace SC
{
struct AsyncEventLoop;
struct AsyncResult;
struct AsyncSequence;
struct AsyncTaskSequence;
 
namespace detail
{
struct AsyncWinOverlapped;
struct AsyncWinOverlappedDefinition
{
    static constexpr int    Windows   = sizeof(void*) * 4 + sizeof(uint64_t);
    static constexpr size_t Alignment = alignof(void*);
 
    using Object = AsyncWinOverlapped;
};
using WinOverlappedOpaque = OpaqueObject<AsyncWinOverlappedDefinition>;
 
struct AsyncWinWaitDefinition
{
    using Handle                    = FileDescriptor::Handle;  // fd
    static constexpr Handle Invalid = FileDescriptor::Invalid; // invalid fd
 
    static Result releaseHandle(Handle& waitHandle);
};
struct WinWaitHandle : public UniqueHandle<AsyncWinWaitDefinition>
{
};
} // namespace detail
 
struct AsyncRequest
{
    AsyncRequest* next = nullptr;
    AsyncRequest* prev = nullptr;
 
    void setDebugName(const char* newDebugName);
 
    void executeOn(AsyncSequence& sequence);
 
    Result executeOn(AsyncTaskSequence& task, ThreadPool& pool);
 
    void disableThreadPool();
 
    enum class Type : uint8_t
    {
        LoopTimeout,         
        LoopWakeUp,          
        LoopWork,            
        ProcessExit,         
        SocketAccept,        
        SocketConnect,       
        SocketSend,          
        SocketSendTo,        
        SocketReceive,       
        SocketReceiveFrom,   
        FileRead,            
        FileWrite,           
        FilePoll,            
        FileSystemOperation, 
    };
 
    AsyncRequest(Type type) : state(State::Free), type(type), flags(0), userFlags(0), unused(0) {}
 
    Result stop(AsyncEventLoop& eventLoop, Function<void(AsyncResult&)>* afterStopped = nullptr);
 
    [[nodiscard]] bool isFree() const;
 
    [[nodiscard]] bool isCancelling() const;
 
    [[nodiscard]] bool isActive() const;
 
    [[nodiscard]] Type getType() const { return type; }
 
    Result start(AsyncEventLoop& eventLoop);
 
    void setUserFlags(uint16_t externalFlags) { userFlags = externalFlags; }
 
    uint16_t getUserFlags() const { return userFlags; }
 
    [[nodiscard]] Function<void(AsyncResult&)>* getCloseCallback() { return closeCallback; }
 
    [[nodiscard]] const Function<void(AsyncResult&)>* getCloseCallback() const { return closeCallback; }
 
  protected:
    Result checkState();
 
    void queueSubmission(AsyncEventLoop& eventLoop);
 
    AsyncSequence* sequence = nullptr;
 
    AsyncTaskSequence* getTask();
 
  private:
    Function<void(AsyncResult&)>* closeCallback = nullptr;
 
    friend struct AsyncEventLoop;
    friend struct AsyncResult;
 
    void markAsFree();
 
    [[nodiscard]] static const char* TypeToString(Type type);
    enum class State : uint8_t
    {
        Free,       // not in any queue, this can be started with an async.start(...)
        Setup,      // when in submission queue waiting to be setup (after an async.start(...))
        Submitting, // when in submission queue waiting to be activated or re-activated
        Active,     // when monitored by OS syscall or in activeLoopWakeUps / activeTimeouts queues
        Reactivate, // when flagged for reactivation inside the callback (after a result.reactivateRequest(true))
        Cancelling, // when in cancellation queue waiting for a cancelAsync (on active async)
    };
 
#if SC_ASYNC_ENABLE_LOG
    const char* debugName = "None";
#endif
    State   state; // 1 byte
    Type    type;  // 1 byte
    int16_t flags; // 2 bytes
 
    uint16_t unused;    // 2 bytes
    uint16_t userFlags; // 2 bytes
};
 
struct AsyncSequence
{
    AsyncSequence* next = nullptr;
    AsyncSequence* prev = nullptr;
 
    bool clearSequenceOnCancel = true; 
    bool clearSequenceOnError  = true; 
  private:
    friend struct AsyncEventLoop;
    bool runningAsync = false; // true if an async from this sequence is being run
    bool tracked      = false;
 
    IntrusiveDoubleLinkedList<AsyncRequest> submissions;
};
 
struct AsyncCompletionData
{
};
 
struct AsyncResult
{
    AsyncResult(AsyncEventLoop& eventLoop, AsyncRequest& request, SC::Result& res, bool* hasBeenReactivated = nullptr)
        : eventLoop(eventLoop), async(request), returnCode(res), hasBeenReactivated(hasBeenReactivated)
    {}
 
    void reactivateRequest(bool shouldBeReactivated);
 
    [[nodiscard]] const SC::Result& isValid() const { return returnCode; }
 
    AsyncEventLoop& eventLoop;
    AsyncRequest&   async;
 
  protected:
    friend struct AsyncEventLoop;
 
    bool  shouldCallCallback = true;
    bool* hasBeenReactivated = nullptr;
 
    SC::Result& returnCode;
};
 
template <typename T, typename C>
struct AsyncResultOf : public AsyncResult
{
    T&       getAsync() { return static_cast<T&>(AsyncResult::async); }
    const T& getAsync() const { return static_cast<const T&>(AsyncResult::async); }
 
    using AsyncResult::AsyncResult;
 
    C       completionData;
    int32_t eventIndex = 0;
};
 
struct AsyncLoopTimeout : public AsyncRequest
{
    AsyncLoopTimeout() : AsyncRequest(Type::LoopTimeout) {}
 
    using CompletionData = AsyncCompletionData;
    using Result         = AsyncResultOf<AsyncLoopTimeout, CompletionData>;
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, Time::Milliseconds relativeTimeout);
 
    Function<void(Result&)> callback; 
 
    Time::Milliseconds relativeTimeout; 
 
    Time::Absolute getExpirationTime() const { return expirationTime; }
 
  private:
    SC::Result validate(AsyncEventLoop&);
    friend struct AsyncEventLoop;
    Time::Absolute expirationTime;
};
 
struct AsyncLoopWakeUp : public AsyncRequest
{
    AsyncLoopWakeUp() : AsyncRequest(Type::LoopWakeUp) {}
 
    using CompletionData = AsyncCompletionData;
    using Result         = AsyncResultOf<AsyncLoopWakeUp, CompletionData>;
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, EventObject& eventObject);
 
    SC::Result wakeUp(AsyncEventLoop& eventLoop);
 
    Function<void(Result&)> callback; 
    EventObject* eventObject = nullptr; 
 
  private:
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
 
    Atomic<bool> pending = false;
};
 
struct AsyncProcessExit : public AsyncRequest
{
    AsyncProcessExit() : AsyncRequest(Type::ProcessExit) {}
 
    struct CompletionData : public AsyncCompletionData
    {
        ProcessDescriptor::ExitStatus exitStatus;
    };
 
    struct Result : public AsyncResultOf<AsyncProcessExit, CompletionData>
    {
        using AsyncResultOf<AsyncProcessExit, CompletionData>::AsyncResultOf;
 
        SC::Result get(ProcessDescriptor::ExitStatus& status)
        {
            status = completionData.exitStatus;
            return returnCode;
        }
    };
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, ProcessDescriptor::Handle process);
 
    Function<void(Result&)> callback; 
 
  private:
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
 
    ProcessDescriptor::Handle handle = ProcessDescriptor::Invalid;
#if SC_PLATFORM_WINDOWS
    detail::WinOverlappedOpaque overlapped;
    detail::WinWaitHandle       waitHandle;
    AsyncEventLoop*             eventLoop = nullptr;
#elif SC_PLATFORM_LINUX
    FileDescriptor pidFd;
#endif
};
 
struct AsyncSocketAccept;
namespace detail
{
struct AsyncSocketAcceptData
{
#if SC_PLATFORM_WINDOWS
    void (*pAcceptEx)() = nullptr;
    detail::WinOverlappedOpaque overlapped;
    SocketDescriptor            clientSocket;
    uint8_t                     acceptBuffer[288] = {0};
#elif SC_PLATFORM_LINUX
    AlignedStorage<28> sockAddrHandle;
    uint32_t           sockAddrLen;
#endif
};
 
struct AsyncSocketAcceptBase : public AsyncRequest
{
    AsyncSocketAcceptBase() : AsyncRequest(Type::SocketAccept) {}
 
    struct CompletionData : public AsyncCompletionData
    {
        SocketDescriptor acceptedClient;
    };
 
    struct Result : public AsyncResultOf<AsyncSocketAccept, CompletionData>
    {
        using AsyncResultOf<AsyncSocketAccept, CompletionData>::AsyncResultOf;
 
        SC::Result moveTo(SocketDescriptor& client)
        {
            SC_TRY(returnCode);
            return client.assign(move(completionData.acceptedClient));
        }
    };
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& socketDescriptor, AsyncSocketAcceptData& data);
    SC::Result validate(AsyncEventLoop&);
 
    Function<void(Result&)>    callback; 
    SocketDescriptor::Handle   handle        = SocketDescriptor::Invalid;
    SocketFlags::AddressFamily addressFamily = SocketFlags::AddressFamilyIPV4;
    AsyncSocketAcceptData*     acceptData    = nullptr;
};
 
} // namespace detail
 
struct AsyncSocketAccept : public detail::AsyncSocketAcceptBase
{
    AsyncSocketAccept() { AsyncSocketAcceptBase::acceptData = &data; }
    using AsyncSocketAcceptBase::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& socketDescriptor);
 
  private:
    detail::AsyncSocketAcceptData data;
};
 
struct AsyncSocketConnect : public AsyncRequest
{
    AsyncSocketConnect() : AsyncRequest(Type::SocketConnect) {}
 
    using CompletionData = AsyncCompletionData;
    using Result         = AsyncResultOf<AsyncSocketConnect, CompletionData>;
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, SocketIPAddress address);
 
    Function<void(Result&)> callback; 
 
    SocketDescriptor::Handle handle = SocketDescriptor::Invalid;
    SocketIPAddress          ipAddress;
 
  private:
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
 
#if SC_PLATFORM_WINDOWS
    void (*pConnectEx)() = nullptr;
    detail::WinOverlappedOpaque overlapped;
#endif
};
 
struct AsyncSocketSend : public AsyncRequest
{
    AsyncSocketSend() : AsyncRequest(Type::SocketSend) {}
    struct CompletionData : public AsyncCompletionData
    {
        size_t numBytes = 0;
    };
    using Result = AsyncResultOf<AsyncSocketSend, CompletionData>;
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, Span<const char> data);
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, Span<Span<const char>> data);
 
    Function<void(Result&)> callback; 
 
    SocketDescriptor::Handle handle = SocketDescriptor::Invalid; 
 
    Span<const char>       buffer;              
    Span<Span<const char>> buffers;             
    bool                   singleBuffer = true; 
 
  protected:
    AsyncSocketSend(Type type) : AsyncRequest(type) {}
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
 
    size_t totalBytesWritten = 0;
#if SC_PLATFORM_WINDOWS
    detail::WinOverlappedOpaque overlapped;
#endif
};
 
struct AsyncSocketSendTo : public AsyncSocketSend
{
    AsyncSocketSendTo() : AsyncSocketSend(Type::SocketSendTo) {}
 
    SocketIPAddress address;
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, SocketIPAddress ipAddress,
                     Span<const char> data);
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, SocketIPAddress ipAddress,
                     Span<Span<const char>> data);
 
  private:
    using AsyncSocketSend::start;
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
#if SC_PLATFORM_LINUX
    AlignedStorage<56> typeErasedMsgHdr;
#endif
};
 
struct AsyncSocketReceive : public AsyncRequest
{
    AsyncSocketReceive() : AsyncRequest(Type::SocketReceive) {}
 
    struct CompletionData : public AsyncCompletionData
    {
        size_t numBytes     = 0;
        bool   disconnected = false;
    };
 
    struct Result : public AsyncResultOf<AsyncSocketReceive, CompletionData>
    {
        using AsyncResultOf<AsyncSocketReceive, CompletionData>::AsyncResultOf;
 
        SC::Result get(Span<char>& outData)
        {
            SC_TRY(getAsync().buffer.sliceStartLength(0, completionData.numBytes, outData));
            return returnCode;
        }
 
        SocketIPAddress getSourceAddress() const;
    };
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, const SocketDescriptor& descriptor, Span<char> data);
 
    Function<void(Result&)> callback; 
 
    Span<char>               buffer; 
    SocketDescriptor::Handle handle = SocketDescriptor::Invalid; 
 
  protected:
    AsyncSocketReceive(Type type) : AsyncRequest(type) {}
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
#if SC_PLATFORM_WINDOWS
    detail::WinOverlappedOpaque overlapped;
#endif
};
 
struct AsyncSocketReceiveFrom : public AsyncSocketReceive
{
    AsyncSocketReceiveFrom() : AsyncSocketReceive(Type::SocketReceiveFrom) {}
    using AsyncSocketReceive::start;
 
  private:
    SocketIPAddress address;
    friend struct AsyncSocketReceive;
    friend struct AsyncEventLoop;
#if SC_PLATFORM_LINUX
    AlignedStorage<56> typeErasedMsgHdr;
#endif
};
 
struct AsyncFileRead : public AsyncRequest
{
    AsyncFileRead() : AsyncRequest(Type::FileRead) { handle = FileDescriptor::Invalid; }
 
    struct CompletionData : public AsyncCompletionData
    {
        size_t numBytes  = 0;
        bool   endOfFile = false;
    };
 
    struct Result : public AsyncResultOf<AsyncFileRead, CompletionData>
    {
        using AsyncResultOf<AsyncFileRead, CompletionData>::AsyncResultOf;
 
        SC::Result get(Span<char>& data)
        {
            SC_TRY(getAsync().buffer.sliceStartLength(0, completionData.numBytes, data));
            return returnCode;
        }
    };
    using AsyncRequest::start;
 
    Function<void(Result&)> callback; 
    Span<char>              buffer;   
    FileDescriptor::Handle  handle;   
 
    uint64_t getOffset() const { return offset; }
 
    void setOffset(uint64_t fileOffset)
    {
        useOffset = true;
        offset    = fileOffset;
    }
 
  private:
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
    bool       useOffset = false;
    uint64_t   offset    = 0; 
#if SC_PLATFORM_WINDOWS
    uint64_t                    readCursor = 0;
    detail::WinOverlappedOpaque overlapped;
#endif
};
 
struct AsyncFileWrite : public AsyncRequest
{
    AsyncFileWrite() : AsyncRequest(Type::FileWrite) { handle = FileDescriptor::Invalid; }
 
    struct CompletionData : public AsyncCompletionData
    {
        size_t numBytes = 0;
    };
 
    struct Result : public AsyncResultOf<AsyncFileWrite, CompletionData>
    {
        using AsyncResultOf<AsyncFileWrite, CompletionData>::AsyncResultOf;
 
        SC::Result get(size_t& writtenSizeInBytes)
        {
            writtenSizeInBytes = completionData.numBytes;
            return returnCode;
        }
    };
 
    using AsyncRequest::start;
 
    SC::Result start(AsyncEventLoop& eventLoop, Span<Span<const char>> data);
 
    SC::Result start(AsyncEventLoop& eventLoop, Span<const char> data);
 
    Function<void(Result&)> callback; 
 
    FileDescriptor::Handle handle; 
 
    Span<const char>       buffer;              
    Span<Span<const char>> buffers;             
    bool                   singleBuffer = true; 
 
    uint64_t getOffset() const { return offset; }
 
    void setOffset(uint64_t fileOffset)
    {
        useOffset = true;
        offset    = fileOffset;
    }
 
  private:
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
 
    bool     isWatchable = false;
    bool     useOffset   = false;
    uint64_t offset      = 0xffffffffffffffff; 
 
    size_t totalBytesWritten = 0;
#if SC_PLATFORM_WINDOWS
    detail::WinOverlappedOpaque overlapped;
#endif
};
 
struct AsyncFilePoll : public AsyncRequest
{
    AsyncFilePoll() : AsyncRequest(Type::FilePoll) {}
 
    using CompletionData = AsyncCompletionData;
    using Result         = AsyncResultOf<AsyncFilePoll, CompletionData>;
 
    SC::Result start(AsyncEventLoop& eventLoop, FileDescriptor::Handle fileDescriptor);
 
#if SC_PLATFORM_WINDOWS
    [[nodiscard]] auto& getOverlappedOpaque() { return overlapped; }
#endif
 
    Function<void(Result&)> callback;
 
  private:
    friend struct AsyncEventLoop;
    SC::Result validate(AsyncEventLoop&);
 
    FileDescriptor::Handle handle = FileDescriptor::Invalid;
#if SC_PLATFORM_WINDOWS
    detail::WinOverlappedOpaque overlapped;
#endif
};
 
// forward declared because it must be defined after AsyncTaskSequence
struct AsyncLoopWork;
struct AsyncFileSystemOperation;
 
struct AsyncFileSystemOperationCompletionData : public AsyncCompletionData
{
    FileDescriptor::Handle handle = FileDescriptor::Invalid; // for open
 
    int    code     = 0; // for open/close
    size_t numBytes = 0; // for read
};
 
namespace detail
{
// A simple hand-made variant of all completion types
struct AsyncCompletionVariant
{
    AsyncCompletionVariant() {}
    ~AsyncCompletionVariant() { destroy(); }
 
    AsyncCompletionVariant(const AsyncCompletionVariant&)            = delete;
    AsyncCompletionVariant(AsyncCompletionVariant&&)                 = delete;
    AsyncCompletionVariant& operator=(const AsyncCompletionVariant&) = delete;
    AsyncCompletionVariant& operator=(AsyncCompletionVariant&&)      = delete;
 
    bool inited = false;
 
    AsyncRequest::Type type;
    union
    {
        AsyncCompletionData completionDataLoopWork; // Defined after AsyncCompletionVariant / AsyncTaskSequence
        AsyncLoopTimeout::CompletionData       completionDataLoopTimeout;
        AsyncLoopWakeUp::CompletionData        completionDataLoopWakeUp;
        AsyncProcessExit::CompletionData       completionDataProcessExit;
        AsyncSocketAccept::CompletionData      completionDataSocketAccept;
        AsyncSocketConnect::CompletionData     completionDataSocketConnect;
        AsyncSocketSend::CompletionData        completionDataSocketSend;
        AsyncSocketSendTo::CompletionData      completionDataSocketSendTo;
        AsyncSocketReceive::CompletionData     completionDataSocketReceive;
        AsyncSocketReceiveFrom::CompletionData completionDataSocketReceiveFrom;
        AsyncFileRead::CompletionData          completionDataFileRead;
        AsyncFileWrite::CompletionData         completionDataFileWrite;
        AsyncFilePoll::CompletionData          completionDataFilePoll;
 
        AsyncFileSystemOperationCompletionData completionDataFileSystemOperation;
    };
 
    auto& getCompletion(AsyncLoopWork&) { return completionDataLoopWork; }
    auto& getCompletion(AsyncLoopTimeout&) { return completionDataLoopTimeout; }
    auto& getCompletion(AsyncLoopWakeUp&) { return completionDataLoopWakeUp; }
    auto& getCompletion(AsyncProcessExit&) { return completionDataProcessExit; }
    auto& getCompletion(AsyncSocketAccept&) { return completionDataSocketAccept; }
    auto& getCompletion(AsyncSocketConnect&) { return completionDataSocketConnect; }
    auto& getCompletion(AsyncSocketSend&) { return completionDataSocketSend; }
    auto& getCompletion(AsyncSocketReceive&) { return completionDataSocketReceive; }
    auto& getCompletion(AsyncFileRead&) { return completionDataFileRead; }
    auto& getCompletion(AsyncFileWrite&) { return completionDataFileWrite; }
    auto& getCompletion(AsyncFilePoll&) { return completionDataFilePoll; }
    auto& getCompletion(AsyncFileSystemOperation&) { return completionDataFileSystemOperation; }
 
    template <typename T>
    auto& construct(T& t)
    {
        destroy();
        placementNew(getCompletion(t));
        inited = true;
        type   = t.getType();
        return getCompletion(t);
    }
    void destroy();
};
} // namespace detail
 
struct AsyncTaskSequence : public AsyncSequence
{
  protected:
    ThreadPoolTask task;
    ThreadPool*    threadPool = nullptr;
 
    friend struct AsyncEventLoop;
    friend struct AsyncRequest;
 
    detail::AsyncCompletionVariant completion;
 
    SC::Result returnCode = SC::Result(true);
};
 
struct AsyncLoopWork : public AsyncRequest
{
    AsyncLoopWork() : AsyncRequest(Type::LoopWork) {}
 
    using CompletionData = AsyncCompletionData;
    using Result         = AsyncResultOf<AsyncLoopWork, CompletionData>;
 
    SC::Result setThreadPool(ThreadPool& threadPool);
 
    Function<SC::Result()>  work;     
    Function<void(Result&)> callback; 
 
  private:
    friend struct AsyncEventLoop;
    SC::Result        validate(AsyncEventLoop&);
    AsyncTaskSequence task;
};
 
struct AsyncFileSystemOperation : public AsyncRequest
{
    AsyncFileSystemOperation() : AsyncRequest(Type::FileSystemOperation) {}
    ~AsyncFileSystemOperation() { destroy(); }
 
    enum class Operation
    {
        None = 0,
        Open,
        Close,
        Read,
        Write,
        CopyFile,
    };
 
    using CompletionData = AsyncFileSystemOperationCompletionData;
    using Result         = AsyncResultOf<AsyncFileSystemOperation, CompletionData>;
 
    SC::Result setThreadPool(ThreadPool& threadPool);
 
    Function<void(Result&)> callback; 
 
    SC::Result open(AsyncEventLoop& eventLoop, StringViewData path, FileOpen mode);
 
    SC::Result close(AsyncEventLoop& eventLoop, FileDescriptor::Handle handle);
 
    SC::Result read(AsyncEventLoop& eventLoop, FileDescriptor::Handle handle, Span<char> buffer, uint64_t offset);
 
    SC::Result write(AsyncEventLoop& eventLoop, FileDescriptor::Handle handle, Span<const char> buffer,
                     uint64_t offset);
 
    SC::Result copyFile(AsyncEventLoop& eventLoop, StringViewData path, StringViewData destinationPath,
                        FileSystemCopyFlags copyFlags = FileSystemCopyFlags());
 
  private:
    friend struct AsyncEventLoop;
    Operation      operation = Operation::None;
    AsyncLoopWork  loopWork;
    CompletionData completionData;
 
    void onOperationCompleted(AsyncLoopWork::Result& res);
 
    struct FileDescriptorData
    {
        FileDescriptor::Handle handle;
    };
 
    struct OpenData
    {
        StringViewData path;
        FileOpen       mode;
    };
 
    struct ReadData
    {
        FileDescriptor::Handle handle;
        Span<char>             buffer;
        uint64_t               offset;
    };
 
    struct WriteData
    {
        FileDescriptor::Handle handle;
        Span<const char>       buffer;
        uint64_t               offset;
    };
 
    struct CopyFileData
    {
        StringViewData      path;
        StringViewData      destinationPath;
        FileSystemCopyFlags copyFlags;
    };
 
    using CloseData = FileDescriptorData;
 
    union
    {
        OpenData     openData;
        CloseData    closeData;
        ReadData     readData;
        WriteData    writeData;
        CopyFileData copyFileData;
    };
 
    void destroy();
 
    SC::Result start(AsyncEventLoop& eventLoop, FileDescriptor::Handle fileDescriptor);
    SC::Result validate(AsyncEventLoop&);
};
 
struct AsyncKernelEvents
{
    Span<uint8_t> eventsMemory; 
 
  private:
    int numberOfEvents = 0;
    friend struct AsyncEventLoop;
};
 
struct AsyncEventLoopListeners
{
    Function<void(AsyncEventLoop&)> beforeBlockingPoll;
    Function<void(AsyncEventLoop&)> afterBlockingPoll;
};
 
struct AsyncEventLoop
{
    struct Options
    {
        enum class ApiType : uint8_t
        {
            Automatic = 0,   
            ForceUseIOURing, 
            ForceUseEpoll,   
        };
        ApiType apiType; 
 
        Options() { apiType = ApiType::Automatic; }
    };
 
    AsyncEventLoop();
 
    Result create(Options options = Options());
 
    Result close();
 
    Result start(AsyncRequest& async);
 
    void interrupt();
 
    [[nodiscard]] bool isInitialized() const;
 
    Result run();
 
    Result runOnce();
 
    Result runNoWait();
 
    Result submitRequests(AsyncKernelEvents& kernelEvents);
 
    Result blockingPoll(AsyncKernelEvents& kernelEvents);
 
    Result dispatchCompletions(AsyncKernelEvents& kernelEvents);
 
    Result wakeUpFromExternalThread(AsyncLoopWakeUp& wakeUp);
 
    Result wakeUpFromExternalThread();
 
    Result createAsyncTCPSocket(SocketFlags::AddressFamily family, SocketDescriptor& outDescriptor);
 
    Result createAsyncUDPSocket(SocketFlags::AddressFamily family, SocketDescriptor& outDescriptor);
 
    Result associateExternallyCreatedSocket(SocketDescriptor& outDescriptor);
 
    Result associateExternallyCreatedFileDescriptor(FileDescriptor& outDescriptor);
 
    static Result removeAllAssociationsFor(SocketDescriptor& outDescriptor);
 
    static Result removeAllAssociationsFor(FileDescriptor& outDescriptor);
 
    void updateTime();
 
    [[nodiscard]] Time::Monotonic getLoopTime() const;
 
    [[nodiscard]] int getNumberOfActiveRequests() const;
 
    [[nodiscard]] int getNumberOfSubmittedRequests() const;
 
    [[nodiscard]] AsyncLoopTimeout* findEarliestLoopTimeout() const;
 
    void excludeFromActiveCount(AsyncRequest& async);
 
    void includeInActiveCount(AsyncRequest& async);
 
    void enumerateRequests(Function<void(AsyncRequest&)> enumerationCallback);
 
    void setListeners(AsyncEventLoopListeners* listeners);
 
    [[nodiscard]] static bool isExcludedFromActiveCount(const AsyncRequest& async);
 
    [[nodiscard]] static bool tryLoadingLiburing();
 
    void clearSequence(AsyncSequence& sequence);
 
    struct Internal;
 
  private:
    struct InternalDefinition
    {
        static constexpr int Windows = 520;
        static constexpr int Apple   = 512;
        static constexpr int Linux   = 720;
        static constexpr int Default = Linux;
 
        static constexpr size_t Alignment = 8;
 
        using Object = Internal;
    };
 
  public:
    using InternalOpaque = OpaqueObject<InternalDefinition>;
 
  private:
    InternalOpaque internalOpaque;
    Internal&      internal;
 
    friend struct AsyncRequest;
    friend struct AsyncFileWrite;
    friend struct AsyncFileRead;
    friend struct AsyncFileSystemOperation;
    friend struct AsyncResult;
};
 
struct AsyncEventLoopMonitor
{
    Function<void(void)> onNewEventsAvailable; 
 
    Result create(AsyncEventLoop& eventLoop);
 
    Result close();
 
    Result startMonitoring();
 
    Result stopMonitoringAndDispatchCompletions();
 
  private:
#if SC_COMPILER_MSVC
#pragma warning(push)
#pragma warning(disable : 4324) // useless warning on 32 bit... (structure was padded due to __declspec(align()))
#endif
    alignas(uint64_t) uint8_t eventsMemory[8 * 1024]; // 8 Kb of kernel events
#if SC_COMPILER_MSVC
#pragma warning(pop)
#endif
 
    AsyncKernelEvents asyncKernelEvents;
    AsyncEventLoop*   eventLoop = nullptr;
    AsyncLoopWakeUp   eventLoopWakeUp;
 
    Thread      eventLoopThread;
    EventObject eventObjectEnterBlockingMode;
    EventObject eventObjectExitBlockingMode;
 
    Atomic<bool> finished    = false;
    Atomic<bool> needsWakeUp = true;
 
    bool wakeUpHasBeenCalled = false;
 
    Result monitoringLoopThread(Thread& thread);
};
 
} // namespace SC