Improve the pthread key functions' documentation.
We should probably fix the "destructors are called on null values" bug, but let's at least document the current situation first.
(Why only "probably"? Because code that needs to run on existing versions of Android is going to need to write its destructors to cope with null values, so there's an app compat aspect to this. Technically, it's not impossible that someone has a destructor that _relies_ on getting called even for null too.)
Change-Id: I3a2ead05a91c9e6166cfdd6baf047db3cd2917a8
diff --git a/libc/include/pthread.h b/libc/include/pthread.h
index cdf1b8c..f3b7068 100644
--- a/libc/include/pthread.h
+++ b/libc/include/pthread.h
@@ -170,8 +170,6 @@
int pthread_getcpuclockid(pthread_t __pthread, clockid_t* _Nonnull __clock);
-void* _Nullable pthread_getspecific(pthread_key_t __key);
-
pid_t pthread_gettid_np(pthread_t __pthread);
int pthread_join(pthread_t __pthread, void* _Nullable * _Nullable __return_value_ptr);
@@ -189,6 +187,9 @@
* different language, you should consider similar implementation choices and
* avoid a direct one-to-one mapping from thread locals to pthread keys.
*
+ * On Android, the destructor function is called even for null values,
+ * even though POSIX specifies that it is only called for non-null values.
+ *
* 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));
@@ -197,10 +198,28 @@
* [pthread_key_delete(3)](https://man7.org/linux/man-pages/man3/pthread_key_delete.3p.html)
* deletes a key for thread-specific data.
*
+ * Note that pthread_key_delete() does _not_ run destructor functions:
+ * the caller must take care of any necessary cleanup of thread-specific data themselves.
+ * This function only deletes the key itself.
+ *
* Returns 0 on success and returns an error number on failure.
*/
int pthread_key_delete(pthread_key_t __key);
+/**
+ * [pthread_getspecific(3)](https://man7.org/linux/man-pages/man3/pthread_getspecific.3p.html)
+ * returns the calling thread's thread-specific value for the given key.
+ */
+void* _Nullable pthread_getspecific(pthread_key_t __key);
+
+/**
+ * [pthread_setspecific(3)](https://man7.org/linux/man-pages/man3/pthread_setspecific.3p.html)
+ * sets the calling thread's thread-specific value for the given key.
+ *
+ * Returns 0 on success and returns an error number on failure.
+ */
+int pthread_setspecific(pthread_key_t __key, const void* _Nullable __value);
+
int pthread_mutexattr_destroy(pthread_mutexattr_t* _Nonnull __attr);
int pthread_mutexattr_getpshared(const pthread_mutexattr_t* _Nonnull __attr, int* _Nonnull __shared);
int pthread_mutexattr_gettype(const pthread_mutexattr_t* _Nonnull __attr, int* _Nonnull __type);
@@ -406,9 +425,6 @@
int pthread_setschedprio(pthread_t __pthread, int __priority) __INTRODUCED_IN(28);
#endif /* __BIONIC_AVAILABILITY_GUARD(28) */
-
-int pthread_setspecific(pthread_key_t __key, const void* _Nullable __value);
-
typedef void (* _Nullable __pthread_cleanup_func_t)(void* _Nullable);
typedef struct __pthread_cleanup_t {