Document concurrency problems with emits (Fixes #403)

Author: miguelgrinberg

socketio/asyncio_client.py

@@ -148,7 +148,13 @@ async def emit(self, event, data=None, namespace=None, callback=None):
                          by the client. Callback functions can only be used
                          when addressing an individual client.
 
-        Note: this method is a coroutine.
+        Note: this method is not designed to be used concurrently. If multiple
+        tasks are emitting at the same time on the same client connection, then
+        messages composed of multiple packets may end up being sent in an
+        incorrect sequence. Use standard concurrency solutions (such as a Lock
+        object) to prevent this situation.
+
+        Note 2: this method is a coroutine.
         """
         namespace = namespace or '/'
         if namespace != '/' and namespace not in self.namespaces:
@@ -214,7 +220,13 @@ async def call(self, event, data=None, namespace=None, timeout=60):
                         the client acknowledges the event, then a
                         ``TimeoutError`` exception is raised.
 
-        Note: this method is a coroutine.
+        Note: this method is not designed to be used concurrently. If multiple
+        tasks are emitting at the same time on the same client connection, then
+        messages composed of multiple packets may end up being sent in an
+        incorrect sequence. Use standard concurrency solutions (such as a Lock
+        object) to prevent this situation.
+
+        Note 2: this method is a coroutine.
         """
         callback_event = self.eio.create_event()
         callback_args = []

socketio/asyncio_server.py

@@ -118,7 +118,13 @@ async def emit(self, event, data=None, to=None, room=None, skip_sid=None,
                              to always leave this parameter with its default
                              value of ``False``.
 
-        Note: this method is a coroutine.
+        Note: this method is not designed to be used concurrently. If multiple
+        tasks are emitting at the same time to the same client connection, then
+        messages composed of multiple packets may end up being sent in an
+        incorrect sequence. Use standard concurrency solutions (such as a Lock
+        object) to prevent this situation.
+
+        Note 2: this method is a coroutine.
         """
         namespace = namespace or '/'
         room = to or room
@@ -194,6 +200,14 @@ async def call(self, event, data=None, to=None, sid=None, namespace=None,
                              single server process is used. It is recommended
                              to always leave this parameter with its default
                              value of ``False``.
+
+        Note: this method is not designed to be used concurrently. If multiple
+        tasks are emitting at the same time to the same client connection, then
+        messages composed of multiple packets may end up being sent in an
+        incorrect sequence. Use standard concurrency solutions (such as a Lock
+        object) to prevent this situation.
+
+        Note 2: this method is a coroutine.
         """
         if not self.async_handlers:
             raise RuntimeError(

socketio/client.py

@@ -311,6 +311,12 @@ def emit(self, event, data=None, namespace=None, callback=None):
                          that will be passed to the function are those provided
                          by the client. Callback functions can only be used
                          when addressing an individual client.
+
+        Note: this method is not thread safe. If multiple threads are emitting
+        at the same time on the same client connection, messages composed of
+        multiple packets may end up being sent in an incorrect sequence. Use
+        standard concurrency solutions (such as a Lock object) to prevent this
+        situation.
         """
         namespace = namespace or '/'
         if namespace != '/' and namespace not in self.namespaces:
@@ -373,6 +379,12 @@ def call(self, event, data=None, namespace=None, timeout=60):
         :param timeout: The waiting timeout. If the timeout is reached before
                         the client acknowledges the event, then a
                         ``TimeoutError`` exception is raised.
+
+        Note: this method is not thread safe. If multiple threads are emitting
+        at the same time on the same client connection, messages composed of
+        multiple packets may end up being sent in an incorrect sequence. Use
+        standard concurrency solutions (such as a Lock object) to prevent this
+        situation.
         """
         callback_event = self.eio.create_event()
         callback_args = []

socketio/server.py

@@ -280,6 +280,12 @@ def emit(self, event, data=None, to=None, room=None, skip_sid=None,
                              single server process is used. It is recommended
                              to always leave this parameter with its default
                              value of ``False``.
+
+        Note: this method is not thread safe. If multiple threads are emitting
+        at the same time to the same client, then messages composed of
+        multiple packets may end up being sent in an incorrect sequence. Use
+        standard concurrency solutions (such as a Lock object) to prevent this
+        situation.
         """
         namespace = namespace or '/'
         room = to or room
@@ -352,6 +358,12 @@ def call(self, event, data=None, to=None, sid=None, namespace=None,
                              single server process is used. It is recommended
                              to always leave this parameter with its default
                              value of ``False``.
+
+        Note: this method is not thread safe. If multiple threads are emitting
+        at the same time to the same client, then messages composed of
+        multiple packets may end up being sent in an incorrect sequence. Use
+        standard concurrency solutions (such as a Lock object) to prevent this
+        situation.
         """
         if not self.async_handlers:
             raise RuntimeError(