.\" This manpage has been automatically generated by docbook2man 
.\" from a DocBook document.  This tool can be found at:
.\" <http://shell.ipoline.com/~elmert/comp/docbook2X/> 
.\" Please send any bug reports, improvements, comments, patches, 
.\" etc. to Steve Cheng <steve@ggi-project.org>.
.\"
.\" Traducido por Juan Piernas <piernas en ditec.um.es> el 5-febrero-2005
.\"
.TH "FUTEX" "2" "31 diciembre 2002" "" ""
.SH NOMBRE
futex \- llamada al sistema para bloqueos rápidos en espacio de usuario
.SH SINOPSIS
.sp
.B "#include <linux/futex.h>"
.sp
.B "#include <sys/time.h>"
.sp
.BI "int sys_futex (void *" futex ", int " op ", int " val ", const struct timespec *" timeout );
.SH "DESCRIPCIÓN"
.PP
La llamada al sistema \fBsys_futex\fR proporciona un método que
permite a un programa esperar hasta que cambie el valor de una
dirección dada y un método para despertar a cualquier proceso que esté
esperando en una dirección particular (aunque las direcciones para una
misma zona de memoria en procesos separados pueden no ser iguales, el
núcleo las proyecta internamente para que la misma memoria proyectada
en direcciones distintas concuerde para diferentes llamadas
\fBsys_futex\fR). Típicamente se usa para implementar el caso de
contienda de un bloqueo en memoria compartida, como se describe en
\fBfutex\fR(4).
.PP
Cuando una operación
\fBfutex\fR(4)
termina con contienda en espacio de usuario, es necesario hacer una
llamada al núcleo para que arbitre. El arbitraje puede significar o
bloquear al proceso invocador o, contrariamente, despertar a un
proceso bloqueado.
.PP
Se espera que los procesos que llamen a esta función se adhieran a la
semántica que se expone en \fBfutex\fR(4). Ya que esta semántica
supone escribir instrucciones en ensamblador no (trans)portables, esto a su
vez probablemente significa que la mayoría de los usuarios serán de
hecho autores de bibliotecas y no desarrolladores genéricos de
aplicaciones.
.PP
Es necesario que el argumento \fIfutex\fR apunte a un entero alineado
que almacene el contador. La operación a ejecutar se pasa a través del
parámetro \fIop\fR junto con un valor \fIval\fR.
.PP
Actualmente se definen tres operaciones:
.TP
\fBFUTEX_WAIT\fR
Esta operación verifica atómicamente si la dirección \fIfutex\fR
contiene todavía el valor dado y bloquea al proceso a la espera de
\fIFUTEX_WAKE\fR en esta dirección \fIfutex\fR. Si el argumento 
\fItimeout\fR no es NULL, su contenido describe la duración máxima de
la espera, que es infinita en otro caso. Para \fBfutex\fR(4), esta
llamada se ejecuta si al decrementar el contador se obtuvo un valor
negativo (indicando contención) y se bloqueará hasta que otro proceso
libere el \fIfutex\fR y ejecute la operación FUTEX_WAKE.
.TP
\fBFUTEX_WAKE\fR
Esta operación despierta, como mucho, \fIval\fR procesos que esperan en
esta dirección \fIfutex\fR (es decir, dentro de \fIFUTEX_WAIT\fR).
Para \fBfutex\fR(4), esta llamada se ejecuta si al incrementar el
contador se vio que había procesos esperando una vez que al
\fIfutex\fR se le ha asignado el valor 1 (indicando que está
disponible).
.TP
\fBFUTEX_FD\fR
Para soportar despertares asíncronos, esta operación asocia un
descriptor de fichero con un \fIfutex\fR. Si otro proceso ejecuta un
FUTEX_WAKE, el proceso recibirá el número de señal que se pasó en
\fIval\fR. El proceso invocador debe cerrar el descriptor de fichero
devuelto después de su uso.

Para evitar condiciones de carrera, el invocador debe comprobar si se
ha incrementado el \fIfutex\fR después de que FUTEX_FD regrese.
.SH "VALOR DEVUELTO"
.PP
Dependiendo de la operación que se haya ejecutado, el valor devuelto
puede tener significados diferentes.
.TP
\fBFUTEX_WAIT\fR
Devuelve 0 si el proceso fue despertado por una llamada FUTEX_WAKE. En
el caso de que haya expirado el plazo, se devuelve ETIMEDOUT. Si el
\fIfutex\fR no era igual al valor esperado, la operación devuelve
EWOULDBLOCK. Las señales (u otros falsos despertares) hacen que
FUTEX_WAIT devuelva EINTR.
.TP
\fBFUTEX_WAKE\fR
Devuelve el número de procesos despertados.
.TP
\fBFUTEX_FD\fR
Devuelve el nuevo descriptor de fichero asociado al \fIfutex\fR.
.SH "OBSERVACIONES"
.PP
Insistimos, los \fIfutexes\fR, en su forma más básica, no están
pensados como abstracción sencilla para los usuarios finales. Es de
esperar que los implementadores sean buenos conocedores de ensamblador
y que hayan leído los fuentes de la biblioteca de \fIfutex\fR en
espacio de usuario que se indica más abajo.
.SH "AUTORES"
.PP
Los \fIfutexes\fR fueron diseñados e implementados por Hubertus Franke
(IBM Thomas J. Watson Research Center), Matthew Kirkwood, Ingo Molnar
(Red Hat) y Rusty Russell (IBM Linux Technology Center). Esta página
fue escrita por Bert Hubert.
.SH "VERSIONES"
.PP
El soporte inicial para \fIfutex\fR se añadió a la versión 2.5.7 de
Linux pero con una semántica distinta a la descrita más arriba. La
semántica actual se encuentra disponible desde la versión 2.5.40 de
Linux.
.SH "VÉASE TAMBIÉN"
.PP
\fBfutex\fR(4), 
`Fuss, Futexes and Furwocks: Fast Userlevel Locking in Linux' (actas
del Ottawa Linux Symposium 2002), 
biblioteca de ejemplo de \fIfutex\fR, futex-*.tar.bz2
<URL:ftp://ftp.nl.kernel.org:/pub/linux/kernel/people/rusty/>.