~~NOTOC~~

===== tn_task_reference() =====

{{tnkernel:ref:attr_call_task.png|Разрешен вызов только в контексте задачи}}

Функция предназначена для получения информации о задаче, такой как текущее состояние, причина ожидания, время таймаута, текущий приоритет и др. После вызова функции заполняется структура типа ''TN_TASK_REF'', указатель на которую передается в качестве параметра функции:

<code cpp>
typedef struct _TN_TASK_REF
{
    TN_TASK_STATE       state;
    TN_TASK_WAIT_REASON wait_reason;
    TN_UWORD            base_priority;
    TN_UWORD            current_priority;
    TN_TIMEOUT          timeout;
} TN_TASK_REF;
</code>

В состав структура ''TN_TASK_REF'' входят следующие элементы:

  ; ''state'' : состояние задачи, может принимать одно из следующих значений:
{| class = "fpl"
|-
| ''TSK_STATE_RUNNABLE''
| Задача находится в очереди готовых к выполнению
|-
| ''TSK_STATE_WAIT''
| Задача ожидает событие
|-
| ''TSK_STATE_SUSPEND''
| Задача приостановлена
|-
| ''TSK_STATE_DORMANT''
| Задача создана, но еще не запущена
|}

  ; ''wait_reason'' : событие, которого ожидает задача, может принимать одно из следующих значений:
{| class = "fpl"
|-
| ''TSK_WAIT_REASON_SLEEP''
| Задача ожидает таймаута, переведена в состояние ожидания функцией ''tn_task_sleep()''
|-
| ''TSK_WAIT_REASON_SEM''
| Задача ожидает освобождения семафора
|-
| ''TSK_WAIT_REASON_EVENT''
| Задача ожидает флаг
|-
| ''TSK_WAIT_REASON_DQUE_WSEND''
| Задача ожидает освобождение очереди сообщений
|-
| ''TSK_WAIT_REASON_DQUE_WRECEIVE''
| Задача ожидает сообщения
|-
| ''TSK_WAIT_REASON_MUTEX_C''
| Задача ожидает освобождения ресурса, заблокированного "priority ceiling" мютексом FIXME
|-
| ''TSK_WAIT_REASON_MUTEX_C_BLK''
| Задача ожидает освобождения ресурса, заблокированного "priority ceiling" мютексом FIXME
|-
| ''TSK_WAIT_REASON_MUTEX_I''
| Задача ожидает освобождения ресурса, заблокированного "priority inheritance" мютексом
|-
| ''%%TSK_WAIT_REASON_WFIXMEM%%''
| Задача ожидает освобождения блока памяти фиксированного размера
|}

  ; ''base_priority'' : базовый приоритет задачи (назначенный при ее создании)
  ; ''current_priority'' : текущий приоритет задачи
  ; ''timeout'' : время в системных тиках до момента перевода задачи в состояние ''TSK_STATE_RUNNABLE'' (актуально в случае, если задача находится в состоянии ожидания с таймаутом)

\\ 


**Вызов:**
<code cpp>
TN_RETVAL tn_task_reference(TN_TCB *task, TN_TASK_REF *ref);
</code>

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

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

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

  ; ''task'' : указатель на TCB задачи
  ; ''ref'' : указатель на структуру информации о задаче

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

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

\\ 
**Пример вызова:**  
<code cpp>
TN_TASK_REF task_info;

if (tn_task_reference(&task_1, &task_info) == TERR_NO_ERR)
{
    if (task_info.state       == TSK_STATE_WAIT &&
        task_info.wait_reason == TSK_WAIT_REASON_SLEEP
       )
    {
        tn_task_wakeup(&task_1);
    }
}
</code>

<code cpp>
if (tn_task_reference(&task_1, &task_info) == TERR_NOEXS)
{
    /* задача не создана */
}
</code>

\\ 

----
[[tnkernel:ref:task:intro#сервисы_управления_задачами|К списку сервисов]]