Zephyr API Documentation  3.7.0-rc3
A Scalable Open Source RTOS
Loading...
Searching...
No Matches
Message Queue APIs

Data Structures

struct  k_msgq
 Message Queue Structure. More...
 
struct  k_msgq_attrs
 Message Queue Attributes. More...
 

Macros

#define K_MSGQ_FLAG_ALLOC   BIT(0)
 
#define K_MSGQ_DEFINE(q_name, q_msg_size, q_max_msgs, q_align)
 Statically define and initialize a message queue.
 

Functions

void k_msgq_init (struct k_msgq *msgq, char *buffer, size_t msg_size, uint32_t max_msgs)
 Initialize a message queue.
 
int k_msgq_alloc_init (struct k_msgq *msgq, size_t msg_size, uint32_t max_msgs)
 Initialize a message queue.
 
int k_msgq_cleanup (struct k_msgq *msgq)
 Release allocated buffer for a queue.
 
int k_msgq_put (struct k_msgq *msgq, const void *data, k_timeout_t timeout)
 Send a message to a message queue.
 
int k_msgq_get (struct k_msgq *msgq, void *data, k_timeout_t timeout)
 Receive a message from a message queue.
 
int k_msgq_peek (struct k_msgq *msgq, void *data)
 Peek/read a message from a message queue.
 
int k_msgq_peek_at (struct k_msgq *msgq, void *data, uint32_t idx)
 Peek/read a message from a message queue at the specified index.
 
void k_msgq_purge (struct k_msgq *msgq)
 Purge a message queue.
 
uint32_t k_msgq_num_free_get (struct k_msgq *msgq)
 Get the amount of free space in a message queue.
 
void k_msgq_get_attrs (struct k_msgq *msgq, struct k_msgq_attrs *attrs)
 Get basic attributes of a message queue.
 
uint32_t k_msgq_num_used_get (struct k_msgq *msgq)
 Get the number of messages in a message queue.
 

Detailed Description

Macro Definition Documentation

◆ K_MSGQ_DEFINE

#define K_MSGQ_DEFINE (   q_name,
  q_msg_size,
  q_max_msgs,
  q_align 
)

#include <zephyr/kernel.h>

Value:
static char __noinit __aligned(q_align) \
_k_fifo_buf_##q_name[(q_max_msgs) * (q_msg_size)]; \
STRUCT_SECTION_ITERABLE(k_msgq, q_name) = \
Z_MSGQ_INITIALIZER(q_name, _k_fifo_buf_##q_name, \
(q_msg_size), (q_max_msgs))
Message Queue Structure.
Definition: kernel.h:4426

Statically define and initialize a message queue.

The message queue's ring buffer contains space for q_max_msgs messages, each of which is q_msg_size bytes long. Alignment of the message queue's ring buffer is not necessary, setting q_align to 1 is sufficient.

The message queue can be accessed outside the module where it is defined using:

extern struct k_msgq <name>;
Parameters
q_nameName of the message queue.
q_msg_sizeMessage size (in bytes).
q_max_msgsMaximum number of messages that can be queued.
q_alignAlignment of the message queue's ring buffer (power of 2).

◆ K_MSGQ_FLAG_ALLOC

#define K_MSGQ_FLAG_ALLOC   BIT(0)

#include <zephyr/kernel.h>

Function Documentation

◆ k_msgq_alloc_init()

int k_msgq_alloc_init ( struct k_msgq msgq,
size_t  msg_size,
uint32_t  max_msgs 
)

#include <zephyr/kernel.h>

Initialize a message queue.

This routine initializes a message queue object, prior to its first use, allocating its internal ring buffer from the calling thread's resource pool.

Memory allocated for the ring buffer can be released by calling k_msgq_cleanup(), or if userspace is enabled and the msgq object loses all of its references.

Parameters
msgqAddress of the message queue.
msg_sizeMessage size (in bytes).
max_msgsMaximum number of messages that can be queued.
Returns
0 on success, -ENOMEM if there was insufficient memory in the thread's resource pool, or -EINVAL if the size parameters cause an integer overflow.

◆ k_msgq_cleanup()

int k_msgq_cleanup ( struct k_msgq msgq)

#include <zephyr/kernel.h>

Release allocated buffer for a queue.

Releases memory allocated for the ring buffer.

Parameters
msgqmessage queue to cleanup
Return values
0on success
-EBUSYQueue not empty

◆ k_msgq_get()

int k_msgq_get ( struct k_msgq msgq,
void *  data,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

Receive a message from a message queue.

This routine receives a message from message queue q in a "first in, first out" manner.

Note
timeout must be set to K_NO_WAIT if called from ISR.
Function properties (list may not be complete)
isr-ok
Parameters
msgqAddress of the message queue.
dataAddress of area to hold the received message.
timeoutWaiting period to receive the message, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
0Message received.
-ENOMSGReturned without waiting.
-EAGAINWaiting period timed out.

◆ k_msgq_get_attrs()

void k_msgq_get_attrs ( struct k_msgq msgq,
struct k_msgq_attrs attrs 
)

#include <zephyr/kernel.h>

Get basic attributes of a message queue.

This routine fetches basic attributes of message queue into attr argument.

Parameters
msgqAddress of the message queue.
attrspointer to message queue attribute structure.

◆ k_msgq_init()

void k_msgq_init ( struct k_msgq msgq,
char *  buffer,
size_t  msg_size,
uint32_t  max_msgs 
)

#include <zephyr/kernel.h>

Initialize a message queue.

This routine initializes a message queue object, prior to its first use.

The message queue's ring buffer must contain space for max_msgs messages, each of which is msg_size bytes long. Alignment of the message queue's ring buffer is not necessary.

Parameters
msgqAddress of the message queue.
bufferPointer to ring buffer that holds queued messages.
msg_sizeMessage size (in bytes).
max_msgsMaximum number of messages that can be queued.

◆ k_msgq_num_free_get()

uint32_t k_msgq_num_free_get ( struct k_msgq msgq)

#include <zephyr/kernel.h>

Get the amount of free space in a message queue.

This routine returns the number of unused entries in a message queue's ring buffer.

Parameters
msgqAddress of the message queue.
Returns
Number of unused ring buffer entries.

◆ k_msgq_num_used_get()

uint32_t k_msgq_num_used_get ( struct k_msgq msgq)

#include <zephyr/kernel.h>

Get the number of messages in a message queue.

This routine returns the number of messages in a message queue's ring buffer.

Parameters
msgqAddress of the message queue.
Returns
Number of messages.

◆ k_msgq_peek()

int k_msgq_peek ( struct k_msgq msgq,
void *  data 
)

#include <zephyr/kernel.h>

Peek/read a message from a message queue.

This routine reads a message from message queue q in a "first in, first out" manner and leaves the message in the queue.

Function properties (list may not be complete)
isr-ok
Parameters
msgqAddress of the message queue.
dataAddress of area to hold the message read from the queue.
Return values
0Message read.
-ENOMSGReturned when the queue has no message.

◆ k_msgq_peek_at()

int k_msgq_peek_at ( struct k_msgq msgq,
void *  data,
uint32_t  idx 
)

#include <zephyr/kernel.h>

Peek/read a message from a message queue at the specified index.

This routine reads a message from message queue at the specified index and leaves the message in the queue. k_msgq_peek_at(msgq, data, 0) is equivalent to k_msgq_peek(msgq, data)

Function properties (list may not be complete)
isr-ok
Parameters
msgqAddress of the message queue.
dataAddress of area to hold the message read from the queue.
idxMessage queue index at which to peek
Return values
0Message read.
-ENOMSGReturned when the queue has no message at index.

◆ k_msgq_purge()

void k_msgq_purge ( struct k_msgq msgq)

#include <zephyr/kernel.h>

Purge a message queue.

This routine discards all unreceived messages in a message queue's ring buffer. Any threads that are blocked waiting to send a message to the message queue are unblocked and see an -ENOMSG error code.

Parameters
msgqAddress of the message queue.

◆ k_msgq_put()

int k_msgq_put ( struct k_msgq msgq,
const void *  data,
k_timeout_t  timeout 
)

#include <zephyr/kernel.h>

Send a message to a message queue.

This routine sends a message to message queue q.

Note
The message content is copied from data into msgq and the data pointer is not retained, so the message content will not be modified by this function.
Function properties (list may not be complete)
isr-ok
Parameters
msgqAddress of the message queue.
dataPointer to the message.
timeoutWaiting period to add the message, or one of the special values K_NO_WAIT and K_FOREVER.
Return values
0Message sent.
-ENOMSGReturned without waiting or queue purged.
-EAGAINWaiting period timed out.