~~NOTOC~~

===== tn_queue_receive() =====

Функция предназначена для приема сообщения через очередь сообщений ''dque''. Принятое сообщение (точнее говоря //адрес сообщения//) сохраняется по указателю ''data_ptr''.

Если буфер очереди сообщений не пуст, функция передает первое сообщение в буфере по указателю ''data_ptr''. Таким образом, после выхода из сервиса ''data_ptr'' будет указывать на сообщение, которое было отправлено через очередь. Если есть задача (задачи) ожидающая освобождения буфера для того чтобы отправить сообщение - эта задача будет переведена в состояние готовых к выполнению, а ее сообщение будет положено в очередь.

Если буфер очереди сообщений пуст, и нет задач, ожидающих освобождение буфера, то задача, вызвавшая сервис переводится в состояние ожидания. Если значение параметра ''timeout'' не равно ''TN_WAIT_INFINITE'', то задача "проснется" по истечении //''timeout''// системных тиков с кодом ошибки ''TERR_TIMEOUT''.

**Вызов:**
<code cpp>
TN_RETVAL tn_queue_receive (TN_DQUE     *dque,
                            void       **data_ptr,
                            TN_TIMEOUT   timeout
                           );
</code>

**Разрешен вызов:** \\ 

В контексте задачи

**Параметры функции:**

  ; ''dque'' : указатель на объект очереди сообщений.
  ; ''data_ptr'' : указатель на указатель, в который сохраняется адрес сообщения
  ; ''timeout'' : время по истечении которого задача будет переведена из состояния ожидания в состояние готовых к выполнению, если не будет получено сообщения

\\ 

**Возвращаемые значения:**  

  ; ''TERR_WRONG_PARAM'' : некорректное значение параметра (__замечание:__ данный код возврата возможен только в случае использования сервисов с проверкой параметров)
  ; ''TERR_NOEXS'' : попытка обращения к объекту, который не является очередью (__замечание:__ данный код возврата возможен только в случае использования сервисов с проверкой параметров)
  ; ''TERR_WCONTEXT'' : вызов сервиса в пользовательской критической секции или в обработчике прерывания
  ; ''TERR_TIMEOUT'' : выход из функции по таймауту
  ; ''TERR_NO_ERR'' : успешное выполнение

\\ 
**Пример вызова:**  
<code cpp>
TN_DQUE  queue TN_DATA;    /* очередь сообщений      */
MY_MSG   *message;         /* указатель на сообщение */

tn_queue_receive(&queue, &message, 10);
if (message->a)
{
    /* ... */
}
</code>


\\ 

----
[[tnkernel:ref:dqueue:intro#Сервисы управления очередями сообщений|К списку сервисов]]