epoch.9: fix some style and speeling issues
Reported by: Yutaro Hayakawa <yhayakawa3720@gmail.com> (spelling) Differential Revision: https://reviews.freebsd.org/D15961
This commit is contained in:
parent
917d184626
commit
7d9389b096
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/head/; revision=335531
@ -1,5 +1,5 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>.
|
.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>.
|
||||||
.\"
|
.\"
|
||||||
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
||||||
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
||||||
@ -65,15 +65,15 @@
|
|||||||
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
||||||
Epochs are used to guarantee liveness and immutability of data by
|
Epochs are used to guarantee liveness and immutability of data by
|
||||||
deferring reclamation and mutation until a grace period has elapsed.
|
deferring reclamation and mutation until a grace period has elapsed.
|
||||||
Epochs do not have any lock ordering issues. Entering and leaving
|
Epochs do not have any lock ordering issues.
|
||||||
an epoch section will never block.
|
Entering and leaving an epoch section will never block.
|
||||||
.Pp
|
.Pp
|
||||||
Epochs are allocated with
|
Epochs are allocated with
|
||||||
.Fn epoch_alloc
|
.Fn epoch_alloc
|
||||||
and freed with
|
and freed with
|
||||||
.Fn epoch_free .
|
.Fn epoch_free .
|
||||||
The flags passed to epoch_alloc determine whether preemption is
|
The flags passed to epoch_alloc determine whether preemption is
|
||||||
allowed during a section or not (the dafult), as specified by
|
allowed during a section or not (the default), as specified by
|
||||||
EPOCH_PREEMPT.
|
EPOCH_PREEMPT.
|
||||||
Threads indicate the start of an epoch critical section by calling
|
Threads indicate the start of an epoch critical section by calling
|
||||||
.Fn epoch_enter .
|
.Fn epoch_enter .
|
||||||
@ -104,16 +104,17 @@ INVARIANTS can assert that a thread is in an epoch by using
|
|||||||
.Fn in_epoch .
|
.Fn in_epoch .
|
||||||
.Pp
|
.Pp
|
||||||
The epoch API currently does not support sleeping in epoch_preempt sections.
|
The epoch API currently does not support sleeping in epoch_preempt sections.
|
||||||
A caller cannot do epoch_enter recursively on different preemptible epochs. A
|
A caller cannot do epoch_enter recursively on different preemptible epochs.
|
||||||
caller should never call
|
A caller should never call
|
||||||
.Fn epoch_wait
|
.Fn epoch_wait
|
||||||
in the middle of an epoch section as this will lead to a deadlock.
|
in the middle of an epoch section as this will lead to a deadlock.
|
||||||
.Pp
|
.Pp
|
||||||
Note that epochs are not a straight replacement for read locks. Callers
|
Note that epochs are not a straight replacement for read locks.
|
||||||
must use safe list and tailq traversal routines in an epoch (see ck_queue).
|
Callers must use safe list and tailq traversal routines in an epoch (see ck_queue).
|
||||||
When modifying a list referenced from an epoch section safe removal
|
When modifying a list referenced from an epoch section safe removal
|
||||||
routines must be used and the caller can no longer modify a list entry
|
routines must be used and the caller can no longer modify a list entry
|
||||||
in place. An item to be modified must be handled with copy on write
|
in place.
|
||||||
|
An item to be modified must be handled with copy on write
|
||||||
and frees must be deferred until after a grace period has elapsed.
|
and frees must be deferred until after a grace period has elapsed.
|
||||||
.Sh RETURN VALUES
|
.Sh RETURN VALUES
|
||||||
.Fn in_epoch
|
.Fn in_epoch
|
||||||
@ -123,11 +124,11 @@ One must be cautious when using
|
|||||||
.Fn epoch_wait_preempt
|
.Fn epoch_wait_preempt
|
||||||
threads are pinned during epoch sections so if a thread in a section is then
|
threads are pinned during epoch sections so if a thread in a section is then
|
||||||
preempted by a higher priority compute bound thread on that CPU it can be
|
preempted by a higher priority compute bound thread on that CPU it can be
|
||||||
prevented from leaving the section. Thus the wait time for the waiter is
|
prevented from leaving the section.
|
||||||
|
Thus the wait time for the waiter is
|
||||||
potentially unbounded.
|
potentially unbounded.
|
||||||
.Sh EXAMPLES
|
.Sh EXAMPLES
|
||||||
Async free example:
|
Async free example:
|
||||||
|
|
||||||
Thread 1:
|
Thread 1:
|
||||||
.Bd -literal
|
.Bd -literal
|
||||||
int
|
int
|
||||||
@ -164,7 +165,7 @@ void
|
|||||||
if_purgeaddrs(struct ifnet *ifp)
|
if_purgeaddrs(struct ifnet *ifp)
|
||||||
{
|
{
|
||||||
|
|
||||||
/* .... */
|
/* .... *
|
||||||
IF_ADDR_WLOCK(ifp);
|
IF_ADDR_WLOCK(ifp);
|
||||||
CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link);
|
CK_STAILQ_REMOVE(&ifp->if_addrhead, ifa, ifaddr, ifa_link);
|
||||||
IF_ADDR_WUNLOCK(ifp);
|
IF_ADDR_WUNLOCK(ifp);
|
||||||
@ -172,10 +173,11 @@ if_purgeaddrs(struct ifnet *ifp)
|
|||||||
}
|
}
|
||||||
.Ed
|
.Ed
|
||||||
.Pp
|
.Pp
|
||||||
Thread 1 traverses the ifaddr list in an epoch. Thread 2 unlinks
|
Thread 1 traverses the ifaddr list in an epoch.
|
||||||
with the corresponding epoch safe macro, marks as logically free,
|
Thread 2 unlinks with the corresponding epoch safe macro, marks as logically free,
|
||||||
and then defers deletion. More general mutation or a synchronous
|
and then defers deletion.
|
||||||
free would have to follow a a call to
|
More general mutation or a synchronous
|
||||||
|
free would have to follow a call to
|
||||||
.Fn epoch_wait .
|
.Fn epoch_wait .
|
||||||
.Sh ERRORS
|
.Sh ERRORS
|
||||||
None.
|
None.
|
||||||
|
Loading…
Reference in New Issue
Block a user