[*] Updated comments in IProtocolStack.hpp

This commit is contained in:
Reece Wilson 2024-02-25 20:09:02 +00:00
parent 78e0c2d442
commit ddebc422ed
3 changed files with 24 additions and 12 deletions

View File

@ -17,12 +17,16 @@ namespace Aurora::IO::Protocol
* *
* @param pReadInByteBuffer a buffer to read from. returning false returns the readPtr of this buffer. * @param pReadInByteBuffer a buffer to read from. returning false returns the readPtr of this buffer.
* @param pWriteOutByteBuffer a buffer to write into. you should return false if that buffer begins to fail. * @param pWriteOutByteBuffer a buffer to write into. you should return false if that buffer begins to fail.
* @param pProtocolStack A pointer that might be used to store user contexts. might be null. \ * @param pProtocolStack A pointer that might be used to store user contexts. This parameters might be empty.
* This is only provided for convenience to users outside of Aurora Runtime. \ * This is provided for convenience to users outside of Aurora Runtime (AURT_ADD_USR_DATA/PrivateUserDataGetSharedData<T>() accessors, etc).
* *
* *
* @return false restores the read head of pReadInByteBuffer. future callbacks will still be made. * @return false - restores the read head of pReadInByteBuffer.
* true nothing; pReadInByteBuffer's heads will remain set by the user and the tick is propagated down the stack. * future callbacks will still be made, unless bKillPipeOnFirstRootLevelFalse is enabled, and the first interceptor fails.
* alternatively, you can force the protocol stack to death via
* a) pWriteOutByteBuffer->flagWriteError = true; or
* b) if (pProtocolPiece) pProtocolPiece->GetParent()->Destroy();
* 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. * @warning the error flags of both bytebuffers can seize up the protocol stack by design.
* *
@ -32,6 +36,6 @@ namespace Aurora::IO::Protocol
*/ */
AUI_METHOD(bool, OnDataAvailable, (const AuSPtr<Memory::ByteBuffer> &, pReadInByteBuffer, AUI_METHOD(bool, OnDataAvailable, (const AuSPtr<Memory::ByteBuffer> &, pReadInByteBuffer,
const AuSPtr<Memory::ByteBuffer> &, pWriteOutByteBuffer, const AuSPtr<Memory::ByteBuffer> &, pWriteOutByteBuffer,
const AuSPtr<IProtocolPiece>&, pProtocolPiece)) const AuSPtr<IProtocolPiece> &, pProtocolPiece))
); );
} }

View File

@ -17,9 +17,10 @@ namespace Aurora::IO::Protocol
{ {
/** /**
* @brief * @brief
* Warning: AppendInterceptorEx is preferred * Warning: AddInterceptorEx is preferred
* @param pInterceptor * @param pInterceptor
* @param uOutputBufferSize When 0, a hopefully not stupid default is used. * @param uOutputBufferSize When 0, a hopefully not stupid default is used.
* (Configurable at runtime init via RuntimeConfig.ioConfig.uProtocolStackDefaultBufferSize)
* @return * @return
*/ */
virtual AuSPtr<IProtocolPiece> AddInterceptor(EProtocolWhere eWhere, virtual AuSPtr<IProtocolPiece> AddInterceptor(EProtocolWhere eWhere,
@ -27,9 +28,13 @@ namespace Aurora::IO::Protocol
AuUInt uOutputBufferSize) = 0; AuUInt uOutputBufferSize) = 0;
/** /**
* @brief * @brief Registers a protocol stack interceptor to be called once per tick of the protocol stack.
* Be careful to not use stupid uOutputBufferSize sizes otherwise you'll quickly find yourself running out of memory.
* You can mitigate excessive resource consumption by using smaller IO frames and repeated callbacks via ::AddSingleFrameProcessor;
* or by using ::AddInterceptorDynamicBuffer with a defined base size and upper limit.
* @param pInterceptorEx * @param pInterceptorEx
* @param uOutputBufferSize When 0, a hopefully not stupid default is used. * @param uOutputBufferSize When 0, a hopefully not stupid default is used.
* (Configurable at runtime init via RuntimeConfig.ioConfig.uProtocolStackDefaultBufferSize)
* @return * @return
*/ */
virtual AuSPtr<IProtocolPiece> AddInterceptorEx(EProtocolWhere eWhere, virtual AuSPtr<IProtocolPiece> AddInterceptorEx(EProtocolWhere eWhere,
@ -37,7 +42,7 @@ namespace Aurora::IO::Protocol
AuUInt uOutputBufferSize) = 0; AuUInt uOutputBufferSize) = 0;
/** /**
* @brief defer to AppendInterceptorEx * @brief defer to AddInterceptorEx
* @param pInterceptorEx * @param pInterceptorEx
* @param uOutputBufferSize * @param uOutputBufferSize
* @return * @return
@ -48,7 +53,7 @@ namespace Aurora::IO::Protocol
AuUInt uOutputBufferMaximumSize) = 0; AuUInt uOutputBufferMaximumSize) = 0;
/** /**
* @brief Same as AppendInterceptor, except that DoTick will repeat until the input is fully consumed. * @brief Same as AddInterceptor, 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 to us. * 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 * Such paradigm contrasts the default unframed/raw stream behaviour where the processor is responsible for consuming all
@ -121,6 +126,10 @@ namespace Aurora::IO::Protocol
*/ */
virtual AuSPtr<IProtocolPiece> GetInterceptorAtIndex(AuUInt32 uIndex) = 0; virtual AuSPtr<IProtocolPiece> GetInterceptorAtIndex(AuUInt32 uIndex) = 0;
/**
* @brief
* @return
*/
virtual bool IsValid() = 0; virtual bool IsValid() = 0;
AURT_ADD_USR_DATA; AURT_ADD_USR_DATA;

View File

@ -662,7 +662,7 @@ namespace Aurora::IO::Protocol
return false; return false;
} }
return true; return !this->bDead;
} }
bool ProtocolStack::TryReadMore(bool bForce) bool ProtocolStack::TryReadMore(bool bForce)
@ -729,7 +729,6 @@ namespace Aurora::IO::Protocol
bool bStatus = pCurrent->pInterceptorEx->OnDataAvailable(pRead, pNextStream, pCurrent); bool bStatus = pCurrent->pInterceptorEx->OnDataAvailable(pRead, pNextStream, pCurrent);
if (!bStatus) if (!bStatus)
{ {
if (pNextStream) if (pNextStream)
@ -808,7 +807,7 @@ namespace Aurora::IO::Protocol
} }
} }
} }
while (bTryAgain); while (bTryAgain && this->IsValid());
return true; return true;
} }