DragonFly On-Line Manual Pages

Search: Section:  

SLEEP(9)              DragonFly Kernel Developer's Manual             SLEEP(9)


NAME

     tsleep, ssleep, lksleep, mtxsleep, zsleep, tsleep_interlock, wakeup,
     wakeup_one -- wait/sleep/block for events


SYNOPSIS

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

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

     int
     ssleep(const volatile void *ident, struct spinlock *spin, int flags,
         const char *wmesg, int timo);

     int
     lksleep(const volatile void *ident, struct lock *lock, int flags,
         const char *wmesg, int timo);

     int
     mtxsleep(const volatile void *ident, struct mtx *mtx, int flags,
         const char *wmesg, int timo);

     int
     zsleep(const volatile void *ident, struct lwkt_serialize *slz, int flags,
         const char *wmesg, int timo);

     void
     tsleep_interlock(const volatile void *ident, int flags);

     void
     wakeup(const volatile void *ident);

     void
     wakeup_one(const volatile void *ident);


DESCRIPTION

     The functions tsleep(), ssleep(), lksleep(), mtxsleep(), zsleep(), and
     wakeup() handle event-based process blocking.  If a process must wait for
     an external event, it is put on sleep by tsleep(), ssleep(), lksleep(),
     mtxsleep(), or zsleep().

     The parameter ident is an arbitrary address that uniquely identifies 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/thread 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
     arbitrary strings, this message should not be longer than 6 characters.

     The tsleep() function is general in its use and suspends the current
     process/thread until a wakeup is performed on the specified identifier.
     The process/thread will then be made runnable.  The process/thread will
     sleep at most timo / hz seconds (0 means no timeout).  If flags contains
     the PCATCH flag, signals are checked before and after sleeping, else
     signals are ignored.

     The tsleep_interlock() function is similar to tsleep(), in that it queues
     a thread on a sleep queue, but it does not actually put the thread to
     sleep.  This allows coupling tsleep with higher-level synchronization
     primitives.  The pattern is:

     (acquire high level synchronization primitive)
     (test condition of interest)
     tsleep_interlock(ident, flags)
     (release high level synchronization primitive)
     tsleep(..., flags | PINTERLOCKED, ...)

     For example, to implement ssleep():

     spin_lock(&important_lock);
     if (important_condition == 0) {
             tsleep_interlock(ident, flags);
             spin_unlock(&important_lock);
             tsleep(..., flags | PINTERLOCKED, ...);
     }

     The ssleep() function works like tsleep() while at the same time
     releasing the exclusive spinlock spin before sleeping and reacquiring it
     before ssleep() returns.  This is an atomic operation, which guarantees
     that a wakeup() interlocked by spin will not be missed.

     The lksleep() function works like tsleep() while at the same time
     releasing the exclusive lockmgr lock lock before sleeping and reacquiring
     it before lksleep() returns.  This is an atomic operation, which
     guarantees that a wakeup() interlocked by lock will not be missed.

     The mtxsleep() function works like tsleep() while at the same time
     atomically releasing the mutex mtx before sleeping and reacquiring it in
     exclusive state before mtxsleep() returns.

     The zsleep() function works like tsleep() while at the same time
     releasing the serializer slz before sleeping and reacquiring it before
     zsleep() returns.  This is an atomic operation, which guarantees that a
     wakeup() interlocked by slz will not be missed.

     The wakeup_one() function is used to make the first process/thread 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/threads are sleeping on the same address, but only one of them
     can actually do any useful work when made runnable.


IMPLEMENTATION NOTES

     Unlike FreeBSD, the tsleep() function in DragonFly ignores priority
     information because it is not required by the LWKT subsystem.  Sleeps
     without the LWP_SINTR flag set are assumed to be disk-waits, otherwise
     they are normal sleeps.


RETURN VALUES

     The tsleep() function returns 0 if awakened, otherwise an appropriate
     error code is returned.


FILES

     The various sleep functions are in /sys/kern/kern_synch.c.


ERRORS

     [EWOULDBLOCK]      The timeout expired.

     [ERESTART]         A signal needs to be delivered and the system call
                        should be restarted if possible.  This only happens if
                        PCATCH was set in flags.

     [EINTR]            The system call needs to be interrupted by the signal.
                        This only happens if PCATCH was set in flags.


SEE ALSO

     ps(1), kmalloc(9), serializer(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.

     ssleep() appeared in DragonFly 1.6, zsleep() in DragonFly 2.0, and
     lksleep() and mtxsleep() in DragonFly 2.3.


AUTHORS

     This manual page was written by Jorg Wunsch and modified for DragonFly by
     Hiten Pandya <hmp@dragonflybsd.org>.

DragonFly 4.5                  October 12, 2012                  DragonFly 4.5

Search: Section: