'\" t
.\"     Title: waitqueue_active
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: January 2017
.\"    Manual: Driver Basics
.\"    Source: Kernel Hackers Manual 4.8.15
.\"  Language: English
.\"
.TH "WAITQUEUE_ACTIVE" "9" "January 2017" "Kernel Hackers Manual 4\&.8\&." "Driver Basics"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
waitqueue_active \- \- locklessly test for waiters on the queue
.SH "SYNOPSIS"
.HP \w'int\ waitqueue_active('u
.BI "int waitqueue_active(wait_queue_head_t\ *\ " "q" ");"
.SH "ARGUMENTS"
.PP
\fIq\fR
.RS 4
the waitqueue to test for waiters
.RE
.SH "DESCRIPTION"
.PP
returns true if the wait list is not empty
.SH "NOTE"
.PP
this function is lockless and requires care, incorrect usage _will_ lead to sporadic and non\-obvious failure\&.
.PP
Use either while holding wait_queue_head_t::lock or when used for wakeups with an extra
\fBsmp_mb\fR
like:
.PP
CPU0 \- waker CPU1 \- waiter
.PP
for (;;) {
\fIcond\fR
= true; prepare_to_wait(wq,
wait, state);
\fBsmp_mb\fR; //
\fBsmp_mb\fR
from
\fBset_current_state\fR
if (waitqueue_active(wq)) if (\fIcond\fR) wake_up(wq); break;
\fBschedule\fR; } finish_wait(wq,
wait);
.PP
Because without the explicit
\fBsmp_mb\fR
it\*(Aqs possible for the
\fBwaitqueue_active\fR
load to get hoisted over the
\fIcond\fR
store such that we\*(Aqll observe an empty wait list while the waiter might not observe
\fIcond\fR\&.
.PP
Also note that this \*(Aqoptimization\*(Aq trades a
\fBspin_lock\fR
for an
\fBsmp_mb\fR, which (when the lock is uncontended) are of roughly equal cost\&.
.SH "COPYRIGHT"
.br