PTHREAD_SETCANCELSTATE(3)

ИМЯ
pthread_setcancelstate, pthread_setcanceltype - изменяет состояния и тип отменяемости

ОБЗОР
#include <pthread.h>

int pthread_setcancelstate(int state, int *oldstate);
int pthread_setcanceltype(int type, int *oldtype);

Компилируется и компонуется вместе с -pthread.

ОПИСАНИЕ
Функция pthread_setcancelstate() изменяет состояние отменяемости вызывающий нити на значение state. Предыдущее состояние отменяемости нити возвращается в буфер, на который указывает oldstate. Аргументом state должно быть одно из следующих значений:

PTHREAD_CANCEL_ENABLE
    Нить является отменяемой. Для всех новых нитей, включая начальную, это состояние является основным по умолчанию. Тип отменяемости нити определяет, когда нить будет отвечать на запрос об отмене.

PTHREAD_CANCEL_DISABLE
    Нить является неотменяемой. Если был получен запрос об отмене, он будет блокироваться до тех пор, пока не будет включена отменяемость.

Функция pthread_setcanceltype() изменяет тип отменяемости вызывающий нити на значение type. Предыдущий тип отменяемости нити возвращается в буфер, на который указывает oldstate. Аргументом type должно быть одно из следующих значений:

PTHREAD_CANCEL_DEFERRED
    Запрос отменяемости откладывается до тех пор, пока нить не вызовет функцию, являющуюся точкой отмены (смотрите pthreads(7)). Данный тип является умолчательным для всех нитей, включая начальную.

PTHREAD_CANCEL_ASYNCHRONOUS
    Нить может быть отменена в любой момент (практически сразу же после получения запроса об отмене, однако система не гарантирует этого).

Операции установки и получения (set-and-get), выполняемые каждой из этих функций, являются атомарными для предотвращения пересечения с другими процессами, вызывающими ту же функцию.

ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении эти функции возвращают 0; при ошибке возвращается ненулевой номер ошибки.

ОШИБКИ
Функция pthread_setcancelstate() может завершиться со следующей ошибкой:

EINVAL
    Неправильное значение для state.

Функция pthread_setcanceltype() может завершиться со следующей ошибкой:

EINVAL
    Неправильное значение для type.

АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
Интерфейс | Атрибут | Значение
pthread_setcancelstate(), pthread_setcanceltype() | Безвредность в нитях | MT-Safe
pthread_setcancelstate(), pthread_setcanceltype() | Async-cancel-safety | AC-Safe

СООТВЕТСТВИЕ СТАНДАРТАМ
POSIX.1-2001, POSIX.1-2008.

ЗАМЕЧАНИЯ
Информацию о том, что происходит с отменяемой нитью, смотрите в pthread_cancel(3).

Запрет отмены на короткое время полезен, если нить выполняет какое-то важное действие, которое не должно прерываться запросом отмены. Остерегайтесь запретов отмены на длительный срок или для операций, которые могут занять много времени, так как нить при этом перестанет отвечать на запросы отмены.

  Асинхронная отменяемость
Задание типа отменяемости PTHREAD_CANCEL_ASYNCHRONOUS полезно редко. Так как нить может быть отменена в любой момент, невозможно безопасно резервировать ресурсы (например, выделять память с помощью malloc(3)), захватывать мьютексы, семафоры или блокировки и так далее. Резервирование ресурсов небезопасно, так как приложение не может узнать состояние этих ресурсов при отмене нити; то есть, произошла ли отмена до резервирования ресурсов, во время из резервирования или после их освобождения? Кроме того, некоторые внутренние структуры данных (например, связные списки свободных блоков, управляемые семейством функций malloc(3)) могут остаться в не целостном состоянии, если отмена происходит в середине вызова функции. Следовательно, обработчики очистки перестают быть полезными.

Функции, которые можно безопасно асинхронно отменять называются функциями async-cancel-safe. В POSIX.1-2001 и POSIX.1-2008 требуется, чтобы такими функция были только pthread_cancel(3), pthread_setcancelstate() и pthread_setcanceltype(). В общем, другие функции библиотеки нельзя безопасно вызывать из асинхронно отменяемой нити.

Одной из нескольких ситуаций, в которых асинхронная отменяемость полезна, является отменяемость нити, которая находится в цикле, занимающимся только вычислениями.

  Замечания о переносимости
Реализации нитей в Linux позволяют присваивать аргументу oldstate функции pthread_setcancelstate() значение NULL; в этом случае информация о предыдущем состоянии отмены не возвращается вызывающему. Многие другие реализации также допускают NULL в качестве значения oldstat, но POSIX.1 этот случай не рассматривается, поэтому переносимые приложения должны всегда указывать в oldstate значение, отличное от NULL. Эти утверждения относятся и к аргументу oldtype функции pthread_setcanceltype().

ПРИМЕР
Смотрите pthread_cancel(3).

СМОТРИТЕ ТАКЖЕ
pthread_cancel(3), pthread_cleanup_push(3), pthread_testcancel(3), pthreads(7)