mirror of
https://gitlab.com/libvirt/libvirt.git
synced 2025-03-07 17:28:15 +00:00
qemu: improve thread documentation
* src/qemu/THREADS.txt: Fix problems with typos, grammar, and outdated examples.
This commit is contained in:
parent
0d0bf8507c
commit
9a34ebd357
@ -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);
|
||||
|
Loading…
x
Reference in New Issue
Block a user