sys/sys/sleepqueue.h

   1 /*-
   2  * SPDX-License-Identifier: BSD-2-Clause-FreeBSD
   3  *
   4  * Copyright (c) 2004 John Baldwin <jhb@FreeBSD.org>
   5  *
   6  * Redistribution and use in source and binary forms, with or without
   7  * modification, are permitted provided that the following conditions
   8  * are met:
   9  * 1. Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  * 2. Redistributions in binary form must reproduce the above copyright
  12  *    notice, this list of conditions and the following disclaimer in the
  13  *    documentation and/or other materials provided with the distribution.
  14  *
  15  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  16  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  17  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  18  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  19  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  20  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  21  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  22  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  25  * SUCH DAMAGE.
  26  *
  27  * $FreeBSD$
  28  */
  29
  30 #ifndef _SYS_SLEEPQUEUE_H_
  31 #define _SYS_SLEEPQUEUE_H_
  32
  33 /*
  34  * Sleep queue interface.  Sleep/wakeup, condition variables, and sx
  35  * locks use a sleep queue for the queue of threads blocked on a sleep
  36  * channel.
  37  *
  38  * A thread calls sleepq_lock() to lock the sleep queue chain associated
  39  * with a given wait channel.  A thread can then call call sleepq_add() to
  40  * add themself onto a sleep queue and call one of the sleepq_wait()
  41  * functions to actually go to sleep.  If a thread needs to abort a sleep
  42  * operation it should call sleepq_release() to unlock the associated sleep
  43  * queue chain lock.  If the thread also needs to remove itself from a queue
  44  * it just enqueued itself on, it can use sleepq_remove() instead.
  45  *
  46  * If the thread only wishes to sleep for a limited amount of time, it can
  47  * call sleepq_set_timeout() after sleepq_add() to setup a timeout.  It
  48  * should then use one of the sleepq_timedwait() functions to block.
  49  *
  50  * A thread is normally resumed from a sleep queue by either the
  51  * sleepq_signal() or sleepq_broadcast() functions.  Sleepq_signal() wakes
  52  * the thread with the highest priority that is sleeping on the specified
  53  * wait channel.  Sleepq_broadcast() wakes all threads that are sleeping
  54  * on the specified wait channel.  A thread sleeping in an interruptible
  55  * sleep can be interrupted by calling sleepq_abort().  A thread can also
  56  * be removed from a specified sleep queue using the sleepq_remove()
  57  * function.  Note that the sleep queue chain must first be locked via
  58  * sleepq_lock() before calling sleepq_abort(), sleepq_broadcast(), or
  59  * sleepq_signal().  These routines each return a boolean that will be true
  60  * if at least one swapped-out thread was resumed.  In that case, the caller
  61  * is responsible for waking up the swapper by calling kick_proc0() after
  62  * releasing the sleep queue chain lock.
  63  *
  64  * Each thread allocates a sleep queue at thread creation via sleepq_alloc()
  65  * and releases it at thread destruction via sleepq_free().  Note that
  66  * a sleep queue is not tied to a specific thread and that the sleep queue
  67  * released at thread destruction may not be the same sleep queue that the
  68  * thread allocated when it was created.
  69  *
  70  * XXX: Some other parts of the kernel such as ithread sleeping may end up
  71  * using this interface as well (death to TDI_IWAIT!)
  72  */
  73
  74 struct lock_object;
  75 struct sleepqueue;
  76 struct thread;
  77
  78 #ifdef _KERNEL
  79
  80 #define SLEEPQ_TYPE             0x0ff           /* Mask of sleep queue types. */
  81 #define SLEEPQ_SLEEP            0x00            /* Used by sleep/wakeup. */
  82 #define SLEEPQ_CONDVAR          0x01            /* Used for a cv. */
  83 #define SLEEPQ_PAUSE            0x02            /* Used by pause. */
  84 #define SLEEPQ_SX               0x03            /* Used by an sx lock. */
  85 #define SLEEPQ_LK               0x04            /* Used by a lockmgr. */
  86 #define SLEEPQ_INTERRUPTIBLE    0x100           /* Sleep is interruptible. */
  87 #define SLEEPQ_UNFAIR           0x200           /* Unfair wakeup order. */
  88 #define SLEEPQ_DROP             0x400           /* Return without lock held. */
  89
  90 #if 0
  91 /* NOT APPLICABLE TO DRAGONFLY */
  92 struct sleepqueue *sleepq_alloc(void);
  93 void    sleepq_free(struct sleepqueue *sq);
  94 struct sleepqueue *sleepq_lookup(const void *wchan);
  95 #endif
  96
  97 void    sleepq_setup_thread(struct thread *td);
  98 void    sleepq_teardown_thread(struct thread *td);
  99
 100 void    sleepq_add(const void *wchan, struct lock_object *lock,
 101             const char *wmesg, int flags, int queue);
 102 int     sleepq_broadcast(const void *wchan, int flags, int pri, int queue);
 103 void    sleepq_lock(const void *wchan);
 104 void    sleepq_release(const void *wchan);
 105 #if 0
 106 /* NOT APPLICABLE TO DRAGONFLY */
 107 int     sleepq_abort(struct thread *td, int intrval);
 108 void    sleepq_chains_remove_matching(bool (*matches)(struct thread *));
 109 void    sleepq_remove(struct thread *td, const void *wchan);
 110 int     sleepq_remove_matching(struct sleepqueue *sq, int queue,
 111             bool (*matches)(struct thread *), int pri);
 112 void    sleepq_remove_nested(struct thread *td);
 113 #endif
 114 int     sleepq_signal(const void *wchan, int flags, int pri, int queue);
 115 void    sleepq_set_timeout_sbt(const void *wchan, sbintime_t sbt,
 116             sbintime_t pr, int flags);
 117 #define sleepq_set_timeout(wchan, timo)                                 \
 118     sleepq_set_timeout_sbt((wchan), tick_sbt * (timo), 0, C_HARDCLOCK)
 119 u_int   sleepq_sleepcnt(const void *wchan, int queue);
 120 int     sleepq_timedwait(const void *wchan, int pri);
 121 int     sleepq_timedwait_sig(const void *wchan, int pri);
 122 int     sleepq_type(const void *wchan);
 123 void    sleepq_wait(const void *wchan, int pri);
 124 int     sleepq_wait_sig(const void *wchan, int pri);
 125
 126 #endif  /* _KERNEL */
 127 #endif  /* !_SYS_SLEEPQUEUE_H_ */