From 4b0dfabd67a3b9f83374d9f9f8ec546a227cd0dd Mon Sep 17 00:00:00 2001 From: Reece Date: Fri, 21 Apr 2023 05:44:23 +0100 Subject: [PATCH] [*] Comments --- Include/Aurora/Exit/IExitSubscriber.hpp | 5 +--- Include/Aurora/IO/FS/Overlapped.hpp | 4 +++- .../IO/Protocol/IProtocolInterceptorEx.hpp | 5 ++-- Include/Aurora/IO/Protocol/IProtocolPiece.hpp | 3 +-- Include/Aurora/IO/Protocol/IProtocolStack.hpp | 23 ++++++++++--------- 5 files changed, 20 insertions(+), 20 deletions(-) diff --git a/Include/Aurora/Exit/IExitSubscriber.hpp b/Include/Aurora/Exit/IExitSubscriber.hpp index 540c74f7..1dd2d96a 100644 --- a/Include/Aurora/Exit/IExitSubscriber.hpp +++ b/Include/Aurora/Exit/IExitSubscriber.hpp @@ -13,10 +13,7 @@ namespace Aurora::Exit { Threading::Threads::IAuroraThread *pCaller; }; - - /** - * @brief User definedable callback - */ + AUKN_INTERFACE(IExitSubscriber, AUI_METHOD(void, OnTrigger, (ETriggerLevel, level, const ExitInvoker *, pInvoker)) ); diff --git a/Include/Aurora/IO/FS/Overlapped.hpp b/Include/Aurora/IO/FS/Overlapped.hpp index c554bdb3..bed382a7 100644 --- a/Include/Aurora/IO/FS/Overlapped.hpp +++ b/Include/Aurora/IO/FS/Overlapped.hpp @@ -7,6 +7,8 @@ Note: Defer to Async.hpp for creation of overlapped stream objects This header defines FS.hpp-like APIs that run overlapped or on a worker thread or two. + + **IMPL IN PROGRESS** ***/ #pragma once @@ -49,7 +51,7 @@ namespace Aurora::IO::FS * @brief If running under AuAsync runner, we use the local thread for the entire IO operation. * In the future, whence I can be bothered to finish the APC api, *all* overlapped operations * will be processed on the local thread. - * Specifying true forces all IO to occour on a preallocated pool of IO workers + * Specifying true forces all IO to occur on a preallocated pool of IO workers * @warning this api is thread-local * @warning this api does not change the behaviour of overlapped file streamss */ diff --git a/Include/Aurora/IO/Protocol/IProtocolInterceptorEx.hpp b/Include/Aurora/IO/Protocol/IProtocolInterceptorEx.hpp index 3eec2406..3634584e 100644 --- a/Include/Aurora/IO/Protocol/IProtocolInterceptorEx.hpp +++ b/Include/Aurora/IO/Protocol/IProtocolInterceptorEx.hpp @@ -12,8 +12,9 @@ namespace Aurora::IO::Protocol AUKN_INTERFACE(IProtocolInterceptorEx, /** * @brief - * @return false restores the read head, will retrieve further callbacks - * true nothing + * @return false restores the read head of pReadInByteBuffer. future callbacks will still be made. + * true nothing; pReadInByteBuffer's heads will remain set by the user and the tick is propagated down the stack. + * @warning the error flags of both bytebuffers can seize up the protocol stack by design. */ AUI_METHOD(bool, OnDataAvailable, (const AuSPtr &, pReadInByteBuffer, const AuSPtr &, pWriteOutByteBuffer)) diff --git a/Include/Aurora/IO/Protocol/IProtocolPiece.hpp b/Include/Aurora/IO/Protocol/IProtocolPiece.hpp index cf06cb28..81560f4f 100644 --- a/Include/Aurora/IO/Protocol/IProtocolPiece.hpp +++ b/Include/Aurora/IO/Protocol/IProtocolPiece.hpp @@ -17,8 +17,7 @@ namespace Aurora::IO::Protocol virtual void Remove() = 0; /** - * @brief Fetches an IStreamWriter representation of the next piece - * in the stack + * @brief Fetches an IStreamWriter representation of the next piece in the stack * @return */ virtual AuSPtr ToNextWriter() = 0; diff --git a/Include/Aurora/IO/Protocol/IProtocolStack.hpp b/Include/Aurora/IO/Protocol/IProtocolStack.hpp index 22b673a3..db9e1b15 100644 --- a/Include/Aurora/IO/Protocol/IProtocolStack.hpp +++ b/Include/Aurora/IO/Protocol/IProtocolStack.hpp @@ -37,15 +37,19 @@ namespace Aurora::IO::Protocol /** * @brief Same as AppendInterceptor, except that DoTick will repeat until the input is fully consumed. - * This allows us to tick processors under our frame, followed by a retick if there is more data available. - * Such paradigm contrasts the default stream-specific/non-framing behaviour where the processor is - * responsible for consuming all non-segmented data (ala everything except the start of the final unfinished frame). + * + * This allows us to tick processors under our frame, followed by a retick if there is more data available to us. + * Such paradigm contrasts the default unframed/raw stream behaviour where the processor is responsible for consuming all + * available data. * With such limitations, it's impossible to build a protocol where a piece in the middle - * 1) can/should only flush 1 frame to the next processor - * 2) reads only a portion of pReadInByteBuffer - * This function sets an internal flag that indicates re-ticks from the root are to be expected to complete - * a tick. Otherwise, the read head of the inbound frame of a persumed stream may only skip back to frame zero - * on error OR frame +1 on success. With this flag, frame current to frame end will be ticked. + * 1) can/should only flush 1 frame to the following interceptor + * (this is a problem when the frame does not contain a length prefix and the next interceptor is a frame processor) + * 2) only reads a portion of pReadInByteBuffer + * (the current interceptor can only process a frame of data per tick) + * + * This function sets an internal flag that indicates re-ticks from the root single frame processor are to be expected + * in order to complete a single ::DoTick tick. With this flag enabled, multiple tick may occur as opposed to a single + * callback per ::DoTick(). * @param pInterceptorEx * @return */ @@ -76,8 +80,6 @@ namespace Aurora::IO::Protocol /** * @brief Sends one tick down the protocol stack, regardless of how much data is written into the * next piece/interceptor, and regardless of if another read tick is required. - * Latterly, you are responsible for consuming all available bytes in your non-framed - * (~AppendSingleFrameProcessor[Ex]) interceptors. */ virtual void DoTick() = 0; @@ -96,7 +98,6 @@ namespace Aurora::IO::Protocol /** * @brief Creates a protocol stack backed by the memory of a pipe. - * DoTick must be called each time the pipe has data. * @param pWork * @return */