How does the function pthread_yield work?

Question

I am implementing a threads library in C and I am stuck on the meaning of pthread_yield(). I have looked it up on the man page in the terminal but I did not really understand the explanation. Could someone explain it to me?

Answer 1

Note well that its name notwithstanding, pthread_yield is not standardized. Its Linux manual page says this, for example:

This call is nonstandard, but present on several other systems. Use the standardized sched_yield(2) instead.

The specifications for sched_yield() are written in much the same terms as those of pthread_yield(), however:

The sched_yield() function shall force the running thread to relinquish the processor until it again becomes the head of its thread list. It takes no arguments.

This just means that the thread that calls the function allows other threads and processes a chance to run, waiting to resume until its turn comes again. It is not necessary to do this in a preemptive multitasking system such as pthreads is designed around -- the kernel manages assigning CPU time to threads and processes without any such help -- but there may occasionally be special cases where it smooths out thread scheduling issues.

Answer 2

In the GLIBC, pthread_yield merely invokes sched_yield() system call (cf. nptl/pthread_yield.c in the source tree of the library):

/* With the 1-on-1 model we implement this function is equivalent to
   the 'sched_yield' function.  */
int
pthread_yield (void)
{
  return sched_yield ();
}

As you are implementing a thread library, note that the above GLIBC source code (2.31 version) of pthread_yield() results in an unusual pthread API behavior which may be an implementation bug as it returns directly the result of sched_yield(). Like most of the Linux system calls, the latter returns -1 and sets errno if it fails (even if the manual specifies that it actually never returns in error). So, theoretically, this makes pthread_yield() return -1 and set errno in case of error although the pthread API usually returns 0 if successful and the error number in case of error (errno is not supposed to be set). So, the manual is wrong or at least does not comply with the GLIBC's implementation when it describes the returned value as:

RETURN VALUE
On success, pthread_yield() returns 0; on error, it returns an error number.

The expected source code could be something like:

int
pthread_yield (void)
{
  return sched_yield() == -1 ? errno : 0;
}

For example, pthread_sigmask() is coded as:

int
pthread_sigmask (int how, const sigset_t *newmask, sigset_t *oldmask)
{
[...]
  return sigprocmask (how, newmask, oldmask) == -1 ? errno : 0;
[...]
}

which complies with what is stated in the manual:

RETURN VALUE
On success, pthread_sigmask() returns 0; on error, it returns an error number.