[tor-commits] [tor/master] Various documentation notes and tweaks for pubsub

[asn at torproject.org]

commit 28fd4996aca0c560d4af0c035b53323951c13476
Author: Nick Mathewson <nickm at torproject.org>
Date:   Thu Mar 14 15:35:41 2019 -0400

    Various documentation notes and tweaks for pubsub
---
 src/core/mainloop/mainloop_pubsub.c |  3 +++
 src/lib/pubsub/pubsub_macros.h      | 16 ++++++++++++++--
 2 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/core/mainloop/mainloop_pubsub.c b/src/core/mainloop/mainloop_pubsub.c
index aac607126..724a3115c 100644
--- a/src/core/mainloop/mainloop_pubsub.c
+++ b/src/core/mainloop/mainloop_pubsub.c
@@ -123,6 +123,9 @@ alertfn_immediate(dispatch_t *d, channel_id_t chan, void *arg)
 
 /**
  * Set the strategy to be used for delivering messages on the named channel.
+ *
+ * This function needs to be called once globally for each channel, to
+ * set up how messages are delivered.
  **/
 int
 tor_mainloop_set_delivery_strategy(const char *msg_channel_name,
diff --git a/src/lib/pubsub/pubsub_macros.h b/src/lib/pubsub/pubsub_macros.h
index 12cfa7d39..11c7c63ec 100644
--- a/src/lib/pubsub/pubsub_macros.h
+++ b/src/lib/pubsub/pubsub_macros.h
@@ -165,6 +165,10 @@
 
 /* Macro to declare common elements shared by DECLARE_MESSAGE and
  * DECLARE_MESSAGE_INT.  Don't call this directly.
+ *
+ * Note that the "msg_arg_name" string constant is defined in each
+ * translation unit.  This might be undesirable; we can tweak it in the
+ * future if need be.
  */
 #define DECLARE_MESSAGE_COMMON__(messagename, typename, c_type)         \
   typedef c_type msg_arg_type__ ##messagename;                          \
@@ -179,6 +183,8 @@
  * C identifier.
  *
  * "typename" is a unique identifier for the type of the auxiliary data.
+ * It needs to be defined somewhere in Tor, using
+ * "DISPATCH_DEFINE_TYPE."
  *
  * "c_type" is a C pointer type (like "char *" or "struct foo *").
  */
@@ -203,7 +209,8 @@
  * "messagename" is a unique identifier for the message; it must be a valid
  * C identifier.
  *
- * "typename" is a unique identifier for the type of the auxiliary data.
+ * "typename" is a unique identifier for the type of the auxiliary data.  It
+ * needs to be defined somewhere in Tor, using "DISPATCH_DEFINE_TYPE."
  *
  * "c_type" is a C integer type, like "int" or "bool".  It needs to fit inside
  * a uint64_t.
@@ -231,6 +238,8 @@
  *
  * Before you use this, you need to include the header where DECLARE_MESSAGE*()
  * was used for this message.
+ *
+ * You can only use this once per message in each subsystem.
  */
 #define DECLARE_PUBLISH(messagename)                                    \
   static pub_binding_t pub_binding__ ##messagename;                     \
@@ -256,6 +265,8 @@
  * "hookfn".  The type of this function will be:
  *     static void hookfn(const msg_t *, const c_type)
  * where c_type is the c type that you declared in the header.
+ *
+ * You can only use this once per message in each subsystem.
  */
 #define DECLARE_SUBSCRIBE(messagename, hookfn) \
   static void hookfn(const msg_t *,                             \
@@ -341,7 +352,8 @@
     DISPATCH_ADD_SUB_(connector, channel, messagename, DISP_FLAG_EXCL)
 
 /**
- * Publish a given message with a given argument.
+ * Publish a given message with a given argument.  (Takes ownership of the
+ * argument if it is a pointer.)
  */
 #define PUBLISH(messagename, arg)               \
   publish_fn__ ##messagename(arg)