__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
-nosplit The thrsleep() and thrwakeup() syscalls were created by Ted Unangst <tedu@OpenBSD.org>. This manual page was written by Philip Guenther <guenther@OpenBSD.org>.