__THRSLEEP(2) | 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 <tedu@OpenBSD.org>. This manual page was written by Philip Guenther <guenther@OpenBSD.org>.

April 24, 2018 | Debian