[lesnik512]

Follow-up to #726, which fixed #719 by copying the finalizer queue at the start of every close. The copy was hard to read and cost about 40-50 ns per close with cached items. This PR puts cache.py back close to its 4.2.0 shape and changes how a close walks the queue: it pops items newest first until the queue is empty.

Behavior:

• A cached instance that finishes building on another thread while a close runs is finalized by that close. Its item is appended to the queue, and the loop pops it. Since fix: finalize a cached instance built during a close at the next close #726 it waited for the next close. One that finishes after the close returns is still finalized by the next close.
• An async finalizer under close_sync() still goes back on the front of the queue for a later close_async().
• A cancelled or interrupted close puts the item it popped back on the queue, so the documented cancelled-close behavior holds: everything not finalized, the interrupted item included, stays queued. close_sync() also puts back the async-finalizer items it had already set aside. Before this PR, close_sync() got this for free because it never mutated the queue mid-loop.
• Teardown order and FinalizerError aggregation are unchanged.

Tests:

• The three race tests from fix: finalize a cached instance built during a close at the next close #726 now expect the racing build to be finalized by the same close. They fail on main with (['Y'], []) == (['Y'], ['X']) and DID NOT RAISE FinalizerError.
• New: test_interrupted_close_sync_keeps_unfinalized_items_queued, the sync twin of the cancelled close_async() test. A KeyboardInterrupt in a sync finalizer, with a newer async-finalizer item already set aside, leaves both queued, and a later close_async() finalizes all three in order. It passes on main and pins what the pop loop must keep.
• Full suite: 1099 passed, 100% coverage.

Docs: the lifecycle page's "Closing does not wait for resolves running on other threads" paragraph and the two close docstrings now say a build that finishes during a close is finalized by it.

Guard benchmarks, 3 interleaved rounds, medians:

scenario	4.2.0	main (copy)	this PR
G7b, 1 cached item per cycle	1.110-1.117 µs	1.154-1.168 µs	1.070-1.075 µs
G7, 100 request cycles	167.6-169.3 µs	173.1-175.1 µs	161.1-164.9 µs
G13, 10 finalizers	6.75-6.88 µs	6.83 µs	6.92-7.00 µs
G13b, 100 cycles × 10 items, async	748-757 µs	752-757 µs	761-780 µs

The common case, one or a few cached items per request, is faster than both 4.2.0 and main. With 10 items per request it is 1-3% slower than 4.2.0, because it pops each item instead of iterating.

[github-actions]

Benchmark

Details

Benchmark suite	Current: d337565	Previous: 39b91a1	Ratio
benchmarks/test_guard_by_type.py::test_g16_resolve_by_type	3165752.133637998 iter/sec (stddev: 1.1644942050834567e-8)	4999244.864071952 iter/sec (stddev: 1.980734361769726e-8)	1.58
benchmarks/test_guard_by_type.py::test_g17_resolve_by_type_large_registry	3307268.2014180776 iter/sec (stddev: 1.0212120365258875e-8)	4962885.06404828 iter/sec (stddev: 2.334752512989382e-8)	1.50
benchmarks/test_guard_cold.py::test_g8_cold_first_resolve	14979.418629201416 iter/sec (stddev: 0.00005756360640852104)	20867.957702284 iter/sec (stddev: 0.000046250339898333545)	1.39
benchmarks/test_guard_cold.py::test_g8b_cold_first_resolve_cached	11235.245202440132 iter/sec (stddev: 0.00017933727709220547)	18231.298112280736 iter/sec (stddev: 0.00018278666932784236)	1.62
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[1]	386.9599995121513 iter/sec (stddev: 0.00008202256478147653)	664.3516247305504 iter/sec (stddev: 0.00004619173819970973)	1.72
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[2]	461.7668690867955 iter/sec (stddev: 0.00024225405251556003)	639.6911708326553 iter/sec (stddev: 0.00015795813490786226)	1.39
benchmarks/test_guard_concurrency.py::test_g14_concurrent_cached_hit[4]	441.49959050247327 iter/sec (stddev: 0.00010645286670854151)	600.4701935079781 iter/sec (stddev: 0.00011200131082821)	1.36
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[1]	13544.476675192294 iter/sec (stddev: 0.000009411914694484994)	19763.3243097465 iter/sec (stddev: 0.000005991560777129713)	1.46
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[2]	6519.820389798216 iter/sec (stddev: 0.000022101293083622422)	9344.945778277157 iter/sec (stddev: 0.000013938352893437438)	1.43
benchmarks/test_guard_concurrency.py::test_g15_concurrent_first_resolve[4]	3420.429145850076 iter/sec (stddev: 0.0000397915277343421)	5034.094875818457 iter/sec (stddev: 0.000025286259846105463)	1.47
benchmarks/test_guard_concurrency.py::test_g15b_concurrent_first_resolve_sibling_children[1]	10225.146651938254 iter/sec (stddev: 0.000011027250585870611)	15277.280735843626 iter/sec (stddev: 0.00000783901623831582)	1.49
benchmarks/test_guard_concurrency.py::test_g15b_concurrent_first_resolve_sibling_children[2]	4326.940447082379 iter/sec (stddev: 0.00002514959200698666)	6460.799395789914 iter/sec (stddev: 0.000015804041351451427)	1.49
benchmarks/test_guard_concurrency.py::test_g15b_concurrent_first_resolve_sibling_children[4]	2032.131762613718 iter/sec (stddev: 0.000050851149442533955)	2840.497676022588 iter/sec (stddev: 0.00009220723533385155)	1.40
benchmarks/test_guard_concurrency.py::test_g15c_worker_pool_floor_control[1]	41198.95835251273 iter/sec (stddev: 0.000005703787964685512)	54665.2708804148 iter/sec (stddev: 0.00000293441505411239)	1.33
benchmarks/test_guard_concurrency.py::test_g15c_worker_pool_floor_control[2]	14010.244524149262 iter/sec (stddev: 0.000015278901949636965)	21065.152409805036 iter/sec (stddev: 0.000010598773032420739)	1.50
benchmarks/test_guard_concurrency.py::test_g15c_worker_pool_floor_control[4]	5871.287004227655 iter/sec (stddev: 0.000032825885818786634)	8830.198808996982 iter/sec (stddev: 0.00002062976445345776)	1.50
benchmarks/test_guard_lifecycle.py::test_g6_build_child_container	1588699.2643985436 iter/sec (stddev: 5.4230813462120934e-8)	2168877.9461705256 iter/sec (stddev: 2.2011321208934898e-8)	1.37
benchmarks/test_guard_lifecycle.py::test_g6b_build_child_container_auto_scope	1714020.334959547 iter/sec (stddev: 3.2217315869877e-8)	2382222.899831129 iter/sec (stddev: 1.1417635227932936e-8)	1.39
benchmarks/test_guard_lifecycle.py::test_g7_request_lifecycle_batch	3273.2826088864736 iter/sec (stddev: 0.000011462357950014567)	4164.441741148263 iter/sec (stddev: 0.000023515551091265132)	1.27
benchmarks/test_guard_lifecycle.py::test_g7c_event_loop_floor_control	57472.447554071325 iter/sec (stddev: 0.000044818979219982346)	74573.11199710562 iter/sec (stddev: 0.0000017987109289637315)	1.30
benchmarks/test_guard_lifecycle.py::test_g7b_request_cycle_sync	426261.1116146593 iter/sec (stddev: 7.539694923028048e-8)	527329.8725730837 iter/sec (stddev: 8.617792754542178e-8)	1.24
benchmarks/test_guard_lifecycle.py::test_g13_teardown_at_scale	63579.53452906972 iter/sec (stddev: 0.0000015207530977313781)	93010.72110238169 iter/sec (stddev: 0.0000010571227925657647)	1.46
benchmarks/test_guard_lifecycle.py::test_g13b_teardown_at_scale_async_no_finalizers	593.121946954321 iter/sec (stddev: 0.0010546267643382358)	815.9729015861969 iter/sec (stddev: 0.0013615627486766862)	1.38
benchmarks/test_guard_resolve.py::test_g1_transient_resolve	2137759.9215401555 iter/sec (stddev: 2.323232023203666e-8)	3062880.0076726153 iter/sec (stddev: 2.3554470652001465e-8)	1.43
benchmarks/test_guard_resolve.py::test_g2_cached_resolve	3580449.513980562 iter/sec (stddev: 8.822140457321009e-9)	5019185.837870243 iter/sec (stddev: 7.718348624032926e-9)	1.40
benchmarks/test_guard_resolve.py::test_g3_deep_chain	824703.5834916317 iter/sec (stddev: 4.999808722446682e-8)	1155541.1215641191 iter/sec (stddev: 4.1438433664222e-8)	1.40
benchmarks/test_guard_resolve.py::test_g4_wide_resolve	478892.30677099247 iter/sec (stddev: 3.98263654215346e-7)	619796.1527642523 iter/sec (stddev: 3.8040978456143346e-7)	1.29
benchmarks/test_guard_resolve.py::test_g5_cross_scope	1968263.619009899 iter/sec (stddev: 2.6205749633839813e-8)	2738224.505116492 iter/sec (stddev: 2.605572283931181e-8)	1.39
benchmarks/test_guard_resolve.py::test_g9_context_resolve	1384141.8590379173 iter/sec (stddev: 1.4038077926551953e-7)	2117276.809390873 iter/sec (stddev: 1.4582534055509644e-7)	1.53
benchmarks/test_guard_resolve.py::test_g12_override_active_resolve	829684.8632903465 iter/sec (stddev: 3.580336137663037e-8)	1177440.7994509386 iter/sec (stddev: 3.498992186141233e-8)	1.42
benchmarks/test_guard_resolve.py::test_g18_alias_hop	3587343.307557385 iter/sec (stddev: 1.1035597554946676e-8)	5051929.796766053 iter/sec (stddev: 5.463976457985513e-9)	1.41
benchmarks/test_guard_validate.py::test_g10_validate_deep_chain	35235.21431748702 iter/sec (stddev: 0.000020489783999211203)	54412.738907088235 iter/sec (stddev: 0.000014540776108788054)	1.54
benchmarks/test_guard_validate.py::test_g11_validate_wide	21217.55181234026 iter/sec (stddev: 0.000025332843029356488)	31462.115947147005 iter/sec (stddev: 0.00001927071767546512)	1.48

This comment was automatically generated by workflow using github-action-benchmark.