diff --git a/docs/source/reference-io.rst b/docs/source/reference-io.rst index d1eb083b08..4c19674855 100644 --- a/docs/source/reference-io.rst +++ b/docs/source/reference-io.rst @@ -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 @@ -702,6 +708,12 @@ Asynchronous file objects files are not `__. + 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: diff --git a/newsfragments/3379.doc.rst b/newsfragments/3379.doc.rst new file mode 100644 index 0000000000..fcc8c51e98 --- /dev/null +++ b/newsfragments/3379.doc.rst @@ -0,0 +1 @@ +Clarified how :func:`trio.wrap_file` async wrappers interact with the wrapped synchronous file object's close lifecycle and concurrent use.