1#######################################
2# C Globals and CPython Runtime State.
3
4CPython's C code makes extensive use of global variables (whether static
5globals or static locals).  Each such variable falls into one of several
6categories:
7
8* strictly const data
9* used exclusively in main or in the REPL
10* process-global state (e.g. managing process-level resources
11  like signals and file descriptors)
12* Python "global" runtime state
13* per-interpreter runtime state
14
15The last one can be a problem as soon as anyone creates a second
16interpreter (AKA "subinterpreter") in a process.  It is definitely a
17problem under subinterpreters if they are no longer sharing the GIL,
18since the GIL protects us from a lot of race conditions.  Keep in mind
19that ultimately *all* objects (PyObject) should be treated as
20per-interpreter state.  This includes "static types", freelists,
21_PyIdentifier, and singletons.  Take that in for a second.  It has
22significant implications on where we use static variables!
23
24Be aware that module-global state (stored in C statics) is a kind of
25per-interpreter state.  There have been efforts across many years, and
26still going, to provide extension module authors mechanisms to store
27that state safely (see PEPs 3121, 489, etc.).
28
29(Note that there has been discussion around support for running multiple
30Python runtimes in the same process.  That would ends up with the same
31problems, relative to static variables, that subinterpreters have.)
32
33Historically we have been bad at keeping per-interpreter state out of
34static variables, mostly because until recently subinterpreters were
35not widely used nor even factored in to solutions.  However, the
36feature is growing in popularity and use in the community.
37
38Mandate: "Eliminate use of static variables for per-interpreter state."
39
40The "c-statics.py" script in this directory, along with its accompanying
41data files, are part of the effort to resolve existing problems with
42our use of static variables and to prevent future problems.
43
44#-------------------------
45## statics for actually-global state (and runtime state consolidation)
46
47In general, holding any kind of state in static variables
48increases maintenance burden and increases the complexity of code (e.g.
49we use TSS to identify the active thread state).  So it is a good idea
50to avoid using statics for state even if for the "global" runtime or
51for process-global state.
52
53Relative to maintenance burden, one problem is where the runtime
54state is spread throughout the codebase in dozens of individual
55globals.  Unlike the other globals, the runtime state represents a set
56of values that are constantly shifting in a complex way.  When they are
57spread out it's harder to get a clear picture of what the runtime
58involves.  Furthermore, when they are spread out it complicates efforts
59that change the runtime.
60
61Consequently, the globals for Python's runtime state have been
62consolidated under a single top-level _PyRuntime global. No new globals
63should be added for runtime state.  Instead, they should be added to
64_PyRuntimeState or one of its sub-structs.  The tools in this directory
65are run as part of the test suite to ensure that no new globals have
66been added.  The script can be run manually as well:
67
68  ./python Lib/test/test_c_statics/c-statics.py check
69
70If it reports any globals then they should be resolved.  If the globals
71are runtime state then they should be folded into _PyRuntimeState.
72Otherwise they should be marked as ignored.
73