Adding a library
A library is registered as one of two kinds of pool.
Counted pools
Anything with an imperative thread-count setter:
function __init__()
NestedThreading.register_counted_pool!(
MyLib.get_threads, MyLib.set_threads; name = :mylib
)
endThe pool then participates in the refcounted snapshot/restore, so it is safe under concurrency for free.
A boolean toggle is a counted pool too. Map it onto a count rather than reaching for a guard — this is how the NFFT extension is written:
_full() = max(2, NestedThreading.capacity())
_get_threads() = MyLib.threading_enabled[] ? _full() : 1
_set_threads(n) = (MyLib.threading_enabled[] = n >= _full())
NestedThreading.register_counted_pool!(_get_threads, _set_threads; name = :mylib)The threshold is capacity() rather than 1 because a library with no partial control should be off whenever anything is restricted; see Composition rules.
The getter and setter must round-trip: set(get()) has to be a no-op, because that is exactly what the last scope exit does. With a bare capacity() threshold that breaks in a single-threaded session, where capacity() == 1 makes "restricted to 1" and "full throttle" the same number — the getter maps false to 1 and the setter maps 1 back to true, so every budget scope silently enables a library the user had switched off and never restores it. max(2, capacity()) is identical everywhere else and costs only that with_full_threads will not enable the library on a machine with one thread, where its threaded path has no workers anyway.
Guarded pools
Only for libraries whose sole control is a scoped context manager with no imperative form — Polyester's disable_polyester_threads is the motivating case:
# `guard` is only ever called when a restriction is in force; `budget` is the applied
# thread budget, provided in case the library has a proportional control.
_guard(f, budget::Int) = MyLib.without_threads(f)
NestedThreading.register_guarded_pool!(_guard; name = :mylib)Switching the library fully off is usually right even when a partial limit is available; see Composition rules for the measurements behind that.
A guard of the form prev = X[]; X[] = new; try f() finally X[] = prev end reintroduces exactly the interleaving bug described in Composition rules — two concurrent guards will capture each other's temporary value. If the library has an imperative setter, register it as a counted pool instead and let the registry do the bookkeeping. Polyester is safe because disable_polyester_threads reserves worker threads rather than saving and restoring a count.
Quiesce pools
A separate question from "how many threads may this library use": does it let go of Julia's threads once its own parallel region has ended? Polyester's workers do not — they are Julia tasks that spin for about 2^20 pause() iterations before parking, and a Threads.@threads region opened during that window waits for them instead of running on them. On 8 threads with an empty loop body that is 5.7 µs against 219.9 µs.
Register a hook that makes the library release them, and this package calls it before every region it opens on Julia's own scheduler:
NestedThreading.register_quiesce_pool!(MyLib.park_workers!; name = :mylib)The hook takes no arguments, has no paired restore, and must be cheap — the Polyester one is ThreadingUtilities.sleep_all_tasks() at about 0.1 µs, and re-waking the workers for the next @batch costs nothing measurable. A library whose workers park themselves promptly needs no quiesce pool at all.
Doing it from an extension
Registration belongs in __init__ so that it happens exactly once, when both your package and the library are loaded. If you own neither package, a small extension in your own package works the same way:
[weakdeps]
MyLib = "..."
[extensions]
MyPkgMyLibExt = "MyLib"module MyPkgMyLibExt
import MyLib, NestedThreading
__init__() = NestedThreading.register_counted_pool!(
MyLib.get_threads, MyLib.set_threads; name = :mylib
)
endRegistering the same name twice is a no-op, so duplicate extensions across packages are harmless.