Skip to content

Commit

Permalink
System::Layer thread context documentation (project-chip#15047)
Browse files Browse the repository at this point in the history
#### Problem

Fixes  project-chip#7497 System timer API does not document what thread the callback is called on

#### Change overview

Added comment:

> The SDK is not generally thread safe. System::Layer methods should
> only be called from a single context, or otherwise externally
> synchronized. For platforms that use a CHIP event loop thread, timer
> callbacks are invoked on that thread; for platforms that use a CHIP
> lock, the lock is held.

#### Testing

Changes comment only.
  • Loading branch information
kpschoedel authored Feb 11, 2022
1 parent d44e04e commit dc95b77
Showing 1 changed file with 7 additions and 8 deletions.
15 changes: 7 additions & 8 deletions src/system/SystemLayer.h
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,13 @@ using TimerCompleteCallback = void (*)(Layer * aLayer, void * appState);
* - LayerLwIP: Adds methods specific to CHIP_SYSTEM_CONFIG_USING_LWIP.
* - LayerSockets: Adds I/O event methods specific to CHIP_SYSTEM_CONFIG_USING_SOCKETS.
* - LayerSocketsLoop: Adds methods for event-loop-based implementations.
*
* Threading notes:
*
* The SDK is not generally thread safe. System::Layer methods should only be called from
* a single context, or otherwise externally synchronized. For platforms that use a CHIP
* event loop thread, timer callbacks are invoked on that thread; for platforms that use
* a CHIP lock, the lock is held.
*/
class DLL_EXPORT Layer
{
Expand Down Expand Up @@ -125,14 +132,6 @@ class DLL_EXPORT Layer
* @brief
* Schedules a function with a signature identical to `OnCompleteFunct` to be run as soon as possible in the CHIP context.
*
* @note
* This function could, in principle, be implemented as `StartTimer`. The specification for `SystemTimer` however
* permits certain optimizations that might make that implementation impossible. Specifically, `SystemTimer`
* API may only be called from the thread owning the particular `System::Layer`, whereas the `ScheduleWork` may be
* called from any thread. Additionally, whereas the `SystemTimer` API permits the invocation of the already
* expired handler in line, `ScheduleWork` guarantees that the handler function will be called only after the
* current CHIP event completes.
*
* @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.
*
Expand Down

0 comments on commit dc95b77

Please sign in to comment.