FurEventLoop: add support for FuriEventFlag, simplify API (#3958)

* Core: event_flag, removing duplicate code
* event_loop: add support furi_event_flags
* Examples: add missing free in event loop examples
* Furi: fix event flag
* Sync api symbols
* Unit_test: evet_loop_event_flags
* Fix multiple waiting list elements handling
* Unit_test: add event_loop_event_flag test
* FURI: event_loop add restrictions
* Fix multiple waiting lists items for good
* Improve FuriEventLoop unit tests
* Abolish callback return value
* Remove return value from callback signature
* Use bool level value instead of int32_t
* Add unit tests for FuriStreamBuffer
* Add unit tests for FuriSemaphore
* Speed up test execution
* Improve docs
* Add a stub for furi os-level primitives
* Add more checks for edge cases
* Allow event loop notification from ISR
* Bump api version

Co-authored-by: Aleksandr Kutuzov <alleteam@gmail.com>
Co-authored-by: Georgii Surkov <georgii.surkov@outlook.com>
Co-authored-by: Georgii Surkov <37121527+gsurkov@users.noreply.github.com>

furi/core/event_flag.c

@@ -5,11 +5,15 @@
 #include <FreeRTOS.h>
 #include <event_groups.h>
 
+#include "event_loop_link_i.h"
+
 #define FURI_EVENT_FLAG_MAX_BITS_EVENT_GROUPS 24U
-#define FURI_EVENT_FLAG_INVALID_BITS          (~((1UL << FURI_EVENT_FLAG_MAX_BITS_EVENT_GROUPS) - 1U))
+#define FURI_EVENT_FLAG_VALID_BITS            ((1UL << FURI_EVENT_FLAG_MAX_BITS_EVENT_GROUPS) - 1U)
+#define FURI_EVENT_FLAG_INVALID_BITS          (~(FURI_EVENT_FLAG_VALID_BITS))
 
 struct FuriEventFlag {
     StaticEventGroup_t container;
+    FuriEventLoopLink event_loop_link;
 };
 
 // IMPORTANT: container MUST be the FIRST struct member
@@ -27,6 +31,11 @@ FuriEventFlag* furi_event_flag_alloc(void) {
 
 void furi_event_flag_free(FuriEventFlag* instance) {
     furi_check(!FURI_IS_IRQ_MODE());
+
+    // Event Loop must be disconnected
+    furi_check(!instance->event_loop_link.item_in);
+    furi_check(!instance->event_loop_link.item_out);
+
     vEventGroupDelete((EventGroupHandle_t)instance);
     free(instance);
 }
@@ -39,6 +48,8 @@ uint32_t furi_event_flag_set(FuriEventFlag* instance, uint32_t flags) {
     uint32_t rflags;
     BaseType_t yield;
 
+    FURI_CRITICAL_ENTER();
+
     if(FURI_IS_IRQ_MODE()) {
         yield = pdFALSE;
         if(xEventGroupSetBitsFromISR(hEventGroup, (EventBits_t)flags, &yield) == pdFAIL) {
@@ -48,11 +59,15 @@ uint32_t furi_event_flag_set(FuriEventFlag* instance, uint32_t flags) {
             portYIELD_FROM_ISR(yield);
         }
     } else {
-        vTaskSuspendAll();
         rflags = xEventGroupSetBits(hEventGroup, (EventBits_t)flags);
-        (void)xTaskResumeAll();
     }
 
+    if(rflags & flags) {
+        furi_event_loop_link_notify(&instance->event_loop_link, FuriEventLoopEventIn);
+    }
+
+    FURI_CRITICAL_EXIT();
+
     /* Return event flags after setting */
     return rflags;
 }
@@ -64,6 +79,7 @@ uint32_t furi_event_flag_clear(FuriEventFlag* instance, uint32_t flags) {
     EventGroupHandle_t hEventGroup = (EventGroupHandle_t)instance;
     uint32_t rflags;
 
+    FURI_CRITICAL_ENTER();
     if(FURI_IS_IRQ_MODE()) {
         rflags = xEventGroupGetBitsFromISR(hEventGroup);
 
@@ -79,6 +95,11 @@ uint32_t furi_event_flag_clear(FuriEventFlag* instance, uint32_t flags) {
         rflags = xEventGroupClearBits(hEventGroup, (EventBits_t)flags);
     }
 
+    if(rflags & flags) {
+        furi_event_loop_link_notify(&instance->event_loop_link, FuriEventLoopEventOut);
+    }
+    FURI_CRITICAL_EXIT();
+
     /* Return event flags before clearing */
     return rflags;
 }
@@ -146,6 +167,36 @@ uint32_t furi_event_flag_wait(
         }
     }
 
+    if((rflags & FuriFlagError) == 0U) {
+        furi_event_loop_link_notify(&instance->event_loop_link, FuriEventLoopEventOut);
+    }
+
     /* Return event flags before clearing */
     return rflags;
 }
+
+static FuriEventLoopLink* furi_event_flag_event_loop_get_link(FuriEventLoopObject* object) {
+    FuriEventFlag* instance = object;
+    furi_assert(instance);
+    return &instance->event_loop_link;
+}
+
+static bool
+    furi_event_flag_event_loop_get_level(FuriEventLoopObject* object, FuriEventLoopEvent event) {
+    FuriEventFlag* instance = object;
+    furi_assert(instance);
+
+    if(event == FuriEventLoopEventIn) {
+        return (furi_event_flag_get(instance) & FURI_EVENT_FLAG_VALID_BITS);
+    } else if(event == FuriEventLoopEventOut) {
+        return (furi_event_flag_get(instance) & FURI_EVENT_FLAG_VALID_BITS) !=
+               FURI_EVENT_FLAG_VALID_BITS;
+    } else {
+        furi_crash();
+    }
+}
+
+const FuriEventLoopContract furi_event_flag_event_loop_contract = {
+    .get_link = furi_event_flag_event_loop_get_link,
+    .get_level = furi_event_flag_event_loop_get_level,
+};

furi/core/event_loop.c

@@ -101,36 +101,39 @@ void furi_event_loop_free(FuriEventLoop* instance) {
 }
 
 static inline FuriEventLoopProcessStatus
-    furi_event_loop_poll_process_level_event(FuriEventLoopItem* item) {
-    if(!item->contract->get_level(item->object, item->event)) {
-        return FuriEventLoopProcessStatusComplete;
-    } else if(item->callback(item->object, item->callback_context)) {
-        return FuriEventLoopProcessStatusIncomplete;
-    } else {
-        return FuriEventLoopProcessStatusAgain;
-    }
+    furi_event_loop_process_edge_event(FuriEventLoopItem* item) {
+    FuriEventLoopProcessStatus status = FuriEventLoopProcessStatusComplete;
+    item->callback(item->object, item->callback_context);
+
+    return status;
 }
 
 static inline FuriEventLoopProcessStatus
-    furi_event_loop_poll_process_edge_event(FuriEventLoopItem* item) {
-    if(item->callback(item->object, item->callback_context)) {
-        return FuriEventLoopProcessStatusComplete;
-    } else {
-        return FuriEventLoopProcessStatusAgain;
+    furi_event_loop_process_level_event(FuriEventLoopItem* item) {
+    FuriEventLoopProcessStatus status = FuriEventLoopProcessStatusComplete;
+    if(item->contract->get_level(item->object, item->event)) {
+        item->callback(item->object, item->callback_context);
+
+        if(item->contract->get_level(item->object, item->event)) {
+            status = FuriEventLoopProcessStatusIncomplete;
+        }
     }
+
+    return status;
 }
 
 static inline FuriEventLoopProcessStatus
-    furi_event_loop_poll_process_event(FuriEventLoop* instance, FuriEventLoopItem* item) {
+    furi_event_loop_process_event(FuriEventLoop* instance, FuriEventLoopItem* item) {
     FuriEventLoopProcessStatus status;
+
     if(item->event & FuriEventLoopEventFlagOnce) {
         furi_event_loop_unsubscribe(instance, item->object);
     }
 
     if(item->event & FuriEventLoopEventFlagEdge) {
-        status = furi_event_loop_poll_process_edge_event(item);
+        status = furi_event_loop_process_edge_event(item);
     } else {
-        status = furi_event_loop_poll_process_level_event(item);
+        status = furi_event_loop_process_level_event(item);
     }
 
     if(item->owner == NULL) {
@@ -140,7 +143,7 @@ static inline FuriEventLoopProcessStatus
     return status;
 }
 
-static void furi_event_loop_process_waiting_list(FuriEventLoop* instance) {
+static inline FuriEventLoopItem* furi_event_loop_get_waiting_item(FuriEventLoop* instance) {
     FuriEventLoopItem* item = NULL;
 
     FURI_CRITICAL_ENTER();
@@ -152,27 +155,42 @@ static void furi_event_loop_process_waiting_list(FuriEventLoop* instance) {
 
     FURI_CRITICAL_EXIT();
 
+    return item;
+}
+
+static inline void furi_event_loop_sync_flags(FuriEventLoop* instance) {
+    FURI_CRITICAL_ENTER();
+
+    if(!WaitingList_empty_p(instance->waiting_list)) {
+        xTaskNotifyIndexed(
+            (TaskHandle_t)instance->thread_id,
+            FURI_EVENT_LOOP_FLAG_NOTIFY_INDEX,
+            FuriEventLoopFlagEvent,
+            eSetBits);
+    }
+
+    FURI_CRITICAL_EXIT();
+}
+
+static void furi_event_loop_process_waiting_list(FuriEventLoop* instance) {
+    FuriEventLoopItem* item = furi_event_loop_get_waiting_item(instance);
     if(!item) return;
 
-    while(true) {
-        FuriEventLoopProcessStatus ret = furi_event_loop_poll_process_event(instance, item);
+    FuriEventLoopProcessStatus status = furi_event_loop_process_event(instance, item);
 
-        if(ret == FuriEventLoopProcessStatusComplete) {
-            // Event processing complete, break from loop
-            break;
-        } else if(ret == FuriEventLoopProcessStatusIncomplete) {
-            // Event processing incomplete more processing needed
-        } else if(ret == FuriEventLoopProcessStatusAgain) { //-V547
-            furi_event_loop_item_notify(item);
-            break;
-            // Unsubscribed from inside the callback, delete item
-        } else if(ret == FuriEventLoopProcessStatusFreeLater) { //-V547
-            furi_event_loop_item_free(item);
-            break;
-        } else {
-            furi_crash();
-        }
+    if(status == FuriEventLoopProcessStatusComplete) {
+        // Event processing complete, do nothing
+    } else if(status == FuriEventLoopProcessStatusIncomplete) {
+        // Event processing incomplete, put item back in waiting list
+        furi_event_loop_item_notify(item);
+    } else if(status == FuriEventLoopProcessStatusFreeLater) { //-V547
+        // Unsubscribed from inside the callback, delete item
+        furi_event_loop_item_free(item);
+    } else {
+        furi_crash();
     }
+
+    furi_event_loop_sync_flags(instance);
 }
 
 static void furi_event_loop_restore_flags(FuriEventLoop* instance, uint32_t flags) {
@@ -239,14 +257,28 @@ void furi_event_loop_run(FuriEventLoop* instance) {
     }
 }
 
+static void furi_event_loop_notify(FuriEventLoop* instance, FuriEventLoopFlag flag) {
+    if(FURI_IS_IRQ_MODE()) {
+        BaseType_t yield = pdFALSE;
+
+        (void)xTaskNotifyIndexedFromISR(
+            (TaskHandle_t)instance->thread_id,
+            FURI_EVENT_LOOP_FLAG_NOTIFY_INDEX,
+            flag,
+            eSetBits,
+            &yield);
+
+        portYIELD_FROM_ISR(yield);
+
+    } else {
+        (void)xTaskNotifyIndexed(
+            (TaskHandle_t)instance->thread_id, FURI_EVENT_LOOP_FLAG_NOTIFY_INDEX, flag, eSetBits);
+    }
+}
+
 void furi_event_loop_stop(FuriEventLoop* instance) {
     furi_check(instance);
-
-    xTaskNotifyIndexed(
-        (TaskHandle_t)instance->thread_id,
-        FURI_EVENT_LOOP_FLAG_NOTIFY_INDEX,
-        FuriEventLoopFlagStop,
-        eSetBits);
+    furi_event_loop_notify(instance, FuriEventLoopFlagStop);
 }
 
 /*
@@ -268,11 +300,7 @@ void furi_event_loop_pend_callback(
 
     PendingQueue_push_front(instance->pending_queue, item);
 
-    xTaskNotifyIndexed(
-        (TaskHandle_t)instance->thread_id,
-        FURI_EVENT_LOOP_FLAG_NOTIFY_INDEX,
-        FuriEventLoopFlagPending,
-        eSetBits);
+    furi_event_loop_notify(instance, FuriEventLoopFlagPending);
 }
 
 /*
@@ -328,6 +356,17 @@ static void furi_event_loop_object_subscribe(
  * Public specialized subscription API
  */
 
+void furi_event_loop_subscribe_event_flag(
+    FuriEventLoop* instance,
+    FuriEventFlag* event_flag,
+    FuriEventLoopEvent event,
+    FuriEventLoopEventCallback callback,
+    void* context) {
+    extern const FuriEventLoopContract furi_event_flag_event_loop_contract;
+    furi_event_loop_object_subscribe(
+        instance, event_flag, &furi_event_flag_event_loop_contract, event, callback, context);
+}
+
 void furi_event_loop_subscribe_message_queue(
     FuriEventLoop* instance,
     FuriMessageQueue* message_queue,
@@ -491,11 +530,7 @@ static void furi_event_loop_item_notify(FuriEventLoopItem* instance) {
 
     FURI_CRITICAL_EXIT();
 
-    xTaskNotifyIndexed(
-        (TaskHandle_t)owner->thread_id,
-        FURI_EVENT_LOOP_FLAG_NOTIFY_INDEX,
-        FuriEventLoopFlagEvent,
-        eSetBits);
+    furi_event_loop_notify(owner, FuriEventLoopFlagEvent);
 }
 
 static bool furi_event_loop_item_is_waiting(FuriEventLoopItem* instance) {

furi/core/event_loop.h

@@ -11,6 +11,9 @@
  *             provide any compatibility with other event driven APIs. But
  *             programming concepts are the same, except some runtime
  *             limitations from our side.
+ *
+ * @warning Only ONE instance of FuriEventLoop per thread is possible. ALL FuriEventLoop
+ * funcitons MUST be called from the same thread that the instance was created in.
  */
 #pragma once
 
@@ -197,10 +200,29 @@ typedef void FuriEventLoopObject;
  *
  * @param      object   The object that triggered the event
  * @param      context  The context that was provided upon subscription
- *
- * @return     true if event was processed, false if we need to delay processing
  */
-typedef bool (*FuriEventLoopEventCallback)(FuriEventLoopObject* object, void* context);
+typedef void (*FuriEventLoopEventCallback)(FuriEventLoopObject* object, void* context);
+
+/** Opaque event flag type */
+typedef struct FuriEventFlag FuriEventFlag;
+
+/** Subscribe to event flag events
+ *
+ * @warning you can only have one subscription for one event type.
+ *
+ * @param      instance       The Event Loop instance
+ * @param      event_flag     The event flag to add
+ * @param[in]  event          The Event Loop event to trigger on
+ * @param[in]  callback       The callback to call on event
+ * @param      context        The context for callback
+ */
+
+void furi_event_loop_subscribe_event_flag(
+    FuriEventLoop* instance,
+    FuriEventFlag* event_flag,
+    FuriEventLoopEvent event,
+    FuriEventLoopEventCallback callback,
+    void* context);
 
 /** Opaque message queue type */
 typedef struct FuriMessageQueue FuriMessageQueue;

furi/core/event_loop_i.h

@@ -59,7 +59,6 @@ typedef enum {
 typedef enum {
     FuriEventLoopProcessStatusComplete,
     FuriEventLoopProcessStatusIncomplete,
-    FuriEventLoopProcessStatusAgain,
     FuriEventLoopProcessStatusFreeLater,
 } FuriEventLoopProcessStatus;
 

furi/core/event_loop_link_i.h

@@ -21,7 +21,7 @@ void furi_event_loop_link_notify(FuriEventLoopLink* instance, FuriEventLoopEvent
 
 typedef FuriEventLoopLink* (*FuriEventLoopContractGetLink)(FuriEventLoopObject* object);
 
-typedef uint32_t (
+typedef bool (
     *FuriEventLoopContractGetLevel)(FuriEventLoopObject* object, FuriEventLoopEvent event);
 
 typedef struct {

furi/core/event_loop_timer.h

@@ -1,6 +1,9 @@
 /**
  * @file event_loop_timer.h
  * @brief Software timer functionality for FuriEventLoop.
+ *
+ * @warning ALL FuriEventLoopTimer functions MUST be called from the
+ * same thread that the owner FuriEventLoop instance was created in.
  */
 
 #pragma once

furi/core/message_queue.c

@@ -213,7 +213,7 @@ static FuriEventLoopLink* furi_message_queue_event_loop_get_link(FuriEventLoopOb
     return &instance->event_loop_link;
 }
 
-static uint32_t
+static bool
     furi_message_queue_event_loop_get_level(FuriEventLoopObject* object, FuriEventLoopEvent event) {
     FuriMessageQueue* instance = object;
     furi_assert(instance);

furi/core/mutex.c

@@ -144,13 +144,13 @@ static FuriEventLoopLink* furi_mutex_event_loop_get_link(FuriEventLoopObject* ob
     return &instance->event_loop_link;
 }
 
-static uint32_t
+static bool
     furi_mutex_event_loop_get_level(FuriEventLoopObject* object, FuriEventLoopEvent event) {
     FuriMutex* instance = object;
     furi_assert(instance);
 
     if(event == FuriEventLoopEventIn || event == FuriEventLoopEventOut) {
-        return furi_mutex_get_owner(instance) ? 0 : 1;
+        return !furi_mutex_get_owner(instance);
     } else {
         furi_crash();
     }

furi/core/semaphore.c

@@ -165,7 +165,7 @@ static FuriEventLoopLink* furi_semaphore_event_loop_get_link(FuriEventLoopObject
     return &instance->event_loop_link;
 }
 
-static uint32_t
+static bool
     furi_semaphore_event_loop_get_level(FuriEventLoopObject* object, FuriEventLoopEvent event) {
     FuriSemaphore* instance = object;
     furi_assert(instance);

furi/core/stream_buffer.c

@@ -157,7 +157,7 @@ static FuriEventLoopLink* furi_stream_buffer_event_loop_get_link(FuriEventLoopOb
     return &stream_buffer->event_loop_link;
 }
 
-static uint32_t
+static bool
     furi_stream_buffer_event_loop_get_level(FuriEventLoopObject* object, FuriEventLoopEvent event) {
     FuriStreamBuffer* stream_buffer = object;
     furi_assert(stream_buffer);