Document pthread_key_create(3), pthread_key_delete(3), and PTHREAD_KEYS_MAX.

In particular "how to work around the PTHREAD_KEYS_MAX limit".

Change-Id: I330936d598ddddfa0903f0505fd00f8fcbf02543

2 files changed, 30 insertions, 2 deletions

diff --git a/libc/include/limits.h b/libc/include/limits.h
index 80fc45d2a..e1f566c83 100644
--- a/libc/include/limits.h
+++ b/libc/include/limits.h
@@ -148,9 +148,15 @@
 
 /* >= _POSIX_THREAD_DESTRUCTOR_ITERATIONS */
 #define PTHREAD_DESTRUCTOR_ITERATIONS 4
-/* >= _POSIX_THREAD_KEYS_MAX */
+
+/**
+ * The number of calls to pthread_key_create() without intervening calls to
+ * pthread_key_delete() that are guaranteed to succeed. See pthread_key_create()
+ * for more details and ways to avoid hitting this limit.
+ */
 #define PTHREAD_KEYS_MAX 128
-/* bionic has no specific limit */
+
+/** bionic has no specific limit on the number of threads. */
 #undef PTHREAD_THREADS_MAX
 
 #endif /* !_LIMITS_H_ */
diff --git a/libc/include/pthread.h b/libc/include/pthread.h
index 871c62ce8..ef41e2d71 100644
--- a/libc/include/pthread.h
+++ b/libc/include/pthread.h
@@ -174,7 +174,29 @@ pid_t pthread_gettid_np(pthread_t __pthread);
 
 int pthread_join(pthread_t __pthread, void* _Nullable * _Nullable __return_value_ptr);
 
+/**
+ * [pthread_key_create(3)](https://man7.org/linux/man-pages/man3/pthread_key_create.3p.html)
+ * creates a key for thread-specific data.
+ *
+ * There is a limit of `PTHREAD_KEYS_MAX` keys per process, but most callers
+ * should just use the C or C++ `thread_local` storage specifier anyway. When
+ * targeting new enough OS versions, the compiler will automatically use
+ * ELF TLS; when targeting old OS versions the emutls implementation will
+ * multiplex pthread keys behind the scenes, using one per library rather than
+ * one per thread-local variable. If you are implementing the runtime for a
+ * different language, you should consider similar implementation choices and
+ * avoid a direct one-to-one mapping from thread locals to pthread keys.
+ *
+ * Returns 0 on success and returns an error number on failure.
+ */
 int pthread_key_create(pthread_key_t* _Nonnull __key_ptr, void (* _Nullable __key_destructor)(void* _Nullable));
+
+/**
+ * [pthread_key_delete(3)](https://man7.org/linux/man-pages/man3/pthread_key_delete.3p.html)
+ * deletes a key for thread-specific data.
+ *
+ * Returns 0 on success and returns an error number on failure.
+ */
 int pthread_key_delete(pthread_key_t __key);
 
 int pthread_mutexattr_destroy(pthread_mutexattr_t* _Nonnull __attr);