__THRSLEEP(2) FreeBSD System Calls Manual __THRSLEEP(2)
NAME
__thrsleep, __thrwakeup - userspace thread sleep and wakeup
SYNOPSIS
#include <sys/time.h>
int
__thrsleep(const volatile void *id, clockid_t clock_id,
const struct timespec *abstime, void *lock, const int *abort);
int
__thrwakeup(const volatile void *id, int count);
DESCRIPTION
The __thrsleep() and __thrwakeup() functions provide thread sleep and
wakeup primitives with which synchronization primitives such as mutexes
and condition variables can be implemented. __thrsleep() blocks the
calling thread on the abstract "wait channel" identified by the id
argument until another thread calls __thrwakeup() with the same id value.
If the abstime argument is not NULL, then it specifies an absolute time,
measured against the clock_id clock, after which __thrsleep() should time
out and return. If the specified time is in the past then __thrsleep()
will return immediately without blocking.
The lock argument, if not NULL, points to a locked spinlock that will be
unlocked by __thrsleep() atomically with respect to calls to
__thrwakeup(), such that if another thread locks the spinlock before
calling __thrwakeup() with the same id, then the thread that called
__thrsleep() will be eligible for being woken up and unblocked.
The abort argument, if not NULL, points to an int that will be examined
after unlocking the spinlock pointed to by lock and immediately before
blocking. If that int is non-zero then __thrsleep() will immediately
return EINTR without blocking. This provides a mechanism for a signal
handler to keep a call to __thrsleep() from blocking, even if the signal
is delivered immediately before the call.
The __thrwakeup() function unblocks one or more threads that are sleeping
on the wait channel identified by id. The number of threads unblocked is
specified by the count argument, except that if zero is specified then
all threads sleeping on that id are unblocked.
RETURN VALUES
__thrsleep() will return zero if woken by a matching call to
__thrwakeup(), otherwise an error number will be returned to indicate the
error.
__thrwakeup() will return zero if at least one matching call to
__thrsleep() was unblocked, otherwise an error number will be returned to
indicate the error.
ERRORS
__thrsleep() and __thrwakeup() will fail if:
[EINVAL] The ident argument is NULL.
In addition, __thrsleep() may return one of the following errors:
[EWOULDBLOCK] The time specified by the abstime and clock_id
arguments was reached.
[EINTR] A signal arrived or the abort argument pointed to a
non-zero value.
[ECANCELED] A signal arrived and SA_RESTART was set.
[EINVAL] The clock_id argument is not a valid clock_gettime(2)
clock id or abstime specified a nanosecond value less
than zero or greater than 1000 million.
__thrwakeup() may return the following error:
[ESRCH] No threads calling __thrsleep() with the same id were
found.
SEE ALSO
sigaction(2), pthread_cond_wait(3), pthread_mutex_lock(3), tsleep(9)
STANDARDS
The __thrsleep() and __thrwakeup() functions are specific to OpenBSD and
should not be used in portable applications.
HISTORY
The thrsleep() and thrwakeup() syscalls appeared in OpenBSD 3.9. The
clock_id and abstime arguments were added in OpenBSD 4.9. The functions
were renamed to __thrsleep() and __thrwakeup() and the abort argument was
added in OpenBSD 5.1
AUTHORS
The thrsleep() and thrwakeup() syscalls were created by Ted Unangst
<
[email protected]>. This manual page was written by Philip Guenther
<
[email protected]>.
FreeBSD 14.1-RELEASE-p8 April 24, 2018 FreeBSD 14.1-RELEASE-p8