FreeBSD 4.11 manual page repository

FreeBSD is a free computer operating system based on BSD UNIX originally. Many IT companies, like DeployIS is using it to provide an up-to-date, stable operating system.

sleep, tsleep, asleep, await, wakeup - wait for events

 

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 pro‐
      cess 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 priority includes the PCATCH flag, sig‐
      nals 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.
      See above.
      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 Jörg Wunsch.  Asleep and await were designed
      and written by Matthew Dillon.
 

Sections

Based on BSD UNIX
FreeBSD is an advanced operating system for x86 compatible (including Pentium and Athlon), amd64 compatible (including Opteron, Athlon64, and EM64T), UltraSPARC, IA-64, PC-98 and ARM architectures. It is derived from BSD, the version of UNIX developed at the University of California, Berkeley. It is developed and maintained by a large team of individuals. Additional platforms are in various stages of development.