From d487c1ca34f9c3f0f0ee9d72c3bc15d7a8458d11 Mon Sep 17 00:00:00 2001
From: NotAFile <notafile@gmail.com>
Date: Wed, 15 Jun 2022 08:22:03 +0200
Subject: [PATCH] fs: warn about performance pitfall (#4762)

---
 tokio/src/fs/mod.rs | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/tokio/src/fs/mod.rs b/tokio/src/fs/mod.rs
index ca0264b3678..3afefc6e3fb 100644
--- a/tokio/src/fs/mod.rs
+++ b/tokio/src/fs/mod.rs
@@ -22,6 +22,24 @@
 //! `std::io::ErrorKind::WouldBlock` if a *worker* thread can not be converted
 //! to a *backup* thread immediately.
 //!
+//! **Warning**: These adapters may create a large number of temporary tasks,
+//! especially when reading large files. When performing a lot of operations
+//! in one batch, it may be significantly faster to use [`spawn_blocking`]
+//! directly:
+//!
+//! ```
+//! use tokio::fs::File;
+//! use std::io::{BufReader, BufRead};
+//! async fn count_lines(file: File) -> Result<usize, std::io::Error> {
+//!     let file = file.into_std().await;
+//!     tokio::task::spawn_blocking(move || {
+//!         let line_count = BufReader::new(file).lines().count();
+//!         Ok(line_count)
+//!     }).await?
+//! }
+//! ```
+//!
+//! [`spawn_blocking`]: fn@crate::task::spawn_blocking
 //! [`AsyncRead`]: trait@crate::io::AsyncRead
 
 mod canonicalize;