commit 28fd4996aca0c560d4af0c035b53323951c13476 Author: Nick Mathewson <nickm@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)