commit 8746fedce4a440cccde2b4683d7aa72e7c0b0c89 Author: Nick Mathewson <nickm@torproject.org> Date: Fri Nov 15 09:00:54 2019 -0500 Initialization documents: incorporate feedback from review. (Thanks, Taylor!) --- src/lib/subsys/initialization.dox | 18 +++++++++--------- src/lib/subsys/subsys.h | 9 +++++---- 2 files changed, 14 insertions(+), 13 deletions(-) diff --git a/src/lib/subsys/initialization.dox b/src/lib/subsys/initialization.dox index ed2d5abf2..561cd17ba 100644 --- a/src/lib/subsys/initialization.dox +++ b/src/lib/subsys/initialization.dox @@ -9,7 +9,7 @@ Tor has a single entry point: tor_run_main() in main.c. All the ways of starting a Tor process (ntmain.c, tor_main.c, and tor_api.c) work by invoking tor_run_main(). -The tor_run_main() function normally exits (\ref init_exceptwhen "1") by +The tor_run_main() function normally exits (@ref init_exceptwhen "1") by returning: not by calling abort() or exit(). Before it returns, it calls tor_cleanup() in shutdown.c. @@ -17,7 +17,7 @@ Conceptually, there are several stages in running Tor. 1. First, we initialize those modules that do not depend on the configuration. This happens in the first half of tor_run_main(), and the - first half of tor_init(). (\ref init_pending_refactor "2") + first half of tor_init(). (@ref init_pending_refactor "2") 2. Second, we parse the command line and our configuration, and configure systems that depend on our configuration or state. This configuration @@ -33,16 +33,16 @@ Conceptually, there are several stages in running Tor. running. -> \anchor init_exceptwhen 1. tor_run_main() _can_ terminate with a call to +> @anchor init_exceptwhen 1. tor_run_main() _can_ terminate with a call to

abort() or exit(), but only when crashing due to a bug, or when forking to run as a daemon.

-> \anchor init_pending_refactor 2. The pieces of code that I'm describing as +> @anchor init_pending_refactor 2. The pieces of code that I'm describing as

"the first part of tor_init()" and so on deserve to be functions with their own name. I'd like to refactor them, but before I do so, there is some slight reorganization that needs to happen. Notably, the nt_service_parse_options() call ought logically to be later in our -> initialization sequence. See \ticket{32447} for our refactoring progress. +> initialization sequence. See @ticket{32447} for our refactoring progress.

@section subsys Subsystems and initialization @@ -55,10 +55,10 @@ In simplest terms, a **subsytem** is a logically separate part of Tor that can be initialized, shut down, managed, and configured somewhat independently of the rest of the program. -To define a subsystem, we declare a `const` instance of subsys_fns_t, -describing the subsystem and a set of functions that initialize it, -deconstruct it, and so on. See the documentation for subsys_fns_t for a full -list of these functions. +The subsys_fns_t type describes a subsystem and a set of functions that +initialize it, desconstruct it, and so on. To define a subsystem, we declare +a `const` instance of subsys_fns_t. See the documentation for subsys_fns_t +for a full list of these functions. After defining a subsytem, it must be inserted in subsystem_list.c. At that point, table-driven mechanisms in subsysmgr.c will invoke its functions when diff --git a/src/lib/subsys/subsys.h b/src/lib/subsys/subsys.h index 258d060bb..324f4f294 100644 --- a/src/lib/subsys/subsys.h +++ b/src/lib/subsys/subsys.h @@ -23,10 +23,11 @@ struct config_format_t; * All callbacks are optional -- if a callback is set to NULL, the subsystem * manager will treat it as a no-op. * - * You should use c99 named-field initializers with this structure: we - * will be adding more fields, often in the middle of the structure. + * You should use c99 named-field initializers with this structure, for + * readability and safety. (There are a lot of functions here, all of them + * optional, and many of them with similar signatures.) * - * See \ref initialization for more information about initialization and + * 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 @@ -71,7 +72,7 @@ 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 + * 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.