From nobody Mon May 26 08:17:07 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4b5TBr2yrZz5xSkH; Mon, 26 May 2025 08:17:08 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4b5TBr0dwFz3RlD; Mon, 26 May 2025 08:17:08 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1748247428; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Mwf4RXJYMyXmj2D3/ZxfzIumJ63pdc5cerLgbsYZsus=; b=AHB5BLGSvoCCPzTlqBwIRo5/DxbL7Y/W16vFoPEFsapqOTRVn58hm1lhy9IY7FciQ/mDTE LZ3KHDPe/MgckgYUopQwrtgGTbbbtAcYQXRI1b7qiyjZZU2CvoJ97tpGlWoLDMKuciSz8m 89RJRXbVNw98tX3d5IfbLqWwlbes4yWqNISJwlS+ZsMSYq8JLkrbvvhggTjNawpcaTivfx xutXjsGnAIJTybp+k6nUdoPctLVAc64sJikZdW2u/s+nIImMcbSZ9NbydPH6UTalAjPt+6 APKHf1R3AE6suWRAkA8ItrhIec2h6X6Z89wN4XVhxl6WnpUJU0p2LE8ck31heQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1748247428; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=Mwf4RXJYMyXmj2D3/ZxfzIumJ63pdc5cerLgbsYZsus=; b=RASwkLrR2lltPUBJ2ghVtizV1mdXov3Poq0sdpB7g+bRA9yV8lW6ZXpM6MetN8lnQC/K26 Fi+b2DAsPtiZUNZ830ZXGj0l7uKD8Axnv8vG4MlXYh2zCQkuIocwFMgkhi0nJ/UGDpUW/E QKdVY3mefnIJudVFEAlDN/inJ3a8G8nJN7MR3BFd7twaj2K8K8QYUbEmz6SGUwj2vZhos+ jpkG844Z+qyBpqhLtRhwpC6P042Ynoztno2SvkUFg58j/jjj9eNjUCCBNgjasZtH/T7EGf SgTWK617cu3wbLe1mJVbO/HVODMKKz9ruJBlL7lI3FHDZ6fmJn6C6GUeDtki2Q== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1748247428; a=rsa-sha256; cv=none; b=pchrOpCs+FOMkUP8A6/9jPqmr5SxhUuPUeCrPE30sF/enOQ7V154eyhlIKFbs/nJC10WUi SrHD2TBh2Hanh+vmju6sFqq3AJX37UQOlWhmHBRcyWTDTkQbARvXxJb8TB9ad6uXqAJLnC inSMAM4aoOZonbnYXAnSlLrA5Iq4fmfyDSS5kdyRUGNjwShE1l5zatecqETn5ZqVeT5lxG W7isw1tg+zlPnyUvbirRSOT4Q1rNDXP7wogQH0NfmeNAC7Ho5ADT6mjXAKw/LDloD5/hVr VejtcYwspmm7v8Ud51Q5uMvPy7TnZoc3R+TjuYDSgVUqZA8fBC1DdGhAPiEt3w== ARC-Authentication-Results: i=1; mx1.freebsd.org; none Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4b5TBq4ZmXzync; Mon, 26 May 2025 08:17:07 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 54Q8H7dd021157; Mon, 26 May 2025 08:17:07 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 54Q8H7jb021154; Mon, 26 May 2025 08:17:07 GMT (envelope-from git) Date: Mon, 26 May 2025 08:17:07 GMT Message-Id: <202505260817.54Q8H7jb021154@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Konstantin Belousov Subject: git: e57eeaf54cb8 - stable/14 - pthread_signals_block_np(3): document List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: kib X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: e57eeaf54cb83b3d38b5a16dd7e9e37e7adf13d6 Auto-Submitted: auto-generated The branch stable/14 has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=e57eeaf54cb83b3d38b5a16dd7e9e37e7adf13d6 commit e57eeaf54cb83b3d38b5a16dd7e9e37e7adf13d6 Author: Konstantin Belousov AuthorDate: 2025-05-16 13:24:27 +0000 Commit: Konstantin Belousov CommitDate: 2025-05-26 08:16:35 +0000 pthread_signals_block_np(3): document (cherry picked from commit 1393f9a36b9c471d4af3518a3d3bb56c2a6adc58) --- 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 3aa215d095e7..0cabb74c6266 100644 --- a/share/man/man3/Makefile +++ b/share/man/man3/Makefile @@ -459,6 +459,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 \ @@ -524,6 +525,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 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