Detailed Description

Core event-processing loop for SatCat5 software.

This file defines the main event-processing loop for all SatCat5 software. To function properly, SatCat5 requires users to connect several subsystems to platform-specific logic:

Call timekeeper::request_poll() at regular intervals.
- In FreeRTOS, this should be linked to the system tick. (See hal_freertos/satcat_task.h)
- In Linux or Windows systems, use the PosixTimekeeper class. (See hal_posix/posix_utils.h)
- In baremetal systems, this may be linked to a timer interrupt. (See cfgbus_timer.h for one possible implementation)
- In other systems, consider using the VirtualTimer class.
Call satcat5::poll::service_all() at frequent intervals.
- In FreeRTOS, this should be linked to the system tick.
- In baremetal systems, this may be an infinite loop: while(1) {satcat5::poll::service_all();}
(Optional) Set the elapsed-time reference (TimeRef).
- Use timekeeper::set_clock() to force a specific reference.
- Use timekeeper::suggest_clock() to automatically select the "best" reference from among all suggested clocks.
- If no TimeRef is provided, poll timekeeper at exactly 1 kHz.

SatCat5 event-processing is single-threaded. Each call to the main service function (i.e., satcat5::poll::service_all()) processes all queued events in sequence.

There are three built-in event types:

satcat5::poll::Always This object is polled whenever the main service function is called. (Users may inherit from this class and override "poll_always".)
satcat5::poll::OnDemand This object is polled only after request_poll() method has been called. For example, many interrupt handlers call request_poll() in order to request additional service at the next convenient time. This method is also used for io::Readable::data_rcvd() callbacks. (Users may inherit from this class and override "poll_demand".)
satcat5::poll::Timer Poll this object at a designated time, or at a designated interval. (Users may inherit from this class and override "timer_event".)

Definition in file polling.h.

#include <satcat5/timeref.h>
#include <satcat5/types.h>

Include dependency graph for polling.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
class	satcat5::poll::Always
	An "Always" object is polled whenever service() is called. More...

class	satcat5::poll::OnDemand
	An "OnDemand" object is polled only on request. More...

class	satcat5::poll::Timekeeper
	Global coordinator for multiple Timer objects. More...

class	satcat5::poll::Timer
	Timer objects are polled after a fixed delay or at a regular interval. More...

class	satcat5::poll::TimerAdapter
	Connect a Timer to any OnDemand object. More...

class	satcat5::irq::VirtualTimer
	Poll any OnDemand object using a TimeRef. More...

Functions
void	satcat5::poll::service ()
	Single-pass service loop. More...

void	satcat5::poll::service_all (unsigned limit=100)
	Multi-pass service loop Calling this function regularly is required for SatCat5 operation. More...

bool	satcat5::poll::pre_test_reset ()
	Hard-reset of global variables at the start of each unit test. More...

Variables
Timekeeper	satcat5::poll::timekeeper
	There is a single global instance of the Timekeeper class. More...

Function Documentation

◆ pre_test_reset()

bool satcat5::poll::pre_test_reset ( )

Hard-reset of global variables at the start of each unit test.

(Unit testing only, should not be called in production.)

A hard reset may leak memory but prevents contamination of global state across tests, which can be extremely difficult to debug. Returns true if globals were already in the expected state.

Definition at line 134 of file polling.cc.

◆ service()

void satcat5::poll::service ( )

Single-pass service loop.

See also: satcat5::poll::service_all

This function processes all queued events, then returns. Most users should instead call service_all().

Definition at line 143 of file polling.cc.

◆ service_all()

void satcat5::poll::service_all ( unsigned limit = 100 )

Multi-pass service loop Calling this function regularly is required for SatCat5 operation.

SatCat5 event-loop concepts.

This is the preferred service method, because it will continue processing queued events until the queue is empty or the iteration limit is reached. Iterated polling is preferred because on-demand event processing often triggers additional event(s). (For example, incoming data from a UART may pass data to a SLIP decoder, which may pass data to an IPv4 stack.)

Users must call this method frequently.

Definition at line 157 of file polling.cc.

Variable Documentation

◆ timekeeper

poll::Timekeeper satcat5::poll::timekeeper

extern

There is a single global instance of the Timekeeper class.

SatCat5 event-loop concepts.

User MUST link it to a once-per-millisecond event source such as a hardware interrupt or the VirtualTimer.

Definition at line 50 of file polling.cc.