[*] 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 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. \
* This is only provided for convenience to users outside of Aurora Runtime. \
* @param pProtocolStack A pointer that might be used to store user contexts. This parameters might be empty.
* 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.
* true nothing; pReadInByteBuffer's heads will remain set by the user and the tick is propagated down the stack.
* @return false - restores the read head of pReadInByteBuffer.
* 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.
*

View File

@ -17,9 +17,10 @@ namespace Aurora::IO::Protocol
{
/**
* @brief
* Warning: AppendInterceptorEx is preferred
* Warning: AddInterceptorEx is preferred
* @param pInterceptor
* @param uOutputBufferSize When 0, a hopefully not stupid default is used.
* (Configurable at runtime init via RuntimeConfig.ioConfig.uProtocolStackDefaultBufferSize)
* @return
*/
virtual AuSPtr<IProtocolPiece> AddInterceptor(EProtocolWhere eWhere,
@ -27,9 +28,13 @@ namespace Aurora::IO::Protocol
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 uOutputBufferSize When 0, a hopefully not stupid default is used.
* (Configurable at runtime init via RuntimeConfig.ioConfig.uProtocolStackDefaultBufferSize)
* @return
*/
virtual AuSPtr<IProtocolPiece> AddInterceptorEx(EProtocolWhere eWhere,
@ -37,7 +42,7 @@ namespace Aurora::IO::Protocol
AuUInt uOutputBufferSize) = 0;
/**
* @brief defer to AppendInterceptorEx
* @brief defer to AddInterceptorEx
* @param pInterceptorEx
* @param uOutputBufferSize
* @return
@ -48,7 +53,7 @@ namespace Aurora::IO::Protocol
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.
* 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;
/**
* @brief
* @return
*/
virtual bool IsValid() = 0;
AURT_ADD_USR_DATA;

View File

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