time_source.h

Go to the documentation of this file.

// ProtoCore v1.0.16 - Copyright (C) 2026 Douglas Quigg (dstroy0) <dquigg123@gmail.com>
// SPDX-License-Identifier: AGPL-3.0-or-later
 
/**
 * @file time_source.h
 * @brief Multi-source time fallback matrix (PROTOCORE_ENABLE_TIME_SOURCE).
 *
 * A small, zero-heap registry of user-defined time sources (NTP, an RTC, GPS, a
 * manually-set clock, ...). Each source is a callback returning the current Unix
 * epoch seconds, or 0 when that source currently has no valid time. Sources are
 * registered with a priority; protocore_time_now() queries them in ascending priority
 * order and returns the first nonzero result, so the device falls back
 * automatically when its preferred clock is unavailable (e.g. GPS loses its fix
 * -> RTC -> NTP). The validity rule lives in each user callback (return 0 when
 * invalid/stale), keeping this layer a pure prioritizer.
 *
 * Everything lives in a fixed BSS table (PROTOCORE_TIME_SOURCE_MAX entries); no heap.
 * The whole core is host-testable. The API is declared unconditionally and
 * compiles to no-op stubs when PROTOCORE_ENABLE_TIME_SOURCE is 0.
 *
 * @author  Douglas Quigg (dstroy0)
 * @date    2026
 */
 
#ifndef PROTOCORE_TIME_SOURCE_H
#define PROTOCORE_TIME_SOURCE_H
 
#include "protocore_config.h"
 
/**
 * @brief A time source: returns the current Unix epoch seconds for this source,
 *        or 0 if it currently has no valid time.
 *
 * Sits outside the feature gate: the disabled build still defines the no-op registry entry points,
 * so it has to be able to spell their argument type.
 */
typedef uint32_t (*TimeSourceFn)(void);
 
#if PROTOCORE_ENABLE_TIME_SOURCE
 
PROTOCORE_BEGIN_DECLS
 
/**
 * @brief Register a time source.
 *
 * @param name      stable label (referenced by pointer; must outlive the source -
 *                  point it at a string literal / static, like the rest of the lib).
 * @param priority  lower value = higher priority (queried first).
 * @param fn        the source callback.
 * @return true if registered; false if @p fn is null or the table is full.
 */
proto_bool protocore_time_source_add(const char *name, uint8_t priority, TimeSourceFn fn);
 
/**
 * @brief Current best time.
 *
 * Queries registered sources in ascending priority and returns the first nonzero
 * epoch (stopping at the first valid source). Returns 0 if none have valid time.
 */
uint32_t protocore_time_now(void);
 
/** @brief Name of the source that satisfied the last protocore_time_now(), or nullptr. */
const char *protocore_time_source_active(void);
 
/** @brief Clear all registered sources. */
void protocore_time_source_reset(void);
 
PROTOCORE_END_DECLS
 
#endif // PROTOCORE_ENABLE_TIME_SOURCE
 
#endif // PROTOCORE_TIME_SOURCE_H