====== OSA : Счетные семафоры ======

===== Введение =====
Счетные семафоры - переменные типа //unsigned char//, //unsigned int// или //unsigned long// (в зависимости от установки константы [[osa:ref:appendix:configuration|OS_CSEM_SIZE]] в ##[[osa:ref:appendix:configuration|OSAcfg.h]]##). Для того чтобы использовать счетные семафоры, в ##[[osa:ref:appendix:configuration|OSAcfg.h]]## нужно определить константу [[osa:ref:appendix:configuration|OS_ENABLE_CSEM]].

В программе счетный семафор определяется как переменная:
<code cpp>
OST_CSEM  mycsem;
</code>

<note>
Для HT-PICC16 счетные семафоры можно размещать только в банках bank0 и bank1.
</note>

Функционально счетные семафоры отличаются от [[osa:ref:services:binary_semaphores|бинарных]] тем, что могут принимать любое значение в диапазоне от 0 до максимального значения, допустимого типом семафора (255, 65535, 4294967295).

Перед работой со счетным семафором, его необходимо создать сервисом ##[[osa:ref:allservices:OS_Csem_Create|OS_Csem_Create]]##. После создания семафор имеет нулевое значение. Задача, ожидающая семафор, будет находиться в режиме ожидания до тех пор, пока семафор не станет ненулевым. Как только задача дождется этого события, она переходит в состояние готовности и при получении управления вычитает из семафора 1.

Значение семафора может быть изменено одним из сервисов **установки значения**. Следует обратить внимание на то, что эти сервисы делятся на 2 подгруппы: обычные (можно использовать только вне прерываний) и для работы в прерывании. Для того, чтобы пользоваться счетными семафорами внутри прерываний, в файле ##[[osa:ref:appendix:configuration|OSAcfg.h]]## нужно определить константу [[osa:ref:appendix:configuration|OS_ENABLE_INT]]

Отдельно можно выделить сервис ##[[osa:ref:allservices:OS_Csem_Signal|OS_Csem_Signal]]##. Этот сервис увеличивает счетный семафор на 1. Но если на момент вызова сервиса семафор уже имеет максимально допустимое значение, то установится флаг bEventError (проверяется сервисом ##[[osa:ref:allservices:OS_IsEventError|OS_IsEventError]]##), а семафор останется неизменным.

~~UP~~

===== Все сервисы для работы со счетными семафорами. =====

^  Сервис  ^  Аргументы  ^  Описание  ^  Свойства  ^
| **Создание**    ||||
| ##[[osa:ref:allservices:OS_Csem_Create|OS_Csem_Create]]##  |  ''(csem)''  | Подготавливает счетный семафор к работе (обнуляет его)  | {{osa:ref:attr_call_not_int.png|Нельзя вызывать из прерывания}}  |
| **Управление**  ||||
| ##[[osa:ref:allservices:OS_Csem_Signal|OS_Csem_Signal]]##  |  ''(csem)''  | Увеличивает значение семафора на 1 (с ожиданием при переполнении)  | {{osa:ref:attr_call_not_int.png|Нельзя вызывать из прерывания}}  |
| ##[[osa:ref:allservices:OS_Csem_Signal_Now|OS_Csem_Signal_Now]]##  |  ''(csem)''  | Увеличивает значение семафора на 1 (без ожидания при переполнении).  | {{osa:ref:attr_call_can_int.png|Есть расширенный сервис с суффиксом _I для работы в прерывании}}  |
| ##[[osa:ref:allservices:OS_Csem_Set|OS_Csem_Set]]##  |  ''(csem)''  | Устанавливаем счетный семафор в 1.  | {{osa:ref:attr_call_can_int.png|Есть расширенный сервис с суффиксом _I для работы в прерывании}}  |
| ##[[osa:ref:allservices:OS_Csem_SetValue|OS_Csem_SetValue]]##  |  ''(csem, value)''  | Устанавливаем счетный семафор в конкретное значение //value//.  | {{osa:ref:attr_call_can_int.png|Есть расширенный сервис с суффиксом _I для работы в прерывании}}  |
| ##[[osa:ref:allservices:OS_Csem_Reset|OS_Csem_Reset]]##  |  ''(csem)''  | Обнуляем счетный семафор  | {{osa:ref:attr_call_can_int.png|Есть расширенный сервис с суффиксом _I для работы в прерывании}}  |
| **Проверка**    ||||
| ##[[osa:ref:allservices:OS_Csem_Accept|OS_Csem_Accept]]##  |  ''(csem)''  | Принимаем счетный семафор (уменьшаем его на 1).  | {{osa:ref:attr_call_can_int.png|Есть расширенный сервис с суффиксом _I для работы в прерывании}}  |
| ''bool ''\\ ##[[osa:ref:allservices:OS_Csem_Check|OS_Csem_Check]]##  |  ''(csem)''  | Смотрим, установлен ли семафор (д.б. != 0)  | {{osa:ref:attr_call_can_int.png|Есть расширенный сервис с суффиксом _I для работы в прерывании}}  |
| **Ожидание**    ||||
| ##[[osa:ref:allservices:OS_Csem_Wait|OS_Csem_Wait]]##  |  ''(csem)''  | Ожидаем установки семафора в ненулевое значение. Уменьшает значение семафора на 1.  | {{osa:ref:attr_call_task.png|Разрешен вызов только в контексте задачи}}{{osa:ref:attr_call_ct_sw.png|Переключает контекст}}  |
| ##[[osa:ref:allservices:OS_Csem_Wait_TO|OS_Csem_Wait_TO]]##  |  ''(csem, timeout)''  | Ожидаем установки семафора с таймаутом.  | {{osa:ref:attr_call_task.png|Разрешен вызов только в контексте задачи}}{{osa:ref:attr_call_ct_sw.png|Переключает контекст}}{{osa:ref:attr_call_to.png|Использует системный таймер}}  |


~~UP~~