5:21 p.m.
* src/qemu/THREADS.txt: Fix problems with typos, grammar, and
outdated examples.
---
Doc only, so pushing under the trivial rule.
src/qemu/THREADS.txt | 30 ++++++++++++++++--------------
1 files changed, 16 insertions(+), 14 deletions(-)
diff --git a/src/qemu/THREADS.txt b/src/qemu/THREADS.txt
index 3a27a85..e73076c 100644
--- 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);
--
1.7.4.4