Code comment on *mut Stream effect on thread safety

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>,

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
 }