New public APIs

Two new Python APIs are added to thegcmodule:

• gc.set_mode(mode)sets the current mode of operation (either “serial” or “threaded” ). If setting to “serial” and the current mode is “threaded”, then the function also waits for the GC thread to end.
• gc.get_mode()returns the current mode of operation.

It is allowed to switch back and forth between modes of operation.

Intended use

Given the per-process nature of the switch and its repercussions on semantics of all finalization callbacks, it is recommended that it is set at the beginning of an application’s code (and/or in initializers for child processes e.g. when usingmultiprocessing). Library functions should probably not mess with this setting, just as they shouldn’t call gc.enableorgc.disable,but there’s nothing to prevent them from doing so.

Non-goals

This PEP does not address reentrancy issues with other kinds of asynchronous code execution (for example signal handlers registered with thesignalmodule). The author believes that the overwhelming majority of painful reentrancy issues occur with finalizers. Most of the time, signal handlers are able to set a single flag and/or wake up a file descriptor for the main program to notice. As for those signal handlers which raise an exception, theyhaveto execute in-thread.

This PEP also does not change the execution of finalization callbacks when they are called as part of regular reference counting, i.e. when releasing a visible reference drops an object’s reference count to zero. Since such execution happens at deterministic points in code, it is usually not a problem.

gcmodule

An internal flaggc_is_threadedis added, telling whether GC is serial or threaded.

An internal structuregc_mutexis added to avoid two GC runs at once:

staticstruct{
PyThread_type_locklock;/*takenwhencollecting*/
PyThreadState*owner;/*whicheverthreadiscurrentlycollecting
(NULLifnocollectionistakingplace)*/
}gc_mutex;

An internal structuregc_threadis added to handle synchronization with the GC thread:

staticstruct{
PyThread_type_lockwakeup;/*actsasanevent
towakeuptheGCthread*/
intcollection_requested;/*non-zeroifcollectionrequested*/
PyThread_type_lockdone;/*actsasaneventsignaling
theGCthreadhasexited*/
}gc_thread;

threadingmodule

Two private functions are added to thethreadingmodule:

• threading._ensure_dummy_thread(name)creates and registers aThread instance for the current thread with the givenname,and returns it.
• threading._remove_dummy_thread(thread)removes the giventhread (as returned by_ensure_dummy_thread) from the threading module’s internal state.

The purpose of these two functions is to improve debugging and introspection by lettingthreading.current_thread()return a more meaningfully-named object when called inside a finalization callback in the GC thread.

Pseudo-code

Here is a proposed pseudo-code for the main primitives, public and internal, required for implementing this PEP. All of them will be implemented in C and live inside thegcmodule, unless otherwise noted:

defcollect_with_callback(generation):
"""
Collect up to the given *generation*.
"""
# Same code as currently (see collect_with_callback() in gcmodule.c)


defcollect_generations():
"""
Collect as many generations as desired by the heuristic.
"""
# Same code as currently (see collect_generations() in gcmodule.c)


deflock_and_collect(generation=-1):
"""
Perform a collection with thread safety.
"""
me=PyThreadState_GET()
ifgc_mutex.owner==me:
# reentrant GC collection request, bail out
return
Py_BEGIN_ALLOW_THREADS
gc_mutex.lock.acquire()
Py_END_ALLOW_THREADS
gc_mutex.owner=me
try:
ifgeneration>=0:
returncollect_with_callback(generation)
else:
returncollect_generations()
finally:
gc_mutex.owner=NULL
gc_mutex.lock.release()


defschedule_gc_request():
"""
Ask the GC thread to run an implicit collection.
"""
assertgc_is_threaded==True
# Note this is extremely fast if a collection is already requested
ifgc_thread.collection_requested==False:
gc_thread.collection_requested=True
gc_thread.wakeup.release()


defis_implicit_gc_desired():
"""
Whether an implicit GC run is currently desired based on allocation
stats. Return a generation number, or -1 if none desired.
"""
# Same heuristic as currently (see _PyObject_GC_Alloc in gcmodule.c)


defPyGC_Malloc():
"""
Allocate a GC-enabled object.
"""
# Update allocation statistics (same code as currently, omitted for brevity)
ifis_implicit_gc_desired():
ifgc_is_threaded:
schedule_gc_request()
else:
lock_and_collect()
# Go ahead with allocation (same code as currently, omitted for brevity)


defgc_thread(interp_state):
"""
Dedicated loop for threaded GC.
"""
# Init Python thread state (omitted, see t_bootstrap in _threadmodule.c)
# Optional: init thread in Python threading module, for better introspection
me=threading._ensure_dummy_thread(name="GC thread")

whilegc_is_threaded==True:
Py_BEGIN_ALLOW_THREADS
gc_thread.wakeup.acquire()
Py_END_ALLOW_THREADS
ifgc_thread.collection_requested!=0:
gc_thread.collection_requested=0
lock_and_collect(generation=-1)

threading._remove_dummy_thread(me)
# Signal we're exiting
gc_thread.done.release()
# Free Python thread state (omitted)


defgc.set_mode(mode):
"""
Set current GC mode. This is a process-global setting.
"""
ifmode=="threaded":
ifnotgc_is_threaded==False:
# Launch thread
gc_thread.done.acquire(block=False)# should not fail
gc_is_threaded=True
PyThread_start_new_thread(gc_thread)
elifmode=="serial":
ifgc_is_threaded==True:
# Wake up thread, asking it to end
gc_is_threaded=False
gc_thread.wakeup.release()
# Wait for thread exit
Py_BEGIN_ALLOW_THREADS
gc_thread.done.acquire()
Py_END_ALLOW_THREADS
gc_thread.done.release()
else:
raiseValueError("unsupported mode%r"%(mode,))


defgc.get_mode(mode):
"""
Get current GC mode.
"""
return"threaded"ifgc_is_threadedelse"serial"


defgc.collect(generation=2):
"""
Schedule collection of the given generation and wait for it to
finish.
"""
returnlock_and_collect(generation)

Default mode

One may wonder whether the default mode should simply be changed to “threaded”. For multi-threaded applications, it would probably not be a problem: those applications must already be prepared for finalization handlers to be run in arbitrary threads. In single-thread applications, however, it is currently guaranteed that finalizers will always be called in the main thread. Breaking this property may induce subtle behaviour changes or bugs, for example if finalizers rely on some thread-local values.

Another problem is when a program usesfork()for concurrency. Callingfork()from a single-threaded program is safe, but it’s fragile (to say the least) if the program is multi-threaded.

Explicit collections

One may ask whether explicit collections should also be delegated to the background thread. The answer is it doesn’t really matter: since gc.collectandPyGC_Collectactuallywaitfor the collection to end (breaking this property would break compatibility), delegating the actual work to a background thread wouldn’t ease synchronization with the thread requesting an explicit collection.

In the end, this PEP choses the behaviour that seems simpler to implement based on the pseudo-code above.

Impact on memory use

The “threaded” mode incurs a slight delay in implicit collections compared to the default “serial” mode. This obviously may change the memory profile of certain applications. By how much remains to be measured in real-world use, but we expect the impact to remain minor and bearable. First because implicit collections are based on aheuristicwhose effect does not result in deterministic visible behaviour anyway. Second because the GC deals with reference cycles while many objects are reclaimed immediately when their last visible reference disappears.

Impact on CPU consumption

The pseudo-code above adds two lock operations for each implicit collection request in “threaded” mode: one in the thread making the request (a releasecall) and one in the GC thread (anacquirecall). It also adds two other lock operations, regardless of the current mode, around each actual collection.

We expect the cost of those lock operations to be very small, on modern systems, compared to the actual cost of crawling through the chains of pointers during the collection itself ( “pointer chasing” being one of the hardest workloads on modern CPUs, as it lends itself poorly to speculation and superscalar execution).

Actual measurements on worst-case mini-benchmarks may help provide reassuring upper bounds.

Impact on GC pauses

While this PEP does not concern itself with GC pauses, there is a practical chance that releasing the GIL at some point during an implicit collection (for example by virtue of executing a pure Python finalizer) will allow application code to run in-between, lowering thevisibleGC pause time for some applications.

If this PEP is accepted, future work may try to better realize this potential by speculatively releasing the GIL during collections, though it is unclear how doable that is.