JosiahWI commented on code in PR #13804:
URL: https://github.com/apache/trafficserver/pull/13804#discussion_r4218130713
##########
include/iocore/eventsystem/Continuation.h:
##########
@@ -195,30 +307,56 @@ class Continuation : private force_VFPT_to_top
return false;
}
+ /**
+ Returns the EThread previously installed as this Continuation's
+ affinity, or nullptr if none has been set.
+
+ @par Thread Safety
+ Caller-synchronized read; see @c thread_affinity.
+ */
EThread *
getThreadAffinity()
{
return thread_affinity;
}
+ /**
+ Clears the dispatch-thread affinity, restoring the "no preference"
+ state.
+
+ @par Thread Safety
+ Caller-synchronized; see @c thread_affinity.
+ */
void
clearThreadAffinity()
{
thread_affinity = nullptr;
}
/**
- Receives the event code and data for an Event.
-
- This function receives the event code and data for an event and
- forwards them to the current continuation handler. The processor
- calling back the continuation is responsible for acquiring its
- lock. If the lock is present and not held, this method will assert.
-
- @param event Event code to be passed at callback (Processor specific).
- @param data General purpose data related to the event code (Processor
specific).
- @return State machine and processor specific return code.
-
+ Dispatches an event to this Continuation's currently installed
+ handler.
+
+ @param[in] event Event code to forward. Meaning is Processor-specific
+ (e.g., @c VC_EVENT_READ_READY, @c EVENT_IMMEDIATE).
+ Defaults to @c CONTINUATION_EVENT_NONE.
+ @param[in,out] data Auxiliary payload to forward. Lifetime, ownership, and
+ type are Processor-specific. Defaults to nullptr.
+ @return The handler's return value. The Event System dispatcher
+ discards it; only direct callers of @c handleEvent define
+ its meaning. @c CONTINUATION_DONE and @c CONTINUATION_CONT
+ are the base-level conventions; Processor-specific protocols
+ may define additional return values.
+
+ @pre @c this->handler is non-null. Calling with a null handler is
+ undefined behavior (invokes a null pointer-to-member).
+
+ @par Thread Safety
+ Caller-synchronized via @c this->mutex when non-null. The Event
+ System holds the mutex around its calls when @c this->mutex is
+ non-null; Continuations with a null mutex run without
+ serialization. Ad-hoc callers MUST hold @c this->mutex before
+ calling when it is non-null.
Review Comment:
What does it communicate to say "this precondition is enforced"? It
communicates that all the other preconditions are not enforced. That's a
message we don't want to convey. All preconditions are equally binding
requirements and are implicitly enforceable at our discretion.
--
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]
