qemu: improve thread documentation

* src/qemu/THREADS.txt: Fix problems with typos, grammar, and
outdated examples.

diff --git a/src/qemu/THREADS.txt b/src/qemu/THREADS.txt
index 3a27a850be86198739381fcb420d5ce363af3ad7..e73076c021c9168785f2219d727ac231ac97cbf7 100644 (file)
--- a/src/qemu/THREADS.txt
+++ b/src/qemu/THREADS.txt
@@ -6,7 +6,7 @@ the QEMU driver. The criteria for this model are:
 
  - Objects must never be exclusively locked for any prolonged time
  - Code which sleeps must be able to time out after suitable period
- - Must be safe against dispatch asynchronous events from monitor
+ - Must be safe against dispatch of asynchronous events from monitor
 
 
 Basic locking primitives
@@ -19,7 +19,7 @@ There are a number of locks on various objects
     This is the top level lock on the entire driver. Every API call in
     the QEMU driver is blocked while this is held, though some internal
     callbacks may still run asynchronously. This lock must never be held
-    for anything which sleeps/waits (ie monitor commands)
+    for anything which sleeps/waits (i.e. monitor commands)
 
     When obtaining the driver lock, under *NO* circumstances must
     any lock be held on a virDomainObjPtr. This *WILL* result in
@@ -44,7 +44,7 @@ There are a number of locks on various objects
     to have the driver locked when re-acquiring the dropped locked, since the
     reference count prevents it being freed by another thread.
 
-    This lock must not be held for anything which sleeps/waits (ie monitor
+    This lock must not be held for anything which sleeps/waits (i.e. monitor
     commands).
 
 
@@ -80,7 +80,7 @@ There are a number of locks on various objects
     whenever it hits a piece of code which may sleep/wait, and
     re-acquire it after the sleep/wait.  Whenever an asynchronous job
     wants to talk to the monitor, it needs to acquire nested job (a
-    special kind of normla job) to obtain exclusive access to the
+    special kind of normal job) to obtain exclusive access to the
     monitor.
 
     Since the virDomainObjPtr lock was dropped while waiting for the
@@ -139,7 +139,7 @@ To acquire the normal job condition
     - Increments ref count on virDomainObjPtr
     - Waits until the job is compatible with current async job or no
       async job is running
-    - Waits job.cond condition 'job.active != 0' using virDomainObjPtr
+    - Waits for job.cond condition 'job.active != 0' using virDomainObjPtr
       mutex
     - Rechecks if the job is still compatible and repeats waiting if it
       isn't
@@ -150,7 +150,7 @@ To acquire the normal job condition
     - Unlocks driver
     - Waits until the job is compatible with current async job or no
       async job is running
-    - Waits job.cond condition 'job.active != 0' using virDomainObjPtr
+    - Waits for job.cond condition 'job.active != 0' using virDomainObjPtr
       mutex
     - Rechecks if the job is still compatible and repeats waiting if it
       isn't
@@ -160,7 +160,7 @@ To acquire the normal job condition
     - Locks virDomainObjPtr
 
    NB: this variant is required in order to comply with lock ordering
-   rules for virDomainObjPtr vs driver
+   rules for virDomainObjPtr vs. driver
 
 
   qemuDomainObjEndJob()
@@ -175,7 +175,7 @@ To acquire the asynchronous job condition
   qemuDomainObjBeginAsyncJob()            (if driver is unlocked)
     - Increments ref count on virDomainObjPtr
     - Waits until no async job is running
-    - Waits job.cond condition 'job.active != 0' using virDomainObjPtr
+    - Waits for job.cond condition 'job.active != 0' using virDomainObjPtr
       mutex
     - Rechecks if any async job was started while waiting on job.cond
       and repeats waiting in that case
@@ -185,7 +185,7 @@ To acquire the asynchronous job condition
     - Increments ref count on virDomainObjPtr
     - Unlocks driver
     - Waits until no async job is running
-    - Waits job.cond condition 'job.active != 0' using virDomainObjPtr
+    - Waits for job.cond condition 'job.active != 0' using virDomainObjPtr
       mutex
     - Rechecks if any async job was started while waiting on job.cond
       and repeats waiting in that case
@@ -271,7 +271,7 @@ Design patterns
 
 
 
- * Accessing something directly todo with a virDomainObjPtr
+ * Accessing something directly to do with a virDomainObjPtr
 
      virDomainObjPtr obj;
 
@@ -285,7 +285,7 @@ Design patterns
 
 
 
- * Accessing something directly todo with a virDomainObjPtr and driver
+ * Accessing something directly to do with a virDomainObjPtr and driver
 
      virDomainObjPtr obj;
 
@@ -299,11 +299,11 @@ Design patterns
 
 
 
- * Updating something directly todo with a virDomainObjPtr
+ * Updating something directly to do with a virDomainObjPtr
 
      virDomainObjPtr obj;
 
-     qemuDriverLockRO(driver);
+     qemuDriverLock(driver);
      obj = virDomainFindByUUID(driver->domains, dom->uuid);
      qemuDriverUnlock(driver);
 
@@ -324,7 +324,7 @@ Design patterns
      virDomainObjPtr obj;
      qemuDomainObjPrivatePtr priv;
 
-     qemuDriverLockRO(driver);
+     qemuDriverLock(driver);
      obj = virDomainFindByUUID(driver->domains, dom->uuid);
      qemuDriverUnlock(driver);
 
@@ -333,6 +333,7 @@ Design patterns
      ...do prep work...
 
      if (virDomainObjIsActive(vm)) {
+         /* using ignore_value is safe since vm is active */
          ignore_value(qemuDomainObjEnterMonitor(obj));
          qemuMonitorXXXX(priv->mon);
          qemuDomainObjExitMonitor(obj);
@@ -360,6 +361,7 @@ Design patterns
      ...do prep work...
 
      if (virDomainObjIsActive(vm)) {
+         /* using ignore_value is safe since vm is active */
          ignore_value(qemuDomainObjEnterMonitorWithDriver(driver, obj));
          qemuMonitorXXXX(priv->mon);
          qemuDomainObjExitMonitorWithDriver(driver, obj);