---

   futex - быстрая блокировка в пользовательском пространстве

---

В аргументе timeout задаётся время ожидания захвата блокировки. Он рассматривается как абсолютное время, отсчитываемое по часам CLOCK_REALTIME. Если timeout равно NULL, то операция может быть в блокировке бесконечно долго.

Аргументы uaddr2, val и val3 игнорируются.

FUTEX_TRYLOCK_PI (начиная с Linux 2.6.18) Эта операция пытается получить блокировку по адресу uaddr. Она вызывается, когда не удалось выполнить атомарное получение из пользовательского пространства, так как слово фьютекса не равно 0.

Так как ядро имеет больший доступ к информации о состоянии, чем пользовательское пространство, получение блокировки из ядра может осуществиться, в случаях когда слово фьютекса (т. е., информация о состоянии доступна из пользовательского пространства) устарело (FUTEX_WAITERS и/или FUTEX_OWNER_DIED). Это может случиться, если владелец фьютекса неожиданно завершился. Пользовательское пространство не может учесть это событие не получив состязательности, но ядро может решить данную проблему и получить блокировку.

Аргументы uaddr2, val, timeout и val3 игнорируются.

FUTEX_UNLOCK_PI (начиная с Linux 2.6.18) Данная операция будит ожидающего с самым высоким приоритетом, который ждёт фьютекс по адресу из uaddr посредством операции FUTEX_LOCK_PI.

Операция вызывается, когда значение по адресу uaddr пользовательского пространства невозможно изменить атомарно с TID (владельца) на 0.

Аргументы uaddr2, val, timeout и val3 игнорируются.

FUTEX_CMP_REQUEUE_PI (начиная с Linux 2.6.31) Данная операция является PI-аналогом операции FUTEX_CMP_REQUEUE. Она перестанавливает ожидающих, заблокированных с помощью FUTEX_WAIT_REQUEUE_PI для uaddr, из очереди не PI-фьютекса источника (uaddr) в очередь PI-фьютекса назначения (uaddr2).

Как и FUTEX_CMP_REQUEUE, эта операция пробуждает не более val ожидающих, которые ждут фьютекса по адресу uaddr. Однако у FUTEX_CMP_REQUEUE_PI значение val должно быть равно 1 (чтобы избежать «нашествия орды»). Оставшиеся ожидающие удаляются из очереди ожидания фьютекса-источника по адресу uaddr и добавляются в очередь ожидания фьютекса-назначения по адресу uaddr2.

Аргументы val2 и val3 служат тем же целям, что и в FUTEX_CMP_REQUEUE.

FUTEX_WAIT_REQUEUE_PI (начиная с Linux 2.6.31) Ждать не PI-фьютекса по адресу uaddr и, потенциально быть перемещённым в очередь (при операции FUTEX_CMP_REQUEUE_PI из другой задачи) PI-фьютекса по адресу uaddr2. Операция ожидания на адресе uaddr такая же как для FUTEX_WAIT.

Ожидающий может быть удалён из ожидающих на адресе uaddr перемещения в очередь у uaddr2 при операции FUTEX_WAKE из другой задачи. В этом случае операция FUTEX_WAIT_REQUEUE_PI завершается с ошибкой EAGAIN.

Если значение timeout не равно NULL, то им определяется длительность операции ожидания; данное значение имеет тот же смысл, что и в описании выше к параметру FUTEX_CLOCK_REALTIME. Если timeout равно NULL, то операция может блокироваться бесконечно.

Аргумент val3 игнорируется.

Операции FUTEX_WAIT_REQUEUE_PI и FUTEX_CMP_REQUEUE_PI добавлены для довольно узкого варианта применения — поддержки переменных условия нитей POSIX с наследованием приоритета. Идея в том, что эти операции всегда должны использоваться попарно, для поддержания синхронизации между пользовательским пространством и ядром. То есть в операции FUTEX_WAIT_REQUEUE_PI приложение пользовательского пространства заранее задаёт назначение для перемещения в очередь, которое проводится операцией FUTEX_CMP_REQUEUE_PI.

---

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ

В случае ошибки (предполагается, что futex() был вызван через syscall(2)), все операции возвращают -1 и присваивают errno номер ошибки.

При успешном выполнении возвращаемое значение зависит от операции:

FUTEX_WAIT Значение 0 возвращается, если вызывающий был разбужен. Заметим, что пробуждение также может быть вызвано часто используемыми вариантами использования фьютексов в не связанном коде, которое случается, если память под слово фьютекса использовалась ранее (например, при типичной реализации фьютексов на основе мьютексов Pthreads это может возникать при определённых условиях). Поэтому вызывающий всегда должен консервативно предполагать, что возвращаемое значение 0 может означать побочное пробуждение (spurious wake-up), и учитывать значение слово фьютекса (т. е. схема с синхронизацией пользовательского пространства) при принятии решения нужна дальнейшее ожидание или нет.

FUTEX_WAKE Возвращается количество разбуженных ожидающих.

FUTEX_FD Возвращается новый файловый дескриптор, связанный с фьютексом.

FUTEX_REQUEUE Возвращается количество разбуженных ожидающих.

FUTEX_CMP_REQUEUE Возвращается общее количество ожидающих, которые будятся или перемещаются в очередь фьютекса, у которого слово фьютекса задано по адресу uaddr2. Если это значение больше чем val, то разница это количество ожидающих, перемещённых в очередь фьютекса, у которого слово фьютекса задано по адресу uaddr2.

FUTEX_WAKE_OP Возвращается общее количество разбуженных ожидающих. Это сумма разбуженных ожидающих у двух фьютексов для слов фьютексов по адресам uaddr и uaddr2.

FUTEX_WAIT_BITSET Возвращается 0, если вызывающий был разбужен. Смотрите в описании FUTEX_WAIT, как это правильно учитывать на практике.

FUTEX_WAKE_BITSET Возвращается количество разбуженных ожидающих.

FUTEX_LOCK_PI Возвращается 0, если фьютекс был успешно заблокирован.

FUTEX_TRYLOCK_PI Возвращается 0, если фьютекс был успешно заблокирован.

FUTEX_UNLOCK_PI Возвращается 0, если фьютекс был успешно разблокирован.

FUTEX_CMP_REQUEUE_PI Возвращается общее количество ожидающих, которые будятся или перемещаются в очередь фьютекса, у которого слово фьютекса задано по адресу uaddr2. Если это значение больше чем val, то разница это количество ожидающих, перемещённых в очередь фьютекса, у которого слово фьютекса задано по адресу uaddr2.

FUTEX_WAIT_REQUEUE_PI Возвращается 0, если вызывающий был успешно перемещён в очередь фьютекса со словом фьютекса по адресу uaddr2.

---

ОШИБКИ

EACCES Нет доступа на чтение памяти слова фьютекса.

EAGAIN (FUTEX_WAIT, FUTEX_WAIT_BITSET, FUTEX_WAIT_REQUEUE_PI) Значение, на которое указывает uaddr, не было равно ожидаемому значению val на момент вызова.

Замечание: в Linux символические имена EAGAIN и EWOULDBLOCK (оба есть в разных частях кода фьютекса ядра) имеют одинаковое значение.

EAGAIN (FUTEX_CMP_REQUEUE, FUTEX_CMP_REQUEUE_PI) Значение, на которое указывает uaddr, не равно ожидаемому значению val3.

EAGAIN (FUTEX_LOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_CMP_REQUEUE_PI) ID нити владельца фьютекса по адресу uaddr (для FUTEX_CMP_REQUEUE_PI — uaddr2) вскоре закончит работу, но не выполнил очистку внутреннего состояния. Попробуйте ещё раз.

EDEADLK (FUTEX_LOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_CMP_REQUEUE_PI) Слово фьютекса по адресу uaddr уже заблокировано вызывающим.

EDEADLK (FUTEX_CMP_REQUEUE_PI) Во время перемещения в другую очередь ожидающего PI-фьютекса со словом фьютекса по адресу uaddr2 ядро обнаружило тупиковую блокировку (deadlock).

EFAULT Требуемый аргумент указателя (т. е., uaddr, uaddr2 или timeout) не указывает на допустимый адрес пользовательского пространства.

EINTR Операция FUTEX_WAIT или FUTEX_WAIT_BITSET была прервана сигналом (смотрите signal(7)). В ядрах до версии Linux 2.6.22 эта ошибка также возвращалась при побочном пробуждении; начиная с Linux 2.6.22 этого больше не происходит.

EINVAL Операция в futex_op является одной из тех, что используют ожидание (timeout), но значение аргумента timeout некорректно (tv_sec меньше нуля или tv_nsec больше 1000000000).

EINVAL Операция, указанная в futex_op, использует один или оба указателя uaddr и uaddr2, но один из них не указывает на корректный объект, то есть адрес не выровнен по четырёх байтовой границе.

EINVAL (FUTEX_WAIT_BITSET, FUTEX_WAKE_BITSET) Битовая маска, указанная в val3, равна нулю.

EINVAL (FUTEX_CMP_REQUEUE_PI) Значение uaddr равно uaddr2 (т. е., предпринята попытка выполнить перемещение в одну и ту же очередь).

EINVAL (FUTEX_FD) В val указан некорректный номер сигнала.

EINVAL (FUTEX_WAKE, FUTEX_WAKE_OP, FUTEX_WAKE_BITSET, FUTEX_REQUEUE, FUTEX_CMP_REQUEUE) Ядро обнаружило противоречие между состояние в пользовательском пространстве по адресу uaddr и состоянием в ядре, то есть обнаружило, что ожидающий ждёт посредством операции FUTEX_LOCK_PI на адресе uaddr.

EINVAL (FUTEX_LOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_UNLOCK_PI) Ядро обнаружило противоречие между состояние в пользовательском пространстве по адресу uaddr и состоянием в ядре. Это указывает на поврежденное значение состояния или что ядро обнаружило ожидающего на адресе uaddr, который делает это посредством операции FUTEX_WAIT или FUTEX_WAIT_BITSET.

EINVAL (FUTEX_CMP_REQUEUE_PI) Ядро обнаружило противоречие между состояние в пользовательском пространстве по адресу uaddr2 и состоянием в ядре, то есть обнаружило, что ожидающий ждёт посредством операции FUTEX_WAIT или FUTEX_WAIT_BITSET на адресе uaddr2.

EINVAL (FUTEX_CMP_REQUEUE_PI) Ядро обнаружило противоречие между состояние в пользовательском пространстве по адресу uaddr и состоянием в ядре, то есть обнаружило, что ожидающий ждёт посредством операции FUTEX_WAIT или FUTEX_WAIT_BITESET на адресе uaddr.

EINVAL (FUTEX_CMP_REQUEUE_PI) Ядро обнаружило противоречие между состояние в пользовательском пространстве по адресу uaddr и состоянием в ядре, то есть обнаружило, что ожидающий ждёт посредством операции FUTEX_LOCK_PI на адресе uaddr (вместо FUTEX_WAIT_REQUEUE_PI).

EINVAL (FUTEX_CMP_REQUEUE_PI) Предпринята попытка выполнить перемещение ожидающего на фьютекс, отличный от указанного в соответствующем вызове FUTEX_WAIT_REQUEUE_PI для этого вызывающего.

EINVAL (FUTEX_CMP_REQUEUE_PI) Значение аргумента val не равно 1.

EINVAL Неверный аргумент.

ENOMEM (FUTEX_LOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_CMP_REQUEUE_PI) Ядро не может выделить память для хранения информации о состоянии.

ENFILE (FUTEX_FD) Достигнуто ограничение на общее количество открытых файлов в системе.

ENOSYS В futex_op задана неверная операция.

ENOSYS В futex_op был указан параметр FUTEX_CLOCK_REALTIME, но сопутствующая операция не равна FUTEX_WAIT_BITSET или FUTEX_WAIT_REQUEUE_PI.

ENOSYS (FUTEX_LOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_UNLOCK_PI, FUTEX_CMP_REQUEUE_PI, FUTEX_WAIT_REQUEUE_PI) Проверка во время выполнения обнаружила, что операция недоступна. Операции с PI-фьютексами реализованы не на всех архитектурах и не поддерживаются на некоторых моделях ЦП.

EPERM (FUTEX_LOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_CMP_REQUEUE_PI) Вызывающему запрещено самостоятельно присоединяться к фьютексу по адресу uaddr (для FUTEX_CMP_REQUEUE_PI: фьютексу по адресу uaddr2) (это может быть вызвано повреждением состояния в пользовательском пространстве).

EPERM (FUTEX_UNLOCK_PI) Вызывающему не принадлежит блокировка, представленная в слове фьютекса.

ESRCH (FUTEX_LOCK_PI, FUTEX_TRYLOCK_PI, FUTEX_CMP_REQUEUE_PI) Идентификатор нити из слова фьютекса по адресу uaddr не существует.

ESRCH (FUTEX_CMP_REQUEUE_PI) Идентификатор нити из слова фьютекса по адресу uaddr2 не существует.

ETIMEDOUT Операция в futex_op использует время ожидания, указанное в timeout, и время истекло до завершения операции.

ВЕРСИИ

Фьютексы появились в стабильном ядре Linux версии 2.6.0.

Начальная поддержка фьютексов была встроена в Linux 2.5.7, но с другой семантикой, отличающейся от описанной выше. Семантика системного вызова с четырьмя аргументами, описанная в этой странице, появилась в Linux 2.5.40. Пятый аргумент была добавлен в Linux 2.5.70, а шестой аргумент был добавлен в Linux 2.6.7.

---

СООТВЕТСТВИЕ СТАНДАРТАМ

---

ЗАМЕЧАНИЯ

На основе фьютексов было реализовано несколько высокоуровневых программных абстракций, например, семафоры POSIX и различные механизмы синхронизации нитей POSIX (мьютексы, переменные условий, блокировки чтения-записи и барьеры).

---

ПРИМЕР

$ ./futex_demo
Родитель (18534) 0
Потомок  (18535) 0
Родитель (18534) 1
Потомок  (18535) 1
Родитель (18534) 2
Потомок  (18535) 2
Родитель (18534) 3
Потомок  (18535) 3
Родитель (18534) 4
Потомок  (18535) 4

Исходный код программы

/* futex_demo.c
   Использование: futex_demo [nloops]
                    (по умолчанию: 5)
   Продемонстрировано использование фьютексов в программе, где родитель
   и потомок используют пару фьютексов, расположенных в общем анонимном
   отображении, для синхронизации доступа к общему ресурсу: терминалу.
   Каждый из процессов записывает num-loops на терминал и использует
   протокол синхронизации, который гарантирует, что они выполняют запись
   поочерёдно.
*/
#define _GNU_SOURCE
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/wait.h>
#include <sys/mman.h>
#include <sys/syscall.h>
#include <linux/futex.h>
#include <sys/time.h>
#define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \
                        } while (0)
static int *futex1, *futex2, *iaddr;
static int
futex(int *uaddr, int futex_op, int val,
      const struct timespec *timeout, int *uaddr2, int val3)
{
    return syscall(SYS_futex, uaddr, futex_op, val,
                   timeout, uaddr, val3);
}
/* Получить фьютекс, указанный 'futexp': подождать пока его
   значение не станет 1, и изменить значение на 0. */
static void
fwait(int *futexp)
{
    int s;
    /* __sync_bool_compare_and_swap(ptr, oldval, newval) — встроенная
       функция gcc. Она атомарно выполняет эквивалент кода:
           if (*ptr == oldval)
               *ptr = newval;
       Она возвращает true, если тест вернул true и было обновлено *ptr.
       Вместо неё здесь можно было бы использовать эквивалентные
       атомарные инструкции процессора. Подробней смотрите в
       руководстве по GCC. */
    while (1) {
        /* фьютекс доступен? */
        if (__sync_bool_compare_and_swap(futexp, 1, 0))
            break;      /* да */
        /* фьютекс недоступен, ждём */
        s = futex(futexp, FUTEX_WAIT, 0, NULL, NULL, 0);
        if (s == -1 && errno != EAGAIN)
            errExit("futex-FUTEX_WAIT");
    }
}
/* Освобождаем фьютекс, указанный в 'futexp': если значение фьютекса
   сейчас равно 0, то присваиваем ему 1 и пробуждаем ожидающий фьютекса,
   то есть, если вторая сторона заблокирована в fpost(), то она может
   продолжить работу. */
static void
fpost(int *futexp)
{
    int s;
    /* __sync_bool_compare_and_swap() описана в комментариях выше */
    if (__sync_bool_compare_and_swap(futexp, 0, 1)) {
        s = futex(futexp, FUTEX_WAKE, 1, NULL, NULL, 0);
        if (s  == -1)
            errExit("futex-FUTEX_WAKE");
    }
}
int
main(int argc, char *argv[])
{
    pid_t childPid;
    int j, nloops;
    setbuf(stdout, NULL);
    nloops = (argc > 1) ? atoi(argv[1]) : 5;
    /* Создаём общее анонимное отображение, в котором будем хранить
       фьютексы. Так как фьютексы совместно используются процессами,
       воспользуемся операциями с «общими» фьютексами (т. е., без
       суффикса «_PRIVATE»). */
    iaddr = mmap(NULL, sizeof(int) * 2, PROT_READ | PROT_WRITE,
                MAP_ANONYMOUS | MAP_SHARED, -1, 0);
    if (iaddr == MAP_FAILED)
        errExit("mmap");
    futex1 = &iaddr[0];
    futex2 = &iaddr[1];
    *futex1 = 0;        /* Состояние: недоступен */
    *futex2 = 1;        /* Состояние: доступен */
    /* Создаём дочерний процесс, который наследует общее анонимное
       отображение. */
    childPid = fork();
    if (childPid == -1)
        errExit("fork");
    if (childPid == 0) {        /* Child */
        for (j = 0; j < nloops; j++) {
            fwait(futex1);
            printf("Потомок  (%ld) %d\n", (long) getpid(), j);
            fpost(futex2);
        }
        exit(EXIT_SUCCESS);
    }
    /* предок попадает сюда */
    for (j = 0; j < nloops; j++) {
        fwait(futex2);
        printf("Родитель (%ld) %d\n", (long) getpid(), j);
        fpost(futex1);
    }
    wait(NULL);
    exit(EXIT_SUCCESS);
}