a brief note about threads and multiprocessing, #281

docgen/programming_guide/index.txt

@@ -26,3 +26,4 @@ If this is your first time reading about cocos2d, we suggest you start at :doc:`
    default_handlers
    collision
    skeleton/skeleton
+   threading_and_multiprocessing

docgen/programming_guide/threading_and_multiprocessing.txt

@@ -0,0 +1,16 @@
+===========================================
+A few tips on threading and multiprocessing
+===========================================
+
+  * be familiarized with cocos and pyglet in single threaded code before attempting threads or subprocess
+  * consider to use events and timers instead of threads or subproces
+  * multiprocessing: import cocos and pyglet only in one process, see `issue #281 <https://github.com/los-cocos/cocos/issues/281>`_
+  * threading
+
+    - the gui thread must be the main thread
+    - cocos code is not reentrant or thread-safe; call it only from the gui thread
+    - use a queue to communicate with the gui thread; in the gui thread schedule a function to poll (non-blocking) the queue and dispatch as events
+  * The pyglet and cocos google groups have a few threads relevant, search there for 'threading' or 'subprocess'
+
+
+