Move doc(hidden) items to __private module and make yielder::pair uns…

…afe (#84) To clarify that they are not public APIs.
tokio-rs · Dec 6, 2022 · e1d440f · e1d440f
1 parent ac3fa6b
commit e1d440f
Show file tree

Hide file tree

Showing 3 changed files with 21 additions and 19 deletions.
diff --git a/async-stream-impl/src/lib.rs b/async-stream-impl/src/lib.rs
@@ -173,7 +173,7 @@ impl VisitMut for Scrub<'_> {
                     };
                     #label
                     loop {
-                        let #pat = match #crate_path::reexport::next(&mut __pinned).await {
+                        let #pat = match #crate_path::__private::next(&mut __pinned).await {
                             ::core::option::Option::Some(e) => e,
                             ::core::option::Option::None => break,
                         };
@@ -227,8 +227,8 @@ pub fn stream_inner(input: TokenStream) -> TokenStream {
     };
 
     quote!({
-        let (mut __yield_tx, __yield_rx) = #crate_path::yielder::pair();
-        #crate_path::AsyncStream::new(__yield_rx, async move {
+        let (mut __yield_tx, __yield_rx) = unsafe { #crate_path::__private::yielder::pair() };
+        #crate_path::__private::AsyncStream::new(__yield_rx, async move {
             #dummy_yield
             #(#stmts)*
         })
@@ -261,8 +261,8 @@ pub fn try_stream_inner(input: TokenStream) -> TokenStream {
     };
 
     quote!({
-        let (mut __yield_tx, __yield_rx) = #crate_path::yielder::pair();
-        #crate_path::AsyncStream::new(__yield_rx, async move {
+        let (mut __yield_tx, __yield_rx) = unsafe { #crate_path::__private::yielder::pair() };
+        #crate_path::__private::AsyncStream::new(__yield_rx, async move {
             #dummy_yield
             #(#stmts)*
         })

diff --git a/async-stream/src/lib.rs b/async-stream/src/lib.rs
@@ -158,15 +158,7 @@
 
 mod async_stream;
 mod next;
-#[doc(hidden)]
-pub mod yielder;
-
-// Used by the macro, but not intended to be accessed publicly.
-#[doc(hidden)]
-pub use crate::async_stream::AsyncStream;
-
-#[doc(hidden)]
-pub use async_stream_impl;
+mod yielder;
 
 /// Asynchronous stream
 ///
@@ -198,7 +190,7 @@ pub use async_stream_impl;
 #[macro_export]
 macro_rules! stream {
     ($($tt:tt)*) => {
-        $crate::async_stream_impl::stream_inner!(($crate) $($tt)*)
+        $crate::__private::stream_inner!(($crate) $($tt)*)
     }
 }
 
@@ -234,12 +226,17 @@ macro_rules! stream {
 #[macro_export]
 macro_rules! try_stream {
     ($($tt:tt)*) => {
-        $crate::async_stream_impl::try_stream_inner!(($crate) $($tt)*)
+        $crate::__private::try_stream_inner!(($crate) $($tt)*)
     }
 }
 
+// Not public API.
 #[doc(hidden)]
-pub mod reexport {
-    #[doc(hidden)]
+pub mod __private {
+    pub use crate::async_stream::AsyncStream;
     pub use crate::next::next;
+    pub use async_stream_impl::{stream_inner, try_stream_inner};
+    pub mod yielder {
+        pub use crate::yielder::pair;
+    }
 }
diff --git a/async-stream/src/yielder.rs b/async-stream/src/yielder.rs
@@ -20,7 +20,12 @@ pub(crate) struct Enter<'a, T> {
     prev: *mut (),
 }
 
-pub fn pair<T>() -> (Sender<T>, Receiver<T>) {
+// Note: It is considered unsound for anyone other than our macros to call
+// this function. This is a private API intended only for calls from our
+// macros, and users should never call it, but some people tend to
+// misinterpret it as fine to call unless it is marked unsafe.
+#[doc(hidden)]
+pub unsafe fn pair<T>() -> (Sender<T>, Receiver<T>) {
     let tx = Sender { _p: PhantomData };
     let rx = Receiver { _p: PhantomData };
     (tx, rx)