JosiahWI commented on code in PR #13804:
URL: https://github.com/apache/trafficserver/pull/13804#discussion_r4218151918
##########
include/iocore/eventsystem/Continuation.h:
##########
@@ -108,83 +146,157 @@ 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 Event
+ System.
+
+ A Continuation pairs the @c handler that @c handleEvent invokes with
+ the @c mutex that serializes those invocations. Derived classes add
+ state and handler methods, and typically replace @c handler as they
+ move between states.
+
+ @par Lifetime
+ A handler must be installed before the Continuation is scheduled or
+ passed to an asynchronous operation. From then on, the Continuation
+ must stay alive until no further event can be dispatched to it, i.e.,
+ until each such operation has completed or been cancelled. It may then
+ be destroyed through a @c Continuation pointer, including by
+ @c delete @c this from its own handler, provided nothing, including
+ callers further up the stack, accesses it afterward.
+
+ @par Thread Safety
+ Not thread-safe. While @c mutex is non-null, concurrent accesses must
+ hold it, except where a member documents otherwise; the Event System
+ holds it for the duration of each dispatch.
*/
-
class Continuation : private force_VFPT_to_top
{
public:
/**
- The current continuation handler function.
+ The member function that @c handleEvent invokes.
- The current handler should not be set directly. In order to
- change it, first acquire the Continuation's lock and then use
- the SET_HANDLER macro which takes care of the type casting
- issues.
+ Install a handler with @c SET_HANDLER or @c SET_CONTINUATION_HANDLER
+ rather than by direct assignment; see @c ContinuationHandler for why
+ a @c reinterpret_cast is unsafe. A handler may replace this field
+ while it runs; the new handler receives the next dispatch.
+ @par Thread Safety
+ Not thread-safe.
*/
ContinuationHandler handler = nullptr;
#ifdef DEBUG
+ /**
+ Name of the most recently installed handler, captured by
+ @c SET_HANDLER / @c SET_CONTINUATION_HANDLER for diagnostic use.
+ Present only in DEBUG builds. Initial value is null. Same
+ synchronization rules as @c handler.
+ */
const char *handler_name = nullptr;
Review Comment:
Leaving as is, but good flag.
--
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]
