Merge pull request #18598 from benpicco/event_periodic_callback

event_periodic_callback: add convenience wrapper for periodic callbacks

sys/Makefile.dep

@@ -559,6 +559,12 @@ ifneq (,$(filter asymcute,$(USEMODULE)))
   USEMODULE += event_callback
 endif
 
+ifneq (,$(filter event_periodic_callback,$(USEMODULE)))
+  USEMODULE += event_callback
+  USEMODULE += event_periodic
+  USEMODULE += event_thread
+endif
+
 ifneq (,$(filter emcute,$(USEMODULE)))
   USEMODULE += core_thread_flags
   USEMODULE += sock_udp

sys/include/event/periodic_callback.h

@@ -0,0 +1,126 @@
+/*
+ * Copyright (C) 2022 ML!PA Consulting GmbH
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     sys_event
+ * @brief       Provides functionality to trigger periodic event callbacks
+ *
+ * This provides convenience functions to trigger periodic event callbacks
+ * executed by the event thread.
+ *
+ * @{
+ *
+ * @file
+ * @brief       Event Periodic Callback API
+ *
+ * @author      Benjamin Valentin <benjamin.valentin@ml-pa.com>
+ *
+ */
+
+#ifndef EVENT_PERIODIC_CALLBACK_H
+#define EVENT_PERIODIC_CALLBACK_H
+
+#include "event/callback.h"
+#include "event/periodic.h"
+#include "event/thread.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief   Periodic Callback Event structure
+ */
+typedef struct {
+    event_periodic_t periodic;  /**< periodic event portion */
+    event_callback_t event;     /**< callback event portion */
+} event_periodic_callback_t;
+
+/**
+ * @brief   Initialize a periodic callback event
+ *
+ * @note: On init the periodic event is to to run forever.
+ *
+ * @param[in]   event           event_periodic_callback object to initialize
+ * @param[in]   clock           the clock to configure this timer on
+ * @param[in]   queue           queue that the timed-out event will be added to
+ * @param[in]   callback        callback to set up
+ * @param[in]   arg             callback argument to set up
+ */
+static inline void event_periodic_callback_init(event_periodic_callback_t *event,
+                                                ztimer_clock_t *clock, event_queue_t *queue,
+                                                void (*callback)(void *), void *arg)
+{
+    memset(&event->event, 0, sizeof(event->event));
+    event->event.super.handler = _event_callback_handler;
+    event->event.callback = callback;
+    event->event.arg = arg;
+
+    event_periodic_init(&event->periodic, clock, queue, &event->event.super);
+}
+
+/**
+ * @brief   Starts a periodic callback event
+ *
+ * If the event is already started, it's interval will be updated and it
+ * will be scheduled with the new interval.
+ *
+ * This will make the event as configured in @p event be triggered
+ * at every interval ticks (based on event->periodic.clock).
+ *
+ * @note: the used event_periodic struct must stay valid until after the timeout
+ *        event has been processed!
+ *
+ * @note: this function does not touch the current count value.
+ *
+ * @param[in]   event           event_periodic_callback context object to use
+ * @param[in]   interval        period length for the event
+ */
+static inline void event_periodic_callback_start(event_periodic_callback_t *event,
+                                                 uint32_t interval)
+{
+    event_periodic_start(&event->periodic, interval);
+}
+
+/**
+ * @brief   Set the amount of times the periodic callback event should repeat itself.
+ *
+ * @param[in]   event           event_periodic_callback context object to use
+ * @param[in]   count           times the event should repeat itself,
+ *                              EVENT_PERIODIC_FOREVER to run for ever.
+ */
+static inline void event_periodic_callback_set_count(event_periodic_callback_t *event,
+                                                     uint32_t count)
+{
+    event_periodic_set_count(&event->periodic, count);
+}
+
+/**
+ * @brief   Stop a periodic callback event
+ *
+ * Calling this function will cancel the timeout by removing its underlying
+ * timer. If the timer has already fired before calling this function, the
+ * connected event will be put already into the given event queue and this
+ * function does not have any effect.
+ *
+ * @note Calling this function does not touch event_periodic->count, if the
+ * periodic event was not set to run for ever and did run until expiration,
+ * then count will be != 0 after this function is called.
+ *
+ * @param[in]   event           event_periodic_callback context object to use
+ */
+static inline void event_periodic_callback_stop(event_periodic_callback_t *event)
+{
+    event_periodic_stop(&event->periodic);
+}
+
+#ifdef __cplusplus
+}
+#endif
+#endif /* EVENT_PERIODIC_CALLBACK_H */
+/** @} */

tests/event_periodic_callback/Makefile

@@ -0,0 +1,6 @@
+include ../Makefile.tests_common
+
+USEMODULE += event_periodic_callback
+USEMODULE += ztimer_msec
+
+include $(RIOTBASE)/Makefile.include

tests/event_periodic_callback/Makefile.ci

@@ -0,0 +1,3 @@
+BOARD_INSUFFICIENT_MEMORY := \
+    nucleo-l011k4 \
+    #

tests/event_periodic_callback/main.c

@@ -0,0 +1,49 @@
+/*
+ * Copyright (C) 2022 ML!PA Consulting GmbH
+ *
+ * This file is subject to the terms and conditions of the GNU Lesser
+ * General Public License v2.1. See the file LICENSE in the top level
+ * directory for more details.
+ */
+
+/**
+ * @ingroup     tests
+ * @{
+ *
+ * @file
+ * @brief       Periodic Callback test application
+ *
+ * @author      Benjamin Valentin <benjamin.valentin@ml-pa.com>
+ *
+ * @}
+ */
+
+#include <stdio.h>
+
+#include "event/periodic_callback.h"
+
+static void _event_cb(void *ctx)
+{
+    puts(ctx);
+}
+
+int main(void)
+{
+    event_periodic_callback_t a, b, c;
+
+    event_periodic_callback_init(&a, ZTIMER_MSEC, EVENT_PRIO_MEDIUM, _event_cb, "event A");
+    event_periodic_callback_init(&b, ZTIMER_MSEC, EVENT_PRIO_MEDIUM, _event_cb, "event B");
+    event_periodic_callback_init(&c, ZTIMER_MSEC, EVENT_PRIO_MEDIUM, _event_cb, "event C");
+
+    event_periodic_callback_set_count(&a, 6);
+    event_periodic_callback_set_count(&b, 3);
+    event_periodic_callback_set_count(&c, 2);
+
+    event_periodic_callback_start(&a,  502);
+    event_periodic_callback_start(&b, 1001);
+    event_periodic_callback_start(&c, 1500);
+
+    ztimer_sleep(ZTIMER_MSEC, 3020);
+
+    return 0;
+}

tests/event_periodic_callback/tests/01-run.py

@@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+
+import sys
+from testrunner import run
+
+
+def testfunc(child):
+    child.expect_exact("event A")
+    child.expect_exact("event B")
+    child.expect_exact("event A")
+    child.expect_exact("event C")
+    child.expect_exact("event A")
+    child.expect_exact("event B")
+    child.expect_exact("event A")
+    child.expect_exact("event A")
+    child.expect_exact("event C")
+    child.expect_exact("event B")
+    child.expect_exact("event A")
+
+
+if __name__ == "__main__":
+    sys.exit(run(testfunc))