Tor  0.4.7.0-alpha-dev
pubsub_builder_st.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_builder_st.h
9  *
10  * @brief private structures used for configuring dispatchers and messages.
11  */
12 
13 #ifndef TOR_PUBSUB_BUILDER_ST_H
14 #define TOR_PUBSUB_BUILDER_ST_H
15 
16 #ifdef PUBSUB_PRIVATE
17 
18 #include <stdbool.h>
19 #include <stddef.h>
20 
21 struct dispatch_cfg_t;
22 struct smartlist_t;
23 struct pub_binding_t;
24 
25 /**
26  * Configuration for a single publication or subscription request.
27  *
28  * These can be stored while the dispatcher is in use, but are only used for
29  * setup, teardown, and debugging.
30  *
31  * There are various fields in this request describing the message; all of
32  * them must match other descriptions of the message, or a bug has occurred.
33  **/
34 typedef struct pubsub_cfg_t {
35  /** True if this is a publishing request; false for a subscribing request. */
36  bool is_publish;
37  /** The system making this request. */
38  subsys_id_t subsys;
39  /** The channel on which the message is to be sent. */
40  channel_id_t channel;
41  /** The message ID to be sent or received. */
42  message_id_t msg;
43  /** The C type associated with the message. */
44  msg_type_id_t type;
45  /** One or more DISP_FLAGS_* items, combined with bitwise OR. */
46  unsigned flags;
47 
48  /**
49  * Publishing only: a pub_binding object that will receive the binding for
50  * this request. We will finish filling this in when the dispatcher is
51  * constructed, so that the subsystem can publish then and not before.
52  */
53  struct pub_binding_t *pub_binding;
54 
55  /**
56  * Subscribing only: a function to receive message objects for this request.
57  */
58  recv_fn_t recv_fn;
59 
60  /** The file from which this message was configured */
61  const char *added_by_file;
62  /** The line at which this message was configured */
63  unsigned added_by_line;
64 } pubsub_cfg_t;
65 
66 /**
67  * Configuration request for a single C type.
68  *
69  * These are stored while the dispatcher is in use, but are only used for
70  * setup, teardown, and debugging.
71  **/
72 typedef struct pubsub_type_cfg_t {
73  /**
74  * The identifier for this type.
75  */
76  msg_type_id_t type;
77  /**
78  * Functions to use when manipulating the type.
79  */
81 
82  /** The subsystem that configured this type. */
83  subsys_id_t subsys;
84  /** The file from which this type was configured */
85  const char *added_by_file;
86  /** The line at which this type was configured */
87  unsigned added_by_line;
88 } pubsub_type_cfg_t;
89 
90 /**
91  * The set of configuration requests for a dispatcher, as made by various
92  * subsystems.
93  **/
94 struct pubsub_items_t {
95  /** List of pubsub_cfg_t. */
96  struct smartlist_t *items;
97  /** List of pubsub_type_cfg_t. */
98  struct smartlist_t *type_items;
99 };
100 
101 /**
102  * Type used to construct a dispatcher. We use this type to build up the
103  * configuration for a dispatcher, and then pass ownership of that
104  * configuration to the newly constructed dispatcher.
105  **/
106 struct pubsub_builder_t {
107  /** Number of outstanding pubsub_connector_t objects pointing to this
108  * pubsub_builder_t. */
109  int n_connectors;
110  /** Number of errors encountered while constructing this object so far. */
111  int n_errors;
112  /** In-progress configuration that we're constructing, as a list of the
113  * requests that have been made. */
114  struct pubsub_items_t *items;
115  /** In-progress configuration that we're constructing, in a form that can
116  * be converted to a dispatch_t. */
117  struct dispatch_cfg_t *cfg;
118 };
119 
120 /**
121  * Type given to a subsystem when adding connections to a pubsub_builder_t.
122  * We use this type to force each subsystem to get blamed for the
123  * publications, subscriptions, and types that it adds.
124  **/
125 struct pubsub_connector_t {
126  /** The pubsub_builder that this connector refers to. */
127  struct pubsub_builder_t *builder;
128  /** The subsystem that has been given this connector. */
129  subsys_id_t subsys_id;
130 };
131 
132 /**
133  * Helper structure used when constructing a dispatcher that sorts the
134  * pubsub_cfg_t objects in various ways.
135  **/
136 typedef struct pubsub_adjmap_t {
137  /* XXXX The next three fields are currently constructed but not yet
138  * XXXX used. I believe we'll want them in the future, though. -nickm
139  */
140  /** Number of subsystems; length of the *_by_subsys arrays. */
141  size_t n_subsystems;
142  /** Array of lists of publisher pubsub_cfg_t objects, indexed by
143  * subsystem. */
144  struct smartlist_t **pub_by_subsys;
145  /** Array of lists of subscriber pubsub_cfg_t objects, indexed by
146  * subsystem. */
147  struct smartlist_t **sub_by_subsys;
148 
149  /** Number of message IDs; length of the *_by_msg arrays. */
150  size_t n_msgs;
151  /** Array of lists of publisher pubsub_cfg_t objects, indexed by
152  * message ID. */
153  struct smartlist_t **pub_by_msg;
154  /** Array of lists of subscriber pubsub_cfg_t objects, indexed by
155  * message ID. */
156  struct smartlist_t **sub_by_msg;
157 } pubsub_adjmap_t;
158 
159 #endif /* defined(PUBSUB_PRIVATE) */
160 
161 #endif /* !defined(TOR_PUBSUB_BUILDER_ST_H) */
uint16_t subsys_id_t
Definition: msgtypes.h:22
uint16_t msg_type_id_t
Definition: msgtypes.h:29
void(* recv_fn_t)(const msg_t *m)
Definition: msgtypes.h:66
struct pubsub_items_t pubsub_items_t
Definition: pubsub_build.h:35
struct pubsub_builder_t pubsub_builder_t
Definition: pubsub_build.h:28
struct pubsub_connector_t pubsub_connector_t