Document calling non-threadsafe primitives from threads (#314)

Also added a tox environment for buildings docs.

Author: uSpike

docs/contributing.rst

@@ -9,6 +9,9 @@ passes tests locally. To that end, the use of tox_ is recommended. The default t
 code style fixing tools and then the actual test suite. To only run the code style fixers, run
 ``tox -e lint``. To run the checks on all environments in parallel, invoke tox with ``tox -p``.
 
+To build the documentation, run ``tox -e docs`` which will generate a directory named ``build``
+in which you may view the formatted HTML documentation.
+
 The use of pre-commit_ is also highly recommended. You can find a sample configuration file at the
 root of the repository.
 

docs/synchronization.rst

@@ -7,6 +7,9 @@ Synchronization primitives are objects that are used by tasks to communicate and
 each other. They are useful for things like distributing workload, notifying other tasks and
 guarding access to shared resources.
 
+.. note:: AnyIO primitives are not thread-safe, therefore they should not be used directly from
+          worker threads.  Use :func:`~from_thread.run_sync` for that.
+
 Events
 ------
 

docs/threads.rst

@@ -53,6 +53,29 @@ If you need to call a coroutine function from a worker thread, you can do this::
 .. note:: The worker thread must have been spawned using :func:`~run_sync_in_worker_thread`
    for this to work.
 
+Calling synchronous code from a worker thread
+---------------------------------------------
+
+Occasionally you may need to call synchronous code in the event loop thread from a worker thread.
+Common cases include setting asynchronous events or sending data to a memory object stream.
+Because these methods aren't thread safe, you need to arrange them to be called inside the event
+loop thread using :func:`~from_thread.run_sync`::
+
+    import time
+
+    from anyio import Event, from_thread, to_thread, run
+
+    def worker(event):
+        time.sleep(1)
+        from_thread.run_sync(event.set)
+
+    async def main():
+        event = Event()
+        await to_thread.run_sync(worker, event)
+        await event.wait()
+
+    run(main)
+
 Calling asynchronous code from an external thread
 -------------------------------------------------
 

tox.ini

@@ -36,3 +36,7 @@ deps = mypy >= 0.900
 extras = test
 commands = mypy {posargs} src tests
 skip_install = true
+
+[testenv:docs]
+extras = doc
+commands = sphinx-build docs build/sphinx