mt.h - Man Page
Поддержка многозадачности
Synopsis
#include 'bee2/defs.h'
Определения типов
typedef bool_t mt_mtx_t
Мьютекс
Функции
bool_t mtMtxCreate (mt_mtx_t *mtx)
Создание мьютекса
bool_t mtMtxIsValid (const mt_mtx_t *mtx)
Корректный мьютекс?
void mtMtxLock (mt_mtx_t *mtx)
Блокировка мьютекса
void mtMtxUnlock (mt_mtx_t *mtx)
Разблокировка мьютекса
void mtMtxClose (mt_mtx_t *mtx)
Закрытие мьютекса
void mtSleep (u32 ms)
Приостановка потока
bool_t mtCallOnce (size_t *once, void(*fn)())
Вызов один раз
size_t mtAtomicIncr (size_t *ctr)
Атомарный инкремент
size_t mtAtomicDecr (size_t *ctr)
Атомарный декремент
size_t mtAtomicCmpSwap (size_t *ctr, size_t cmp, size_t swap)
Атомарное сравнение с заменой
Подробное описание
Предусловие
Все входные указатели действительны, если не оговорено противное.
Мьютексы
Мьютексы — это объект, который может находиться в одном из двух состояний — 'заблокирован' или 'разблокирован'. Поток блокирует мьютекс с помощью функций mtMtxLock(), mtMtxTryLock() и снимает блокировку с помощью функции mtMtxUnlock(). Заблокировать можно только разблокированный мьютекс. Поэтому вызов mtMtxLock() повлечет приостановку выполнения потока вплоть до разблокировки мьютекса.
С помощью мьютексов можно синхронизировать доступ к общим объектам потоков. Перед досупом к объекту каждый из потоков должен заблокировать мьютекс, а после операции над объектом разблокировать его.
Управление мьютексами реализуется по схемам, заданным в стандарте языка Си ISO/IEC 9899:2011 (см. заголовочный файл threads.h).
Интерфейс мьютексов упрощен по сравнению со стандартом: ошибки при блокировке и разблокировке мьютекса не предполагаются.
Если операционная система не распознана, то мьютексы будут 'положительно пустыми': они всегда будут успешно создаваться, блокироваться и разблокироваться, хотя за этими действиями не будет стоять никакого функционала.
Прим.
В реализации для Windows используются облегченные мьютексы -- так называемые критические секции (critical sections).
Управление потоками
Управление потоками реализуется по схемам, заданным в стандарте языка Си ISO/IEC 9899:2011 (см. заголовочный файл threads.h).
Элементарные атомарные операции
Операции выполняются над счетчиками типа size_t, представленными указателями. Операции атомарны в том смысле, что счетчик защищен от изменения в других потоках вплоть до завершения операции.
Предупреждения
Если указатель на счетчик не выровнен на границу size_t, то поведение функций может быть непредсказуемым.
Типы
mt_mtx_t
Функции
size_t mtAtomicCmpSwap (size_t * ctr, size_t cmp, size_t swap)
Счетчик ctr атомарно сравнивается с cmp и, в случае совпадения, устанавливается равным swap.
Возвращает
Первоначальное значение счетчика.
- Аргументы
ctr [in/out] счетчик
cmp сравниваемое значение
swap новое значение
size_t mtAtomicDecr (size_t * ctr)
Счетчик ctr атомарно уменьшается на 1.
Прим.
Возможно переполнение (снизу, undeflow).
Возвращает
Новое значение счетчика.
- Аргументы
ctr [in/out] счетчик
size_t mtAtomicIncr (size_t * ctr)
Счетчик ctr атомарно увеличивается на 1.
Прим.
Возможно переполнение (сверху, overflow).
Возвращает
Новое значение счетчика.
- Аргументы
ctr [in/out] счетчик
bool_t mtCallOnce (size_t * once, void(*)() fn)
Функция fn() вызывается в точности один раз даже в ситуации конкурентных запросов на вызов из разных потоков. Для контроля однократности вызова используется триггер once, первоначально нулевой.
Ожидается:\n Триггер once инициализируется нулем и не меняется за пределами
функции.
- Возвращает
TRUE, если fn() успешно вызвана в данном или предыдущем обращении к mtCallOnce(), и FALSE в противном случае.
- Аргументы
once [in/out] триггер
fn функция
void mtMtxClose (mt_mtx_t * mtx)
Мьютекс mtx закрывается.
Предусловие
Мьютекс корректен и не заблокирован.
mtMtxClose() < mtMtxCreate().
Прим.
Закрытие заблокированного мьютекса может привести к непредсказуемым последствиям.
- Аргументы
mtx [in/out] мьютекс
bool_t mtMtxCreate (mt_mtx_t * mtx)
Создается мьютекс mtx.
Возвращает
Признак успеха.
Постусловие
В случае успеха мьютекс корректен.
- Аргументы
mtx мьютекс
bool_t mtMtxIsValid (const mt_mtx_t * mtx)
Проверяется корректность мьютекса mtx.
Возвращает
Признак корректности.
- Аргументы
mtx мьютекс
void mtMtxLock (mt_mtx_t * mtx)
Мьютекс mtx блокируется.
Предусловие
Мьютекс корректен.
Прим.
Если мьютекс заблокирован в момент вызова, то ожидается снятие блокировки (в другом потоке).
- Аргументы
mtx [in/out] мьютекс
void mtMtxUnlock (mt_mtx_t * mtx)
Мьютекс mtx разблокируется.
- Предусловие
mtMtxUnlock() < mtMtxLock().
Мьютекс корректен.
- Аргументы
mtx [in/out] мьютекс
void mtSleep (u32 ms)
Текущий поток приостанавливается на ms миллисекунд.
Прим.
1 секунда = 10^3 миллисекунд = 10^6 микросекунд = 10^9 наносекунд.
Если операционная система не распознана или операционная система не поддерживает многозадачность, то приостановки не будет.
- Аргументы
ms число миллисекунд
Автор
Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.