| epoch.9 (2b02de2c94d092409cb44810fed84632ef6cccf3) | epoch.9 (2f3e7fb2cc8ddbc20711e82809430bf7c5eb88b3) |
|---|---|
| 1.\" 2.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as --- 196 unchanged lines hidden (view full) --- 205referred to by the epoch callback(s) which are not refcounted and are 206rarely freed. 207The typical place for calling this function is right before freeing or 208invalidating the shared resource(s) used by the epoch callback(s). 209This function can sleep and is not optimized for performance. 210.Sh RETURN VALUES 211.Fn in_epoch curepoch 212will return 1 if curthread is in curepoch, 0 otherwise. | 1.\" 2.\" Copyright (C) 2018 Matthew Macy <mmacy@FreeBSD.org>. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice(s), this list of conditions and the following disclaimer as --- 196 unchanged lines hidden (view full) --- 205referred to by the epoch callback(s) which are not refcounted and are 206rarely freed. 207The typical place for calling this function is right before freeing or 208invalidating the shared resource(s) used by the epoch callback(s). 209This function can sleep and is not optimized for performance. 210.Sh RETURN VALUES 211.Fn in_epoch curepoch 212will return 1 if curthread is in curepoch, 0 otherwise. |
| 213.Sh CAVEATS 214One must be cautious when using 215.Fn epoch_wait_preempt . 216Threads are pinned during epoch sections, so if a thread in a section is then 217preempted by a higher priority compute bound thread on that CPU, it can be 218prevented from leaving the section indefinitely. 219.Pp 220Epochs are not a straight replacement for read locks. 221Callers must use safe list and tailq traversal routines in an epoch (see ck_queue). 222When modifying a list referenced from an epoch section safe removal 223routines must be used and the caller can no longer modify a list entry 224in place. 225An item to be modified must be handled with copy on write 226and frees must be deferred until after a grace period has elapsed. | |
| 227.Sh EXAMPLES 228Async free example: 229Thread 1: 230.Bd -literal 231int 232in_pcbladdr(struct inpcb *inp, struct in_addr *faddr, struct in_laddr *laddr, 233 struct ucred *cred) 234{ --- 40 unchanged lines hidden (view full) --- 275and then defers deletion. 276More general mutation or a synchronous 277free would have to follow a call to 278.Fn epoch_wait . 279.Sh NOTES 280The 281.Nm 282kernel programming interface is under development and is subject to change. | 213.Sh EXAMPLES 214Async free example: 215Thread 1: 216.Bd -literal 217int 218in_pcbladdr(struct inpcb *inp, struct in_addr *faddr, struct in_laddr *laddr, 219 struct ucred *cred) 220{ --- 40 unchanged lines hidden (view full) --- 261and then defers deletion. 262More general mutation or a synchronous 263free would have to follow a call to 264.Fn epoch_wait . 265.Sh NOTES 266The 267.Nm 268kernel programming interface is under development and is subject to change. |
| 283.El 284.Sh HISTORY 285The 286.Nm 287framework first appeared in 288.Fx 11.0 . | |
| 289.Sh SEE ALSO 290.Xr locking 9 , 291.Xr mtx_pool 9 , 292.Xr mutex 9 , 293.Xr rwlock 9 , 294.Xr sema 9 , 295.Xr sleep 9 , 296.Xr sx 9 , 297.Xr timeout 9 | 269.Sh SEE ALSO 270.Xr locking 9 , 271.Xr mtx_pool 9 , 272.Xr mutex 9 , 273.Xr rwlock 9 , 274.Xr sema 9 , 275.Xr sleep 9 , 276.Xr sx 9 , 277.Xr timeout 9 |
| 278.Sh HISTORY 279The 280.Nm 281framework first appeared in 282.Fx 11.0 . 283.Sh CAVEATS 284One must be cautious when using 285.Fn epoch_wait_preempt . 286Threads are pinned during epoch sections, so if a thread in a section is then 287preempted by a higher priority compute bound thread on that CPU, it can be 288prevented from leaving the section indefinitely. 289.Pp 290Epochs are not a straight replacement for read locks. 291Callers must use safe list and tailq traversal routines in an epoch (see ck_queue). 292When modifying a list referenced from an epoch section safe removal 293routines must be used and the caller can no longer modify a list entry 294in place. 295An item to be modified must be handled with copy on write 296and frees must be deferred until after a grace period has elapsed. |
|