[PATCH v2 1/2] manual: Consolidate POSIX Semaphores docs in Threads chapter

[Adhemerval Zanella Netto]

On 13/01/25 22:52, Arjun Shankar wrote:
> This commit moves the `sem_*' family of functions from the IPC chapter,
> replacing them with a reference to their new location in the Threads
> chapter.  `sem_clockwait' is also moved out of the Non-POSIX Extensions
> subsection since it is now included in the standard since Issue 8:
> https://pubs.opengroup.org/onlinepubs/9799919799/functions/sem_clockwait.html

LGTM, thanks.

Reviewed-by: Adhemerval Zanella  <adhemerval.zanella@linaro.org>

> ---
> v1: https://sourceware.org/pipermail/libc-alpha/2024-December/163203.html
> Changes in v2: addressed Florian's comments:
> https://sourceware.org/pipermail/libc-alpha/2025-January/163667.html
> 
>  manual/ipc.texi     | 71 ++-------------------------------
>  manual/threads.texi | 95 ++++++++++++++++++++++++++++++++++++++++-----
>  2 files changed, 88 insertions(+), 78 deletions(-)
> 
> diff --git a/manual/ipc.texi b/manual/ipc.texi
> index 32c5ac066f..f9c7638359 100644
> --- a/manual/ipc.texi
> +++ b/manual/ipc.texi
> @@ -46,71 +46,6 @@ by @theglibc{}.
>  @end deftypefun
>  
>  @subsection POSIX Semaphores
> -
> -@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value})
> -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
> -@c Does not atomically update sem_t therefore AC-unsafe
> -@c because it can leave sem_t partially initialized.
> -@end deftypefun
> -
> -@deftypefun int sem_destroy (sem_t *@var{sem})
> -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -@c Function does nothing and is therefore always safe.
> -@end deftypefun
> -
> -@deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...)
> -@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
> -@c pthread_once asuinit
> -@c
> -@c We are AC-Unsafe because we use pthread_once to initialize
> -@c a global variable that holds the location of the mounted
> -@c shmfs on Linux.
> -@end deftypefun
> -
> -@deftypefun int sem_close (sem_t *@var{sem})
> -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
> -@c lll_lock asulock aculock
> -@c twalk mtsrace{:root}
> -@c
> -@c We are AS-unsafe because we take a non-recursive lock.
> -@c We are AC-unsafe because several internal data structures
> -@c are not updated atomically.
> -@end deftypefun
> -
> -@deftypefun int sem_unlink (const char *@var{name})
> -@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}}
> -@c pthread_once asuinit acucorrupt aculock
> -@c mempcpy acucorrupt
> -@end deftypefun
> -
> -@deftypefun int sem_wait (sem_t *@var{sem})
> -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
> -@c atomic_fetch_add_relaxed (nwaiters) acucorrupt
> -@c
> -@c Given the use atomic operations this function seems
> -@c to be AS-safe.  It is AC-unsafe because there is still
> -@c a window between atomic_fetch_add_relaxed and the pthread_push
> -@c of the handler that undoes that operation.  A cancellation
> -@c at that point would fail to remove the process from the
> -@c waiters count.
> -@end deftypefun
> -
> -@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime})
> -@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
> -@c Same safety issues as sem_wait.
> -@end deftypefun
> -
> -@deftypefun int sem_trywait (sem_t *@var{sem})
> -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -@c All atomic operations are safe in all contexts.
> -@end deftypefun
> -
> -@deftypefun int sem_post (sem_t *@var{sem})
> -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -@c Same safety as sem_trywait.
> -@end deftypefun
> -
> -@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval})
> -@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> -@c Atomic write of a value is safe in all contexts.
> -@end deftypefun
> +@Theglibc{} provides POSIX semaphores as well.  These functions' names begin
> +with @code{sem_} and they are declared in @file{semaphore.h}.  @xref{POSIX
> +Semaphores}.
> diff --git a/manual/threads.texi b/manual/threads.texi
> index 9ea137cb96..806ab866c5 100644
> --- a/manual/threads.texi
> +++ b/manual/threads.texi
> @@ -554,6 +554,8 @@ This section describes the @glibcadj{} POSIX Threads implementation.
>  @menu
>  * Thread-specific Data::          Support for creating and
>  				  managing thread-specific data
> +* POSIX Semaphores::              Support for process and thread
> +				  synchronization using semaphores
>  * Non-POSIX Extensions::          Additional functions to extend
>  				  POSIX Thread functionality
>  @end menu
> @@ -615,6 +617,86 @@ Associate the thread-specific @var{value} with @var{key} in the calling thread.
>  @end deftypefun
>  
>  
> +@node POSIX Semaphores
> +@subsection POSIX Semaphores
> +
> +@deftypefun int sem_init (sem_t *@var{sem}, int @var{pshared}, unsigned int @var{value})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
> +@c Does not atomically update sem_t therefore AC-unsafe
> +@c because it can leave sem_t partially initialized.
> +@end deftypefun
> +
> +@deftypefun int sem_destroy (sem_t *@var{sem})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Function does nothing and is therefore always safe.
> +@end deftypefun
> +
> +@deftypefun {sem_t *} sem_open (const char *@var{name}, int @var{oflag}, ...)
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acuinit{}}}
> +@c pthread_once asuinit
> +@c
> +@c We are AC-Unsafe because we use pthread_once to initialize
> +@c a global variable that holds the location of the mounted
> +@c shmfs on Linux.
> +@end deftypefun
> +
> +@deftypefun int sem_close (sem_t *@var{sem})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
> +@c lll_lock asulock aculock
> +@c twalk mtsrace{:root}
> +@c
> +@c We are AS-unsafe because we take a non-recursive lock.
> +@c We are AC-unsafe because several internal data structures
> +@c are not updated atomically.
> +@end deftypefun
> +
> +@deftypefun int sem_unlink (const char *@var{name})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asuinit{}}@acunsafe{@acucorrupt{}}}
> +@c pthread_once asuinit acucorrupt aculock
> +@c mempcpy acucorrupt
> +@end deftypefun
> +
> +@deftypefun int sem_wait (sem_t *@var{sem})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
> +@c atomic_fetch_add_relaxed (nwaiters) acucorrupt
> +@c
> +@c Given the use atomic operations this function seems
> +@c to be AS-safe.  It is AC-unsafe because there is still
> +@c a window between atomic_fetch_add_relaxed and the pthread_push
> +@c of the handler that undoes that operation.  A cancellation
> +@c at that point would fail to remove the process from the
> +@c waiters count.
> +@end deftypefun
> +
> +@deftypefun int sem_timedwait (sem_t *@var{sem}, const struct timespec *@var{abstime})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{@acucorrupt{}}}
> +@c Same safety issues as sem_wait.
> +@end deftypefun
> +
> +@deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, const struct timespec *@var{abstime})
> +@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
> +Behaves like @code{sem_timedwait} except the time @var{abstime} is measured
> +against the clock specified by @var{clockid} rather than
> +@code{CLOCK_REALTIME}.  Currently, @var{clockid} must be either
> +@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}.
> +@end deftypefun
> +
> +@deftypefun int sem_trywait (sem_t *@var{sem})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c All atomic operations are safe in all contexts.
> +@end deftypefun
> +
> +@deftypefun int sem_post (sem_t *@var{sem})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Same safety as sem_trywait.
> +@end deftypefun
> +
> +@deftypefun int sem_getvalue (sem_t *@var{sem}, int *@var{sval})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +@c Atomic write of a value is safe in all contexts.
> +@end deftypefun
> +
> +
>  @node Non-POSIX Extensions
>  @subsection Non-POSIX Extensions
>  
> @@ -752,16 +834,6 @@ freed.
>  @Theglibc{} provides several waiting functions that expect an explicit
>  @code{clockid_t} argument.
>  
> -@comment semaphore.h
> -@comment POSIX-proposed
> -@deftypefun int sem_clockwait (sem_t *@var{sem}, clockid_t @var{clockid}, const struct timespec *@var{abstime})
> -@safety{@prelim{}@mtsafe{}@asunsafe{@asulock{}}@acunsafe{@aculock{}}}
> -Behaves like @code{sem_timedwait} except the time @var{abstime} is measured
> -against the clock specified by @var{clockid} rather than
> -@code{CLOCK_REALTIME}.  Currently, @var{clockid} must be either
> -@code{CLOCK_MONOTONIC} or @code{CLOCK_REALTIME}.
> -@end deftypefun
> -
>  @comment pthread.h
>  @comment POSIX-proposed
>  @deftypefun int pthread_cond_clockwait (pthread_cond_t *@var{cond}, pthread_mutex_t *@var{mutex}, clockid_t @var{clockid}, const struct timespec *@var{abstime})
> @@ -835,6 +907,9 @@ Currently, @var{clockid} must be either @code{CLOCK_MONOTONIC} or
>  @code{CLOCK_REALTIME}.
>  @end deftypefun
>  
> +The @code{sem_clockwait} function also works using a @code{clockid_t}
> +argument.  @xref{POSIX Semaphores}.
> +
>  @node Single-Threaded
>  @subsubsection Detecting Single-Threaded Execution
>