Queues

• Messages queues are like an array of mailboxes but with one wait list.
• Each queue uses one Event Control Block (ECB) and one OS_Q block. The ECB points to the OS_Q.
• The OS_Q is a set of pointers used to manage a circular buffer used to hold the queue’s data. The buffer lives in the memory allocated by the caller to OSQCreate. A pointer to the memory for the buffer is pass in as a parameter when the queue is created.
• By default the queue is FIFO, or First In First Out.

OSQCreate

OS_EVENT *OSQCreate(void **start, INT16U size);

• Must be called from a task.
• Caller allocates the memory before the call. For example:

void *ArrayOfMsg[size];

• The funciton takes an ECB and a OS_Q from the free lists and initialize the pointers.
• The queue stars off empty.

OSQDel

OS_EVENT *OSQDel(OS_EVENT *pevent, INT8U opt, INT8U *perr);

• Deletes the queue.
• Frees the Event Control Block (ECB) and the OS_Q used by the queue.
• Requires an option
  • OS_DEL_NO_PEND - don’t delete if tasks are waiting on the queue.
  • OS_DEL_ALWAYS - always delete.
• If called with OS_DEL_ALWAYS, the queue will be deleted even if tasks are waiting on it.
  • All the waiting tasks will become ready.
• Best practice is to first delete all tasks that use the queue before deleting the queue.

OSQPend

void *OSQPend(OS_EVENT *pevent, INT16U timeout, INT8U *perr);

• Must be called from a task.
• Takes messages from the front of the queue.
• If there is a message it returns it right away.
• If there is no message it moves the task to the wait list. The task blocks on the queue.

OSQPendAbort

INT8U OSQPendAbort(OS_EVENT *pevent, INT8U opt, INT8U *perr);

OSQAccept

void *OSQAccept(OS_EVENT *pevent, INT8U *perr);

• Can be called from a task or an ISR.
• Checks if there is are any messages in the Queue. If there is it removes the first one from the queue and returns it to the task.
• If there are no messages it returns 0.
• Does not block.

OSQPost

INT8U OSQPost(OS_EVENT *pevent, void *pmsg);

• First In First Out (FIFO).
• Can be called from a task or an ISR.
• If there is are tasks waiting, then the highest priority task is made ready to run and gets the message at the front of the queue.
• If there are no waiting tasks the message is added to the end of the queue.
• If the queue was full it returns an OS_Q_FULL error.
• If a task was made ready it calls the scheduler.

OSQPostFront

INT8U OSQPostFront(OS_EVENT *pevent, void *pmsg);

• Last In First Out (LIFO). Behaves like a stack.
• Can be called from a task or an ISR.
• If the queue is empty and there is a waiting task then the task is made ready and it gets the message.
• If there are no waiting tasks, then the message is inserted at the front of the message queue ahead of older messages instead of going at the end of the queue.
• If the queue was full it returns an OS_Q_FULL error.
• If a task was made ready it calls the scheduler.

OSQPostOpt

INT8U OSQPostOpt(OS_EVENT *pevent, void *pmsg, INT8U opt);

• Newer function that can replace OSQPost and OSQPostFront.
• Can be called from a task or an ISR.
• Takes options that can be combined together.
  • OS_POST_OPT_BROADCAST
    • All waiting tasks are made ready and all get the message.
    • Calls the scheduler.
  • OS_POST_OPT_FRONT
    • If there are no waiting tasks the message is added to the front of the queue.
  • No option
    • If there are no waiting tasks the message is added to the back of the queue.

OSQFlush

INT8U OSQFlush(OS_EVENT *pevent);

• Reset the queue’s buffer pointers which erases the messages.
• Does not delete the messages memory.
• Can be called from a task or an ISR.

OSQQuery

INT8U OSQQuery(OS_EVENT *pevent, OS_Q_DATA *p_q_data);

• Can be called from a task or an ISR.
• Caller allocates a OS_Q_DATA struct and pass in a pointer to it.
• Copies the queue’s information into the OS_Q_DATA struct.
• OS_Q_DATA
  • OSMSG - points to the message.
  • OSQSIZE - size of the queue.
  • OSNMSG - number of messages in the queue.