1 /* Copyright (c) 2001, Matej Pfajfar.
2 * Copyright (c) 2001-2004, Roger Dingledine.
3 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
4 * Copyright (c) 2007-2021, The Tor Project, Inc. */
5 /* See LICENSE for licensing information */
9 * @brief Header used for constructing the OO publish-subscribe facility.
11 * (See pubsub.h for more general information on this API.)
14 #ifndef TOR_PUBSUB_BUILD_H
15 #define TOR_PUBSUB_BUILD_H
17 #include "lib/dispatch/msgtypes.h"
20 struct pubsub_connector_t
;
23 * A "dispatch builder" is an incomplete dispatcher, used when
24 * registering messages. It does not have the same integrity guarantees
25 * as a dispatcher. It cannot actually handle messages itself: once all
26 * subsystems have registered, it is converted into a dispatch_t.
28 typedef struct pubsub_builder_t pubsub_builder_t
;
31 * A "pubsub items" holds the configuration items used to configure a
32 * pubsub_builder. After the builder is finalized, this field is extracted,
33 * and used later to tear down pointers that enable publishing.
35 typedef struct pubsub_items_t pubsub_items_t
;
38 * Create a new pubsub_builder. This should only happen in the
41 pubsub_builder_t
*pubsub_builder_new(void);
44 int pubsub_builder_check(pubsub_builder_t
*);
47 * Free a pubsub builder. This should only happen on error paths, where
48 * we have decided not to construct a dispatcher for some reason.
50 #define pubsub_builder_free(db) \
51 FREE_AND_NULL(pubsub_builder_t, pubsub_builder_free_, (db))
53 /** Internal implementation of pubsub_builder_free(). */
54 void pubsub_builder_free_(pubsub_builder_t
*);
57 * Create a pubsub connector that a single subsystem will use to
58 * register its messages. The main-init code does this during subsystem
61 struct pubsub_connector_t
*pubsub_connector_for_subsystem(pubsub_builder_t
*,
65 * The main-init code does this after subsystem initialization.
67 #define pubsub_connector_free(c) \
68 FREE_AND_NULL(struct pubsub_connector_t, pubsub_connector_free_, (c))
70 void pubsub_connector_free_(struct pubsub_connector_t
*);
73 * Constructs a dispatcher from a dispatch_builder, after checking that the
74 * invariances on the messages, channels, and connections have been
77 * This should happen after every subsystem has initialized, and before
78 * entering the mainloop.
80 struct dispatch_t
*pubsub_builder_finalize(pubsub_builder_t
*,
81 pubsub_items_t
**items_out
);
84 * Clear all pub_binding_t backpointers in <b>items</b>.
86 void pubsub_items_clear_bindings(pubsub_items_t
*items
);
89 * @copydoc pubsub_items_free_
91 * Additionally, set the pointer <b>cfg</b> to NULL.
93 #define pubsub_items_free(cfg) \
94 FREE_AND_NULL(pubsub_items_t, pubsub_items_free_, (cfg))
95 void pubsub_items_free_(pubsub_items_t
*cfg
);
97 #endif /* !defined(TOR_PUBSUB_BUILD_H) */