Document which threads/queues all user-provided blocks are invoked on

[jpsim]

The block arguments for the methods in our public APIs are sometimes invoked once synchronously (Realm.write(...)), sometimes multiple times asynchronously on the thread on which it was added (Realm.addNotificationBlock(...)) and sometimes multiple times asynchronously on an internal thread or queue (SyncUser.logIn(...)).

We should audit all our APIs that accept blocks to specify their behavior.

[austinzheng]

In terms of the logIn callback (and all other sync callbacks in which users are expected to do UI work or set up Realms), I think the best solution is to just dispatch them to the main queue. Right now the way all these callbacks work violates the principle of least surprise.

[jpsim]

We've discussed this before. I don't think forcing a queue dispatch is the right move, since as a user you then can't avoid it.

In some other ticket, we proposed an improved API where an optional callback queue could be specified, defaulting to the main queue (which addresses the principle of least surprise which you mention) but also settable to nil to avoid a dispatch of any sort.

Regardless that's not what this issue is tracking, rather just documenting our existing behavior.