Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions docs/source/reference-io.rst
Original file line number Diff line number Diff line change
Expand Up @@ -690,6 +690,12 @@ Asynchronous file objects
guaranteed to close the file before returning, even if it is
cancelled or otherwise raises an error.

Calling ``aclose`` on an async file object also closes the
underlying synchronous file object. Trio does not add a
synchronous ``close`` method to the async wrapper, and does not
guarantee that the wrapped file will be closed automatically when
the async wrapper is garbage collected.

* Using the same async file object from multiple tasks
simultaneously: because the async methods on async file objects
are implemented using threads, it's only safe to call two of them
Expand All @@ -702,6 +708,12 @@ Asynchronous file objects
files are not
<https://docs.python.org/3/library/io.html#multi-threading>`__.

The same caveat applies if you keep using the original
synchronous file object after wrapping it with
:func:`trio.wrap_file`: direct synchronous operations can run at
the same time as the wrapper's async operations, so this is only
safe when the wrapped object supports that kind of concurrent use.

* Async file objects can be used as async iterators to iterate over
the lines of the file:

Expand Down
1 change: 1 addition & 0 deletions newsfragments/3379.doc.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Clarified how :func:`trio.wrap_file` async wrappers interact with the wrapped synchronous file object's close lifecycle and concurrent use.
Loading