man2/sched_yield.2

   1 .\" Copyright (C) Tom Bjorkholm & Markus Kuhn, 1996
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-2.0-or-later
   4 .\"
   5 .\" 1996-04-01 Tom Bjorkholm <tomb@mydata.se>
   6 .\"            First version written
   7 .\" 1996-04-10 Markus Kuhn <mskuhn@cip.informatik.uni-erlangen.de>
   8 .\"            revision
   9 .\"
  10 .TH SCHED_YIELD 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  11 .SH NAME
  12 sched_yield \- yield the processor
  13 .SH LIBRARY
  14 Standard C library
  15 .RI ( libc ", " \-lc )
  16 .SH SYNOPSIS
  17 .nf
  18 .B #include <sched.h>
  19 .PP
  20 .B int sched_yield(void);
  21 .fi
  22 .SH DESCRIPTION
  23 .BR sched_yield ()
  24 causes the calling thread to relinquish the CPU.
  25 The thread is moved to the end of the queue for its static
  26 priority and a new thread gets to run.
  27 .SH RETURN VALUE
  28 On success,
  29 .BR sched_yield ()
  30 returns 0.
  31 On error, \-1 is returned, and
  32 .I errno
  33 is set to indicate the error.
  34 .SH ERRORS
  35 In the Linux implementation,
  36 .BR sched_yield ()
  37 always succeeds.
  38 .SH STANDARDS
  39 POSIX.1-2001, POSIX.1-2008.
  40 .SH NOTES
  41 If the calling thread is the only thread in the highest
  42 priority list at that time,
  43 it will continue to run after a call to
  44 .BR sched_yield ().
  45 .PP
  46 POSIX systems on which
  47 .BR sched_yield ()
  48 is available define
  49 .B _POSIX_PRIORITY_SCHEDULING
  50 in
  51 .IR <unistd.h> .
  52 .PP
  53 Strategic calls to
  54 .BR sched_yield ()
  55 can improve performance by giving other threads or processes
  56 a chance to run when (heavily) contended resources (e.g., mutexes)
  57 have been released by the caller.
  58 Avoid calling
  59 .BR sched_yield ()
  60 unnecessarily or inappropriately
  61 (e.g., when resources needed by other
  62 schedulable threads are still held by the caller),
  63 since doing so will result in unnecessary context switches,
  64 which will degrade system performance.
  65 .PP
  66 .BR sched_yield ()
  67 is intended for use with real-time scheduling policies (i.e.,
  68 .B SCHED_FIFO
  69 or
  70 .BR SCHED_RR ).
  71 Use of
  72 .BR sched_yield ()
  73 with nondeterministic scheduling policies such as
  74 .B SCHED_OTHER
  75 is unspecified and very likely means your application design is broken.
  76 .SH SEE ALSO
  77 .BR sched (7)