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
|
- Objects must never be exclusively locked for any prolonged time
|
||||||
- Code which sleeps must be able to time out after suitable period
|
- 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
|
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
|
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
|
the QEMU driver is blocked while this is held, though some internal
|
||||||
callbacks may still run asynchronously. This lock must never be held
|
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
|
When obtaining the driver lock, under *NO* circumstances must
|
||||||
any lock be held on a virDomainObjPtr. This *WILL* result in
|
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
|
to have the driver locked when re-acquiring the dropped locked, since the
|
||||||
reference count prevents it being freed by another thread.
|
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).
|
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
|
whenever it hits a piece of code which may sleep/wait, and
|
||||||
re-acquire it after the sleep/wait. Whenever an asynchronous job
|
re-acquire it after the sleep/wait. Whenever an asynchronous job
|
||||||
wants to talk to the monitor, it needs to acquire nested job (a
|
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.
|
monitor.
|
||||||
|
|
||||||
Since the virDomainObjPtr lock was dropped while waiting for the
|
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
|
- Increments ref count on virDomainObjPtr
|
||||||
- Waits until the job is compatible with current async job or no
|
- Waits until the job is compatible with current async job or no
|
||||||
async job is running
|
async job is running
|
||||||
- Waits job.cond condition 'job.active != 0' using virDomainObjPtr
|
- Waits for job.cond condition 'job.active != 0' using virDomainObjPtr
|
||||||
mutex
|
mutex
|
||||||
- Rechecks if the job is still compatible and repeats waiting if it
|
- Rechecks if the job is still compatible and repeats waiting if it
|
||||||
isn't
|
isn't
|
||||||
@ -150,7 +150,7 @@ To acquire the normal job condition
|
|||||||
- Unlocks driver
|
- Unlocks driver
|
||||||
- Waits until the job is compatible with current async job or no
|
- Waits until the job is compatible with current async job or no
|
||||||
async job is running
|
async job is running
|
||||||
- Waits job.cond condition 'job.active != 0' using virDomainObjPtr
|
- Waits for job.cond condition 'job.active != 0' using virDomainObjPtr
|
||||||
mutex
|
mutex
|
||||||
- Rechecks if the job is still compatible and repeats waiting if it
|
- Rechecks if the job is still compatible and repeats waiting if it
|
||||||
isn't
|
isn't
|
||||||
@ -160,7 +160,7 @@ To acquire the normal job condition
|
|||||||
- Locks virDomainObjPtr
|
- Locks virDomainObjPtr
|
||||||
|
|
||||||
NB: this variant is required in order to comply with lock ordering
|
NB: this variant is required in order to comply with lock ordering
|
||||||
rules for virDomainObjPtr vs driver
|
rules for virDomainObjPtr vs. driver
|
||||||
|
|
||||||
|
|
||||||
qemuDomainObjEndJob()
|
qemuDomainObjEndJob()
|
||||||
@ -175,7 +175,7 @@ To acquire the asynchronous job condition
|
|||||||
qemuDomainObjBeginAsyncJob() (if driver is unlocked)
|
qemuDomainObjBeginAsyncJob() (if driver is unlocked)
|
||||||
- Increments ref count on virDomainObjPtr
|
- Increments ref count on virDomainObjPtr
|
||||||
- Waits until no async job is running
|
- 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
|
mutex
|
||||||
- Rechecks if any async job was started while waiting on job.cond
|
- Rechecks if any async job was started while waiting on job.cond
|
||||||
and repeats waiting in that case
|
and repeats waiting in that case
|
||||||
@ -185,7 +185,7 @@ To acquire the asynchronous job condition
|
|||||||
- Increments ref count on virDomainObjPtr
|
- Increments ref count on virDomainObjPtr
|
||||||
- Unlocks driver
|
- Unlocks driver
|
||||||
- Waits until no async job is running
|
- 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
|
mutex
|
||||||
- Rechecks if any async job was started while waiting on job.cond
|
- Rechecks if any async job was started while waiting on job.cond
|
||||||
and repeats waiting in that case
|
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;
|
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;
|
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;
|
virDomainObjPtr obj;
|
||||||
|
|
||||||
qemuDriverLockRO(driver);
|
qemuDriverLock(driver);
|
||||||
obj = virDomainFindByUUID(driver->domains, dom->uuid);
|
obj = virDomainFindByUUID(driver->domains, dom->uuid);
|
||||||
qemuDriverUnlock(driver);
|
qemuDriverUnlock(driver);
|
||||||
|
|
||||||
@ -324,7 +324,7 @@ Design patterns
|
|||||||
virDomainObjPtr obj;
|
virDomainObjPtr obj;
|
||||||
qemuDomainObjPrivatePtr priv;
|
qemuDomainObjPrivatePtr priv;
|
||||||
|
|
||||||
qemuDriverLockRO(driver);
|
qemuDriverLock(driver);
|
||||||
obj = virDomainFindByUUID(driver->domains, dom->uuid);
|
obj = virDomainFindByUUID(driver->domains, dom->uuid);
|
||||||
qemuDriverUnlock(driver);
|
qemuDriverUnlock(driver);
|
||||||
|
|
||||||
@ -333,6 +333,7 @@ Design patterns
|
|||||||
...do prep work...
|
...do prep work...
|
||||||
|
|
||||||
if (virDomainObjIsActive(vm)) {
|
if (virDomainObjIsActive(vm)) {
|
||||||
|
/* using ignore_value is safe since vm is active */
|
||||||
ignore_value(qemuDomainObjEnterMonitor(obj));
|
ignore_value(qemuDomainObjEnterMonitor(obj));
|
||||||
qemuMonitorXXXX(priv->mon);
|
qemuMonitorXXXX(priv->mon);
|
||||||
qemuDomainObjExitMonitor(obj);
|
qemuDomainObjExitMonitor(obj);
|
||||||
@ -360,6 +361,7 @@ Design patterns
|
|||||||
...do prep work...
|
...do prep work...
|
||||||
|
|
||||||
if (virDomainObjIsActive(vm)) {
|
if (virDomainObjIsActive(vm)) {
|
||||||
|
/* using ignore_value is safe since vm is active */
|
||||||
ignore_value(qemuDomainObjEnterMonitorWithDriver(driver, obj));
|
ignore_value(qemuDomainObjEnterMonitorWithDriver(driver, obj));
|
||||||
qemuMonitorXXXX(priv->mon);
|
qemuMonitorXXXX(priv->mon);
|
||||||
qemuDomainObjExitMonitorWithDriver(driver, obj);
|
qemuDomainObjExitMonitorWithDriver(driver, obj);
|
||||||
|
Loading…
x
Reference in New Issue
Block a user