From b6e1a482745b02931f1282680335c04afca2bf33 Mon Sep 17 00:00:00 2001
From: Tennessee Carmel-Veilleux <tennessee.carmelveilleux@gmail.com>
Date: Tue, 18 Jun 2024 15:39:49 -0400
Subject: [PATCH] Improve documentation of ScheduleLambda (#33967)

* Improve documentation of ScheduleLambda

Problem:
- SystemLayer::ScheduleLambda is critical to allow correct
  context updates to data, but it was claimed it had to be
  executed in Matter context already, which is the opposite
  of the point of the method.

Fixes #26538

This PR:
- Improves the documentation of several methods in SystemLayer.h
- Makes ScheduleLambdaBridge private (not called elsewhere)
- Adds a static assert to avoid arguments on the lambda

Testing done:
- All unit tests still pass

* Restyled by clang-format

---------

Co-authored-by: Restyled.io <commits@restyled.io>
---
 src/system/SystemLayer.h | 37 +++++++++++++++++++------------------
 1 file changed, 19 insertions(+), 18 deletions(-)

diff --git a/src/system/SystemLayer.h b/src/system/SystemLayer.h
index d91a80d9be8f57..76d778a59a6d79 100644
--- a/src/system/SystemLayer.h
+++ b/src/system/SystemLayer.h
@@ -25,6 +25,9 @@
 
 #pragma once
 
+#include <type_traits>
+#include <utility>
+
 // Include configuration headers
 #include <system/SystemConfig.h>
 
@@ -47,8 +50,6 @@
 #include <ev.h>
 #endif // CHIP_SYSTEM_CONFIG_USE_DISPATCH/LIBEV
 
-#include <utility>
-
 namespace chip {
 namespace System {
 
@@ -181,9 +182,11 @@ class DLL_EXPORT Layer
 
     /**
      * @brief
-     *   Schedules a function with a signature identical to `OnCompleteFunct` to be run as soon as possible in the Matter context.
-     *   This must only be called when already in the Matter context (from the Matter event loop, or while holding the Matter
-     *   stack lock).
+     *   Schedules a `TimerCompleteCallback` to be run as soon as possible in the Matter context.
+     *
+     *  WARNING: This must only be called when already in the Matter context (from the Matter event loop, or
+     *           while holding the Matter stack lock). The `PlatformMgr::ScheduleWork()` equivalent method
+     *           is safe to call outside Matter context.
      *
      * @param[in] aComplete     A pointer to a callback function to be called when this timer fires.
      * @param[in] aAppState     A pointer to an application state object to be passed to the callback function as argument.
@@ -196,31 +199,29 @@ class DLL_EXPORT Layer
 
     /**
      * @brief
-     *   Schedules a lambda even to be run as soon as possible in the CHIP context. This function is not thread-safe,
-     *   it must be called with in the CHIP context
+     *   Schedules a lambda object to be run as soon as possible in the Matter context.
      *
-     *  @param[in] event   A object encapsulate the context of a lambda
+     * This is safe to call from any context and will guarantee execution in Matter context.
+     * Note that the Lambda's capture have to fit within `CHIP_CONFIG_LAMBDA_EVENT_SIZE` bytes.
      *
-     *  @retval    CHIP_NO_ERROR                  On success.
-     *  @retval    other Platform-specific errors generated indicating the reason for failure.
-     */
-    CHIP_ERROR ScheduleLambdaBridge(LambdaBridge && event);
-
-    /**
-     * @brief
-     *   Schedules a lambda object to be run as soon as possible in the CHIP context. This function is not thread-safe,
-     *   it must be called with in the CHIP context
+     * @param[in] lambda The Lambda to execute in Matter context.
+     *
+     * @retval CHIP_NO_ERROR On success.
+     * @retval other Platform-specific errors generated indicating the reason for failure.
      */
     template <typename Lambda>
     CHIP_ERROR ScheduleLambda(const Lambda & lambda)
     {
+        static_assert(std::is_invocable_v<Lambda>, "lambda argument must be an invocable with no arguments");
         LambdaBridge bridge;
         bridge.Initialize(lambda);
         return ScheduleLambdaBridge(std::move(bridge));
     }
 
 private:
-    // Copy and assignment NOT DEFINED
+    CHIP_ERROR ScheduleLambdaBridge(LambdaBridge && bridge);
+
+    // Not copyable
     Layer(const Layer &)             = delete;
     Layer & operator=(const Layer &) = delete;
 };