Skip to content

Document limits on sharing transactions across threads - #2253

Open
x0Lazarus wants to merge 1 commit into
fsspec:masterfrom
x0Lazarus:fix/transaction-thread-docs
Open

x0Lazarus wants to merge 1 commit into
fsspec:masterfrom
x0Lazarus:fix/transaction-thread-docs

Conversation

@x0Lazarus

Copy link
Copy Markdown
Contributor

Transaction state belongs to the filesystem instance. When two threads share that instance and overlap transactions, one transaction can interfere with the other's pending writes. The transaction documentation currently has no warning about this.

Add the warning and explain how to use separate instances with skip_instance_cache=True. This follows the maintainer's recommendation in #180 to document the limitation. The changelog entry records the clarification; there is no runtime change.

Checked locally on Windows with Python 3.12:

  • A temporary-file example reproduces interference with a shared instance and preserves the other thread's write with separate instances.
  • Eight existing local transaction tests pass. The cross-device test is skipped on Windows by its existing marker.
  • The changed documentation sections and Dev changelog build with warnings treated as errors in a minimal Sphinx project. The generated HTML contains the warning and a working link to Instance Caching. Codespell and git diff --check pass.

The full documentation site, cloud backends, downstream projects and other OS/Python combinations were not tested.

Refs #180.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant