Message queues

Fixed-size message rings that copy messages in and out. More...

Data Structures
struct	pbl_msgq
	Fixed-size message ring. More...

Macros
#define	PBL_MSGQ_INITIALIZER(buffer, size, max)    {.buf = (buffer), .msg_size = (size), .max_msgs = (max)}
	Static initializer for an empty queue.
#define	PBL_MSGQ_STATIC_BUF(size, max)   ((uint32_t[((size) *(max) + 3) / 4]){0})
	Anonymous, word-aligned storage for a queue.
#define	PBL_MSGQ_DEFINE(name, size, max)    struct pbl_msgq name = PBL_MSGQ_INITIALIZER(PBL_MSGQ_STATIC_BUF(size, max), size, max)
	Define a queue with its own storage, usable without pbl_msgq_init().

Functions
void	pbl_msgq_init (struct pbl_msgq *q, void *buf, size_t msg_size, uint32_t max_msgs)
	Initialize a queue in dynamically allocated memory.
void	pbl_msgq_deinit (struct pbl_msgq *q)
	Release a queue before its memory is reused.
int	pbl_msgq_put (struct pbl_msgq *q, const void *msg, pbl_timeout_t timeout)
	Append a message.
int	pbl_msgq_put_front (struct pbl_msgq *q, const void *msg, pbl_timeout_t timeout)
	Prepend a message, so it is received next.
int	pbl_msgq_get (struct pbl_msgq *q, void *msg, pbl_timeout_t timeout)
	Receive the oldest message.
int	pbl_msgq_peek (struct pbl_msgq *q, void *msg)
	Copy the oldest message without removing it.
void	pbl_msgq_purge (struct pbl_msgq *q)
	Discard every message.
uint32_t	pbl_msgq_num_used (const struct pbl_msgq *q)
	Get the number of queued messages.
uint32_t	pbl_msgq_num_free (const struct pbl_msgq *q)
	Get the free space of a queue.

Detailed Description

Fixed-size message rings that copy messages in and out.

Every message is pbl_msgq::msg_size bytes and is copied, so senders may pass stack variables. Blocked senders and receivers are served highest priority first. Put and get may be called from ISRs, which never block and get -EBUSY on a full or empty queue. A queue can be waited on together with others through a poll group.

struct event {
  uint8_t type;
  uint32_t data;
};
 
static PBL_MSGQ_DEFINE(s_events, sizeof(struct event), 8);
 
static void prv_button_isr(void) {
  const struct event e = {.type = EVENT_BUTTON, .data = prv_read_buttons()};
  pbl_msgq_put(&s_events, &e, PBL_NO_WAIT);
}
 
static void prv_event_thread(void *arg) {
  struct event e;
  for (;;) {
    if (pbl_msgq_get(&s_events, &e, PBL_FOREVER) == 0) {
      prv_handle(&e);
    }
  }
}

---

Data Structure Documentation

pbl_msgq

struct pbl_msgq

Fixed-size message ring.

Usable from ISRs with PBL_NO_WAIT.

Data Fields
struct pbl_msgq_backend	backend	Backend state.
void *	buf	Storage, msg_size * max_msgs bytes.
struct pbl_poll_group *	group	Poll group the queue belongs to, NULL if none.
struct pbl_msgq *	group_next	Next member of the same poll group.
uint32_t	max_msgs	Capacity in messages.
size_t	msg_size	Size of one message in bytes.

Macro Definition Documentation

PBL_MSGQ_DEFINE

#define PBL_MSGQ_DEFINE	(		name,
			size,
			max
	)		struct pbl_msgq name = PBL_MSGQ_INITIALIZER(PBL_MSGQ_STATIC_BUF(size, max), size, max)

Define a queue with its own storage, usable without pbl_msgq_init().

Only valid at file scope.

Parameters

name	Name of the queue variable.
size	Size of one message in bytes.
max	Capacity in messages.

PBL_MSGQ_INITIALIZER

#define PBL_MSGQ_INITIALIZER	(		buffer,
			size,
			max
	)		{.buf = (buffer), .msg_size = (size), .max_msgs = (max)}

Static initializer for an empty queue.

Parameters

buffer	Storage of at least size * max bytes.
size	Size of one message in bytes.
max	Capacity in messages.

PBL_MSGQ_STATIC_BUF

#define PBL_MSGQ_STATIC_BUF	(		size,
			max
	)		((uint32_t[((size) *(max) + 3) / 4]){0})

Anonymous, word-aligned storage for a queue.

A file-scope compound literal has static storage duration, so the buffer needs no name and the definition using it can be prefixed with static.

Parameters

size	Size of one message in bytes.
max	Capacity in messages.

Function Documentation

pbl_msgq_deinit()

void pbl_msgq_deinit

(

struct pbl_msgq *

q

)

Release a queue before its memory is reused.

Required for dynamically allocated queues. Not for poll group members, which cannot leave their group.

Parameters

q

Queue.

pbl_msgq_get()

int pbl_msgq_get	(	struct pbl_msgq *	q,
		void *	msg,
		pbl_timeout_t	timeout
	)

Receive the oldest message.

Parameters

	q	Queue.
[out]	msg	Buffer of pbl_msgq::msg_size bytes.
	timeout	How long to wait for a message; ignored in an ISR, which never waits.

Return values

0	Received.
-EAGAIN	Timed out.
-EBUSY	Empty and timeout is PBL_NO_WAIT, or called from an ISR.
-EINTR	The thread was suspended while waiting.

pbl_msgq_init()

void pbl_msgq_init	(	struct pbl_msgq *	q,
		void *	buf,
		size_t	msg_size,
		uint32_t	max_msgs
	)

Initialize a queue in dynamically allocated memory.

Parameters

[out]	q	Queue.
	buf	Storage of at least msg_size * max_msgs bytes, owned by the caller.
	msg_size	Size of one message in bytes, not 0.
	max_msgs	Capacity in messages, not 0.

pbl_msgq_num_free()

uint32_t pbl_msgq_num_free

(

const struct pbl_msgq *

q

)

Get the free space of a queue.

Parameters

q

Queue.

Returns

Messages that can be put without waiting.

pbl_msgq_num_used()

uint32_t pbl_msgq_num_used

(

const struct pbl_msgq *

q

)

Get the number of queued messages.

Parameters

q

Queue.

Returns

Messages queued.

pbl_msgq_peek()

int pbl_msgq_peek	(	struct pbl_msgq *	q,
		void *	msg
	)

Copy the oldest message without removing it.

Parameters

	q	Queue.
[out]	msg	Buffer of pbl_msgq::msg_size bytes.

Return values

0	Copied.
-EBUSY	Empty.

pbl_msgq_purge()

void pbl_msgq_purge

(

struct pbl_msgq *

q

)

Discard every message.

Wakes the threads waiting for space.

Parameters

q

Queue.

pbl_msgq_put()

int pbl_msgq_put	(	struct pbl_msgq *	q,
		const void *	msg,
		pbl_timeout_t	timeout
	)

Append a message.

Parameters

q	Queue.
msg	Message of pbl_msgq::msg_size bytes, copied in.
timeout	How long to wait for space; ignored in an ISR, which never waits.

Return values

0	Queued.
-EAGAIN	Timed out.
-EBUSY	Full and timeout is PBL_NO_WAIT, or called from an ISR.
-EINTR	The thread was suspended while waiting.

pbl_msgq_put_front()

int pbl_msgq_put_front	(	struct pbl_msgq *	q,
		const void *	msg,
		pbl_timeout_t	timeout
	)

Prepend a message, so it is received next.

Parameters

q	Queue.
msg	Message of pbl_msgq::msg_size bytes, copied in.
timeout	How long to wait for space; ignored in an ISR, which never waits.

Return values

0	Queued.
-EAGAIN	Timed out.
-EBUSY	Full and timeout is PBL_NO_WAIT, or called from an ISR.
-EINTR	The thread was suspended while waiting.