pw_thread: Introduce pw::Thread and pw::Thread::id

- Introduce a pw::Thread alias, which new code should use. Will rename
  pw::thread::Thread in a separate commit since it involves updating all
  backends.
- Add a pw::Thread::id alias for pw::thread::Id for consistency with
  std::thread.

Change-Id: I623fea57111536539e43a967a628dc594597d1c3
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/236796
Commit-Queue: Auto-Submit <[email protected]>
Pigweed-Auto-Submit: Wyatt Hepler <[email protected]>
Lint: Lint 🤖 <[email protected]>
Reviewed-by: Taylor Cramer <[email protected]>

pw_thread/docs.rst

@@ -153,6 +153,8 @@ multiple functions to execute concurrently.
 
 API reference
 =============
+.. doxygentypedef:: pw::Thread
+
 .. doxygenclass:: pw::thread::Thread
    :members:
 

pw_thread/public/pw_thread/id.h

@@ -17,19 +17,7 @@
 
 namespace pw::thread {
 
-// The class thread::Id is a lightweight, trivially copyable class that serves
-// as a unique identifier of Thread objects.
-//
-// Instances of this class may also hold the special distinct value that does
-// not represent any thread. Once a thread has finished, the value of its
-// thread::Id may be reused by another thread.
-//
-// This class is designed for use as key in associative containers, both
-// ordered and unordered.
-//
-// The backend must ensure that:
-// 1) There is a default construct which does not represent a thread.
-// 2) Compare operators (==,!=,<,<=,>,>=) are provided to compare and sort IDs.
+// Legacy alias. Use pw::Thread::id instead.
 using Id = backend::NativeId;
 
 }  // namespace pw::thread

pw_thread/public/pw_thread/thread.h

@@ -25,7 +25,8 @@
 #include "pw_thread_backend/thread_native.h"
 // clang-format on
 
-namespace pw::thread {
+namespace pw {
+namespace thread {
 
 /// The class `Thread` can represent a single thread of execution. Threads allow
 /// multiple functions to execute concurrently.
@@ -50,6 +51,23 @@ class Thread {
   /// is inherently non-portable.
   using native_handle_type = backend::NativeThreadHandle;
 
+  /// The class id is a lightweight, trivially copyable class that serves as a
+  /// unique identifier of Thread objects.
+  ///
+  /// Instances of this class may also hold the special distinct value that does
+  /// not represent any thread. Once a thread has finished, the value of its
+  /// `Thread::id` may be reused by another thread.
+  ///
+  /// This class is designed for use as key in associative containers, both
+  /// ordered and unordered.
+  ///
+  /// The backend must ensure that:
+  ///
+  /// 1. There is a default construct which does not represent a thread.
+  /// 2. Compare operators (`==`, `!=`, `<`, `<=`, `>`, `>=`) are provided to
+  ///    compare and sort IDs.
+  using id = ::pw::thread::backend::NativeId;
+
   /// Creates a new thread object which does not represent a thread of execution
   /// yet.
   Thread();
@@ -123,10 +141,10 @@ class Thread {
   Thread(Thread&&) = delete;
   Thread& operator=(const Thread&) = delete;
 
-  /// Returns a value of Thread::id identifying the thread associated with
-  /// *this. If there is no thread associated, default constructed Thread::id is
-  /// returned.
-  Id get_id() const;
+  /// Returns a value of `Thread::id` identifying the thread associated with
+  /// `*this`. If there is no thread associated, default constructed
+  /// `Thread::id` is returned.
+  id get_id() const;
 
   /// Checks if the `Thread` object identifies an active thread of execution
   /// which has not yet been detached. Specifically, returns true if `get_id()
@@ -136,7 +154,7 @@ class Thread {
   /// A thread that has not started or has finished executing code which was
   /// never detached, but has not yet been joined is still considered an active
   /// thread of execution and is therefore joinable.
-  bool joinable() const { return get_id() != Id(); }
+  bool joinable() const { return get_id() != id(); }
 
 #if PW_THREAD_JOINING_ENABLED
   /// Blocks the current thread until the thread identified by `*this` finishes
@@ -194,6 +212,12 @@ class Thread {
   backend::NativeThread native_type_;
 };
 
-}  // namespace pw::thread
+}  // namespace thread
+
+/// `pw::thread::Thread` will be renamed to `pw::Thread`. New code should refer
+/// to `pw::Thread`.
+using Thread = ::pw::thread::Thread;  // Must use `=` for Doxygen to find this.
+
+}  // namespace pw
 
 #include "pw_thread_backend/thread_inline.h"