Add comments about ThreadIdentity struct allocation behavior.

PiperOrigin-RevId: 662586240
Change-Id: Ibee60b935da5d8135ac99b6caf00b3c035ecfd89

absl/base/internal/thread_identity.h

@@ -130,7 +130,11 @@ struct PerThreadSynch {
 };
 
 // The instances of this class are allocated in NewThreadIdentity() with an
-// alignment of PerThreadSynch::kAlignment.
+// alignment of PerThreadSynch::kAlignment and never destroyed. Initialization
+// should happen in OneTimeInitThreadIdentity().
+//
+// Instances may be reused by new threads - fields should be reset in
+// ResetThreadIdentityBetweenReuse().
 //
 // NOTE: The layout of fields in this structure is critical, please do not
 //       add, remove, or modify the field placements without fully auditing the

absl/synchronization/internal/create_thread_identity.cc

@@ -39,7 +39,8 @@ ABSL_CONST_INIT static base_internal::SpinLock freelist_lock(
 ABSL_CONST_INIT static base_internal::ThreadIdentity* thread_identity_freelist;
 
 // A per-thread destructor for reclaiming associated ThreadIdentity objects.
-// Since we must preserve their storage we cache them for re-use.
+// Since we must preserve their storage, we cache them for re-use instead of
+// truly destructing the object.
 static void ReclaimThreadIdentity(void* v) {
   base_internal::ThreadIdentity* identity =
       static_cast<base_internal::ThreadIdentity*>(v);
@@ -124,6 +125,9 @@ static base_internal::ThreadIdentity* NewThreadIdentity() {
     identity = reinterpret_cast<base_internal::ThreadIdentity*>(
         RoundUp(reinterpret_cast<intptr_t>(allocation),
                 base_internal::PerThreadSynch::kAlignment));
+    // Note that *identity is never constructed.
+    // TODO(b/357097463): change this "one time init" to be a proper
+    // constructor.
     OneTimeInitThreadIdentity(identity);
   }
   ResetThreadIdentityBetweenReuse(identity);