nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-24 12:23:32 +01:00
Code Issues Packages Projects Releases Wiki Activity

Initialization documents: incorporate feedback from review.

Browse Source 
(Thanks, Taylor!)
This commit is contained in:
Nick Mathewson 2019-11-15 09:00:54 -05:00
parent 2d508f8fa5
commit 8746fedce4
2 changed files with 14 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
src/lib/subsys/initialization.dox
View File

@ -9,7 +9,7 @@
Tor has a single entry point: tor_run_main() in main.c. All the ways of 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(). 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 returning: not by calling abort() or exit(). Before it returns, it calls
tor_cleanup() in shutdown.c. 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 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 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 2. Second, we parse the command line and our configuration, and configure
systems that depend on our configuration or state. This configuration systems that depend on our configuration or state. This configuration
@ -33,16 +33,16 @@ Conceptually, there are several stages in running Tor.
running. 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 > abort() or exit(), but only when crashing due to a bug, or when forking to
> run as a daemon. > 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 > "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 > own name. I'd like to refactor them, but before I do so, there is some
> slight reorganization that needs to happen. Notably, the > slight reorganization that needs to happen. Notably, the
> nt_service_parse_options() call ought logically to be later in our > 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 @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 can be initialized, shut down, managed, and configured somewhat independently
of the rest of the program. of the rest of the program.
To define a subsystem, we declare a `const` instance of subsys_fns_t, The subsys_fns_t type describes a subsystem and a set of functions that
describing the subsystem and a set of functions that initialize it, initialize it, desconstruct it, and so on. To define a subsystem, we declare
deconstruct it, and so on. See the documentation for subsys_fns_t for a full a `const` instance of subsys_fns_t. See the documentation for subsys_fns_t
list of these functions. for a full list of these functions.
After defining a subsytem, it must be inserted in subsystem_list.c. At that 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 point, table-driven mechanisms in subsysmgr.c will invoke its functions when

9
src/lib/subsys/subsys.h
View File

@ -23,10 +23,11 @@ struct config_format_t;
* All callbacks are optional -- if a callback is set to NULL, the subsystem * All callbacks are optional -- if a callback is set to NULL, the subsystem
* manager will treat it as a no-op. * manager will treat it as a no-op.
* *
* You should use c99 named-field initializers with this structure: we * You should use c99 named-field initializers with this structure, for
* will be adding more fields, often in the middle of the structure. * 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. * shutdown in Tor.
* *
* To make a new subsystem, you declare a const instance of this type, and * 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. * 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. * set of messages that this subsystem may publish, and may subscribe to.
* *
* See pubsub_macros.h for more information, and for examples. * See pubsub_macros.h for more information, and for examples.