Armin Rigo avatar Armin Rigo committed 55e0d80

Update docs.

Comments (0)

Files changed (1)

 been acquired outside.  In that situation (only), trying to acquire the
 lock will raise ``thread.error``.
 
-A common way for this issue to show up is using ``print`` statements,
-because of the internal lock on ``stdout``.  You are free to use
-``print`` either outside ``thread.atomic`` blocks or inside them, but
-not both concurrently.  An easy fix is to put all ``print`` statements
+Importantly, note that this is not issue with the `high-level
+interface`_, but only if you use ``thread.atomic`` directly.  In the
+high-level interface, the running code is either single-threaded
+(outside ``transaction.run()``) or systematically running in
+``thred.atomic`` blocks.
+
+If you *are* using ``thread.atomic`` directly, then a common way for
+this issue to show up is using ``print`` statements: this is due to the
+internal lock on ``stdout``.  You are free to use ``print`` either
+outside ``thread.atomic`` blocks or inside them, but not both
+concurrently.  A way to fix this is to put all ``print`` statements
 inside ``thread.atomic`` blocks, by writing this kind of code::
 
     with thread.atomic:
 
 In this case, it is always a good idea to protect ``print`` statements
 with ``thread.atomic``.  The reason it is not done automatically is that
-not all file operations would benefit: if you have a read or write that
-may block, putting it in a ``thread.atomic`` would have the negative
-effect of suspending all other threads while we wait for the call to
-complete, as described next__.
+it is not useful for the high-level interface, and moreover not all file
+operations would benefit: if you have a read or write that may block,
+putting it in a ``thread.atomic`` would have the negative effect of
+suspending all other threads while we wait for the call to complete, as
+described next__.
 
 .. __: Parallelization_
 
 successfully) it may cause other transactions that are still in progress
 to abort and retry.  This is a waste of CPU time, but even in the worst
 case senario it is not worse than a GIL, because at least one
-transaction succeeded.  Conflicts do occur, of course, and it is
+transaction succeeded (so we get at worst N-1 CPUs doing useless jobs
+and 1 CPU doing a job that commits successfully).
+
+Conflicts do occur, of course, and it is
 pointless to try to avoid them all.  For example they can be abundant
 during some warm-up phase.  What is important is to keep them rare
 enough in total.
   it must "inevitably" complete.  This results in the following
   internal restrictions: only one transaction in the whole process can
   be inevitable, and moreover no other transaction can commit before
-  the inevitable one --- they will be paused when they reach that point.
+  the inevitable one.  In other words, as soon as there is an inevitable
+  transaction, the other transactions can continue and run until the end,
+  but then they will be paused.
 
 So what you should avoid is transactions that are inevitable for a long
 period of time.  Doing so blocks essentially all other transactions and
 block that runs for a noticable amount of time, you perform no I/O at
 all before you are close to reaching the end of the block.
 
-Similarly, you should avoid doing any blocking I/O in ``thread.atomic``
+Similarly, you should avoid doing any *blocking* I/O in ``thread.atomic``
 blocks.  They work, but because the transaction is turned inevitable
 *before* the I/O is performed, they will prevent any parallel work at
 all.  You need to organize the code so that such operations are done
-completely outside ``thread.atomic``.
+completely outside ``thread.atomic``, e.g. in a separate thread.
 
 (This is related to the fact that blocking I/O operations are
 discouraged with Twisted, and if you really need them, you should do
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.