External/libvirt
1
0
Fork 0
mirror of https://gitlab.com/libvirt/libvirt.git synced 2025-03-07 17:28:15 +00:00
Code

qemu: improve thread documentation

Browse Source 
* src/qemu/THREADS.txt: Fix problems with typos, grammar, and
outdated examples.
This commit is contained in:
Eric Blake 2011-07-27 16:20:00 -06:00
parent 0d0bf8507c
commit 9a34ebd357
1 changed files with 16 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
src/qemu/THREADS.txt
View File

@ -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);