[PATCH v3 5/5] locking/Documentation: Align crossrelease.txt with the width
From: Byungchul Park <hidden>
Date: 2017-11-11 13:27:37
Also in:
linux-mm, lkml
Subsystem:
documentation, locking primitives, the rest · Maintainers:
Jonathan Corbet, Peter Zijlstra, Ingo Molnar, Will Deacon, Boqun Feng, Linus Torvalds
No change of contents at all. Only adjust the width. (Please merge this to another after the review.) Signed-off-by: Byungchul Park <redacted> --- Documentation/locking/crossrelease.txt | 59 +++++++++++++++++----------------- 1 file changed, 30 insertions(+), 29 deletions(-)
diff --git a/Documentation/locking/crossrelease.txt b/Documentation/locking/crossrelease.txt
index dac56f4..c6d628b 100644
--- a/Documentation/locking/crossrelease.txt
+++ b/Documentation/locking/crossrelease.txt@@ -61,9 +61,9 @@ turn cannot be triggered if event B does not happen, which in turn cannot be triggered if event C does not happen. After all, no event can be triggered since any of them never meets its condition to wake up. -A dependency might exist between two waiters and a deadlock happens -due to an incorrect relationship between dependencies. Thus, we must -define what a dependency is first. A dependency exists if: +A dependency might exist between two waiters and a deadlock happens due +to an incorrect relationship between dependencies. Thus, we must define +what a dependency is first. A dependency exists if: 1. There are two waiters waiting for each event at a given time. 2. The only way to wake up each waiter is to trigger its event.
@@ -304,10 +304,10 @@ Considering only typical locks, lockdep builds nothing. However, relaxing the limitation, a dependency 'A -> B' can be added, giving us more chances to check circular dependencies. -However, it might suffer performance degradation since -relaxing the limitation, with which design and implementation of lockdep -can be efficient, might introduce inefficiency inevitably. So lockdep -should provide two options, strong detection and efficient detection. +However, it might suffer performance degradation since relaxing the +limitation, with which design and implementation of lockdep can be +efficient, might introduce inefficiency inevitably. So lockdep should +provide two options, strong detection and efficient detection. Choosing efficient detection:
@@ -404,8 +404,8 @@ There are four types of dependencies: When acquiring BX, lockdep cannot identify the dependency because there's no way to know if it's in the AX's release context. It has - to wait until the decision can be made. Commit is necessary. - But, handling CC type is not implemented yet. It's a future work. + to wait until the decision can be made. Commit is necessary. But, + handling CC type is not implemented yet. It's a future work. Lockdep can work without commit for typical locks, but the step is necessary once crosslocks are involved. Introducing commit, lockdep
@@ -442,9 +442,9 @@ Crossrelease introduces two main data structures. This is an array embedded in task_struct, for keeping lock history so that dependencies can be added using them at the commit step. Since - they are local data, they can be accessed locklessly in the owner context. - The array is filled at the acquisition step and consumed at the - commit step. And it's managed in a circular manner. + they are local data, they can be accessed locklessly in the owner + context. The array is filled at the acquisition step and consumed at + the commit step. And it's managed in a circular manner. 2. cross_lock
@@ -470,8 +470,8 @@ works for typical locks, without crossrelease. where A, B, and C are different lock classes. -Lockdep adds 'the top of held_locks -> the lock to acquire' -dependency every time acquiring a lock. +Lockdep adds 'the top of held_locks -> the lock to acquire' dependency +every time acquiring a lock. After adding 'A -> B', the dependency graph will be:
@@ -561,10 +561,10 @@ for A, B, and C, the graph will be: NOTE: A dependency 'A -> C' is optimized out. We can see the former graph built without the commit step is same as the -latter graph. Of course, the former way leads to -earlier finish for building the graph, which means we can detect a -deadlock or its possibility sooner. So the former way would be preferred -when possible. But we cannot avoid using the latter way for crosslocks. +latter graph. Of course, the former way leads to earlier finish for +building the graph, which means we can detect a deadlock or its +possibility sooner. So the former way would be preferred when possible. +But we cannot avoid using the latter way for crosslocks. Lastly, let's look at how commit works for crosslocks in practice.
@@ -685,10 +685,10 @@ Lastly, let's look at how commit works for crosslocks in practice. Crossrelease considers all acquisitions following acquiring BX because they can create dependencies with BX. The dependencies will be -determined in the release context of BX. Meanwhile, -all typical locks are queued so that they can be used at the commit step. -Finally, two dependencies 'BX -> C' and 'BX -> E' will be added at the -commit step, when identifying the release context. +determined in the release context of BX. Meanwhile, all typical locks +are queued so that they can be used at the commit step. Finally, two +dependencies 'BX -> C' and 'BX -> E' will be added at the commit step, +when identifying the release context. The final graph will be, with crossrelease:
@@ -737,8 +737,8 @@ Make hot paths lockless To keep all locks for later use at the commit step, crossrelease adopts a local array embedded in task_struct, which makes the data locklessly accessible by forcing it to happen only within the owner context. It's -like how lockdep handles held_locks. Lockless implementation is important -since typical locks are very frequently acquired and released. +like how lockdep handles held_locks. Lockless implementation is +important since typical locks are very frequently acquired and released. =================================================
@@ -751,9 +751,10 @@ deadlock exists if the problematic dependencies exist. Thus, it's meaningful to detect not only an actual deadlock but also its potential possibility. The latter is rather valuable. When a deadlock actually occurs, we can identify what happens in the system by some means or -other even without lockdep. However, there's no way to detect a possibility -without lockdep, unless the whole code is parsed in the head. It's terrible. -Lockdep does the both, and crossrelease only focuses on the latter. +other even without lockdep. However, there's no way to detect a +possibility without lockdep, unless the whole code is parsed in the head. +It's terrible. Lockdep does the both, and crossrelease only focuses on +the latter. Whether or not a deadlock actually occurs depends on several factors. For example, what order contexts are switched in is a factor. Assuming
@@ -845,8 +846,8 @@ we can ensure nothing but what actually happened. Relying on what actually happens at runtime, we can anyway add only true ones, though they might be a subset of true ones. It's similar to how lockdep works for typical locks. There might be more true dependencies than lockdep -has detected. Lockdep has no choice but to rely on -what actually happens. Crossrelease also relies on it. +has detected. Lockdep has no choice but to rely on what actually happens. +Crossrelease also relies on it. CONCLUSION
--
1.9.1