Add note on thread safety.

Author: paulross

.gitignore

@@ -1,5 +1,4 @@
 build/
 *.so
-PythonExtensionPatterns/
 doc/sphinx/build/
 __pycache__/

PythonExtensionPatterns.bbprojectd/paulross.bbprojectsettings

@@ -30,43 +30,43 @@
 			<dict>
 				<key>BookmarkData</key>
 				<data>
-				Ym9va0gEAAAAAAQQMAAAAAAAAAAAAAAAAAAAAAAAAAAA
+				Ym9va1QEAAAAAAQQMAAAAAAAAAAAAAAAAAAAAAAAAAAA
 				AAAAAAAAAAAAAAAAAAAAOAMAAAUAAAABAQAAVXNlcnMA
-				AAAIAAAAAQEAAHBhdWxyb3NzCQAAAAEBAABEb2N1bWVu
-				dHMAAAAJAAAAAQEAAHdvcmtzcGFjZQAAABcAAAABAQAA
-				UHl0aG9uRXh0ZW5zaW9uUGF0dGVybnMAAwAAAAEBAABk
-				b2MABgAAAAEBAABzcGhpbngAAAYAAAABAQAAc291cmNl
-				AAAgAAAAAQYAAAQAAAAUAAAAJAAAADgAAABMAAAAbAAA
-				AHgAAACIAAAACAAAAAQDAACOZAIAAAAAAAgAAAAEAwAA
-				OfoIAAAAAAAIAAAABAMAADr6CAAAAAAACAAAAAQDAAD9
-				mAsAAAAAAAgAAAAEAwAACYM5AAAAAAAIAAAABAMAAKHM
-				OQAAAAAACAAAAAQDAADkHjoAAAAAAAgAAAAEAwAA9R46
-				AAAAAAAgAAAAAQYAAMAAAADQAAAA4AAAAPAAAAAAAQAA
-				EAEAACABAAAwAQAACAAAAAAEAABBuR/7+QAAABgAAAAB
-				AgAAAgAAAAAAAAAPAAAAAAAAAAAAAAAAAAAAAAAAAAEF
-				AAAEAAAAAwMAAAMAAAAEAAAAAwMAAAYAAAAEAAAAAwMA
-				APUBAAAMAAAAAQEAAE1hY2ludG9zaCBIRAgAAAAEAwAA
-				ACCIPToAAAAIAAAAAAQAAEG4IjLDAAAAJAAAAAEBAAAy
-				NTQwQUFCQS1DNEZFLTM4MTgtQjQ3RC02MEJFOUJFMTJC
-				MjcYAAAAAQIAAIEAAAABAAgA7xcAAAEACAAAAAAAAAAA
-				AAEAAAABAQAALwAAAN4AAAABAgAAZTgwNDdjOWJiN2I0
-				NjU4NTc2MDAxODM1MTE2NGZkZWE0NjE1NzVhNzswMDAw
-				MDAwMDswMDAwMDAwMDswMDAwMDAwMDAwMDAwMDIwO2Nv
-				bS5hcHBsZS5hcHAtc2FuZGJveC5yZWFkLXdyaXRlOzAw
-				MDAwMDAxOzAxMDAwMDAzOzAwMDAwMDAwMDAzYTFlZjU7
-				L3VzZXJzL3BhdWxyb3NzL2RvY3VtZW50cy93b3Jrc3Bh
-				Y2UvcHl0aG9uZXh0ZW5zaW9ucGF0dGVybnMvZG9jL3Nw
-				aGlueC9zb3VyY2UAAADYAAAA/v///wEAAAAAAAAAEQAA
-				AAQQAACYAAAAAAAAAAUQAABAAQAAAAAAABAQAAB4AQAA
-				AAAAAEAQAABoAQAAAAAAAFUQAACgAQAAAAAAAFYQAACY
-				AQAAAAAAAAIgAABEAgAAAAAAABAgAADEAQAAAAAAABEg
-				AAD4AQAAAAAAABIgAADYAQAAAAAAABMgAADoAQAAAAAA
-				ACAgAAAkAgAAAAAAADAgAACYAQAAAAAAAAHAAACsAQAA
-				AAAAABHAAAAUAAAAAAAAABLAAAC4AQAAAAAAAIDwAABQ
-				AgAAAAAAAA==
+				AAAIAAAAAQEAAHBhdWxyb3NzBgAAAAEBAABHaXRIdWIA
+				ABcAAAABAQAAUHl0aG9uRXh0ZW5zaW9uUGF0dGVybnMA
+				AwAAAAEBAABkb2MABgAAAAEBAABzcGhpbngAAAYAAAAB
+				AQAAc291cmNlAAAgAAAAAQYAAAQAAAAUAAAAJAAAABQA
+				AAA0AAAAVAAAAGAAAABwAAAACAAAAAQDAADwLAYAAAAA
+				AAgAAAAEAwAApGAJAAAAAAAIAAAABAMAAJS7IwAAAAAA
+				CAAAAAQDAAAWJzUAAAAAAAgAAAAEAwAAdzZoAAAAAAAI
+				AAAABAMAAMc2aAAAAAAACAAAAAQDAADKNmgAAAAAAAgA
+				AAAEAwAAzDZoAAAAAAAgAAAAAQYAAKgAAAC4AAAAyAAA
+				ANgAAADoAAAA+AAAAAgBAAAYAQAACAAAAAAEAABBv4y4
+				tAAAABgAAAABAgAAAgAAAAAAAAAPAAAAAAAAAAAAAAAA
+				AAAAAAAAAAEFAAAEAAAAAwMAAAMAAAAEAAAAAwMAAAYA
+				AAAEAAAAAwMAAPUBAAARAAAAAQkAAGZpbGU6Ly9sb2Nh
+				bGhvc3QvAAAADAAAAAEBAABNYWNpbnRvc2ggSEQIAAAA
+				BAMAAAAAAK3oAAAACAAAAAAEAABBvBAmtQAAACQAAAAB
+				AQAAMDdCMTVBNkItNzU0QS0zREJELUEwQTMtRjE0MkYx
+				RTFFNDM1GAAAAAECAACBAAAAAQAAAO8TAAABAAAAAAAA
+				AAAAAAABAAAAAQEAAC8AAADaAAAAAQIAAGFjMDQyNGZm
+				Mzc5YWJjMmFjOTAyYzY0Yjg5MTNhNGM3NGI2NDRjNmY7
+				MDAwMDAwMDA7MDAwMDAwMDA7MDAwMDAwMDAwMDAwMDAy
+				MDtjb20uYXBwbGUuYXBwLXNhbmRib3gucmVhZC13cml0
+				ZTswMDAwMDAwMTswMTAwMDAwNDswMDAwMDAwMDAwNjgz
+				NmNjOy91c2Vycy9wYXVscm9zcy9naXRodWIvcGF1bHJv
+				c3MvcHl0aG9uZXh0ZW5zaW9ucGF0dGVybnMvZG9jL3Nw
+				aGlueC9zb3VyY2UAAADkAAAA/v///wEAAAAAAAAAEgAA
+				AAQQAACAAAAAAAAAAAUQAAAoAQAAAAAAABAQAABgAQAA
+				AAAAAEAQAABQAQAAAAAAAFUQAACIAQAAAAAAAFYQAACA
+				AQAAAAAAAAIgAABIAgAAAAAAAAUgAACsAQAAAAAAABAg
+				AADIAQAAAAAAABEgAAD8AQAAAAAAABIgAADcAQAAAAAA
+				ABMgAADsAQAAAAAAACAgAAAoAgAAAAAAADAgAACAAQAA
+				AAAAAAHAAACUAQAAAAAAABHAAAAUAAAAAAAAABLAAACg
+				AQAAAAAAAIDwAABUAgAAAAAAAA==
 				</data>
 				<key>FileURL</key>
-				<string>file://localhost/Users/paulross/Documents/workspace/PythonExtensionPatterns/doc/sphinx/source/</string>
+				<string>file://localhost/Users/paulross/GitHub/paulross/PythonExtensionPatterns/doc/sphinx/source/</string>
 				<key>RelativePath</key>
 				<string>./doc/sphinx/source</string>
 				<key>TypeID</key>

PythonExtensionPatterns.bbprojectd/project.bbprojectdata

@@ -38,7 +38,9 @@ Configuring Xcode
 Running and Analysing Code Coverage
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-In Xcode select Product->Run then once that has completed note the GCov_build directory in Xcode by selecting Products-><project> in the left hand pane. In the right hand pane under 'Identity and Type' you should see 'Full Path' of something like::
+In Xcode select Product->Run then once that has completed note the GCov_build directory in Xcode by selecting Products-><project> in the left hand pane. In the right hand pane under 'Identity and Type' you should see 'Full Path' of something like:
+
+.. code-block:: console
 
     /Users/$USER/Library/Developer/Xcode/DerivedData/<project name and hash>/Build/Products/GCov_Build/<project>
 

doc/sphinx/source/debugging/gcov.rst

@@ -124,7 +124,7 @@ In the second shell pidmon.py shows the sudden jump in memory usage:
 
 .. code-block:: bash
 
-    python3 pidmon.py 14488
+    $ python3 pidmon.py 14488
     pextmem(rss=7659520, vms=2475937792, pfaults=8380416, pageins=2617344)
          7.660 [Mb]
          7.660 [Mb]     +0.000 [Mb]
@@ -146,7 +146,9 @@ Observing the Total Reference Counts
 
 If you have a debug build of Python with ``Py_REF_DEBUG`` defined you might notice a very high level of total reference counts by either invoking Python with ``-X showrefcount`` or calling ``sys.gettotalrefcount()``.
 
-For example::
+For example:
+
+.. code-block:: python
 
     >>> import sys
     >>> import cPyRefs
@@ -179,7 +181,9 @@ And those references are not collectable::
 Observing the Reference Counts for a Particular Type
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you have a debug build with ``COUNT_ALLOCS`` [See: :ref:`debug-version-of-python-COUNT_ALLOCS-label`] defined you can see the references counts for each type. This build will have a new function ``sys.getcounts()`` which returns a list of tuples ``(tp_name, tp_allocs, tp_frees, tp_maxalloc)`` where ``tp_maxalloc`` is the maximum ever seen value of the reference ``tp_allocs - tp_frees``. The list is ordered by time of first object allocation::
+If you have a debug build with ``COUNT_ALLOCS`` [See: :ref:`debug-version-of-python-COUNT_ALLOCS-label`] defined you can see the references counts for each type. This build will have a new function ``sys.getcounts()`` which returns a list of tuples ``(tp_name, tp_allocs, tp_frees, tp_maxalloc)`` where ``tp_maxalloc`` is the maximum ever seen value of the reference ``tp_allocs - tp_frees``. The list is ordered by time of first object allocation:
+
+.. code-block:: python
 
     >>> import pprint
     >>> import sys
@@ -193,7 +197,9 @@ If you have a debug build with ``COUNT_ALLOCS`` [See: :ref:`debug-version-of-pyt
      ('dict', 1421, 714, 714),
      ('tuple', 13379, 9633, 3746)]
 
-We can try our leaky code::
+We can try our leaky code:
+
+.. code-block:: python
 
     >>> import cPyRefs
     >>> cPyRefs.leakNewRefs(1000, 1000000)
@@ -211,6 +217,8 @@ There is a big jump in ``tp_maxalloc`` for ints that is worth investigating.
 
 When the Python process finishes you get a dump of this list as the interpreter is broken down::
 
+.. code-block:: console
+
     memoryview alloc'd: 210, freed: 210, max in use: 1
     managedbuffer alloc'd: 210, freed: 210, max in use: 1
     PrettyPrinter alloc'd: 2, freed: 2, max in use: 1

doc/sphinx/source/debugging/leak_newrefs_vg.rst

@@ -19,6 +19,7 @@ This describes reliable patterns of coding Python Extensions in C. It covers the
    super_call
    compiler_flags
    debugging/debug
+   thread_safety
 
 
 Indices and tables

doc/sphinx/source/index.rst

@@ -290,32 +290,30 @@ If we try a different string::
 
 At least this will get your attention!
 
-.. note::
+Incidentially from Python 3.3 onwards there is a module `faulthandler <https://docs.python.org/3.3/library/faulthandler.html#module-faulthandler>`_ that can give useful debugging information (file ``FaultHandlerExample.py``):
 
-    Incidentially from Python 3.3 onwards there is a module `faulthandler <https://docs.python.org/3.3/library/faulthandler.html#module-faulthandler>`_ that can give useful debugging information (file ``FaultHandlerExample.py``):
-
-    .. code-block:: python
-        :linenos:
-        :emphasize-lines: 7
-    
-        import faulthandler
-        faulthandler.enable()
+.. code-block:: python
+	:linenos:
+	:emphasize-lines: 5
 
-        import cPyRefs
+	import faulthandler
+	faulthandler.enable()
+	import cPyRefs
+	l = ['abc' * 200]
+	cPyRefs.popBAD(l)
 
-        l = ['abc' * 200]
-        cPyRefs.popBAD(l)
+And this is what you get:
 
-    And this is what you get::
+.. code-block:: console
 
-        $ python3 FaultHandlerExample.py 
-        Ref count was: 1
-        Ref count now: 2305843009213693952
-        Fatal Python error: Segmentation fault
+	$ python3 FaultHandlerExample.py 
+	Ref count was: 1
+	Ref count now: 2305843009213693952
+	Fatal Python error: Segmentation fault
 
-        Current thread 0x00007fff73c88310:
-          File "FaultHandlerExample.py", line 7 in <module>
-        Segmentation fault: 11
+	Current thread 0x00007fff73c88310:
+	  File "FaultHandlerExample.py", line 7 in <module>
+	Segmentation fault: 11
 
 There is a more subtle issue; suppose that in your Python code there is a reference to the last item in the list, then the problem suddenly "goes away"::