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
     sleep, tsleep, asleep, await, wakeup -- wait for events

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

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

     int
     asleep(void *ident, int priority, const char *wmesg, int timo);

     int
     await(int priority, int timo);

     void
     wakeup(void *ident);

     void
     wakeup_one(void *ident);

DESCRIPTION
     The functions tsleep() and	wakeup() handle	event-based process blocking.
     If	a process must wait for	an external event, it is put on	sleep by
     tsleep.  The parameter ident is an	arbitrary address that uniquely	iden-
     tifies the	event on which the process is being asleep.  All processes
     sleeping on a single ident	are woken up later by wakeup, often called
     from inside an interrupt routine, to indicate that	the resource the
     process was blocking on is	available now.

     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 wakeup_one() function is used to make the first process in the	queue
     that is sleeping on the parameter ident runnable.	This can prevent the
     system from becoming saturated when a large number	of processes are
     sleeping on the same address, but only one	of them	can actually do	any
     useful work when made runnable.

     Tsleep is the general sleep call.	Suspends the current process until a
     wakeup is performed on the	specified identifier.  The process will	then
     be	made runnable with the specified priority.  Sleeps at most timo	/ hz
     seconds (0	means no timeout).  If pri includes the	PCATCH flag, signals
     are checked before	and after sleeping, else signals are not checked.
     Returns 0 if awakened, EWOULDBLOCK	if the timeout expires.	 If PCATCH is
     set and a signal needs to be delivered, ERESTART is returned if the cur-
     rent system call should be	restarted if possible, and EINTR is returned
     if	the system call	should be interrupted by the signal (return EINTR).

     Asleep implements the new asynchronous sleep function.  It	takes the same
     arguments as tsleep() and places the process on the appropriate wait
     queue, but	asleep() leaves	the process runnable and returns immediately.
     The caller	is then	expected to, at	some point in the future, call await()
     to	actually wait for the previously queued	wait condition.	 If asleep()
     is	called several times, only the most recent call	is effective.
     asleep() may be called with an ident value	of NULL	to remove any previ-
     ously queued condition.

     Await implements the new asynchronous wait	function.  When	asleep() is
     called on an identifier it	associates the process with that identifier
     but does not block.  await() will actually	block the process until
     wakeup() is called	on that	identifier any time after the asleep().	 If
     wakeup() is called	after you asleep() but before you await() then the
     await() call is effectively a NOP.	 If await() is called multiple times
     without an	intervening asleep(), the await() is effectively a NOP but
     will also call mswitch() for safety.  The await() function	allows you to
     override the priority and timeout values to be used.  If the value	-1 is
     specified for an argument,	the value is taken from	the previous asleep()
     call.  If -1 is passed for	the priority you must be prepared to catch
     signal conditions if the prior call to asleep() specified it in its pri-
     ority.  If	-1 is passed for the timeout you must be prepared to catch a
     timeout condition if the prior call to asleep() specified a timeout.
     When you use -1, it is usually a good idea	to not make assumptions	as to
     the arguments used	by the prior asleep() call.

     The asleep() and await() functions	are mainly used	by the kernel to shift
     the burden	of blocking away from extremely	low level routines and to push
     it	onto their callers.  This in turn allows more complex interlocking
     code to backout of	a temporary resource failure (such as lack of memory)
     in	order to release major locks prior to actually blocking, and to	then
     retry the operation on wakeup.  This key feature is expected to be	heav-
     ily used in SMP situations	in order to allow code to make better use of
     spinlocks.	 A spinlock, by	its very nature, cannot	be used	around code
     that might	block.	It is hoped that these capabilities will make it eas-
     ier to migrate the	SMP master locks deeper	into the kernel.

     These routines may	also be	used to	avoid nasty spl*() calls to get	around
     race conditions with simple conditional test/wait interlocks.  You	simply
     call asleep() prior to your test, then conditionally await() only if the
     test fails.  It is	usually	a good idea to cancel an asleep() if you wind
     up	never calling the related await(), but it is not required.  If you do
     not want to waste cpu calling asleep() unnecessarily, you can surround
     the whole thing with a second test.  The race condition is	still handled
     by	the inside asleep() call.

RETURN VALUES
     See above.

SEE ALSO
     ps(1), malloc(9)

HISTORY
     The sleep/wakeup process synchronization mechanism	is very	old.  It
     appeared in a very	early version of Unix.

     Tsleep appeared in	4.4BSD.

     Asleep/await first	appeared in FreeBSD 3.0	and is designed	to shift the
     burden of blocking	away from extremely low	level routines and push	it up
     to	their callers.

     Sleep used	to be the traditional form.  It	doesn't	let you	specify	a
     timeout or	a wmesg, hence it has been discontinued.

AUTHORS
     This man page was written by Jorg Wunsch.	Asleep and await were designed
     and written by Matthew Dillon.

FreeBSD	9.2		       December	17, 1998		   FreeBSD 9.2

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

Want to link to this manual page? Use this URL:
<http://www.freebsd.org/cgi/man.cgi?query=sleep&sektion=9&manpath=FreeBSD+4.8-RELEASE>

home | help