.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) Joe Korty, 2005
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 2 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, write to the Free
.\" Software Foundation, Inc., 59 Temple Place, Suite 330,
.\" Boston, MA 02111, USA.
.\"
.\" 2005-02-05 Joe Korty <joe.korty@ccur.com>
.\"            First version
.\"
.TH FULOCK_REQUEUE 2
.SH NAME
fulock_requeue \-
transfer all waiters on a fast user queue (fuqueue) to a fast user lock
(fulock).
.SH SYNOPSIS
.B #include <linux/fuqueue.h>
.br
.B #include <linux/fulock.h>
.sp
.BI "long fulock_requeue (volatile unsigned int *" vfuqueue ", unsigned int " val ", volatile unsigned int *" vfulock ", unsigned int " lockflags ")"
.SH DESCRIPTION
If
.I val
==
.IR "" "*" "vfuqueue"
then
.BR fulock_requeue
transfers all threads sleeping on
.I vfuqueue
to
.IR vfulock .
Otherwise nothing is transfered.  The transfered threads
remain sleeping on the same
.BR fuqueue_wait (2)
call, but now it takes a
.BR fulock_unlock (2)
against
.I vfulock
to awaken one of them,  rather than a
.BR fuqueue_wake (2)
against
.IR vfuqueue .
.PP
When so awakened, a transfered thread returns
.B FUQUEUE_WAITER_GOT_LOCK
from its returning
.BR fuqueue_wait (2)
call.  This indicates to the awakened thread that it is
now the owner (that is, has acquired) the fast user lock
that it had been transfered to.  It is up to the awakened
thread to know which fast user lock it now owns, and when
done with it, issue the appropriate
.BR fulock_unlock (2)
call.
.PP
A
.I vfulock
that is marked
.B EOWNERDEAD
or
.B ENOTRECOVERABLE
is not prevented from receiving transfered threads.
.PP
.I lockflags
defines optional features available to
.IR vfulock .
Its values and requirements for use may be found in
.BR fulock_lock (2).
.PP
The purpose of this service is to make possible an
efficient implementation of
.BR pthread_cond_broadcast (2)
that does not suffer from the 'stampeding herd' effect on
the the fast user lock.
.SH "RETURN VALUE"
Zero is returned on success.  Otherwise a small negative
number is returned to indicate that an error occurred and
its absolute value indicates the reason for the error.
.TP 3
.B EAGAIN
.I val
is not equal to
.IR "" "*" vfuqueue .
This test exists to implement atomicity in fuqueue handling,
see
.BR fuqueue_wait (2)
for a similar usage.
.TP
.B EINVAL
.I lockflags
has an invalid mix of set fields.
.TP
.B EINVAL
.I lockflags
is not compatible with past flags that have been applied to
.IR vfulock .
.TP
.B EINVAL
Either
.I vfuqueue
or
.I vfulock
is not properly memory aligned.
.TP
.B EPERM
The application does not have full read/write access to
the memory pointed to by
.I vfuqueue
or
.IR vfulock .
.TP
.B EFAULT
Either
.I vfulock
or
.I vfuqueue
points outside the user address space.
.TP
.B EACCES
The memory pointed to by
.I vfuqueue
or
.I vfulock
is IO not regular memory.
.TP
.B ENOMEM
Insufficient free memory available for this service to do
its job.
.SH CAVEATS
This service is intended to be used by implementors of
standard libraries rather than directly by application
writers.  As such the necessary header files may not be
present in the distribution, and it may be that no standard
library exports this interface to applications.
.SH "CONFORMS TO"
None.  This is a Linux extension.
.SH "SEE ALSO"
.BR fuqueue_wait (2),
.BR fuqueue_wake (2),
.BR fuqueue_ctl (2),
.BR fulock_lock (2),
.BR fulock_unlock (2),
.BR fulock_ctl (2),
.BR futex (2),
.BR futex (4).