Tor 0.4.9.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
21struct dispatch_cfg_t;
22struct smartlist_t;
23struct 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 **/
34typedef 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 **/
72typedef 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 **/
94struct 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 **/
106struct 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 **/
125struct 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 **/
136typedef 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