resource-singleflight 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 El Fenomeno
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,161 @@
1
+ Metadata-Version: 2.4
2
+ Name: resource-singleflight
3
+ Version: 0.1.0
4
+ Summary: A Python library that runs at most one worker per key and hands every caller the same joinable Future.
5
+ Author: El Fenomeno
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/elfenomenokim/resource-singleflight
8
+ Project-URL: Repository, https://github.com/elfenomenokim/resource-singleflight
9
+ Project-URL: Issues, https://github.com/elfenomenokim/resource-singleflight/issues
10
+ Keywords: singleflight,thundering-herd,concurrency,future,cache,python,deduplication
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Dynamic: license-file
21
+
22
+ <div align="center">
23
+
24
+ <img src="https://raw.githubusercontent.com/elfenomenokim/resource-singleflight/main/docs/logo.svg" width="96" height="96" alt="resource-singleflight: many callers, one worker">
25
+
26
+ # resource-singleflight
27
+
28
+ A Python library that runs at most one worker per key and hands every caller the same joinable `Future`.
29
+
30
+ [한국어](README.ko.md) · Python 3.9+
31
+
32
+ [![license](https://img.shields.io/github/license/elfenomenokim/resource-singleflight)](LICENSE)
33
+
34
+ [Install](#install) · [Quick start](#quick-start) · [Why](#why) · [Reference](#reference)
35
+
36
+ </div>
37
+
38
+ 50 threads asking for the same key produced 1 work call in 4.6 ms, and a cached submit costs 3.3 µs. Both values are saved in `docs/bench/coalesce.json`.
39
+
40
+ A refresh loop has a familiar problem: ten panes wake at the same second and each starts the same expensive read. This coordinator lets the first one work and gives the other nine the same `Future` to wait on. When a read has to be replaced, the old one keeps running but cannot publish its result any more, so a slow answer never overwrites a fresh one.
41
+
42
+ Standard library only. One file, no threads of its own beyond the workers it starts.
43
+
44
+ ## Install
45
+
46
+ ```sh
47
+ pip install resource-singleflight
48
+ ```
49
+
50
+ Python 3.9+. No dependencies. Verified on macOS arm64 with Python 3.12.
51
+
52
+ ## Quick start
53
+
54
+ ```python
55
+ from resource_singleflight import ResourceCoordinator
56
+
57
+ coordinator = ResourceCoordinator(thread_name_prefix="refresh")
58
+
59
+ def read_expensive() -> str:
60
+ return "value"
61
+
62
+ first = coordinator.submit("key", read_expensive, cache_ttl=30.0)
63
+ second = coordinator.submit("key", read_expensive, cache_ttl=30.0)
64
+ print(first is second) # True: one worker, one Future
65
+ print(first.result(1)) # 'value'
66
+ ```
67
+
68
+ Ten callers, one work call. The work function blocks until every caller has asked, which is the case coalescing is for:
69
+
70
+ ```python
71
+ import threading
72
+ from resource_singleflight import ResourceCoordinator
73
+
74
+ coordinator = ResourceCoordinator()
75
+ started, release = threading.Event(), threading.Event()
76
+ calls = []
77
+
78
+ def read():
79
+ calls.append(1)
80
+ started.set()
81
+ release.wait(5)
82
+ return "value"
83
+
84
+ futures = []
85
+ target = lambda: futures.append(coordinator.submit("key", read, cache_ttl=30.0))
86
+ threads = [threading.Thread(target=target) for _ in range(10)]
87
+ for thread in threads:
88
+ thread.start()
89
+ started.wait(2)
90
+ release.set()
91
+ for thread in threads:
92
+ thread.join(5)
93
+
94
+ print(len(calls)) # 1
95
+ print({f.result(2) for f in futures}) # {'value'}
96
+ ```
97
+
98
+ A forced refresh replaces the in-flight read, and the superseded `Future` resolves from the replacement instead of hanging:
99
+
100
+ ```python
101
+ old = coordinator.submit("key", slow_read, cache_ttl=30.0)
102
+ new = coordinator.submit("key", fast_read, cache_ttl=30.0, force=True)
103
+ print(old.result(1)) # the replacement's result, not the stale one
104
+ ```
105
+
106
+ ## Why
107
+
108
+ Coalescing requests sounds like a lock around a dictionary. The parts that bite are the edges:
109
+
110
+ - **A detached read must not publish.** If a refresh was replaced, its result is no longer wanted. The coordinator bumps a generation when it replaces work, and a worker may only publish while its generation is current. A superseded worker that finishes late resolves nothing and caches nothing.
111
+ - **Nobody should hang.** Cancelling a `Future` someone is waiting on would raise `CancelledError` in a caller that did nothing wrong. Instead the issued `Future` is resolved from the replacement, so every caller gets an answer.
112
+ - **Work in progress stays owned.** Arbitrary Python code already inside a syscall cannot be stopped. The coordinator keeps every started worker until it exits, and `wait_for_idle()` reports when the last one is done. A shutdown can then wait instead of hoping.
113
+ - **Cache and publication agree.** The generation check and the cache write happen under the same lock, so a replacement lands either wholly before a publication or wholly after it.
114
+
115
+ ## Reference
116
+
117
+ ### `ResourceCoordinator(thread_name_prefix="singleflight")`
118
+
119
+ | Method | Behaviour |
120
+ | --- | --- |
121
+ | `submit(key, function, *, cache_ttl=0.0, force=False)` | Joins the in-flight `Future` for `key`, or serves a cached value, or starts one worker. `force=True` replaces the current generation. |
122
+ | `invalidate(key)` | Drops the cached value and retires the joinable flight, retaining ownership of any running worker. |
123
+ | `clear()` | Drops every cached value and cancels every joinable flight, keeping ownership of running workers. |
124
+ | `wait_for_idle(timeout=None)` | Waits until every worker this coordinator started has exited. Returns `False` on timeout. |
125
+
126
+ `key` is any hashable. `function` takes no arguments; close over what it needs.
127
+
128
+ ### `env_flag(names, *, default=True)`
129
+
130
+ Reads a boolean switch from the first of `names` that is set in the environment. Unset keeps `default`. Any value outside `0`, `false`, `no`, `off` keeps it enabled, so a typo never silently disables coordination.
131
+
132
+ ## Numbers
133
+
134
+ Measured on 2026-11-19 on macOS arm64 (M5 Pro), Python 3.12.8, from `docs/bench/coalesce.json`.
135
+
136
+ | What | Result |
137
+ | --- | --- |
138
+ | 50 threads submitting one key, one 20 ms work item | 1 work call, 4.6 ms total |
139
+ | Cached submit, result already available | 3.3 µs per submit |
140
+
141
+ ## Limits
142
+
143
+ - One process. There is no cross-process coordination; two processes each run their own worker.
144
+ - Only overlapping submissions coalesce. If the work finishes before the next caller submits, that caller starts its own call, or is served the cache when `cache_ttl` is above zero. Ten threads submitting a 5 µs function can produce several calls; the result is still correct.
145
+ - No persistence. The cache is an in-memory dict with a monotonic deadline per key.
146
+ - A worker cannot be interrupted. `force` redirects its result; it does not stop it. Use `wait_for_idle()` when shutdown must be bounded.
147
+ - Linux and Windows have not been exercised.
148
+
149
+ ## FAQ
150
+
151
+ **Why not `functools.lru_cache`?** A cache has no in-flight state, so callers of a cold key each start their own read. This type also owns replacement, which a plain cache does not express.
152
+
153
+ **Why a `Future` and not a lock plus a dict?** A lock says "wait". A `Future` carries the result, the exception and the cancellation state, and a caller can choose its own timeout.
154
+
155
+ ## Contributing
156
+
157
+ Bug reports and patches are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks and the fixture each behaviour change needs.
158
+
159
+ ## Licence
160
+
161
+ MIT, in [LICENSE](LICENSE).
@@ -0,0 +1,140 @@
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/elfenomenokim/resource-singleflight/main/docs/logo.svg" width="96" height="96" alt="resource-singleflight: many callers, one worker">
4
+
5
+ # resource-singleflight
6
+
7
+ A Python library that runs at most one worker per key and hands every caller the same joinable `Future`.
8
+
9
+ [한국어](README.ko.md) · Python 3.9+
10
+
11
+ [![license](https://img.shields.io/github/license/elfenomenokim/resource-singleflight)](LICENSE)
12
+
13
+ [Install](#install) · [Quick start](#quick-start) · [Why](#why) · [Reference](#reference)
14
+
15
+ </div>
16
+
17
+ 50 threads asking for the same key produced 1 work call in 4.6 ms, and a cached submit costs 3.3 µs. Both values are saved in `docs/bench/coalesce.json`.
18
+
19
+ A refresh loop has a familiar problem: ten panes wake at the same second and each starts the same expensive read. This coordinator lets the first one work and gives the other nine the same `Future` to wait on. When a read has to be replaced, the old one keeps running but cannot publish its result any more, so a slow answer never overwrites a fresh one.
20
+
21
+ Standard library only. One file, no threads of its own beyond the workers it starts.
22
+
23
+ ## Install
24
+
25
+ ```sh
26
+ pip install resource-singleflight
27
+ ```
28
+
29
+ Python 3.9+. No dependencies. Verified on macOS arm64 with Python 3.12.
30
+
31
+ ## Quick start
32
+
33
+ ```python
34
+ from resource_singleflight import ResourceCoordinator
35
+
36
+ coordinator = ResourceCoordinator(thread_name_prefix="refresh")
37
+
38
+ def read_expensive() -> str:
39
+ return "value"
40
+
41
+ first = coordinator.submit("key", read_expensive, cache_ttl=30.0)
42
+ second = coordinator.submit("key", read_expensive, cache_ttl=30.0)
43
+ print(first is second) # True: one worker, one Future
44
+ print(first.result(1)) # 'value'
45
+ ```
46
+
47
+ Ten callers, one work call. The work function blocks until every caller has asked, which is the case coalescing is for:
48
+
49
+ ```python
50
+ import threading
51
+ from resource_singleflight import ResourceCoordinator
52
+
53
+ coordinator = ResourceCoordinator()
54
+ started, release = threading.Event(), threading.Event()
55
+ calls = []
56
+
57
+ def read():
58
+ calls.append(1)
59
+ started.set()
60
+ release.wait(5)
61
+ return "value"
62
+
63
+ futures = []
64
+ target = lambda: futures.append(coordinator.submit("key", read, cache_ttl=30.0))
65
+ threads = [threading.Thread(target=target) for _ in range(10)]
66
+ for thread in threads:
67
+ thread.start()
68
+ started.wait(2)
69
+ release.set()
70
+ for thread in threads:
71
+ thread.join(5)
72
+
73
+ print(len(calls)) # 1
74
+ print({f.result(2) for f in futures}) # {'value'}
75
+ ```
76
+
77
+ A forced refresh replaces the in-flight read, and the superseded `Future` resolves from the replacement instead of hanging:
78
+
79
+ ```python
80
+ old = coordinator.submit("key", slow_read, cache_ttl=30.0)
81
+ new = coordinator.submit("key", fast_read, cache_ttl=30.0, force=True)
82
+ print(old.result(1)) # the replacement's result, not the stale one
83
+ ```
84
+
85
+ ## Why
86
+
87
+ Coalescing requests sounds like a lock around a dictionary. The parts that bite are the edges:
88
+
89
+ - **A detached read must not publish.** If a refresh was replaced, its result is no longer wanted. The coordinator bumps a generation when it replaces work, and a worker may only publish while its generation is current. A superseded worker that finishes late resolves nothing and caches nothing.
90
+ - **Nobody should hang.** Cancelling a `Future` someone is waiting on would raise `CancelledError` in a caller that did nothing wrong. Instead the issued `Future` is resolved from the replacement, so every caller gets an answer.
91
+ - **Work in progress stays owned.** Arbitrary Python code already inside a syscall cannot be stopped. The coordinator keeps every started worker until it exits, and `wait_for_idle()` reports when the last one is done. A shutdown can then wait instead of hoping.
92
+ - **Cache and publication agree.** The generation check and the cache write happen under the same lock, so a replacement lands either wholly before a publication or wholly after it.
93
+
94
+ ## Reference
95
+
96
+ ### `ResourceCoordinator(thread_name_prefix="singleflight")`
97
+
98
+ | Method | Behaviour |
99
+ | --- | --- |
100
+ | `submit(key, function, *, cache_ttl=0.0, force=False)` | Joins the in-flight `Future` for `key`, or serves a cached value, or starts one worker. `force=True` replaces the current generation. |
101
+ | `invalidate(key)` | Drops the cached value and retires the joinable flight, retaining ownership of any running worker. |
102
+ | `clear()` | Drops every cached value and cancels every joinable flight, keeping ownership of running workers. |
103
+ | `wait_for_idle(timeout=None)` | Waits until every worker this coordinator started has exited. Returns `False` on timeout. |
104
+
105
+ `key` is any hashable. `function` takes no arguments; close over what it needs.
106
+
107
+ ### `env_flag(names, *, default=True)`
108
+
109
+ Reads a boolean switch from the first of `names` that is set in the environment. Unset keeps `default`. Any value outside `0`, `false`, `no`, `off` keeps it enabled, so a typo never silently disables coordination.
110
+
111
+ ## Numbers
112
+
113
+ Measured on 2026-11-19 on macOS arm64 (M5 Pro), Python 3.12.8, from `docs/bench/coalesce.json`.
114
+
115
+ | What | Result |
116
+ | --- | --- |
117
+ | 50 threads submitting one key, one 20 ms work item | 1 work call, 4.6 ms total |
118
+ | Cached submit, result already available | 3.3 µs per submit |
119
+
120
+ ## Limits
121
+
122
+ - One process. There is no cross-process coordination; two processes each run their own worker.
123
+ - Only overlapping submissions coalesce. If the work finishes before the next caller submits, that caller starts its own call, or is served the cache when `cache_ttl` is above zero. Ten threads submitting a 5 µs function can produce several calls; the result is still correct.
124
+ - No persistence. The cache is an in-memory dict with a monotonic deadline per key.
125
+ - A worker cannot be interrupted. `force` redirects its result; it does not stop it. Use `wait_for_idle()` when shutdown must be bounded.
126
+ - Linux and Windows have not been exercised.
127
+
128
+ ## FAQ
129
+
130
+ **Why not `functools.lru_cache`?** A cache has no in-flight state, so callers of a cold key each start their own read. This type also owns replacement, which a plain cache does not express.
131
+
132
+ **Why a `Future` and not a lock plus a dict?** A lock says "wait". A `Future` carries the result, the exception and the cancellation state, and a caller can choose its own timeout.
133
+
134
+ ## Contributing
135
+
136
+ Bug reports and patches are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks and the fixture each behaviour change needs.
137
+
138
+ ## Licence
139
+
140
+ MIT, in [LICENSE](LICENSE).
@@ -0,0 +1,34 @@
1
+ [build-system]
2
+ requires = ["setuptools>=77"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "resource-singleflight"
7
+ version = "0.1.0"
8
+ description = "A Python library that runs at most one worker per key and hands every caller the same joinable Future."
9
+ readme = "README.md"
10
+ requires-python = ">=3.9"
11
+ license = "MIT"
12
+ license-files = ["LICENSE"]
13
+ authors = [{ name = "El Fenomeno" }]
14
+ keywords = ["singleflight", "thundering-herd", "concurrency", "future", "cache", "python", "deduplication"]
15
+ classifiers = [
16
+ "Development Status :: 4 - Beta",
17
+ "Intended Audience :: Developers",
18
+ "Operating System :: OS Independent",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Topic :: Software Development :: Libraries :: Python Modules",
22
+ ]
23
+ dependencies = []
24
+
25
+ [project.urls]
26
+ Homepage = "https://github.com/elfenomenokim/resource-singleflight"
27
+ Repository = "https://github.com/elfenomenokim/resource-singleflight"
28
+ Issues = "https://github.com/elfenomenokim/resource-singleflight/issues"
29
+
30
+ [tool.setuptools]
31
+ package-dir = { "" = "src" }
32
+
33
+ [tool.setuptools.packages.find]
34
+ where = ["src"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,12 @@
1
+ """Run one worker per key and share its result.
2
+
3
+ `ResourceCoordinator` gives every caller of a key the same joinable `Future`,
4
+ caches a result for a caller-chosen TTL, and supersedes a worker by generation so
5
+ a detached read cannot publish a value its caller already replaced.
6
+ """
7
+
8
+ from .core import FALSE_WORDS, ResourceCoordinator, env_flag
9
+
10
+ __all__ = ["FALSE_WORDS", "ResourceCoordinator", "env_flag"]
11
+
12
+ __version__ = "0.1.0"
@@ -0,0 +1,243 @@
1
+ """Process-wide duplicate-work suppression for refreshable resources.
2
+
3
+ One `ResourceCoordinator` runs at most one worker per key, hands every caller the
4
+ same joinable `Future`, caches a result for a caller-chosen TTL, and supersedes a
5
+ worker by generation so a detached read cannot publish a value its caller already
6
+ replaced. The module depends on the standard library only.
7
+
8
+ Configuration is by argument: `thread_name_prefix` names the workers, and
9
+ `env_flag` reads the caller's own rollback switch. A program that wants one shared
10
+ coordinator creates one; nothing here requires a module-level singleton.
11
+ """
12
+
13
+ from __future__ import annotations
14
+
15
+ import os
16
+ import threading
17
+ import time
18
+ from concurrent.futures import Future, InvalidStateError
19
+ from typing import Any, Callable, Hashable, Sequence
20
+
21
+
22
+ class ResourceCoordinator:
23
+ """Own worker lifetimes while exposing one joinable Future per resource key."""
24
+
25
+ # Bumped whenever a key is invalidated. A read carries the generation it
26
+ # started under and refuses to write its result if that generation is no
27
+ # longer current, so a detached read cannot resurrect a value the caller
28
+ # already replaced.
29
+ def __init__(self, *, thread_name_prefix: str = "singleflight") -> None:
30
+ if not isinstance(thread_name_prefix, str) or not thread_name_prefix:
31
+ raise ValueError("thread_name_prefix must be a non-empty string")
32
+ self._thread_name_prefix = thread_name_prefix
33
+ # Publication invokes Future callbacks synchronously. An RLock keeps the
34
+ # generation decision and publication atomic while allowing our forwarding
35
+ # callback chain to resolve superseded Futures in the same thread.
36
+ self._lock = threading.RLock()
37
+ self._flights: dict[Hashable, Future] = {}
38
+ # `_flights` names only the generation new callers may join. Superseding
39
+ # that generation must not discard ownership of the worker that is still
40
+ # executing, so every started thread remains here until its `finally`.
41
+ self._workers: dict[Future, threading.Thread] = {}
42
+ self._cache: dict[Hashable, tuple[float, Any]] = {}
43
+ self._generation: dict[Hashable, int] = {}
44
+
45
+ @staticmethod
46
+ def _forward_replacement(replacement: Future, superseded: Future) -> None:
47
+ """Resolve an issued Future from the work that replaced its generation."""
48
+ if replacement.cancelled():
49
+ superseded.cancel()
50
+ return
51
+ try:
52
+ result = replacement.result()
53
+ except BaseException as exc:
54
+ try:
55
+ superseded.set_exception(exc)
56
+ except InvalidStateError:
57
+ pass
58
+ else:
59
+ try:
60
+ superseded.set_result(result)
61
+ except InvalidStateError:
62
+ pass
63
+
64
+ def submit(
65
+ self,
66
+ key: Hashable,
67
+ function: Callable[[], Any],
68
+ *,
69
+ cache_ttl: float = 0.0,
70
+ force: bool = False,
71
+ ) -> Future:
72
+ with self._lock:
73
+ existing = self._flights.get(key)
74
+ # A forced submit must not join an in-flight fetch: start a fresh
75
+ # future and replace the stored flight so later non-force submits
76
+ # join the new one. The stale flight keeps running, but its teardown
77
+ # identity check (`is future`) stops it from popping the new future.
78
+ if existing is not None and not force:
79
+ return existing
80
+ if not force:
81
+ cached = self._cache.get(key)
82
+ if cached is not None:
83
+ expires_at, result = cached
84
+ if time.monotonic() < expires_at:
85
+ ready = Future()
86
+ ready.set_result(result)
87
+ return ready
88
+ self._cache.pop(key, None)
89
+
90
+ if force:
91
+ # A forced read replaces the one in flight. Without bumping the
92
+ # generation both shared one, so whichever finished LAST won the
93
+ # cache - and that could be the read the caller replaced.
94
+ self._cache.pop(key, None)
95
+ self._generation[key] = self._generation.get(key, 0) + 1
96
+ future = Future()
97
+ if force and existing is not None and not existing.done():
98
+ # The old function cannot be stopped safely, and its result must
99
+ # not escape. Keep its already-issued promise useful by resolving
100
+ # it from the replacement generation instead of cancelling it.
101
+ future.add_done_callback(
102
+ lambda replacement, superseded=existing: self._forward_replacement(
103
+ replacement,
104
+ superseded,
105
+ )
106
+ )
107
+ self._flights[key] = future
108
+ generation = self._generation.get(key, 0)
109
+
110
+ def execute() -> None:
111
+ try:
112
+ result = function()
113
+ except BaseException as exc:
114
+ with self._lock:
115
+ current = (
116
+ self._generation.get(key, 0) == generation
117
+ and self._flights.get(key) is future
118
+ and not future.cancelled()
119
+ )
120
+ if current:
121
+ try:
122
+ # Publish before releasing the same lock used by
123
+ # force. A replacement can therefore happen only
124
+ # wholly before this exception or wholly after it.
125
+ future.set_exception(exc)
126
+ except InvalidStateError:
127
+ pass
128
+ if self._flights.get(key) is future:
129
+ self._flights.pop(key, None)
130
+ else:
131
+ with self._lock:
132
+ # Result publication and cache ownership share one
133
+ # generation decision. A superseded worker may finish, but
134
+ # it cannot resolve its reattached Future or repopulate cache.
135
+ current = (
136
+ self._generation.get(key, 0) == generation
137
+ and self._flights.get(key) is future
138
+ and not future.cancelled()
139
+ )
140
+ if current:
141
+ if cache_ttl > 0:
142
+ self._cache[key] = (
143
+ time.monotonic() + float(cache_ttl),
144
+ result,
145
+ )
146
+ try:
147
+ # The current-generation check and publication
148
+ # are one atomic coordinator action. If force won
149
+ # first, this branch is skipped and the replacement
150
+ # callback supplies FRESH to this issued Future.
151
+ future.set_result(result)
152
+ except InvalidStateError:
153
+ pass
154
+ if self._flights.get(key) is future:
155
+ self._flights.pop(key, None)
156
+ finally:
157
+ with self._lock:
158
+ if self._flights.get(key) is future:
159
+ self._flights.pop(key, None)
160
+ self._workers.pop(future, None)
161
+
162
+ worker = threading.Thread(
163
+ target=execute,
164
+ name=f"{self._thread_name_prefix}-{str(key)[:48]}",
165
+ daemon=True,
166
+ )
167
+ self._workers[future] = worker
168
+ # Start while ownership is locked in. `invalidate`, `force`, `clear`,
169
+ # and `wait_for_idle` can never observe an unstarted tracked worker or
170
+ # a started untracked one.
171
+ worker.start()
172
+ return future
173
+
174
+ def invalidate(self, key: Hashable) -> None:
175
+ """Drop one cached result so the next submit re-runs its work.
176
+
177
+ Needed after an out-of-band refresh: the Qwen browser fetch can finish
178
+ inside the 2s provider TTL, and the recollection that follows would
179
+ otherwise be served the pre-fetch snapshot and show the same stale card.
180
+ """
181
+ with self._lock:
182
+ self._cache.pop(key, None)
183
+ # Dropping only the cached value let a read that began during an
184
+ # out-of-band refresh stay joinable; the next submit joined it and
185
+ # replayed pre-refresh data. Retire the joinable flight so a fresh read
186
+ # starts, while `_workers` retains ownership until the old work exits.
187
+ flight = self._flights.pop(key, None)
188
+ if flight is not None:
189
+ flight.cancel()
190
+ self._generation[key] = self._generation.get(key, 0) + 1
191
+
192
+ def clear(self) -> None:
193
+ with self._lock:
194
+ self._cache.clear()
195
+ # Resetting generations to zero made an already-detached gen-0 read
196
+ # current again, so it could write after clear(). Bump instead.
197
+ for key in set(self._generation) | set(self._flights):
198
+ self._generation[key] = self._generation.get(key, 0) + 1
199
+ for future in self._flights.values():
200
+ future.cancel()
201
+ self._flights.clear()
202
+
203
+ def wait_for_idle(self, timeout: float | None = None) -> bool:
204
+ """Wait until every worker owned by this coordinator has exited.
205
+
206
+ Supersession redirects the public Future, while invalidate/clear cancel it;
207
+ none can stop arbitrary Python code already inside a syscall. Those workers
208
+ remain owned and observable here until their bounded work returns.
209
+ """
210
+ deadline = None if timeout is None else time.monotonic() + max(0.0, timeout)
211
+ while True:
212
+ with self._lock:
213
+ workers = list(self._workers.values())
214
+ if not workers:
215
+ return True
216
+ for worker in workers:
217
+ remaining = None
218
+ if deadline is not None:
219
+ remaining = max(0.0, deadline - time.monotonic())
220
+ if remaining == 0:
221
+ return False
222
+ worker.join(timeout=remaining)
223
+ if deadline is not None and time.monotonic() >= deadline:
224
+ with self._lock:
225
+ return not self._workers
226
+
227
+
228
+ FALSE_WORDS = frozenset({"0", "false", "no", "off"})
229
+
230
+
231
+ def env_flag(names: str | Sequence[str], *, default: bool = True) -> bool:
232
+ """Read a boolean switch from the first of `names` that is set.
233
+
234
+ Unset keeps `default`. Any value outside the false words keeps it enabled, so a
235
+ typo never silently disables coordination.
236
+ """
237
+
238
+ candidates = (names,) if isinstance(names, str) else names
239
+ for name in candidates:
240
+ value = os.environ.get(name)
241
+ if value is not None:
242
+ return value.strip().lower() not in FALSE_WORDS
243
+ return default
@@ -0,0 +1,161 @@
1
+ Metadata-Version: 2.4
2
+ Name: resource-singleflight
3
+ Version: 0.1.0
4
+ Summary: A Python library that runs at most one worker per key and hands every caller the same joinable Future.
5
+ Author: El Fenomeno
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://github.com/elfenomenokim/resource-singleflight
8
+ Project-URL: Repository, https://github.com/elfenomenokim/resource-singleflight
9
+ Project-URL: Issues, https://github.com/elfenomenokim/resource-singleflight/issues
10
+ Keywords: singleflight,thundering-herd,concurrency,future,cache,python,deduplication
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: Developers
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3 :: Only
16
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
17
+ Requires-Python: >=3.9
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Dynamic: license-file
21
+
22
+ <div align="center">
23
+
24
+ <img src="https://raw.githubusercontent.com/elfenomenokim/resource-singleflight/main/docs/logo.svg" width="96" height="96" alt="resource-singleflight: many callers, one worker">
25
+
26
+ # resource-singleflight
27
+
28
+ A Python library that runs at most one worker per key and hands every caller the same joinable `Future`.
29
+
30
+ [한국어](README.ko.md) · Python 3.9+
31
+
32
+ [![license](https://img.shields.io/github/license/elfenomenokim/resource-singleflight)](LICENSE)
33
+
34
+ [Install](#install) · [Quick start](#quick-start) · [Why](#why) · [Reference](#reference)
35
+
36
+ </div>
37
+
38
+ 50 threads asking for the same key produced 1 work call in 4.6 ms, and a cached submit costs 3.3 µs. Both values are saved in `docs/bench/coalesce.json`.
39
+
40
+ A refresh loop has a familiar problem: ten panes wake at the same second and each starts the same expensive read. This coordinator lets the first one work and gives the other nine the same `Future` to wait on. When a read has to be replaced, the old one keeps running but cannot publish its result any more, so a slow answer never overwrites a fresh one.
41
+
42
+ Standard library only. One file, no threads of its own beyond the workers it starts.
43
+
44
+ ## Install
45
+
46
+ ```sh
47
+ pip install resource-singleflight
48
+ ```
49
+
50
+ Python 3.9+. No dependencies. Verified on macOS arm64 with Python 3.12.
51
+
52
+ ## Quick start
53
+
54
+ ```python
55
+ from resource_singleflight import ResourceCoordinator
56
+
57
+ coordinator = ResourceCoordinator(thread_name_prefix="refresh")
58
+
59
+ def read_expensive() -> str:
60
+ return "value"
61
+
62
+ first = coordinator.submit("key", read_expensive, cache_ttl=30.0)
63
+ second = coordinator.submit("key", read_expensive, cache_ttl=30.0)
64
+ print(first is second) # True: one worker, one Future
65
+ print(first.result(1)) # 'value'
66
+ ```
67
+
68
+ Ten callers, one work call. The work function blocks until every caller has asked, which is the case coalescing is for:
69
+
70
+ ```python
71
+ import threading
72
+ from resource_singleflight import ResourceCoordinator
73
+
74
+ coordinator = ResourceCoordinator()
75
+ started, release = threading.Event(), threading.Event()
76
+ calls = []
77
+
78
+ def read():
79
+ calls.append(1)
80
+ started.set()
81
+ release.wait(5)
82
+ return "value"
83
+
84
+ futures = []
85
+ target = lambda: futures.append(coordinator.submit("key", read, cache_ttl=30.0))
86
+ threads = [threading.Thread(target=target) for _ in range(10)]
87
+ for thread in threads:
88
+ thread.start()
89
+ started.wait(2)
90
+ release.set()
91
+ for thread in threads:
92
+ thread.join(5)
93
+
94
+ print(len(calls)) # 1
95
+ print({f.result(2) for f in futures}) # {'value'}
96
+ ```
97
+
98
+ A forced refresh replaces the in-flight read, and the superseded `Future` resolves from the replacement instead of hanging:
99
+
100
+ ```python
101
+ old = coordinator.submit("key", slow_read, cache_ttl=30.0)
102
+ new = coordinator.submit("key", fast_read, cache_ttl=30.0, force=True)
103
+ print(old.result(1)) # the replacement's result, not the stale one
104
+ ```
105
+
106
+ ## Why
107
+
108
+ Coalescing requests sounds like a lock around a dictionary. The parts that bite are the edges:
109
+
110
+ - **A detached read must not publish.** If a refresh was replaced, its result is no longer wanted. The coordinator bumps a generation when it replaces work, and a worker may only publish while its generation is current. A superseded worker that finishes late resolves nothing and caches nothing.
111
+ - **Nobody should hang.** Cancelling a `Future` someone is waiting on would raise `CancelledError` in a caller that did nothing wrong. Instead the issued `Future` is resolved from the replacement, so every caller gets an answer.
112
+ - **Work in progress stays owned.** Arbitrary Python code already inside a syscall cannot be stopped. The coordinator keeps every started worker until it exits, and `wait_for_idle()` reports when the last one is done. A shutdown can then wait instead of hoping.
113
+ - **Cache and publication agree.** The generation check and the cache write happen under the same lock, so a replacement lands either wholly before a publication or wholly after it.
114
+
115
+ ## Reference
116
+
117
+ ### `ResourceCoordinator(thread_name_prefix="singleflight")`
118
+
119
+ | Method | Behaviour |
120
+ | --- | --- |
121
+ | `submit(key, function, *, cache_ttl=0.0, force=False)` | Joins the in-flight `Future` for `key`, or serves a cached value, or starts one worker. `force=True` replaces the current generation. |
122
+ | `invalidate(key)` | Drops the cached value and retires the joinable flight, retaining ownership of any running worker. |
123
+ | `clear()` | Drops every cached value and cancels every joinable flight, keeping ownership of running workers. |
124
+ | `wait_for_idle(timeout=None)` | Waits until every worker this coordinator started has exited. Returns `False` on timeout. |
125
+
126
+ `key` is any hashable. `function` takes no arguments; close over what it needs.
127
+
128
+ ### `env_flag(names, *, default=True)`
129
+
130
+ Reads a boolean switch from the first of `names` that is set in the environment. Unset keeps `default`. Any value outside `0`, `false`, `no`, `off` keeps it enabled, so a typo never silently disables coordination.
131
+
132
+ ## Numbers
133
+
134
+ Measured on 2026-11-19 on macOS arm64 (M5 Pro), Python 3.12.8, from `docs/bench/coalesce.json`.
135
+
136
+ | What | Result |
137
+ | --- | --- |
138
+ | 50 threads submitting one key, one 20 ms work item | 1 work call, 4.6 ms total |
139
+ | Cached submit, result already available | 3.3 µs per submit |
140
+
141
+ ## Limits
142
+
143
+ - One process. There is no cross-process coordination; two processes each run their own worker.
144
+ - Only overlapping submissions coalesce. If the work finishes before the next caller submits, that caller starts its own call, or is served the cache when `cache_ttl` is above zero. Ten threads submitting a 5 µs function can produce several calls; the result is still correct.
145
+ - No persistence. The cache is an in-memory dict with a monotonic deadline per key.
146
+ - A worker cannot be interrupted. `force` redirects its result; it does not stop it. Use `wait_for_idle()` when shutdown must be bounded.
147
+ - Linux and Windows have not been exercised.
148
+
149
+ ## FAQ
150
+
151
+ **Why not `functools.lru_cache`?** A cache has no in-flight state, so callers of a cold key each start their own read. This type also owns replacement, which a plain cache does not express.
152
+
153
+ **Why a `Future` and not a lock plus a dict?** A lock says "wait". A `Future` carries the result, the exception and the cancellation state, and a caller can choose its own timeout.
154
+
155
+ ## Contributing
156
+
157
+ Bug reports and patches are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the checks and the fixture each behaviour change needs.
158
+
159
+ ## Licence
160
+
161
+ MIT, in [LICENSE](LICENSE).
@@ -0,0 +1,9 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/resource_singleflight/__init__.py
5
+ src/resource_singleflight/core.py
6
+ src/resource_singleflight.egg-info/PKG-INFO
7
+ src/resource_singleflight.egg-info/SOURCES.txt
8
+ src/resource_singleflight.egg-info/dependency_links.txt
9
+ src/resource_singleflight.egg-info/top_level.txt