From patchwork Thu Jan 30 15:20:10 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Siddhesh Poyarekar X-Patchwork-Id: 105676 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from server2.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 337763858C54 for ; Thu, 30 Jan 2025 15:21:23 +0000 (GMT) X-Original-To: libc-alpha@sourceware.org Delivered-To: libc-alpha@sourceware.org Received: from beige.pine.relay.mailchannels.net (beige.pine.relay.mailchannels.net [23.83.219.16]) by sourceware.org (Postfix) with ESMTPS id 2CDDD3857B9E for ; Thu, 30 Jan 2025 15:20:59 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 2CDDD3857B9E Authentication-Results: sourceware.org; dmarc=fail (p=none dis=none) header.from=sourceware.org Authentication-Results: sourceware.org; spf=fail smtp.mailfrom=sourceware.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 2CDDD3857B9E Authentication-Results: server2.sourceware.org; arc=pass smtp.remote-ip=23.83.219.16 ARC-Seal: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1738250459; cv=pass; b=FeS4DHwL5U0ZQ/bLSedDgKCe9gUtE1q7GpShyjuQnm3aFK6gsGC5zEaXMm2fGLd0xZzbTvKmE4UURG80POxJRZRQfe3anFeaAJ6oH5Z42xAluM0VGuljBYa3QLNeCtc40RWrYP7OJV+FQE73xQQxaj7XlTku9TxfGNgB3AdwIcU= ARC-Message-Signature: i=2; a=rsa-sha256; d=sourceware.org; s=key; t=1738250459; c=relaxed/simple; bh=+gdrLn1G8Ur2KgRXUsgTGrfkMBdPj8vtxPcWfh+971c=; h=From:To:Subject:Date:Message-ID:MIME-Version; b=L4WKJRj+tf8yVnpN8/ZqmGjE/fu0aAB0OCeHoKuNk7YcF+s14IdxSNdfEcfjKddFl8CfCb5PTE0FG5e6NlAQqPBYd0h7qztr00U8N0Ld9o9xr8qWp/dSksPLMtuwKryS/YUjKZTGU+axSfZaKrhbYyImvMV7IbcqFl9SuBJ0cgw= ARC-Authentication-Results: i=2; server2.sourceware.org DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 2CDDD3857B9E Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 60D722C469B; Thu, 30 Jan 2025 15:20:41 +0000 (UTC) Received: from pdx1-sub0-mail-a241.dreamhost.com (trex-6.trex.outbound.svc.cluster.local [100.116.68.50]) (Authenticated sender: dreamhost) by relay.mailchannels.net (Postfix) with ESMTPA id EE84D2C4FB4; Thu, 30 Jan 2025 15:20:19 +0000 (UTC) ARC-Seal: i=1; s=arc-2022; d=mailchannels.net; t=1738250421; a=rsa-sha256; cv=none; b=5rcmDzgcyWgFETl/ro2kWPrhmT2IbvOL6AYf4aCteXuddpWOumQg7XeZ2aDI7H2dRtXu7M g9s3pXxAG0CsgnkS/DzH+XUskvbTe1c1HQpj6IaGNsc97X6aOy7QAfwi1v+L3GmnIP7+NK NfP/mOyw/dmomFLjl9+NglaA5v+GniPu42KtKcLlf5Q1eiOaRAK+ydlyvft/kXlFNoeGxK uqs0pUZmPPDljBQkAGKh6aHrJnb83+0k2Cuju1wF/p3wU6MFiOLlM2Clh/hyfXrCPfa68k ing9DSbhU3zNHwAIK2U9QnSe5j4/5gcMK8LEwn+v2VIMNN8/sGLTEF8rqKqk9A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=mailchannels.net; s=arc-2022; t=1738250421; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding; bh=w+MWPE56KzNy3p+yQf2ShkPS472Qgz6dzqJoNOZoCNU=; b=C5WLcnaKNehkTEVVlCQLUhlONiStV+1Ywu3DWEJKYYea3ufAy5yVaXJf2wrsWtzkqPyrbM DirAIgL2ErsHhjtQ0LV24VPL4QTK4CIvXHa9Sce0CzSXxMyNUl96Q/7Gb2C1l0j1m/zXkA 9OKCs+JvmzlCDTBUiJOdO4rm466gp3Io6SZMfhZRuThw0DVvZ9vh+his4DeJs6igCKr3E0 FidBFl2DeucAUp4pwfsNveCqAk7IgcI79VigxI20f3qVPvnFhhvQcPK15POfmOx3vPJN05 ANQMtAOcJo7I2dJliNNIKXVBAOB8ahf87W11CQd9wo+1g7pfl41gpmTDKBB6sA== ARC-Authentication-Results: i=1; rspamd-8586946c78-dn5z6; auth=pass smtp.auth=dreamhost smtp.mailfrom=siddhesh@sourceware.org Received: from pdx1-sub0-mail-a241.dreamhost.com (pop.dreamhost.com [64.90.62.162]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384) by 100.116.68.50 (trex/7.0.2); Thu, 30 Jan 2025 15:20:21 +0000 Received: from fedora.redhat.com (unknown [38.23.181.90]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) (Authenticated sender: siddhesh@gotplt.org) by pdx1-sub0-mail-a241.dreamhost.com (Postfix) with ESMTPSA id 4YkN4b1PyBz25; Thu, 30 Jan 2025 07:20:15 -0800 (PST) From: Siddhesh Poyarekar To: libc-alpha@sourceware.org Cc: carlos@redhat.com Subject: [PATCH] manual: Explain sched_yield semantics with different schedulers Date: Thu, 30 Jan 2025 10:20:10 -0500 Message-ID: <20250130152010.219924-1-siddhesh@sourceware.org> X-Mailer: git-send-email 2.47.1 MIME-Version: 1.0 X-Spam-Status: No, score=-1165.6 required=5.0 tests=BAYES_00, GIT_PATCH_0, KAM_DMARC_NONE, KAM_DMARC_STATUS, LOCAL_AUTHENTICATION_FAIL_DMARC, LOCAL_AUTHENTICATION_FAIL_SPF, RCVD_IN_DNSWL_NONE, SPF_HELO_NONE, SPF_SOFTFAIL, TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org X-BeenThere: libc-alpha@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Libc-alpha mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: libc-alpha-bounces~patchwork=sourceware.org@sourceware.org The manual entry for sched_yield mentions that the function call could be a nop if there are no other tasks with the same absolute priority. Expand the explanation to include example schedulers on Linux so that it's clear that sched_yield may not always result in a different task being scheduled. Signed-off-by: Siddhesh Poyarekar Reviewed-by: Joseph Myers --- manual/resource.texi | 34 +++++++++++++++++++++++----------- 1 file changed, 23 insertions(+), 11 deletions(-) diff --git a/manual/resource.texi b/manual/resource.texi index 0b82446817..260bfdb2e2 100644 --- a/manual/resource.texi +++ b/manual/resource.texi @@ -929,18 +929,30 @@ function, so there are no specific @code{errno} values. @c Direct syscall on Linux; alias to swtch on HURD. This function voluntarily gives up the task's claim on the CPU. - -Technically, @code{sched_yield} causes the calling task to be made -immediately ready to run (as opposed to running, which is what it was +Depending on the scheduling policy in effect and the tasks ready to run +on the system, another task may be scheduled to run instead. + +A call to @code{sched_yield} does not guarantee that a different task +from the calling task is scheduled as a result; it depends on the +scheduling policy used on the target system. It is possible that the +call may not result in any visible effect, i.e. the same task gets +scheduled again. + +For example on Linux systems, when a simple priority-based FIFO +scheduling policy (SCHED_FIFO) is in effect, the calling task is made +immediately ready to run (as oposed to running, which is what it was before). This means that if it has absolute priority higher than 0, it -gets pushed onto the tail of the queue of tasks that share its -absolute priority and are ready to run, and it will run again when its -turn next arrives. If its absolute priority is 0, it is more -complicated, but still has the effect of yielding the CPU to other -tasks. - -If there are no other tasks that share the calling task's absolute -priority, this function doesn't have any effect. +gets pushed onto the tail of the queue of tasks that share its absolute +priority and are ready to run, and it will run again when its turn next +arrives. If its absolute priority is 0, it is more complicated, but +still has the effect of yielding the CPU to other tasks. If there are +no other tasks that share the calling task's absolute priority, it will +be scheduled again as if @code{sched_yield} was never called. + +Another example could be a time slice based preemptive round-robin +policy, such as the SCHED_RR policy on Linux. It is possible with this +policy that the calling task is scheduled again because it still has +time left in its slice. To the extent that the containing program is oblivious to what other processes in the system are doing and how fast it executes, this