d/freebsd-dev
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Remove list of locking primitives, which is kind of redundant, move

Browse Source 
information about witness(9) to the section about interactions, and
expand 'contexts' table.
This commit is contained in:
Edward Tomasz Napierala 2010-02-13 12:03:03 +00:00
parent a26a657cd2
commit ddcd2bc9ec
Notes: svn2git 2020-12-20 02:59:44 +00:00 
svn path=/head/; revision=203825
1 changed files with 27 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
share/man/man9/locking.9
View File

@ -24,7 +24,7 @@
.\"
.\" $FreeBSD$
.\"
.Dd February 10, 2010
.Dd February 13, 2010
.Dt LOCKING 9
.Os
.Sh NAME
@ -36,41 +36,9 @@ The
kernel is written to run across multiple CPUs and as such requires
several different synchronization primitives to allow the developers
to safely access and manipulate the many data types required.
.Pp
These include:
.Bl -enum
.It
Mutexes
.It
Spin mutexes
.It
Pool mutexes
.It
Shared/exclusive locks
.It
Reader/writer locks
.It
Read-mostly locks
.It
Counting semaphores
.It
Condition variables
.It
Sleep/wakeup
.It
Giant
.It
Lockmanager locks
.El
.Pp
The primitives interact and have a number of rules regarding how
they can and can not be combined.
Many of these rules are checked using the
.Xr witness 4
code.
.Pp
.Ss Mutexes
Mutexes are the most commonly used synchronization primitive in the kernel.
Mutexes (also called "sleep mutexes") are the most commonly used
synchronization primitive in the kernel.
Thread acquires (locks) a mutex before accessing data shared with other
threads (including interrupt threads), and releases (unlocks) it afterwards.
If the mutex cannot be acquired, the thread requesting it will sleep.
@ -85,12 +53,10 @@ the two is that spin mutexes never sleep - instead, they spin, waiting
for the thread holding the lock, which runs on another CPU, to release it.
Differently from ordinary mutex, spin mutexes disable interrupts when acquired.
Since disabling interrupts is expensive, they are also generally slower.
Spin mutexes should only be used to protect data shared with primary
(INTR_FILTER) interrupt code.
You
.Em must not
do anything that deschedules the thread while you
are holding a spin mutex.
Spin mutexes should be used only when neccessary, e.g. to protect data shared
with interrupt filter code (see
.Xr bus_setup_intr 9
for details).
.Ss Pool mutexes
With most synchronisaton primitives, such as mutexes, programmer must
provide a piece of allocated memory to hold the primitive.
@ -284,6 +250,11 @@ See
.Xr lock 9
for details.
.Sh INTERACTIONS
The primitives interact and have a number of rules regarding how
they can and can not be combined.
Many of these rules are checked using the
.Xr witness 4
code.
.Ss Bounded vs. unbounded sleep
The following primitives perform bounded sleep: mutexes, pool mutexes,
reader/writer locks and read-mostly locks.
@ -320,21 +291,23 @@ rwlock, your sleep, will cause a panic.
If the sleep only happens rarely it may be years before the
bad code path is found.
.Pp
It is an error to do any operation that could result in any kind of sleep when
running inside an interrupt filter.
.Pp
It is an error to do any operation that could result in unbounded sleep when
running inside an interrupt thread.
.Ss Interaction table
The following table shows what you can and can not do if you hold
one of the synchronization primitives discussed here:
(someone who knows what they are talking about should write this table)
The following table shows what you can and can not do while holding
one of the synchronization primitives discussed:
.Bl -column ".Ic xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent
.It Xo
.Em "You have: You want:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep
.Xc
.It Ic spin mtx Ta \&ok-1 Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-3
.It Ic mutex Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&ok Ta \&no-3
.It Ic sx Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok Ta \&ok Ta \&ok-4
.It Ic rwlock Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&ok Ta \&no-3
.It Ic rmlock Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok-2 Ta \&no
.It spin mtx Ta \&ok-1 Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no-3
.It mutex Ta \&ok Ta \&ok-1 Ta \&no Ta \&ok Ta \&ok Ta \&no-3
.It sx Ta \&ok Ta \&ok Ta \&ok-2 Ta \&ok Ta \&ok Ta \&ok-4
.It rwlock Ta \&ok Ta \&ok Ta \&no Ta \&ok-2 Ta \&ok Ta \&no-3
.It rmlock Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok-2 Ta \&no
.El
.Pp
.Em *1
@ -364,10 +337,12 @@ The next table shows what can be used in different contexts.
At this time this is a rather easy to remember table.
.Bl -column ".Ic Xxxxxxxxxxxxxxxxxxx" ".Xr XXXXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXXX" ".Xr XXXXXX" -offset indent
.It Xo
.Em "Context:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep
.Em "Context:" Ta spin mtx Ta mutex Ta sx Ta rwlock Ta rmlock Ta sleep
.Xc
.It interrupt: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no
.It idle: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no
.It interrupt filter: Ta \&ok Ta \&no Ta \&no Ta \&no Ta \&no Ta \&no
.It ithread: Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&ok Ta \&no
.It callout: Ta \&ok Ta \&ok Ta \&no Ta \&ok Ta \&no Ta \&no
.It syscall: Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok Ta \&ok
.El
.Sh SEE ALSO
.Xr condvar 9 ,