1mt.h(3) Library Functions Manual mt.h(3)
2
6 mt.h - Поддержка многозадачности
7
10 #include 'bee2/defs.h'
11 Определения типов
14 typedef bool_t mt_mtx_t
15 Мьютекс
16 Функции
18 bool_t mtMtxCreate (mt_mtx_t *mtx)
19 Создание мьютекса
20 bool_t mtMtxIsValid (const mt_mtx_t *mtx)
21 Корректный мьютекс?
22 void mtMtxLock (mt_mtx_t *mtx)
23 Блокировка мьютекса
24 void mtMtxUnlock (mt_mtx_t *mtx)
25 Разблокировка мьютекса
26 void mtMtxClose (mt_mtx_t *mtx)
27 Закрытие мьютекса
28 void mtSleep (u32 ms)
29 Приостановка потока
30 bool_t mtCallOnce (size_t *once, void(*fn)())
31 Вызов один раз
32 size_t mtAtomicIncr (size_t *ctr)
33 Атомарный инкремент
34 size_t mtAtomicDecr (size_t *ctr)
35 Атомарный декремент
36 size_t mtAtomicCmpSwap (size_t *ctr, size_t cmp, size_t swap)
37 Атомарное сравнение с заменой
38
40 Предусловие
41 Все входные указатели действительны, если не оговорено противное.
42
44 Мьютексы — это объект, который может находиться в одном из двух
45 состояний — 'заблокирован' или 'разблокирован'. Поток блокирует мьютекс
46 с помощью функций mtMtxLock(), mtMtxTryLock() и снимает блокировку с
47 помощью функции mtMtxUnlock(). Заблокировать можно только
48 разблокированный мьютекс. Поэтому вызов mtMtxLock() повлечет
49 приостановку выполнения потока вплоть до разблокировки мьютекса.
50 С помощью мьютексов можно синхронизировать доступ к общим объектам
52 потоков. Перед досупом к объекту каждый из потоков должен заблокировать
53 мьютекс, а после операции над объектом разблокировать его.
54 Управление мьютексами реализуется по схемам, заданным в стандарте языка
56 Си ISO/IEC 9899:2011 (см. заголовочный файл threads.h).
57 Интерфейс мьютексов упрощен по сравнению со стандартом: ошибки при
59 блокировке и разблокировке мьютекса не предполагаются.
60 Если операционная система не распознана, то мьютексы будут
62 'положительно пустыми': они всегда будут успешно создаваться,
63 блокироваться и разблокироваться, хотя за этими действиями не будет
64 стоять никакого функционала.
65 Прим.
67 В реализации для Windows используются облегченные мьютексы -- так
68 называемые критические секции (critical sections).
69
71 Управление потоками реализуется по схемам, заданным в стандарте языка
72 Си ISO/IEC 9899:2011 (см. заголовочный файл threads.h).
73
75 Операции выполняются над счетчиками типа size_t, представленными
76 указателями. Операции атомарны в том смысле, что счетчик защищен от
77 изменения в других потоках вплоть до завершения операции.
78 Предупреждения
80 Если указатель на счетчик не выровнен на границу size_t, то
81 поведение функций может быть непредсказуемым.
82
84 mt_mtx_t
86 size_t mtAtomicCmpSwap (size_t * ctr, size_t cmp, size_t swap)
87 Счетчик ctr атомарно сравнивается с cmp и, в случае совпадения,
88 устанавливается равным swap.
89 Возвращает
91 Первоначальное значение счетчика.
92 Аргументы
94 ctr счетчик
95 cmp сравниваемое значение
96 swap новое значение
97 size_t mtAtomicDecr (size_t * ctr)
99 Счетчик ctr атомарно уменьшается на 1.
100 Прим.
102 Возможно переполнение (снизу, undeflow).
103 Возвращает
105 Новое значение счетчика.
106 Аргументы
108 ctr счетчик
109 size_t mtAtomicIncr (size_t * ctr)
111 Счетчик ctr атомарно увеличивается на 1.
112 Прим.
114 Возможно переполнение (сверху, overflow).
115 Возвращает
117 Новое значение счетчика.
118 Аргументы
120 ctr счетчик
121 bool_t mtCallOnce (size_t * once, void(*)() fn)
123 Функция fn() вызывается в точности один раз даже в ситуации
124 конкурентных запросов на вызов из разных потоков. Для контроля
125 однократности вызова используется триггер once, первоначально нулевой.
126 Ожидается
128 Триггер once инициализируется нулем и не меняется за пределами
129 функции.
130 Возвращает
132 TRUE, если fn() успешно вызвана в данном или предыдущем обращении к
133 mtCallOnce(), и FALSE в противном случае.
134 Аргументы
136 once триггер
137 fn функция
138 void mtMtxClose (mt_mtx_t * mtx)
140 Мьютекс mtx закрывается.
141 Предусловие
143 Мьютекс корректен и не заблокирован.
144 mtMtxClose() < mtMtxCreate().
146 Прим.
148 Закрытие заблокированного мьютекса может привести к непредсказуемым
149 последствиям.
150 Аргументы
152 mtx мьютекс
153 bool_t mtMtxCreate (mt_mtx_t * mtx)
155 Создается мьютекс mtx.
156 Возвращает
158 Признак успеха.
159 Постусловие
161 В случае успеха мьютекс корректен.
162 Аргументы
164 mtx мьютекс
165 bool_t mtMtxIsValid (const mt_mtx_t * mtx)
167 Проверяется корректность мьютекса mtx.
168 Возвращает
170 Признак корректности.
171 Аргументы
173 mtx мьютекс
174 void mtMtxLock (mt_mtx_t * mtx)
176 Мьютекс mtx блокируется.
177 Предусловие
179 Мьютекс корректен.
180 Прим.
182 Если мьютекс заблокирован в момент вызова, то ожидается снятие
183 блокировки (в другом потоке).
184 Аргументы
186 mtx мьютекс
187 void mtMtxUnlock (mt_mtx_t * mtx)
189 Мьютекс mtx разблокируется.
190 Предусловие
192 mtMtxUnlock() < mtMtxLock().
193 Мьютекс корректен.
195 Аргументы
197 mtx мьютекс
198 void mtSleep (u32 ms)
200 Текущий поток приостанавливается на ms миллисекунд.
201 Прим.
203 1 секунда = 10^3 миллисекунд = 10^6 микросекунд = 10^9 наносекунд.
204 Если операционная система не распознана или операционная система не
206 поддерживает многозадачность, то приостановки не будет.
207 Аргументы
209 ms число миллисекунд
210
212 Автоматически создано Doxygen для Библиотека Bee2 из исходного текста.
213Библиотека Bee2 Пт 23 Июн 2023 mt.h(3)