davsclaus commented on code in PR #30243:
URL: https://github.com/apache/camel/pull/30243#discussion_r4596719130


##########
components/camel-sanitizer/src/main/docs/sanitizer.adoc:
##########
@@ -229,6 +230,62 @@ pending warning uses too (one notifier for both, added 
when either is on).
 With `camel.sanitizer.checks=commit` only, the step listener is still 
installed (each step is still wrapped, and the
 report still counts the calls of steps), so a report of R2 can name the step 
that handed a commit over.
 
+=== R3: one thread at a time
+
+An exchange can move between threads, but it is never used by two threads at 
the same time. This version checks the
+first part of the rule: the contract of `AsyncProcessor` at the call of each 
step. The value the callback of a call is
+called with (`doneSync`) must be the value `process(exchange, callback)` 
returns, and `true` means that the callback
+was called already, on the calling thread. A caller that uses the return value
+continues the exchange when `process` returns `true`, and leaves it to the 
callback when it returns `false`; a
+processor that returns the other value lets two threads continue the same 
exchange, or none. Most callers in Camel go
+on through the callback and do not use the return value, so in a route the 
mismatch is usually harmless today; it still
+breaks the contract, and the same processor breaks under a caller that uses 
it. It reports:
+
+* *process returned true, and its callback was called on another thread* 
(`RETURNED_TRUE_CALLBACK_ON_OTHER_THREAD`):
+the processor handed the exchange to another thread, which called the 
callback, and then returned `true` as if it had
+done the work itself (such as a processor that waits for its worker). With 
`false` the caller and that thread can both
+continue the exchange; with `true` that thread continued it while `process` 
still ran. The report has the thread and
+stack of the callback, and the return.
+* *process returned true before its callback was called* 
(`RETURNED_TRUE_BEFORE_CALLBACK`): `process` returned `true`,
+and the callback then came on another thread, or with `true`. The caller went 
on before the work of the processor was
+done.
+* *process returned false, and its callback was called with true* 
(`RETURNED_FALSE_CALLBACK_TRUE`): in either order,
+on any thread.
+
+The contract allows one case where the two values differ, and it is not 
reported: a processor that hands its callback
+to the reactive executor returns the value of the processor it calls, and the 
reactive executor then calls the callback
+with `false` on the calling thread, at once or after the work that thread is 
running. The channel of a step without an
+error handler does this, so a step that calls such a channel directly sees it: 
for example a `choice` whose branch has
+one step, in a route with `noErrorHandler()`.
+So a callback with `false` on the thread that called `process` is never 
reported, whatever `process` returns and whether it comes before or after the 
return. The check relies on the

Review Comment:
   Fixed: the source (af24d2c) and the catalog copy (8c7b2de) both have the 
sentence as its own paragraph now.
   
   _Claude Code on behalf of davsclaus_



-- 
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]

Reply via email to