Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SLEEP(9)	       FreeBSD Kernel Developer's Manual	      SLEEP(9)

NAME
     msleep, msleep_sbt, msleep_spin, msleep_spin_sbt, pause, pause_sbt,
     tsleep, tsleep_sbt, wakeup	-- wait	for events

SYNOPSIS
     #include <sys/param.h>
     #include <sys/systm.h>
     #include <sys/proc.h>

     int
     msleep(void *chan,	struct mtx *mtx, int priority, const char *wmesg,
	 int timo);

     int
     msleep_sbt(void *chan, struct mtx *mtx, int priority, const char *wmesg,
	 sbintime_t sbt, sbintime_t pr,	int flags);

     int
     msleep_spin(void *chan, struct mtx	*mtx, const char *wmesg, int timo);

     int
     msleep_spin_sbt(void *chan, struct	mtx *mtx, const	char *wmesg,
	 sbintime_t sbt, sbintime_t pr,	int flags);

     void
     pause(const char *wmesg, int timo);

     void
     pause_sbt(const char *wmesg, sbintime_t sbt, sbintime_t pr, int flags);

     int
     tsleep(void *chan,	int priority, const char *wmesg, int timo);

     int
     tsleep_sbt(void *chan, int	priority, const	char *wmesg, sbintime_t	sbt,
	 sbintime_t pr,	int flags);

     void
     wakeup(void *chan);

     void
     wakeup_one(void *chan);

DESCRIPTION
     The functions tsleep(), msleep(), msleep_spin(), pause(), wakeup(), and
     wakeup_one() handle event-based thread blocking.  If a thread must	wait
     for an external event, it is put to sleep by tsleep(), msleep(),
     msleep_spin(), or pause().	 Threads may also wait using one of the	lock-
     ing primitive sleep routines mtx_sleep(9),	rw_sleep(9), or	sx_sleep(9).

     The parameter chan	is an arbitrary	address	that uniquely identifies the
     event on which the	thread is being	put to sleep.  All threads sleeping on
     a single chan are woken up	later by wakeup(), often called	from inside an
     interrupt routine,	to indicate that the resource the thread was blocking
     on	is available now.

     The parameter priority specifies a	new priority for the thread as well as
     some optional flags.  If the new priority is not 0, then the thread will
     be	made runnable with the specified priority when it resumes.  PZERO
     should never be used, as it is for	compatibility only.  A new priority of
     0 means to	use the	thread's current priority when it is made runnable
     again.

     If	priority includes the PCATCH flag, pending signals are allowed to
     interrupt the sleep, otherwise pending signals are	ignored	during the
     sleep.  If	PCATCH is set and a signal becomes pending, ERESTART is
     returned if the current system call should	be restarted if	possible, and
     EINTR is returned if the system call should be interrupted	by the signal
     (return EINTR).  If the PBDRY flag	is specified in	addition to PCATCH,
     then the sleeping thread is not stopped when SIGSTOP becomes pending or
     some other	stop action occurs while it is sleeping.  Instead, it is woken
     up, with the assumption that the stop will	occur on reaching a stop point
     when returning to usermode.  The flag should be used when the sleeping
     thread owns resources, for	instance vnode locks, that should be released
     in	a timely fashion.

     The parameter wmesg is a string describing	the sleep condition for	tools
     like ps(1).  Due to the limited space of those programs to	display	arbi-
     trary strings, this message should	not be longer than 6 characters.

     The parameter timo	specifies a timeout for	the sleep.  If timo is not 0,
     then the thread will sleep	for at most timo / hz seconds.	If the timeout
     expires, then the sleep function will return EWOULDBLOCK.

     msleep_sbt(), msleep_spin_sbt(), pause_sbt() and tsleep_sbt() functions
     take sbt parameter	instead	of timo.  It allows the	caller to specify rel-
     ative or absolute wakeup time with	higher resolution in form of
     sbintime_t.  The parameter	pr allows the caller to	specify	wanted abso-
     lute event	precision.  The	parameter flags	allows the caller to pass
     additional	callout_reset_sbt() flags.

     Several of	the sleep functions including msleep(),	msleep_spin(), and the
     locking primitive sleep routines specify an additional lock parameter.
     The lock will be released before sleeping and reacquired before the sleep
     routine returns.  If priority includes the	PDROP flag, then the lock will
     not be reacquired before returning.  The lock is used to ensure that a
     condition can be checked atomically, and that the current thread can be
     suspended without missing a change	to the condition, or an	associated
     wakeup.  In addition, all of the sleep routines will fully	drop the Giant
     mutex (even if recursed) while the	thread is suspended and	will reacquire
     the Giant mutex before the	function returns.  Note	that the Giant mutex
     may be specified as the lock to drop.  In that case, however, the PDROP
     flag is not allowed.

     To	avoid lost wakeups, either a lock should be used to protect against
     races, or a timeout should	be specified to	place an upper bound on	the
     delay due to a lost wakeup.  As a result, the tsleep() function should
     only be invoked with a timeout of 0 when the Giant	mutex is held.

     The msleep() function requires that mtx reference a default, i.e. non-
     spin, mutex.  Its use is deprecated in favor of mtx_sleep(9) which	pro-
     vides identical behavior.

     The msleep_spin() function	requires that mtx reference a spin mutex.  The
     msleep_spin() function does not accept a priority parameter and thus does
     not support changing the current thread's priority, the PDROP flag, or
     catching signals via the PCATCH flag.

     The pause() function is a wrapper around tsleep() that suspends execution
     of	the current thread for the indicated timeout.  The thread can not be
     awakened early by signals or calls	to wakeup() or wakeup_one().

     The wakeup_one() function makes the first thread in the queue that	is
     sleeping on the parameter chan runnable.  This reduces the	load when a
     large number of threads are sleeping on the same address, but only	one of
     them can actually do any useful work when made runnable.

     Due to the	way it works, the wakeup_one() function	requires that only
     related threads sleep on a	specific chan address.	It is the programmer's
     responsibility to choose a	unique chan value.  The	older wakeup() func-
     tion did not require this,	though it was never good practice for threads
     to	share a	chan value.  When converting from wakeup() to wakeup_one(),
     pay particular attention to ensure	that no	other threads wait on the same
     chan.

RETURN VALUES
     When awakened by a	call to	wakeup() or wakeup_one(), if a signal is pend-
     ing and PCATCH is specified, a non-zero error code	is returned.  If the
     thread is awakened	by a call to wakeup() or wakeup_one(), the msleep(),
     msleep_spin(), tsleep(), and locking primitive sleep functions return 0.
     Otherwise,	a non-zero error code is returned.

ERRORS
     msleep(), msleep_spin(), tsleep(),	and the	locking	primitive sleep	func-
     tions will	fail if:

     [EINTR]		The PCATCH flag	was specified, a signal	was caught,
			and the	system call should be interrupted.

     [ERESTART]		The PCATCH flag	was specified, a signal	was caught,
			and the	system call should be restarted.

     [EWOULDBLOCK]	A non-zero timeout was specified and the timeout
			expired.

SEE ALSO
     ps(1), locking(9),	malloc(9), mi_switch(9), mtx_sleep(9), rw_sleep(9),
     sx_sleep(9), timeout(9)

HISTORY
     The functions sleep() and wakeup()	were present in	Version	1 AT&T UNIX.
     They were probably	also present in	the preceding PDP-7 version of UNIX.
     They were the basic process synchronization model.

     The tsleep() function appeared in 4.4BSD and added	the parameters wmesg
     and timo.	The sleep() function was removed in FreeBSD 2.2.  The
     wakeup_one() function appeared in FreeBSD 2.2.  The msleep() function
     appeared in FreeBSD 5.0, and the msleep_spin() function appeared in
     FreeBSD 6.2.  The pause() function	appeared in FreeBSD 7.0.

AUTHORS
     This manual page was written by Jorg Wunsch <joerg@FreeBSD.org>.

FreeBSD	10.1		       February	19, 2013		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tsleep&manpath=FreeBSD+10.0-RELEASE>

home | help