Document thread-safety requirements in current version

[mattheworiordan]

We need to document that the iOS lib is not thread-safe and thus we need to:

• Add documentation in realtime usage section stating that the iOS lib is not thread-safe, with a high level summary of the types of problems they can expect, a recommendation and link to how Apple recommends they deal with concurrency and provide a very simple example of how to address this using for example GCD sync dispatch.
• Add the above notes to Github
• Add info about the objects we pass in listeners and notes on their safety to use in that we don't keep references to them.

[tcard]

See 0e48e63.

[mattheworiordan]

@tcard 0e48e63 is not a commit?

[tcard]

@mattheworiordan Sorry, it's a commit on docs: ably/docs@0e48e63

[tcard]

BTW, as part of #603 I put state transitions in GCD serial queues, which should reduce thread-safety issues and possibly even make the library internally thread-safe.

[paddybyers]

and possibly even make the library internally thread-safe

You don't sound very sure?

[tcard]

@paddybyers It definitely improves the situation, I'm not sure if it makes it completely thread-safe internally.

[mattheworiordan]

You don't sound very sure?

@paddybyers remember we still have our spike to complete

[tcard]

Done.