From: Oto Šťáva <oto.stava@nic.cz>
Date: Wed, 28 Aug 2024 15:32:43 +0000 (+0200)
Subject: daemon/session2: comment on event propagation
X-Git-Tag: v6.0.9~25^2
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=refs%2Fenvironments%2Fdocs-develop-even-bt6dky%2Fdeployments%2F4989;p=thirdparty%2Fknot-resolver.git

daemon/session2: comment on event propagation

Minor, but I believe quite important. I stumbled across this while
writing the protocol layer article and thought it was not emphasized
enough in the docs.
---

diff --git a/daemon/session2.h b/daemon/session2.h
index 604c43a1d..514e7b7ad 100644
--- a/daemon/session2.h
+++ b/daemon/session2.h
@@ -575,7 +575,12 @@ enum protolayer_event_cb_result {
  *
  * When `PROTOLAYER_EVENT_PROPAGATE` is returned, iteration over the sequence
  * of layers continues. When `PROTOLAYER_EVENT_CONSUME` is returned, iteration
- * stops. */
+ * stops.
+ *
+ * **IMPORTANT:** A well-behaved layer will **ALWAYS** propagate events it knows
+ * nothing about. Only ever consume events you actually have good reason to
+ * consume (like TLS consumes `CONNECT` from TCP, because it needs to perform
+ * its own handshake first). */
 typedef enum protolayer_event_cb_result (*protolayer_event_cb)(
 		enum protolayer_event_type event, void **baton,
 		struct session2 *session, void *sess_data);