Navigating the API

poco aims to provide all the bare neccessities for a coroutine library. At a glance, it consists of the basic coroutine operations, and a minimal set of corotuine and scheduler aware primitives for synchronisation and communication.

The table below provides a quick reference to the available primitives and their functions. These are organised based on the execution context they are designed for. Details about the specific functions and their usage can be found in the respective sections.

Primitive API Overview
	Creation	Coroutine	ISR and External Code
Events	`event_create()` `event_create_static()` `event_free()`	`event_set()` `event_set_no_wait()` `event_get()` `event_get_no_wait()`	`event_set_from_isr()` `event_get_from_isr()`
Queues	`queue_create()` `queue_create_static()` `queue_free()`	`queue_put()` `queue_put_no_wait()` `queue_get()` `queue_get_no_wait()`	`queue_put_from_isr()` `queue_get_from_isr()`
Streams	`stream_create()` `stream_create_static()` `stream_free()`	`stream_send()` `stream_send_no_wait()` `stream_receive()` `stream_receive_up_to()` `stream_receive_no_wait()`	`stream_send_from_isr()` `stream_receive_from_isr()`
Mutexes	`mutex_create()` `mutex_create_static()` `mutex_free()`	`mutex_acquire()` `mutex_acquire_no_wait()` `mutex_release()`	N/A
Semaphores	`semaphore_create_binary()` `semaphore_create_binary_static()` `semaphore_create()` `semaphore_create_static()` `semaphore_free()`	`semaphore_acquire()` `semaphore_acquire_no_wait()` `semaphore_release()`	`semaphore_acquire_from_isr()` `semaphore_release_from_isr()`

To get the best use out of the APIs, there are a few naming conventions used to help navigate the available functions.

Function Variants

Synchronization primitives (queues, semaphores, events, etc.) expose up to 3 variants of each operation. These are designed to apply to a variety of execution contexts.

Danger

Incorrect usage of each variants may yield undefined or unexpected behaviour. Ensure the variant in use is correct for your specific execution context.

These include 2 general use forms, and a special form:

a plain form,
a *_from_isr form, and
a *_no_wait form.

Some primitives may have all 3, whereas some may only have 1 or 2.

The plain form is designed for use within coroutines.

For primitives that support use within an ISR, the *_from_isr should be used. The ISR variants use a special scheduler based notification system to report events. These variants will return a special code result::RES_NOTIFY_FAILED when the scheduler has insufficient storage in its event buffer to queue up the event.

When creating a scheduler, ensure the event buffer is set up to handle the maximum number of interrupts between the worst case coroutine yield.

The additional form *_no_wait is provided for advanced use cases and are designed for coroutine use where yielding is not desired. As no yielding is performed, these consume the same scheduler event buffer as the *_from_isr variants. Care must be taken ensure sufficient slots are available for the expected use case.