System timer API does not document what thread the callback is called on

[bzbarsky-apple]

Problem

The system timer API does not define what thread the timer callback will happen on. I think it's always the "message thread", though I don't know whether we have that clearly defined as a concept. But, importantly, the callback is NOT necessarily going to happen on the thread that started the timer, as far as I can tell. This is pretty non-obvious.

Proposed Solution

Document exactly how this API works, so consumers don't get surprised.

@tcarmelveilleux @andy31415 @msandstedt

[msandstedt]

Problem

The system timer API does not define what thread the timer callback will happen on. I think it's always the "message thread", though I don't know whether we have that clearly defined as a concept. But, importantly, the callback is NOT necessarily going to happen on the thread that started the timer, as far as I can tell. This is pretty non-obvious.

Proposed Solution

Document exactly how this API works, so consumers don't get surprised.

@tcarmelveilleux @andy31415 @msandstedt

My assumption was that this was how it would work, simply because that's the most straight forward implementation. And in the absence of a truly platform-agnostic mechanism to dispatch work onto other threads (e.g. something that does what delegates do in .NET, what signals and slots do in Qt, etc., but with a generic and consistent interface for all of our platforms), that seems pretty tough to do. I certainly don't know how to do it in a platform-agnostic way.

I think that's OK though. It just means you need to understand this and dispatch to your particular thread context from the callback. So two steps to get code executing in your desired thread context instead of one.

One observation. This interface:

Error StartTimer(uint32_t aMilliseconds, TimerCompleteFunct aComplete, void * aAppState);

I have personally found it more natural to have a delegate class type defined and pass this instead of function and data pointers. It doesn't really matter. You can accomplish the same with both. But that's become a pattern elsewhere in the stack. It just feels easier (to me) to be able to reference this on yourself to get whatever context you need when called back. Not a big deal though.

[bzbarsky-apple]

Right, to be clear I am not asking to change what the API does, just to have clear documentation about the contract.

[mrjerryjohns]

From my coarse analysis, it looks like it runs on the CHIP thread.

Tracing through Timer::Start in SystemTimer.cpp, I found:

On POSIX:

• Calls WakeSelect() in Line 173, which just wakes up select on the CHIP thread and makes it re-assess the timer pool and dispatch any expired timer callbacks.

On FreeRTOS:

• Eventually calls into GenericPlatformManagerImpl_FreeRTOS<ImplClass>::_StartChipTimer, which posts a dummy event to the CHIP event queue which causes it to unblock, and handle timers in GenericPlatformManagerImpl_FreeRTOS<ImplClass>::_RunEventLoop.

On Zephr:

• I believe it uses sockets, and makes the same WakeSelect() call, which should go through the POSIX flow above.