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

FreeBSD Manual Pages

  
 
  

home | help
SLEEPQUEUE(9)		 BSD Kernel Developer's	Manual		 SLEEPQUEUE(9)

NAME
     init_sleepqueues, sleepq_abort, sleepq_add, sleepq_alloc,
     sleepq_broadcast, sleepq_calc_signal_retval, sleepq_catch_signals,
     sleepq_free, sleepq_lookup, sleepq_release, sleepq_remove,	sleepq_signal,
     sleepq_set_timeout, sleepq_timedwait, sleepq_timedwait_sig, sleepq_wait,
     sleepq_wait_sig --	manage the queues of sleeping threads

SYNOPSIS
     #include <sys/param.h>
     #include <sys/sleepqueue.h>

     void
     init_sleepqueues(void);

     void
     sleepq_abort(struct thread	*td);

     void
     sleepq_add(struct sleepqueue *sq, void *wchan, struct mtx *lock,
	 const char *wmesg, int	flags);

     struct sleepqueue *
     sleepq_alloc(void);

     void
     sleepq_broadcast(void *wchan, int flags, int pri);

     int
     sleepq_calc_signal_retval(int sig);

     int
     sleepq_catch_signals(void *wchan);

     void
     sleepq_free(struct	sleepqueue *sq);

     struct sleepqueue *
     sleepq_lookup(void	*wchan);

     void
     sleepq_release(void *wchan);

     void
     sleepq_remove(struct thread *td, void *wchan);

     void
     sleepq_signal(void	*wchan,	int flags, int pri);

     void
     sleepq_set_timeout(void *wchan, int timo);

     int
     sleepq_timedwait(void *wchan, int signal_caught);

     int
     sleepq_timedwait_sig(void *wchan, int signal_caught);

     void
     sleepq_wait(void *wchan);

     int
     sleepq_wait_sig(void *wchan);

DESCRIPTION
     Sleep queues provide a mechanism for suspending execution of a thread un-
     til some condition	is met.	 Each queue is associated with a specific wait
     channel when it is	active,	and only one queue may be associated with a
     wait channel at any given point in	time.  An active queue holds a list of
     threads that are blocked on the associated	wait channel.  Threads that
     are not blocked on	a wait channel have an associated inactive sleep
     queue.  When a thread blocks on a wait channel it donates its inactive
     sleep queue to the	wait channel.  When a thread is	resumed, the wait
     channel that it was blocked on gives it an	inactive sleep queue for later
     use.  The sleepq_alloc() allocates	an inactive sleep queue	and is used to
     assign a sleep queue to a thread during thread creation.  The
     sleepq_free() function frees the resources	associated with	an inactive
     sleep queue and is	used to	free a queue during thread destruction.

     Active sleep queues are stored in a hash table hashed on the addresses
     pointed to	by wait	channels.  Each	bucket in the hash table contains a
     sleep queue chain.	 A sleep queue chain contains a	spin mutex and a list
     of	sleep queues that hash to that specific	chain.	Active sleep queues
     are protected by their chain's spin mutex.	 The init_sleepqueues()	func-
     tion initializes the hash table of	sleep queue chains.

     The sleepq_lookup() function locks	the sleep queue	chain associated with
     wchan and returns a pointer to the	current	active sleep queue for that
     wait channel or NULL if there currently is	not an active sleep queue.
     The sleepq_release() function unlocks the sleep queue chain associated
     with wchan() and is primarily useful when aborting	a pending sleep	re-
     quest before one of the wait functions is called.

     The sleepq_add() function places the current thread on the	sleep queue
     associated	with the wait channel wchan.  The associated sleep queue chain
     must be locked by a call to sleepq_lookup() when this function is called
     and its return value should be passed as the sq parameter.	 If a mutex is
     specified via the lock argument, then the sleep queue code	will perform
     extra checks to ensure that the mutex is held for all threads sleeping on
     wchan.  The wmesg parameter should	be a short description of wchan.  The
     flags parameter currently only specifies the type of sleep	queue being
     slept on.	A value	of 0 indicates a sleep queue used by msleep(9) and a
     value of SLEEPQ_CONDVAR indicates a sleep queue used by condvar(9).  A
     timeout on	the sleep may be specified by calling sleepq_set_timeout() af-
     ter sleepq_add().	The wchan parameter should be the same value from the
     preceding call to sleepq_add().  The timo parameter should	specify	the
     timeout value in ticks.  The thread may be	marked interruptible by	call-
     ing sleepq_catch_signals()	with wchan set to the wait channel.  The func-
     tion returns a signal number if there are any pending signals for the
     current thread and	0 if there is not a pending signal.

     Once the thread is	ready to suspend, one of the wait functions is called
     to	put the	thread to sleep	until it is awakened and context switch	to an-
     other thread.  The	sleepq_wait() function is used for non-interruptible
     sleeps that do not	have a timeout.	 The sleepq_timedwait()	function is
     used for non-interruptible	sleeps that have had a timeout set via
     sleepq_set_timeout().  The	sleepq_wait_sig() function is used for inter-
     ruptible sleeps that do not have a	timeout.  The sleepq_timedwait_sig()
     function is used for interruptible	sleeps that do have a timeout set.
     The wchan argument	to all of the wait functions is	the wait channel being
     slept on.	The signal_caught parameter to the timed wait functions	speci-
     fies if a previous	call to	sleepq_catch_signals() found a pending signal.

     When the thread is	resumed, the wait functions return a non-zero value if
     the thread	was awakened due to an interrupt other than a signal or	a
     timeout.  If the sleep timed out, then EWOULDBLOCK	is returned.  If the
     sleep was interrupted by something	other than a signal, then some other
     return value will be returned.  If	zero is	returned after resuming	from
     an	interruptible sleep, then sleepq_calc_signal_retval() should be	called
     to	determine if the sleep was interrupted by a signal.  If	so,
     sleepq_calc_signal_retval() returns ERESTART if the interrupting signal
     is	restartable and	EINTR otherwise.  If the sleep was not interrupted by
     a signal, sleepq_calc_signal_retval() will	return 0.

     A sleeping	thread is normally resumed by the sleepq_broadcast() and
     sleepq_signal() functions.	 The sleepq_signal() function awakens the
     highest priority thread sleeping on a wait	channel	while
     sleepq_broadcast()	awakens	all of the threads sleeping on a wait channel.
     The wchan argument	specifics which	wait channel to	awaken.	 The flags ar-
     gument should match the flags argument passed to sleepq_add() by the
     threads sleeping on the wait channel.  If the pri argument	does not equal
     -1, then each thread that is awakened will	have its priority raised to
     pri if it has a lower priority.

     A thread in an interruptible sleep	can be interrupted by another thread
     via the sleepq_abort() function.  The td argument specifies the thread to
     interrupt.	 An individual thread can also be awakened from	sleeping on a
     specific wait channel via the sleepq_remove() function.  The td argument
     specifies the thread to awaken and	the wchan argument specifies the wait
     channel to	awaken it from.	 If the	thread td is not blocked on the	the
     wait channel wchan	then this function will	not do anything, even if the
     thread is asleep on a different wait channel.  This function should only
     be	used if	one of the other functions above is not	sufficient.  One pos-
     sible use is waking up a specific thread from a widely shared sleep chan-
     nel.

     The sleep queue interface is currently used to implement the msleep(9)
     and condvar(9) interfaces.	 Almost	all other code in the kernel should
     use one of	those interfaces rather	than manipulating sleep	queues di-
     rectly.

SEE ALSO
     condvar(9), msleep(9), runqueue(9), scheduler(9)

BSD				March 10, 2004				   BSD

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO

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

home | help