Tor  0.4.7.0-alpha-dev
subsys.h
Go to the documentation of this file.
1 /* Copyright (c) 2003-2004, Roger Dingledine
2  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
3  * Copyright (c) 2007-2021, The Tor Project, Inc. */
4 /* See LICENSE for licensing information */
5 
6 /**
7  * @file subsys.h
8  * @brief Types used to declare a subsystem.
9  **/
10 
11 #ifndef TOR_SUBSYS_T
12 #define TOR_SUBSYS_T
13 
14 #include <stdbool.h>
15 
16 struct pubsub_connector_t;
17 struct config_format_t;
18 struct smartlist_t;
19 
20 /**
21  * A subsystem is a part of Tor that is initialized, shut down, configured,
22  * and connected to other parts of Tor.
23  *
24  * All callbacks are optional -- if a callback is set to NULL, the subsystem
25  * manager will treat it as a no-op.
26  *
27  * You should use c99 named-field initializers with this structure, for
28  * readability and safety. (There are a lot of functions here, all of them
29  * optional, and many of them with similar signatures.)
30  *
31  * See @ref initialization for more information about initialization and
32  * shutdown in Tor.
33  *
34  * To make a new subsystem, you declare a const instance of this type, and
35  * include it on the list in subsystem_list.c. The code that manages these
36  * subsystems is in subsysmgr.c.
37  **/
38 typedef struct subsys_fns_t {
39  /**
40  * The name of this subsystem. It should be a programmer-readable
41  * identifier.
42  **/
43  const char *name;
44 
45  /**
46  * The file in which the subsystem object is declared. Used for debugging.
47  **/
48  const char *location;
49 
50  /**
51  * Whether this subsystem is supported -- that is, whether it is compiled
52  * into Tor. For most subsystems, this should be true.
53  **/
54  bool supported;
55 
56  /**
57  * The 'initialization level' for the subsystem. It should run from -100
58  * through +100. The subsystems are initialized from lowest level to
59  * highest, and shut down from highest level to lowest.
60  **/
61  int level;
62 
63  /**
64  * Initialize any global components of this subsystem.
65  *
66  * This function MAY rely on any lower-level subsystem being initialized.
67  *
68  * This function MUST NOT rely on any runtime configuration information;
69  * it is only for global state or pre-configuration state.
70  *
71  * (If you need to do any setup that depends on configuration, you'll need
72  * to declare a configuration callback instead. (Not yet designed))
73  *
74  * This function MUST NOT have any parts that can fail.
75  **/
76  int (*initialize)(void);
77 
78  /**
79  * Connect a subsystem to the message dispatch system.
80  *
81  * This function should use the macros in @refdir{lib/pubsub} to register a
82  * set of messages that this subsystem may publish, and may subscribe to.
83  *
84  * See pubsub_macros.h for more information, and for examples.
85  **/
86  int (*add_pubsub)(struct pubsub_connector_t *);
87 
88  /**
89  * Perform any necessary pre-fork cleanup. This function may not fail.
90  *
91  * On Windows (and any other platforms without fork()), this function will
92  * never be invoked. Otherwise it is used when we are about to start
93  * running as a background daemon, or when we are about to run a unit test
94  * in a subprocess. Unlike the subsys_fns_t.postfork callback, it is run
95  * from the parent process.
96  *
97  * Note that we do not invoke this function when the child process's only
98  * purpose is to call exec() and run another program.
99  */
100  void (*prefork)(void);
101 
102  /**
103  * Perform any necessary post-fork setup. This function may not fail.
104  *
105  * On Windows (and any other platforms without fork()), this function will
106  * never be invoked. Otherwise it is used when we are about to start
107  * running as a background daemon, or when we are about to run a unit test
108  * in a subprocess. Unlike the subsys_fns_t.prefork callback, it is run
109  * from the child process.
110  *
111  * Note that we do not invoke this function when the child process's only
112  * purpose is to call exec() and run another program.
113  */
114  void (*postfork)(void);
115 
116  /**
117  * Free any thread-local resources held by this subsystem. Called before
118  * the thread exits.
119  *
120  * This function is not allowed to fail.
121  *
122  * \bug Note that this callback is currently buggy: See \ticket{32103}.
123  */
124  void (*thread_cleanup)(void);
125 
126  /**
127  * Free all resources held by this subsystem.
128  *
129  * This function is not allowed to fail.
130  *
131  * Subsystems are shut down when Tor is about to exit or return control to
132  * an embedding program. This callback must return the process to a state
133  * such that subsys_fns_t.init will succeed if invoked again.
134  **/
135  void (*shutdown)(void);
136 
137  /**
138  * A config_format_t describing all of the torrc fields owned by this
139  * subsystem.
140  *
141  * This object, if present, is registered in a confmgr_t for Tor's options,
142  * and used to parse option fields from the command line and torrc file.
143  **/
145 
146  /**
147  * A config_format_t describing all of the DataDir/state fields owned by
148  * this subsystem.
149  *
150  * This object, if present, is registered in a confmgr_t for Tor's state,
151  * and used to parse state fields from the DataDir/state file.
152  **/
154 
155  /**
156  * Receive an options object as defined by options_format. Return 0
157  * on success, -1 on failure.
158  *
159  * It is safe to store the pointer to the object until set_options()
160  * is called again.
161  *
162  * This function is only called after all the validation code defined
163  * by subsys_fns_t.options_format has passed.
164  **/
165  int (*set_options)(void *);
166 
167  /* XXXX Add an implementation for options_act_reversible() later in this
168  * branch. */
169 
170  /**
171  * Receive a state object as defined by state_format. Return 0 on success,
172  * -1 on failure.
173  *
174  * It is safe to store the pointer to the object; set_state() is only
175  * called on startup.
176  *
177  * This function is only called after all the validation code defined
178  * by subsys_fns_t.state_format has passed.
179  *
180  * This function will only be called once per invocation of Tor, since
181  * Tor does not reload its state while it is running.
182  **/
183  int (*set_state)(void *);
184 
185  /**
186  * Update any information that needs to be stored in the provided state
187  * object (as defined by state_format). Return 0 on success, -1 on failure.
188  *
189  * The object provided here will be the same one as provided earlier to
190  * set_state(). This method is called when we are about to save the state
191  * to disk.
192  **/
193  int (*flush_state)(void *);
194 
195  /**
196  * Return a list of metrics store of this subsystem. This is called
197  * every time a request arrives on the MetricsPort.
198  *
199  * The list MUST contain metrics_store_t object and contains entries so it
200  * can be formatted for the metrics port.
201  *
202  * This can return NULL or be NULL.
203  **/
204  const struct smartlist_t *(*get_metrics)(void);
205 } subsys_fns_t;
206 
207 #ifndef COCCI
208 /**
209  * Macro to declare a subsystem's location.
210  **/
211 #define SUBSYS_DECLARE_LOCATION() \
212  .location = __FILE__
213 #endif /* !defined(COCCI) */
214 
215 /**
216  * Lowest allowed subsystem level.
217  **/
218 #define MIN_SUBSYS_LEVEL -100
219 /**
220  * Highest allowed subsystem level.
221  **/
222 #define MAX_SUBSYS_LEVEL 100
223 
224 /**
225  * All tor "libraries" (in src/libs) should have a subsystem level equal to or
226  * less than this value.
227  */
228 #define SUBSYS_LEVEL_LIBS -10
229 
230 #endif /* !defined(TOR_SUBSYS_T) */
struct pubsub_connector_t pubsub_connector_t
int(* initialize)(void)
Definition: subsys.h:76
bool supported
Definition: subsys.h:54
int(* flush_state)(void *)
Definition: subsys.h:193
const struct config_format_t * options_format
Definition: subsys.h:144
const char * name
Definition: subsys.h:43
void(* postfork)(void)
Definition: subsys.h:114
int(* set_state)(void *)
Definition: subsys.h:183
void(* shutdown)(void)
Definition: subsys.h:135
void(* thread_cleanup)(void)
Definition: subsys.h:124
int(* set_options)(void *)
Definition: subsys.h:165
int(* add_pubsub)(struct pubsub_connector_t *)
Definition: subsys.h:86
int level
Definition: subsys.h:61
const char * location
Definition: subsys.h:48
const struct config_format_t * state_format
Definition: subsys.h:153
void(* prefork)(void)
Definition: subsys.h:100