aio-libs / multidict / 36156013899

87%

push

github

Document a cache-invalidating watcher in the C API docs (#1586)

<!-- Thank you for your contribution! -->

## What do these changes do?

Adds an "Invalidating a cache" example to `docs/capi.rst`, after the
existing watcher example. It shows the pattern CPython's JIT uses for a
module's globals: the callback clears the cache and unwatches itself,
the next rebuild watches again, and after a fixed number of rebuild
attempts the cache stops trying on a multidict that keeps changing.

An event goes to whoever is watching when the operation finishes, so it
can reach a rebuild that already saw its change, under the GIL too once
`parse()` runs Python code. The cache therefore records the version it
was built from: the callback discards only a cache the multidict has
moved past, and never unwatches while a rebuild owns the watch. On the
free-threaded build the fields also need a lock, which sits behind
`Py_GIL_DISABLED`, so one source serves both builds and works back to
3.10. Bare BATCH brackets are ignored, and a failed parse stops
listening.

## Are there changes in behavior for the user?

No, documentation only.

## Is it a substantial burden for the maintainers to support this?

No.

## Related issue number

Follow-up to #1551.

## Checklist

- [x] I think the code is well written
- [ ] Unit tests for the changes exist (N/A, documentation only)
- [x] Documentation reflects the changes
- [ ] If you provide code modification, please add yourself to
`CONTRIBUTORS.txt` (N/A)
- [x] Add a new news fragment into the `CHANGES/` folder
- [x] `make doc-spelling` passes and any new technical words are added
to `docs/spelling_wordlist.txt`

Drafted with Claude Code (Claude Opus 5.5); to be reviewed by @asvetlov.

<details>
<summary>Agent run details (optional, for reviewers)</summary>

The example code is extracted verbatim from `docs/capi.rst` into a small
extension (stubs only for `my_mod_state` and `parse()`), built with
`-Wall -Wextra -Werror -std=c11` against t... (continued)

780 of 1560 branches covered (50.0%)

Branch coverage included in aggregate %.

8104 of 8651 relevant lines covered (93.68%)

1.87 hits per line