Fix Darwin implementation of RunEventLoop to return when StopEventLoopTask is called.

[bzbarsky-apple]

Problem

Darwin impl of RunEventLoop never returns, even if a task calls StopEventLoopTask.

Change overview

1. Document the PlatformManager API a bit better.
2. Fix Darwin implementation to align with the documentation.

Testing

• Added some unit tests for the defined behavior.
• Ensured that basic tests in ./scripts/tests/test_suites.sh pass.

[mrjerryjohns]

Is there any way to actually prove from a testability standpoint the difference in behavior here vs. calling RunEventLoop?

i.e show that it returns, but still continues to do work on a separable execution context.

e.g

 CHIP_ERROR err = PlatformMgr().InitChipStack();
 NL_TEST_ASSERT(inSuite, err == CHIP_NO_ERROR);

PlatformMgr().ScheduleWork(DidWorkFunc);

NL_TEST_ASSERT(inSuite, DidWorkCheck == false);

PlatformMgr().StartEventLoopTask();

// setup a cond var that gets signaled by the function above, but times out after a while

err = PlatformMgr().StopEventLoopTask();

...

[bzbarsky-apple]

Yes, we could probably do something like that. I ran out of time to add more interesting tests here this morning, but would be very much in favor of more of that happening!