Poll groups

Waiting on several message queues at once. More...

Data Structures
struct	pbl_poll_group
	Set of message queues waited on together. More...

Macros
#define	PBL_POLL_GROUP_INITIALIZER   {.members = NULL, .capacity = 0}
	Static initializer for an empty group.
#define	PBL_POLL_GROUP_DEFINE(name)   struct pbl_poll_group name = PBL_POLL_GROUP_INITIALIZER
	Define an empty group, usable without pbl_poll_group_init().

Functions
void	pbl_poll_group_init (struct pbl_poll_group *g)
	Initialize a group in dynamically allocated memory.
void	pbl_poll_group_add (struct pbl_poll_group *g, struct pbl_msgq *q)
	Add a queue to a group.
struct pbl_msgq *	pbl_poll_group_wait (struct pbl_poll_group *g, pbl_timeout_t timeout)
	Wait until a member queue has a message.
bool	pbl_poll_group_is_empty (const struct pbl_poll_group *g)
	Check whether every member queue is empty.

Detailed Description

Waiting on several message queues at once.

pbl_poll_group_wait() returns a member queue that has a message without dequeuing it; the caller receives it with pbl_msgq_get(). Members are scanned from the one after the last returned, so a busy queue cannot starve the others. Members may also be read directly, outside the group. Queues are added before the first wait and stay members for good; only one thread may wait on a group.

static PBL_MSGQ_DEFINE(s_from_isr, sizeof(struct event), 8);
static PBL_MSGQ_DEFINE(s_from_app, sizeof(struct event), 4);
static PBL_POLL_GROUP_DEFINE(s_group);
 
static void prv_loop(void *arg) {
  pbl_poll_group_add(&s_group, &s_from_isr);
  pbl_poll_group_add(&s_group, &s_from_app);
 
  for (;;) {
    struct pbl_msgq *q = pbl_poll_group_wait(&s_group, PBL_SEC(1));
    if (q == NULL) {
      prv_handle_timeout();
      continue;
    }
    struct event e;
    if (pbl_msgq_get(q, &e, PBL_NO_WAIT) == 0) {
      prv_handle(q, &e);
    }
  }
}

---

Data Structure Documentation

pbl_poll_group

struct pbl_poll_group

Set of message queues waited on together.

Data Fields
struct pbl_poll_group_backend	backend	Backend state.
uint32_t	capacity	Sum of the capacities of all members, in messages.
struct pbl_msgq *	members	First member queue, in the order they were added.

Macro Definition Documentation

PBL_POLL_GROUP_DEFINE

#define PBL_POLL_GROUP_DEFINE

(

name

)

struct pbl_poll_group name = PBL_POLL_GROUP_INITIALIZER

Define an empty group, usable without pbl_poll_group_init().

Parameters

name	Name of the group variable.

PBL_POLL_GROUP_INITIALIZER

#define PBL_POLL_GROUP_INITIALIZER   {.members = NULL, .capacity = 0}

Static initializer for an empty group.

Function Documentation

pbl_poll_group_add()

void pbl_poll_group_add	(	struct pbl_poll_group *	g,
		struct pbl_msgq *	q
	)

Add a queue to a group.

Parameters

g	Group.
q	Queue; must be empty and not already in a group.

pbl_poll_group_init()

void pbl_poll_group_init

(

struct pbl_poll_group *

g

)

Initialize a group in dynamically allocated memory.

Parameters

[out]

g

Group.

pbl_poll_group_is_empty()

bool pbl_poll_group_is_empty

(

const struct pbl_poll_group *

g

)

Check whether every member queue is empty.

Parameters

g

Group.

Returns

true if no member has a message.

pbl_poll_group_wait()

struct pbl_msgq * pbl_poll_group_wait	(	struct pbl_poll_group *	g,
		pbl_timeout_t	timeout
	)

Wait until a member queue has a message.

Not callable from ISRs. The group must have at least one member.

Parameters

g	Group.
timeout	How long to wait.

Returns

A member with a pending message, or NULL on timeout or if the thread was suspended while waiting.