[*] Updated comments in IProtocolStack.hpp

Include/Aurora/IO/Protocol/IProtocolInterceptorEx.hpp

@@ -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. \ 
+         * @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.
          * 
@@ -32,6 +36,6 @@ namespace Aurora::IO::Protocol
         */
         AUI_METHOD(bool, OnDataAvailable, (const AuSPtr<Memory::ByteBuffer> &, pReadInByteBuffer,
                                            const AuSPtr<Memory::ByteBuffer> &, pWriteOutByteBuffer,
-                                           const AuSPtr<IProtocolPiece>&, pProtocolPiece))
+                                           const AuSPtr<IProtocolPiece> &, pProtocolPiece))
     );
 }

Include/Aurora/IO/Protocol/IProtocolStack.hpp

@@ -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;

Source/IO/Protocol/AuProtocolStack.cpp

@@ -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;
         }