Events

Defines event queue functionality for producer/consumer patterns. More...

Collaboration diagram for Events:

Data Structures
struct	sys_event_queue_t
	Event queue structure for producer/consumer patterns. More...

Typedefs
typedef void *	sys_event_t
	Event type for queue items. More...

Functions
sys_event_queue_t	sys_event_queue_init (size_t capacity)
	Initialize a new event queue. More...
void	sys_event_queue_finalize (sys_event_queue_t *queue)
	Finalize and cleanup an event queue. More...
bool	sys_event_queue_push (sys_event_queue_t *queue, sys_event_t event)
	Push an event to the queue (always succeeds) More...
bool	sys_event_queue_try_push (sys_event_queue_t *queue, sys_event_t event)
	Try to push an event without overwriting. More...
sys_event_t	sys_event_queue_peek (sys_event_queue_t *queue)
	Peek at the next event without removing it. More...
sys_event_t	sys_event_queue_pop (sys_event_queue_t *queue)
	Remove and return the next event (blocking) More...
sys_event_t	sys_event_queue_try_pop (sys_event_queue_t *queue)
	Try to remove and return the next event (non-blocking) More...
sys_event_t	sys_event_queue_timed_pop (sys_event_queue_t *queue, uint32_t timeout_ms)
	Remove and return the next event with timeout. More...
size_t	sys_event_queue_size (sys_event_queue_t *queue)
	Get the current number of events in the queue. More...
bool	sys_event_queue_empty (sys_event_queue_t *queue)
	Check if the queue is empty. More...
void	sys_event_queue_shutdown (sys_event_queue_t *queue)
	Shut down the queue gracefully. More...
bool	sys_event_queue_lock (sys_event_queue_t *queue)
	Lock the queue for manual synchronization. More...
bool	sys_event_queue_unlock (sys_event_queue_t *queue)
	Unlock the queue after manual synchronization. More...
static bool	sys_event_queue_valid (sys_event_queue_t *queue)
	Check if the queue is valid and usable for operations. More...

Detailed Description

Defines event queue functionality for producer/consumer patterns.

This file declares types and functions for thread-safe event queues that support multiple producers and consumers with peek-before-acquire semantics.

It is intended to support event channels, for a single producer and single consumer, all the way to multiple producers and consumers.

The event type sys_event_t is a simple pointer type that can be used to hold any data, but that data is not managed by the queue itself; If you want to manage the data, you must do so outside the queue. The queue supports operations to push events, pop events, and peek at events without removing them.

If you peek events you also need to acquire the queue lock before doing so, and release it after you are done. This is to ensure that the queue state is not modified while you are inspecting it.

You set a queue capacity when you initialize it, and the queue will use a circular buffer to store events. When the buffer is full, new events will overwrite the oldest events if you use the sys_event_queue_push() function. If you want to avoid overwriting, you can use sys_event_queue_try_push() function instead, which will return false if the queue is full.

When you wish to shutdown the queue, you can call sys_event_queue_finalize(). Consumers will be woken up and any further attempts to push events will fail, but existing events can still be popped, until the queue is empty.

Typedef Documentation

sys_event_t

typedef void* sys_event_t

Event type for queue items.

Simple event type that can hold any pointer data. This can be enhanced in the future to include metadata like timestamps, priorities, etc.

Definition at line 55 of file event.h.

Function Documentation

sys_event_queue_empty()

bool sys_event_queue_empty

(

sys_event_queue_t *

queue

)

Check if the queue is empty.

Parameters

queue

Pointer to the event queue

Returns

true if empty, false otherwise

Returns true if the queue contains no events. This is a snapshot value that may change immediately after the call returns in a multi-threaded environment.

sys_event_queue_finalize()

void sys_event_queue_finalize

(

sys_event_queue_t *

queue

)

Finalize and cleanup an event queue.

Parameters

queue

Pointer to the queue to finalize

Finalizes the event queue and releases all associated resources. Any threads waiting on the queue will be woken up. The queue should not be used after this call.

Examples:

examples/runtime/infrared/main.c.

sys_event_queue_init()

sys_event_queue_t sys_event_queue_init

(

size_t

capacity

)

Initialize a new event queue.

Parameters

capacity

Maximum number of events the queue can hold

Returns

Initialized event queue structure

Creates a new thread-safe event queue with the specified capacity. The queue uses circular buffer semantics - when full, new items will overwrite the oldest items. The returned queue must be finalized with sys_event_queue_finalize().

Examples:

examples/runtime/gpio/main.c, and examples/runtime/infrared/main.c.

sys_event_queue_lock()

bool sys_event_queue_lock

(

sys_event_queue_t *

queue

)

Lock the queue for manual synchronization.

Parameters

queue

Pointer to the event queue

Returns

true if successful, false on error

Manually locks the queue mutex. This allows for atomic sequences of peek/pop operations. Must be paired with sys_event_queue_unlock().

sys_event_queue_peek()

sys_event_t sys_event_queue_peek

(

sys_event_queue_t *

queue

)

Peek at the next event without removing it.

Parameters

queue

Pointer to the event queue

Returns

Next event or NULL if queue is empty

Returns the next event that would be returned by sys_event_queue_pop() without removing it from the queue. This allows consumers to inspect events before deciding whether to acquire them. The queue must be locked by the caller.

sys_event_queue_pop()

sys_event_t sys_event_queue_pop

(

sys_event_queue_t *

queue

)

Remove and return the next event (blocking)

Parameters

queue

Pointer to the event queue

Returns

Next event, or NULL if queue is shut down

Removes and returns the next event from the queue. If the queue is empty, this function blocks until an event becomes available or the queue is shut down.

Examples:

examples/runtime/gpio/main.c, and examples/runtime/infrared/main.c.

sys_event_queue_push()

bool sys_event_queue_push	(	sys_event_queue_t *	queue,
		sys_event_t	event
	)

Push an event to the queue (always succeeds)

Parameters

queue	Pointer to the event queue
event	Event to add to the queue

Returns

true if successful, false on error

Adds an event to the queue. This operation always succeeds - if the queue is full, the oldest event is overwritten. This ensures producers are never blocked.

Examples:

examples/runtime/infrared/main.c.

sys_event_queue_shutdown()

void sys_event_queue_shutdown

(

sys_event_queue_t *

queue

)

Shut down the queue gracefully.

Parameters

queue

Pointer to the event queue

Sets the shutdown flag and wakes up all waiting consumers. After shutdown, push operations may fail and pop operations will return NULL once the queue is empty.

Examples:

examples/runtime/gpio/main.c.

sys_event_queue_size()

size_t sys_event_queue_size

(

sys_event_queue_t *

queue

)

Get the current number of events in the queue.

Parameters

queue

Pointer to the event queue

Returns

Current number of events, or 0 on error

Returns the current number of events in the queue. This is a snapshot value that may change immediately after the call returns in a multi-threaded environment.

Examples:

examples/runtime/gpio/main.c.

sys_event_queue_timed_pop()

sys_event_t sys_event_queue_timed_pop	(	sys_event_queue_t *	queue,
		uint32_t	timeout_ms
	)

Remove and return the next event with timeout.

Parameters

queue	Pointer to the event queue
timeout_ms	Timeout in milliseconds (0 = no timeout)

Returns

Next event, or NULL if timeout or queue shut down

Removes and returns the next event from the queue. If the queue is empty, waits up to timeout_ms milliseconds for an event to become available.

sys_event_queue_try_pop()

sys_event_t sys_event_queue_try_pop

(

sys_event_queue_t *

queue

)

Try to remove and return the next event (non-blocking)

Parameters

queue

Pointer to the event queue

Returns

Next event, or NULL if queue is empty or error

Attempts to remove and return the next event from the queue. Returns NULL immediately if the queue is empty.

sys_event_queue_try_push()

bool sys_event_queue_try_push	(	sys_event_queue_t *	queue,
		sys_event_t	event
	)

Try to push an event without overwriting.

Parameters

queue	Pointer to the event queue
event	Event to add to the queue

Returns

true if successful, false if queue is full or error

Attempts to add an event to the queue. Returns false if the queue is full, ensuring no existing events are overwritten.

Examples:

examples/runtime/gpio/main.c.

sys_event_queue_unlock()

bool sys_event_queue_unlock

(

sys_event_queue_t *

queue

)

Unlock the queue after manual synchronization.

Parameters

queue

Pointer to the event queue

Returns

true if successful, false on error

Unlocks the queue mutex. Must be called after sys_event_queue_lock().

sys_event_queue_valid()

static bool sys_event_queue_valid ( sys_event_queue_t *  queue )

inlinestatic

Check if the queue is valid and usable for operations.

Parameters

queue

Pointer to the event queue

Returns

true if the queue is valid, false otherwise

Examples:

examples/runtime/infrared/main.c.

Definition at line 238 of file event.h.

                                                                   {
  // Check if the queue pointer is valid and has a non-zero capacity
  if (queue == NULL) {
    return false;
  }
  if (queue->items == NULL || queue->capacity == 0) {
    return false;
  }
  // Ensure the queue is not in a shutdown state
  if (queue->shutdown == true) {
    return false;
  }
  return true;
}