Date: Mon, 19 May 2025 06:08:01 GMT From: Konstantin Belousov <kib@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 1393f9a36b9c - main - pthread_signals_block_np(3): document Message-ID: <202505190608.54J681l7037929@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=1393f9a36b9c471d4af3518a3d3bb56c2a6adc58 commit 1393f9a36b9c471d4af3518a3d3bb56c2a6adc58 Author: Konstantin Belousov <kib@FreeBSD.org> AuthorDate: 2025-05-16 13:24:27 +0000 Commit: Konstantin Belousov <kib@FreeBSD.org> CommitDate: 2025-05-19 06:07:43 +0000 pthread_signals_block_np(3): document Reviewed by: markj Sponsored by: The FreeBSD Foundation MFC after: 1 week Differential revision: https://reviews.freebsd.org/D50377 --- share/man/man3/Makefile | 3 ++ share/man/man3/pthread_np.3 | 6 +++ share/man/man3/pthread_signals_block_np.3 | 81 +++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+) diff --git a/share/man/man3/Makefile b/share/man/man3/Makefile index 5469a69ab265..6cdd443ec067 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -458,6 +458,7 @@ PTHREAD_MAN= pthread.3 \ pthread_setspecific.3 \ pthread_sigmask.3 \ pthread_sigqueue.3 \ + pthread_signals_block_np.3 \ pthread_spin_init.3 \ pthread_spin_lock.3 \ pthread_suspend_all_np.3 \ @@ -523,6 +524,8 @@ PTHREAD_MLINKS+=pthread_schedparam.3 pthread_getschedparam.3 \ PTHREAD_MLINKS+=pthread_set_name_np.3 pthread_get_name_np.3 \ pthread_set_name_np.3 pthread_getname_np.3 \ pthread_set_name_np.3 pthread_setname_np.3 +PTHREAD_MLINKS+=pthread_signals_block_np.3 \ + pthread_signals_unblock_np.3 PTHREAD_MLINKS+=pthread_spin_init.3 pthread_spin_destroy.3 \ pthread_spin_lock.3 pthread_spin_trylock.3 \ pthread_spin_lock.3 pthread_spin_unlock.3 diff --git a/share/man/man3/pthread_np.3 b/share/man/man3/pthread_np.3 index 9fb2544dd3c9..c6f0efac7415 100644 --- a/share/man/man3/pthread_np.3 +++ b/share/man/man3/pthread_np.3 @@ -116,6 +116,11 @@ Sets the specified thread's name. .Xc Sets the specified thread's name. .It Xo +.Ft void +.Fn pthread_signals_block_np void +.Xc +Blocks all asynchronous signals, quickly. +.It Xo .Ft int .Fn pthread_single_np void .Xc @@ -213,6 +218,7 @@ instead. .Xr pthread_resume_all_np 3 , .Xr pthread_resume_np 3 , .Xr pthread_set_name_np 3 , +.Xr pthread_signals_block_np 3 , .Xr pthread_suspend_all_np 3 , .Xr pthread_suspend_np 3 , .Xr pthread_switch_add_np 3 diff --git a/share/man/man3/pthread_signals_block_np.3 b/share/man/man3/pthread_signals_block_np.3 new file mode 100644 index 000000000000..de33f4e6189e --- /dev/null +++ b/share/man/man3/pthread_signals_block_np.3 @@ -0,0 +1,81 @@ +.\" Copyright (c) 2025 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" SPDX-License-Identifier: BSD-2-Clause +.\" +.\" This documentation was written by +.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship +.\" from the FreeBSD Foundation. +.\" +.Dd May 16, 2025 +.Dt PTHREAD_SIGNALS_BLOCK_NP 3 +.Os +.Sh NAME +.Nm pthread_signals_block_np , +.Nm pthread_signals_unblock_np +.Nd fast asynchronous signals blocking and unblocking +.Sh LIBRARY +.Lb libpthread +.Sh SYNOPSIS +.In pthread_np.h +.Ft void +.Fn pthread_signals_block_np "void" +.Ft void +.Fn pthread_signals_unblock_np "void" +.Sh DESCRIPTION +The +.Fn pthread_signals_block_np +and +.Fn pthread_signals_unblock_np +functions provide user programs an interface to the fast asynchronous +signals blocking facility +.Xr sigfastblock 2 . +.Pp +Blocking signals with +.Fn pthread_signals_block_np +disables delivery of any asynchronous signal, until unblocked. +Signal blocking establishes a critical section where the execution +flow of the thread cannot be diverted into a signal handler. +Blocking signals is fast, it is performed by a single memory write into +a location established with the kernel. +.Pp +Synchronous signal delivery cannot be blocked in general, including with +these functions. +.Pp +The blocked state established by the +.Fn pthread_signals_block_np +is not completely POSIX-compliant. +Specifically, system calls executed while in a blocked section, +might abort sleep and return +.Er EINTR +upon queuing of an asynchronous signal to the thread, +but the signal handler is not called until the last unblock is done. +.Pp +Calls to +.Nm pthread_signals_block_np +can be nested, and must be complemented by an equal count of +calls to +.Nm pthread_signals_unblock_np +to return the calling thread to the standard mode of signal receiving. +.Pp +An example use of these function might be the construction of the CPU +state that cannot be done atomically, and which includes stages where +the state of the thread is not ABI compliant. +If a signal is delivered while such state is not yet finished, signal +handlers would misbehave. +Using standard functions +.Pq Fn sigprocmask +to establish critical section might be much slower, because +.Fn sigprocmask +is system call, while +.Fn pthread_signals_block_np +consists of a single atomic memory write. +.Sh RETURN VALUES +The functions do not return a value. +.Sh ERRORS +There are no errors reported by the functions. +.Sh SEE ALSO +.Xr sigfastblock 2 , +.Xr sigprocmask 2 , +.Xr pthread_sigmask 3 , +.Xr pthread_np 3
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202505190608.54J681l7037929>