Add fast-path for accessing the current thread id

Accessing the thread id is often used in profiling and debugging, as
well as some approaches for sound single-threaded access to data.

Currently the only way to access the thread id is by first obtaining a
handle to the current thread. While this is not exactly slow, it does
require an atomic inc-ref and dec-ref operation, as well as the
injection of `Thread`'s drop code into the caller.

This publicly exposes the existing fast-path for accessing the current
thread id.

2 files changed, 25 insertions, 3 deletions

diff --git a/library/std/src/thread/current.rs b/library/std/src/thread/current.rs
index 7da1621da45..f00212bfcb6 100644
--- a/library/std/src/thread/current.rs
+++ b/library/std/src/thread/current.rs
@@ -133,12 +133,32 @@ pub(super) fn set_current(thread: Thread) -> Result<(), Thread> {
     Ok(())
 }
 
-/// Gets the id of the thread that invokes it.
+/// Gets the unique identifier of the thread which invokes it.
+///
+/// Calling this function may be more efficient than accessing the current
+/// thread id through the current thread handle. i.e. `thread::current().id()`.
 ///
 /// This function will always succeed, will always return the same value for
 /// one thread and is guaranteed not to call the global allocator.
+///
+/// # Examples
+///
+/// ```
+/// #![feature(current_thread_id)]
+///
+/// use std::thread;
+///
+/// let other_thread = thread::spawn(|| {
+///     thread::current_id()
+/// });
+///
+/// let other_thread_id = other_thread.join().unwrap();
+/// assert_ne!(thread::current_id(), other_thread_id);
+/// ```
 #[inline]
-pub(crate) fn current_id() -> ThreadId {
+#[must_use]
+#[unstable(feature = "current_thread_id", issue = "147194")]
+pub fn current_id() -> ThreadId {
     // If accessing the persistent thread ID takes multiple TLS accesses, try
     // to retrieve it from the current thread handle, which will only take one
     // TLS access.
diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs
index 4d09b2b4e9d..1768369792a 100644
--- a/library/std/src/thread/mod.rs
+++ b/library/std/src/thread/mod.rs
@@ -183,7 +183,9 @@ mod current;
 
 #[stable(feature = "rust1", since = "1.0.0")]
 pub use current::current;
-pub(crate) use current::{current_id, current_or_unnamed, current_os_id, drop_current};
+#[unstable(feature = "current_thread_id", issue = "147194")]
+pub use current::current_id;
+pub(crate) use current::{current_or_unnamed, current_os_id, drop_current};
 use current::{set_current, try_with_current};
 
 mod spawnhook;