#31078: improve docs for config var abstraction
--------------------------+------------------------------------
Reporter: catalyst | Owner: nickm
Type: enhancement | Status: assigned
Priority: Medium | Milestone: Tor: 0.4.2.x-final
Component: Core Tor/Tor | Version:
Severity: Normal | Resolution:
Keywords: 042-should | Actual Points:
Parent ID: #29211 | Points: 2
Reviewer: | Sponsor: Sponsor31-can
--------------------------+------------------------------------
Comment (by nickm):
I've been trying to figure out which concrete steps would help the most
here. I think that clarity on the final API, and clarity on the words
"type" and "variable" are the biggest requests.
-----
The '''variables''' here might also be called "options" or "fields" or
"settables" or "configurables". Each one is a C value that maps to a
named option in a configuration or state file. I'm okay renaming these
from "variables" to one of the other things if we have a good "other
thing" to rename them to.
In the C code, each "variable" is a member of a some configuration object.
Each module can have its own configuration object. These objects are
registered at startup with a central "configuration manager", which is
responsible for parsing configurations, telling modules about new
configurations, and so on.
The implementation for these variables comes in 4 layers:
1. The lowest level is the "typed_var" layer, which views the C value as a
void *, and views the configuration value as a string. This is the layer
that knows how to encode, decode, copy, etc. The set of functions that
does the encoding/decoding/copying/etc defines the '''type''' of the
variable. "Codec" or "manipulator" might be another good name for this.
2. One level higher is the "struct_member" layer, which views the C value
as stored at a given offset within a structure.
3. One level higher is the "config_var" layer. This layer knows the
_names_ of different configuration values, and knows that some values may
be obsolete, deprecated.
4. At the highest level is the "managed_var" layer. It is an internal
object used by the configmgr code to keep track of which variables
correspond to which objects.
Each layer is consumed by the layer above it. Additionally, layer 1 is
the layer at which you can declare new "types" (codecs? manipulators?).
Layer 3 is the layer at which modules declare their variables.
-----
Here's what I have in mind for the final artchitecture.
There are three main users of the configuration system.
1. There is '''type''' code, which wants to declare new "types" (codecs?
manipulators?) that modules can use for their data. (This kind of user
#includes var_type_def_st.h, and defines a new var_type_def_t.)
2. There are '''modules''' which want to declare configuration or state
variables, and learn what their values are, and learn when those values
change. They declare a structure for their configuration and/or state,
and a table of config_var_t mapping configuration/state variables to the
fields of that structure. They expose this information via the subsystem
API. (There is not yet a separate example of this; all users of
get_options() are currently taking this role, as is the variable-
declaration part of config.c.)
3. There is the '''application''' code, which wants to load, reload,
change, or dump configuration values, and make sure that the right modules
find out about it. (This kind of user uses the "confmgr.h" API to combine
the mapping tables from multiple modules, and to manipulate the correct
fields in their configuration/state objects.)
--
Ticket URL: <https://trac.torproject.org/projects/tor/ticket/31078#comment:7>
Tor Bug Tracker & Wiki <https://trac.torproject.org/>
The Tor Project: anonymity online