From nobody Mon May 19 06:08:01 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 4b16g60LrYz5wZ5G; Mon, 19 May 2025 06:08:02 +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 4b16g54jdJz3m4N; Mon, 19 May 2025 06:08:01 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1747634881; 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=AXkZf0ZJXoDfoOGhzXlmGHRuTsQ8GJ/UGu8V/xLZsNE=; b=Hm7CT49Nc3x/7FM2iAKFKMnHtTSjRz9BjA1aOjhZNfLDLltO1CmC9/kdQwLkRMW9AXG66f pVkpRjRJ+Csb5ACcVEqzVtEA3Rt+6dJfblzAjC+bPJTtKnqIgFljuaVkpQ6aliCgklz421 UWrFak6amnByW8jeAuDNlSnrk6I3WSgs4JLJTDEE+18dhDoF4WXVlaVunefVljmBrGBTNH QHT1prTObnrcf+YtQ3m/vVbnkdyMobG75mMv2Bbt8lEbEt4L/YnqozC0WKpFftbwlJ5nOS 66YPwDTSLapBF0QxqP992U+uvgfC/2O2vo9UJadYVpMvpsQK5n5JnpNRgF4S+Q== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1747634881; 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=AXkZf0ZJXoDfoOGhzXlmGHRuTsQ8GJ/UGu8V/xLZsNE=; b=GVETx/iXk48Wep1D4zzpclSI83JUCfIpor2Ri8uIxnH2nreLskDWlze9BHz7UUXd9akza1 X+Odjx2P0+F0eBeaghV7KKZQ+AN9KVTHnI19O7q7/deZs/zweLcKmHflv3Eu9RR6ZIzfML 4sMb9WKQBIz+TiRdMY5rg0izHfYIqaPSbF/BqJQDWU+O1U/Dv0flg3xHBzx1zRKCXyarwC kVQzWpN8mB+gbo/o1wRSwzgBUFbufM4E/SmDr2uVLXWCRvu6ptakpoCP+68tkCDrMH32+6 KwkVtQWJ4tJpKiXdnWP6VsqwSUbt2mQlsdlo1wZJUw7yVYp48ntat5taBWW52g== ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1747634881; a=rsa-sha256; cv=none; b=LRMmTqDkJigitTLvymQMwa8QcjIneurSI2fNRaMPZuSaoWwKIRRyZAD3miBcpNsscM6MKr Tb4CJSHqWdXspP+pQj6YrrLhl8SMLls085Ue5Qy2S8sWK5JCUQPMK9KLRIPobm+1m9xh4V KCJAspFEjnUJRncibFu7EZPu8tr840gzh7hL9x6D5EW+9PzxkTUPHURhkUoOl9ak4wIMqy QS+5dDUBSR6Z2cdQ9dvtBZUQUzB91CFt47t1rIULguW1wPrTZ/NnaA83hFU83/Yrv2VYcq KFckZPN+BtMOdUDRH7jUUcXy2TRQ9tQ3A1VPwHgzokBPd1cv5TkDBKM409T7MQ== 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 4b16g543CXzsGY; Mon, 19 May 2025 06:08:01 +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 54J681A4037932; Mon, 19 May 2025 06:08:01 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 54J681l7037929; Mon, 19 May 2025 06:08:01 GMT (envelope-from git) Date: Mon, 19 May 2025 06:08:01 GMT Message-Id: <202505190608.54J681l7037929@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Konstantin Belousov Subject: git: 1393f9a36b9c - main - 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/main X-Git-Reftype: branch X-Git-Commit: 1393f9a36b9c471d4af3518a3d3bb56c2a6adc58 Auto-Submitted: auto-generated The branch main has been updated by kib: URL: https://cgit.FreeBSD.org/src/commit/?id=1393f9a36b9c471d4af3518a3d3bb56c2a6adc58 commit 1393f9a36b9c471d4af3518a3d3bb56c2a6adc58 Author: Konstantin Belousov AuthorDate: 2025-05-16 13:24:27 +0000 Commit: Konstantin Belousov 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 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