aboutsummaryrefslogtreecommitdiff
path: root/src/lib/subsys/subsys.h
diff options
context:
space:
mode:
authorNick Mathewson <nickm@torproject.org>2019-11-10 16:11:40 -0500
committerNick Mathewson <nickm@torproject.org>2019-11-10 16:13:23 -0500
commita6d22d7fc2c5f5c868fda4ed1224216a16c25f84 (patch)
tree05c9c4a965ddde80dba2aa666f1014880c5aba20 /src/lib/subsys/subsys.h
parentbaddb30889fd281962f014614a43f323b5df6ae6 (diff)
downloadtor-a6d22d7fc2c5f5c868fda4ed1224216a16c25f84.tar.gz
tor-a6d22d7fc2c5f5c868fda4ed1224216a16c25f84.zip
Improve subsys documentation; add initialization documentation.
Diffstat (limited to 'src/lib/subsys/subsys.h')
-rw-r--r--src/lib/subsys/subsys.h58
1 files changed, 56 insertions, 2 deletions
diff --git a/src/lib/subsys/subsys.h b/src/lib/subsys/subsys.h
index 29a90c049d..258d060bb8 100644
--- a/src/lib/subsys/subsys.h
+++ b/src/lib/subsys/subsys.h
@@ -25,6 +25,13 @@ struct config_format_t;
*
* You should use c99 named-field initializers with this structure: we
* will be adding more fields, often in the middle of the structure.
+ *
+ * See \ref initialization for more information about initialization and
+ * shutdown in Tor.
+ *
+ * To make a new subsystem, you declare a const instance of this type, and
+ * include it on the list in subsystem_list.c. The code that manages these
+ * subsystems is in subsysmgr.c.
**/
typedef struct subsys_fns_t {
/**
@@ -55,7 +62,7 @@ typedef struct subsys_fns_t {
* it is only for global state or pre-configuration state.
*
* (If you need to do any setup that depends on configuration, you'll need
- * to declare a configuration callback. (Not yet designed))
+ * to declare a configuration callback instead. (Not yet designed))
*
* This function MUST NOT have any parts that can fail.
**/
@@ -63,22 +70,49 @@ typedef struct subsys_fns_t {
/**
* Connect a subsystem to the message dispatch system.
+ *
+ * This function should use the macros in \refdir{lib/pubsub} to register a
+ * set of messages that this subsystem may publish, and may subscribe to.
+ *
+ * See pubsub_macros.h for more information, and for examples.
**/
int (*add_pubsub)(struct pubsub_connector_t *);
/**
* Perform any necessary pre-fork cleanup. This function may not fail.
+ *
+ * On Windows (and any other platforms without fork()), this function will
+ * never be invoked. Otherwise it is used when we are about to start
+ * running as a background daemon, or when we are about to run a unit test
+ * in a subprocess. Unlike the subsys_fns_t.postfork callback, it is run
+ * from the parent process.
+ *
+ * Note that we do not invoke this function when the child process's only
+ * purpose is to call exec() and run another program.
*/
void (*prefork)(void);
/**
* Perform any necessary post-fork setup. This function may not fail.
+ *
+ * On Windows (and any other platforms without fork()), this function will
+ * never be invoked. Otherwise it is used when we are about to start
+ * running as a background daemon, or when we are about to run a unit test
+ * in a subprocess. Unlike the subsys_fns_t.prefork callback, it is run
+ * from the child process.
+ *
+ * Note that we do not invoke this function when the child process's only
+ * purpose is to call exec() and run another program.
*/
void (*postfork)(void);
/**
* Free any thread-local resources held by this subsystem. Called before
* the thread exits.
+ *
+ * This function is not allowed to fail.
+ *
+ * \bug Note that this callback is currently buggy: See \ticket{32103}.
*/
void (*thread_cleanup)(void);
@@ -86,18 +120,28 @@ typedef struct subsys_fns_t {
* Free all resources held by this subsystem.
*
* This function is not allowed to fail.
+ *
+ * Subsystems are shut down when Tor is about to exit or return control to
+ * an embedding program. This callback must return the process to a state
+ * such that subsys_fns_t.init will succeed if invoked again.
**/
void (*shutdown)(void);
/**
* A config_format_t describing all of the torrc fields owned by this
* subsystem.
+ *
+ * This object, if present, is registered in a confmgr_t for Tor's options,
+ * and used to parse option fields from the command line and torrc file.
**/
const struct config_format_t *options_format;
/**
* A config_format_t describing all of the DataDir/state fields owned by
* this subsystem.
+ *
+ * This object, if present, is registered in a confmgr_t for Tor's state,
+ * and used to parse state fields from the DataDir/state file.
**/
const struct config_format_t *state_format;
@@ -106,7 +150,11 @@ typedef struct subsys_fns_t {
* on success, -1 on failure.
*
* It is safe to store the pointer to the object until set_options()
- * is called again. */
+ * is called again.
+ *
+ * This function is only called after all the validation code defined
+ * by subsys_fns_t.options_format has passed.
+ **/
int (*set_options)(void *);
/* XXXX Add an implementation for options_act_reversible() later in this
@@ -118,6 +166,12 @@ typedef struct subsys_fns_t {
*
* It is safe to store the pointer to the object; set_state() is only
* called on startup.
+ *
+ * This function is only called after all the validation code defined
+ * by subsys_fns_t.state_format has passed.
+ *
+ * This function will only be called once per invocation of Tor, since
+ * Tor does not reload its state while it is running.
**/
int (*set_state)(void *);