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
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

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
* 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.