From d9b8fef9a032207defc7df05a16037686127dbfb Mon Sep 17 00:00:00 2001
From: Martin Algesten <martin@algesten.se>
Date: Sun, 20 Oct 2019 14:06:24 +0200
Subject: [PATCH] Code comment on *mut Stream effect on thread safety

---
 src/pool.rs     | 5 ++++-
 src/response.rs | 2 ++
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/pool.rs b/src/pool.rs
index b611381..3e45e82 100644
--- a/src/pool.rs
+++ b/src/pool.rs
@@ -77,7 +77,10 @@ impl PoolKey {
 pub(crate) struct PoolReturnRead<R: Read + Sized> {
     // unit that contains the agent where we want to return the reader.
     unit: Option<Unit>,
-    // pointer to underlying stream
+    // pointer to underlying stream.
+    // this pointer forces the entire PoolReturnRead to be !Sync and !Send
+    // that's a good thing, because the pool return logic is certainly not
+    // thread safe.
     stream: *mut Stream,
     // wrapped reader around the same stream
     reader: Option<R>,
diff --git a/src/response.rs b/src/response.rs
index 3976cdc..08f0f70 100644
--- a/src/response.rs
+++ b/src/response.rs
@@ -557,6 +557,8 @@ fn read_next_line<R: Read>(reader: &mut R) -> IoResult<String> {
 /// that api provides no way for us to get the underlying stream back. We need
 /// to get the stream both for sending responses and for pooling.
 pub(crate) struct ReclaimingRead {
+    // this pointer forces ReclaimingRead to be !Send and !Sync. That's a good
+    // thing, cause passing this reader around threads would not be safe.
     stream: *mut Stream,
     dealloc: bool, // whether we are to dealloc stream on drop
 }