Copilot commented on code in PR #13804: URL: https://github.com/apache/trafficserver/pull/13804#discussion_r4199985782
########## include/iocore/eventsystem/Continuation.h: ########## @@ -108,83 +142,195 @@ class force_VFPT_to_top }; /** - Base class for all state machines to receive notification of - events. - - The Continuation class represents the main abstraction mechanism - used throughout the IO Core Event System to communicate its users - the occurrence of an event. A Continuation is a lightweight data - structure that implements a single method with which the user is - called back. - - Continuations are typically subclassed in order to implement - event-driven state machines. By including additional state and - methods, continuations can combine state with control flow, and - they are generally used to support split-phase, event-driven - control flow. - - Given the multithreaded nature of the Event System, every - continuation carries a reference to a ProxyMutex object to protect - its state and ensure atomic operations. This ProxyMutex object - must be allocated by continuation-derived classes or by clients - of the IO Core Event System and it is required as a parameter to - the Continuation's class constructor. - + Base class for event-driven state machines dispatched by the IO Core + Event System. + + A Continuation pairs a member-function handler with a @c ProxyMutex. + When a Processor delivers an event to the Continuation (via + @c handleEvent), the calling thread MUST hold @c this->mutex when it + is non-null; the handler runs while that lock is held and can + manipulate the Continuation's state safely. Continuations with a null + @c mutex run without serialization. Subclasses add state and + additional handler methods, switching between them with + @c SET_HANDLER. + + @par Ownership + Caller-owned. Continuation does not allocate or free itself; the + derived state machine controls its own lifetime. Once a Continuation + has been registered with a Processor (e.g., via a @c schedule_* + call), it MUST remain alive until either (a) the Processor returns + @c ACTION_RESULT_DONE / @c ACTION_IO_ERROR for a synchronous + completion, or (b) every outstanding @c Action returned by that + Processor for this Continuation has been cancelled or, for one-shot + operations, has delivered its terminal callback. Recurring operations + (e.g., periodic events) remain outstanding after each callback return + and are complete only upon cancellation. The Continuation may be Review Comment: This lifetime rule conflicts with the reentrant completion contract in `Action.h:67-75`, which explicitly allows an inline callback to deallocate its state machine before the processor call returns. Requiring the Continuation to survive until `ACTION_RESULT_DONE` or `ACTION_IO_ERROR` is returned also contradicts the self-destruction guidance below. Please distinguish inline completion from outstanding asynchronous actions and warn the caller not to touch state after the sentinel result. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
