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

    File: ILoopSource.hpp
    Date: 2022-2-12
    Author: Reece
***/
#pragma once

namespace Aurora::IO::Loop
{
    /// Is the IO primitive is not IPC, entirely inprocess, this might avoid the kernel or a spinloop
    static const AuUInt8 kFlagLSTryNoSpin     = 1;

    /// Disallows IO Async transaction callbacks and APC callbacks from being called 
    static const AuUInt8 kFlagLSTryNoIOAlerts = 2;

    struct ILoopSource
    {
        /**
         * @brief Atomic is-signaled-and-latch.
         *        Approx equiv to NT: WaitForSingleObjectEx(this, 0, TRUE); but will not break (WAIT_IO_COMPLETION) on APC or IO interruption.
         * @return 
         */
        virtual bool IsSignaled() = 0;

        /**
         * @brief Atomic is-signaled-and-latch.
         *        Approx equiv to NT: WaitForSingleObjectEx(this, 0, !(uFlags & kFlagLSTryNoIOAlerts)); but will not break (WAIT_IO_COMPLETION) on APC or IO interruption
         * @return 
         */
        virtual bool IsSignaledExt(AuUInt8 uFlags) = 0;
        
        /**
         * @brief Returns a generic description about the loop source handle
         * @return 
         */
        virtual ELoopSource GetType() = 0;

        /**
         * @breif Blocks the current thread for the kernel primitive.
         * @warning Are you looking for LoopQueues? You can even reduce async threads down to kernel ILoopQueues.
         * @warning see: (stateful wait context) AuIO::Loop::ILoopQueue
         * @warning see: (arbitrary stateless wait) AuIO::Loop::WaitMultipleLoopSources
         * @warning see: (arbitrary stateless wait) AuIO::Loop::WaitMultipleLoopSourcesEx
         * @warning see: (scheduling on registered thread) Async/IThreadPool::ToKernelWorkQueue
         * @warning see: (scheduling on registered thread) Async/IWorkItem::SetSchedByLoopSourceOnce
         * @warning see: (scheduling on registered thread) Async/IWorkItem::SetSchedByLoopSourceRepeating
         */
        virtual bool WaitOn(AuUInt32 uTimeoutRelMS = 0) = 0;

        virtual bool WaitOnExt(AuUInt8 uFlags, AuUInt32 uTimeoutRelMS = 0) = 0;

        /**
         * Follows steady time & 0 = indefinite convention
         * @warning: The IO subsystem uses miliseconds internally. Expect under and overshoots.
         *           nanosec resolution is useful for dealing with hidden interruptions requiring a resleep.
         */
        virtual bool WaitOnAbs(AuUInt64 uTimeoutAbs = 0) = 0;

        /**
         * Follows steady time & 0 = indefinite convention
         * @warning: The IO subsystem uses miliseconds internally. Expect under and overshoots.
         *           nanosec resolution is useful for dealing with hidden interruptions requiring a resleep.
         */
        virtual bool WaitOnAbsExt(AuUInt8 uFlags, AuUInt64 uTimeoutAbs = 0) = 0;
    };
}