sync: document that const_new() is not instrumented (#6002)

Author: hds

tokio/src/sync/mutex.rs

@@ -371,13 +371,21 @@ impl<T: ?Sized> Mutex<T> {
 
     /// Creates a new lock in an unlocked state ready for use.
     ///
+    /// When using the `tracing` [unstable feature], a `Mutex` created with
+    /// `const_new` will not be instrumented. As such, it will not be visible
+    /// in [`tokio-console`]. Instead, [`Mutex::new`] should be used to create
+    /// an instrumented object if that is needed.
+    ///
     /// # Examples
     ///
     /// ```
     /// use tokio::sync::Mutex;
     ///
     /// static LOCK: Mutex<i32> = Mutex::const_new(5);
     /// ```
+    ///
+    /// [`tokio-console`]: https://github.com/tokio-rs/console
+    /// [unstable feature]: crate#unstable-features
     #[cfg(not(all(loom, test)))]
     pub const fn const_new(t: T) -> Self
     where

tokio/src/sync/notify.rs

@@ -436,13 +436,21 @@ impl Notify {
 
     /// Create a new `Notify`, initialized without a permit.
     ///
+    /// When using the `tracing` [unstable feature], a `Notify` created with
+    /// `const_new` will not be instrumented. As such, it will not be visible
+    /// in [`tokio-console`]. Instead, [`Notify::new`] should be used to create
+    /// an instrumented object if that is needed.
+    ///
     /// # Examples
     ///
     /// ```
     /// use tokio::sync::Notify;
     ///
     /// static NOTIFY: Notify = Notify::const_new();
     /// ```
+    ///
+    /// [`tokio-console`]: https://github.com/tokio-rs/console
+    /// [unstable feature]: crate#unstable-features
     #[cfg(not(all(loom, test)))]
     pub const fn const_new() -> Notify {
         Notify {

tokio/src/sync/once_cell.rs

@@ -153,6 +153,11 @@ impl<T> OnceCell<T> {
     ///
     /// # Example
     ///
+    /// When using the `tracing` [unstable feature], a `OnceCell` created with
+    /// `const_new_with` will not be instrumented. As such, it will not be
+    /// visible in [`tokio-console`]. Instead, [`OnceCell::new_with`] should be
+    /// used to create an instrumented object if that is needed.
+    ///
     /// ```
     /// use tokio::sync::OnceCell;
     ///
@@ -170,6 +175,9 @@ impl<T> OnceCell<T> {
     ///     assert_eq!(*result, 1);
     /// }
     /// ```
+    ///
+    /// [`tokio-console`]: https://github.com/tokio-rs/console
+    /// [unstable feature]: crate#unstable-features
     #[cfg(not(all(loom, test)))]
     pub const fn const_new_with(value: T) -> Self {
         OnceCell {
@@ -184,6 +192,11 @@ impl<T> OnceCell<T> {
     /// Equivalent to `OnceCell::new`, except that it can be used in static
     /// variables.
     ///
+    /// When using the `tracing` [unstable feature], a `OnceCell` created with
+    /// `const_new` will not be instrumented. As such, it will not be visible
+    /// in [`tokio-console`]. Instead, [`OnceCell::new`] should be used to
+    /// create an instrumented object if that is needed.
+    ///
     /// # Example
     ///
     /// ```
@@ -203,6 +216,9 @@ impl<T> OnceCell<T> {
     ///     assert_eq!(*result, 2);
     /// }
     /// ```
+    ///
+    /// [`tokio-console`]: https://github.com/tokio-rs/console
+    /// [unstable feature]: crate#unstable-features
     #[cfg(not(all(loom, test)))]
     pub const fn const_new() -> Self {
         OnceCell {

tokio/src/sync/rwlock.rs

@@ -327,13 +327,21 @@ impl<T: ?Sized> RwLock<T> {
 
     /// Creates a new instance of an `RwLock<T>` which is unlocked.
     ///
+    /// When using the `tracing` [unstable feature], a `RwLock` created with
+    /// `const_new` will not be instrumented. As such, it will not be visible
+    /// in [`tokio-console`]. Instead, [`RwLock::new`] should be used to create
+    /// an instrumented object if that is needed.
+    ///
     /// # Examples
     ///
     /// ```
     /// use tokio::sync::RwLock;
     ///
     /// static LOCK: RwLock<i32> = RwLock::const_new(5);
     /// ```
+    ///
+    /// [`tokio-console`]: https://github.com/tokio-rs/console
+    /// [unstable feature]: crate#unstable-features
     #[cfg(not(all(loom, test)))]
     pub const fn const_new(value: T) -> RwLock<T>
     where

tokio/src/sync/semaphore.rs

@@ -194,13 +194,21 @@ impl Semaphore {
 
     /// Creates a new semaphore with the initial number of permits.
     ///
+    /// When using the `tracing` [unstable feature], a `Semaphore` created with
+    /// `const_new` will not be instrumented. As such, it will not be visible
+    /// in [`tokio-console`]. Instead, [`Semaphore::new`] should be used to
+    /// create an instrumented object if that is needed.
+    ///
     /// # Examples
     ///
     /// ```
     /// use tokio::sync::Semaphore;
     ///
     /// static SEM: Semaphore = Semaphore::const_new(10);
     /// ```
+    ///
+    /// [`tokio-console`]: https://github.com/tokio-rs/console
+    /// [unstable feature]: crate#unstable-features
     #[cfg(not(all(loom, test)))]
     pub const fn const_new(permits: usize) -> Self {
         Self {