Tor  0.4.7.0-alpha-dev
pubsub_build.h
Go to the documentation of this file.
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 */
6 
7 /**
8  * @file pubsub_build.h
9  * @brief Header used for constructing the OO publish-subscribe facility.
10  *
11  * (See pubsub.h for more general information on this API.)
12  **/
13 
14 #ifndef TOR_PUBSUB_BUILD_H
15 #define TOR_PUBSUB_BUILD_H
16 
17 #include "lib/dispatch/msgtypes.h"
18 
19 struct dispatch_t;
20 struct pubsub_connector_t;
21 
22 /**
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.
27  **/
28 typedef struct pubsub_builder_t pubsub_builder_t;
29 
30 /**
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.
34  **/
35 typedef struct pubsub_items_t pubsub_items_t;
36 
37 /**
38  * Create a new pubsub_builder. This should only happen in the
39  * main-init code.
40  */
42 
43 /** DOCDOC */
45 
46 /**
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.
49  */
50 #define pubsub_builder_free(db) \
51  FREE_AND_NULL(pubsub_builder_t, pubsub_builder_free_, (db))
52 
53 /** Internal implementation of pubsub_builder_free(). */
55 
56 /**
57  * Create a pubsub connector that a single subsystem will use to
58  * register its messages. The main-init code does this during subsystem
59  * initialization.
60  */
62  subsys_id_t);
63 
64 /**
65  * The main-init code does this after subsystem initialization.
66  */
67 #define pubsub_connector_free(c) \
68  FREE_AND_NULL(struct pubsub_connector_t, pubsub_connector_free_, (c))
69 
71 
72 /**
73  * Constructs a dispatcher from a dispatch_builder, after checking that the
74  * invariances on the messages, channels, and connections have been
75  * respected.
76  *
77  * This should happen after every subsystem has initialized, and before
78  * entering the mainloop.
79  */
81  pubsub_items_t **items_out);
82 
83 /**
84  * Clear all pub_binding_t backpointers in <b>items</b>.
85  **/
87 
88 /**
89  * @copydoc pubsub_items_free_
90  *
91  * Additionally, set the pointer <b>cfg</b> to NULL.
92  **/
93 #define pubsub_items_free(cfg) \
94  FREE_AND_NULL(pubsub_items_t, pubsub_items_free_, (cfg))
96 
97 #endif /* !defined(TOR_PUBSUB_BUILD_H) */
struct dispatch_t dispatch_t
Definition: dispatch.h:53
Types used for messages in the dispatcher code.
uint16_t subsys_id_t
Definition: msgtypes.h:22
void pubsub_connector_free_(struct pubsub_connector_t *)
Definition: pubsub_build.c:107
void pubsub_builder_free_(pubsub_builder_t *)
Definition: pubsub_build.c:74
struct pubsub_connector_t * pubsub_connector_for_subsystem(pubsub_builder_t *, subsys_id_t)
Definition: pubsub_build.c:89
int pubsub_builder_check(pubsub_builder_t *)
Definition: pubsub_check.c:399
void pubsub_items_free_(pubsub_items_t *cfg)
Definition: pubsub_build.c:42
struct pubsub_items_t pubsub_items_t
Definition: pubsub_build.h:35
struct pubsub_builder_t pubsub_builder_t
Definition: pubsub_build.h:28
pubsub_builder_t * pubsub_builder_new(void)
Definition: pubsub_build.c:56
struct dispatch_t * pubsub_builder_finalize(pubsub_builder_t *, pubsub_items_t **items_out)
Definition: pubsub_build.c:278
void pubsub_items_clear_bindings(pubsub_items_t *items)
Definition: pubsub_build.c:263
struct pubsub_connector_t pubsub_connector_t