Add message queues

[LarryRuane]

Adds protothread_queue.h: message queues, what Go calls channels, built on the core the same way the semaphore, lock and timers are.

A queue is a fixed-capacity ring buffer in storage you supply, so there's no allocator. PT_QUEUE_DEFINE(name, type) generates a type-safe queue and its non-blocking functions, along the lines of <sys/tree.h>, and pt_queue_t is a predefined queue of void *.

PT_QUEUE_DEFINE(msgq, msg_t)
msgq_init(&q, slots, 8);
pt_queue_send(c, &q, &c->msg);            /* blocks while full */
pt_queue_receive(c, &q, &c->msg);         /* blocks while empty */
msgq_try_send(pt, &q, &item);             /* never blocks; safe from an interrupt */
msgq_try_receive(pt, &q, &item);
msgq_count(&q); msgq_at(&q, i); msgq_remove(pt, &q, i, &item);
c->seen = msgq_sent(&q); ... pt_queue_wait_new(c, &q, c->seen);

Design choices worth a look:

• The blocking calls are macros that wait in the caller's own context, the way pt_wait() does, so there's no pt_call() and nothing extra in the context structure. They take the element type from the queue's slots, so the copy is type-checked and one set of macros works on any queue. (An earlier version made them generated protothread functions called through pt_call(); it's kept on the queue-pt-call branch.) The non-blocking calls stay generated functions, since an interrupt handler needs a real function that returns a result.
• Items go in and out by pointer, so each is copied once each way.
• Every wakeup is a broadcast. A send has to wake both receivers and wait_new waiters, and pt_signal() could pick the wait_new one and strand the receiver. Senders and receivers do wait on separate addresses, so a send only wakes receivers.
• pt_queue_wait_new() takes a send count the caller read before looking at the queue. Reading it inside the wait, as the earlier version did, let an interrupt's send slip in between the receiver's scan and its wait, and be slept through.
• pt_call_waited() doesn't apply to queue calls. With queues it's seldom needed, since what a protothread needs to know arrives in the message rather than in memory others may have changed.
• There's no select. The README shows the alternatives: fan-in to one queue of tagged messages (the pattern Pike shows in "Go Concurrency Patterns" just before select); a timeout as a protothread that sleeps and then sends, with how to discard a stale one; selective receive with count(), at(), remove() and wait_new; and queues of queues for request and reply.
• remove() closes the gap from whichever side is shorter, so taking the oldest or the newest moves nothing.

The README also gets a queue version of producer/consumer right after the mailbox one, framed around what moves: with the mailbox the data stays put and the protothreads come to it, with a queue the protothreads stay put and the data moves. With four slots, passing 100 values takes 51 protothread runs instead of 201.

Testing:

• FIFO order with blocking on both sides; the non-blocking calls across the wrap of the ring; removal (which side moved is checked by address); selective receive; request and reply through queues of queues; timeouts, including a stale one; and the void * instance.
• Interrupt tests fire try_send() at every point where a protothread masks interrupts, for a blocked receiver and for a selective receiver. Each fails in all 24 critical-section configurations against the broken variant: a plain wait loop for the receiver, and a send count read after scanning for the selective receiver.
• The freestanding, C++ and install CI checks include queues. All 29 Linux CI configurations pass locally, and every README queue example compiles as written; the producer/consumer one runs.

One caveat, documented: clang targeting Cortex-M turns struct copies of 16 bytes or more into a __aeabi_memcpy call at -Os. That's the compiler, and user code hits it too, but this is the first library code that copies a user's struct. Queues of integers or pointers never need it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01SR7v9BVsFrHiEhQBSqZmAs