lib/frrcu.h

   1 /*
   2  * Copyright (c) 2017-19  David Lamparter, for NetDEF, Inc.
   3  *
   4  * Permission to use, copy, modify, and distribute this software for any
   5  * purpose with or without fee is hereby granted, provided that the above
   6  * copyright notice and this permission notice appear in all copies.
   7  *
   8  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   9  * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  10  * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  11  * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  12  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  13  * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  14  * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  15  */
  16
  17 #ifndef _FRRCU_H
  18 #define _FRRCU_H
  19
  20 #include "memory.h"
  21 #include "atomlist.h"
  22
  23 /* quick RCU primer:
  24  *   There's a global sequence counter.  Whenever a thread does a
  25  *   rcu_read_lock(), it is marked as holding the current sequence counter.
  26  *   When something is cleaned with RCU, the global sequence counter is
  27  *   increased and the item is queued for cleanup - *after* all threads are
  28  *   at a more recent sequence counter (or no sequence counter / unheld).
  29  *
  30  *   So, by delaying resource cleanup, RCU ensures that things don't go away
  31  *   while another thread may hold a (stale) reference.
  32  *
  33  *   Note that even if a thread is in rcu_read_lock(), it is invalid for that
  34  *   thread to access bits after rcu_free() & co on them.  This is a design
  35  *   choice to allow no-op'ing out the entire RCU mechanism if we're running
  36  *   singlethreaded.  (Also allows some optimization on the counter bumping.)
  37  *
  38  * differences from Linux Kernel RCU:
  39  *   - there's no rcu_synchronize(), if you really need to defer something
  40  *     use rcu_call() (and double check it's really necessary)
  41  *   - rcu_dereference() and rcu_assign_pointer() don't exist, use atomic_*
  42  *     instead (ATOM* list structures do the right thing)
  43  */
  44
  45 /* opaque */
  46 struct rcu_thread;
  47
  48 /* called before new thread creation, sets up rcu thread info for new thread
  49  * before it actually exits.  This ensures possible RCU references are held
  50  * for thread startup.
  51  *
  52  * return value must be passed into the new thread's call to rcu_thread_start()
  53  */
  54 extern struct rcu_thread *rcu_thread_prepare(void);
  55
  56 /* cleanup in case pthread_create() fails */
  57 extern void rcu_thread_unprepare(struct rcu_thread *rcu_thread);
  58
  59 /* called early in the new thread, with the return value from the above.
  60  * NB: new thread is initially in RCU-held state! (at depth 1)
  61  *
  62  * TBD: maybe inherit RCU state from rcu_thread_prepare()?
  63  */
  64 extern void rcu_thread_start(struct rcu_thread *rcu_thread);
  65
  66 /* thread exit is handled through pthread_key_create's destructor function */
  67
  68 /* global RCU shutdown - must be called with only 1 active thread left.  waits
  69  * until remaining RCU actions are done & RCU thread has exited.
  70  *
  71  * This is mostly here to get a clean exit without memleaks.
  72  */
  73 extern void rcu_shutdown(void);
  74
  75 /* enter / exit RCU-held state.  counter-based, so can be called nested. */
  76 extern void rcu_read_lock(void);
  77 extern void rcu_read_unlock(void);
  78
  79 /* for debugging / safety checks */
  80 extern void rcu_assert_read_locked(void);
  81 extern void rcu_assert_read_unlocked(void);
  82
  83 enum rcu_action_type {
  84         RCUA_INVALID = 0,
  85         /* used internally by the RCU code, shouldn't ever show up outside */
  86         RCUA_NEXT,
  87         RCUA_END,
  88         /* normal RCU actions, for outside use */
  89         RCUA_FREE,
  90         RCUA_CLOSE,
  91         RCUA_CALL,
  92 };
  93
  94 /* since rcu_head is intended to be embedded into structs which may exist
  95  * with lots of copies, rcu_head is shrunk down to its absolute minimum -
  96  * the atomlist pointer + a pointer to this action struct.
  97  */
  98 struct rcu_action {
  99         enum rcu_action_type type;
 100
 101         union {
 102                 struct {
 103                         struct memtype *mt;
 104                         ptrdiff_t offset;
 105                 } free;
 106
 107                 struct {
 108                         void (*fptr)(void *arg);
 109                         ptrdiff_t offset;
 110                 } call;
 111         } u;
 112 };
 113
 114 /* RCU cleanup function queue item */
 115 PREDECL_ATOMLIST(rcu_heads)
 116 struct rcu_head {
 117         struct rcu_heads_item head;
 118         const struct rcu_action *action;
 119 };
 120
 121 /* special RCU head for delayed fd-close */
 122 struct rcu_head_close {
 123         struct rcu_head rcu_head;
 124         int fd;
 125 };
 126
 127 /* enqueue RCU action - use the macros below to get the rcu_action set up */
 128 extern void rcu_enqueue(struct rcu_head *head, const struct rcu_action *action);
 129
 130 /* RCU free() and file close() operations.
 131  *
 132  * freed memory / closed fds become _immediately_ unavailable to the calling
 133  * thread, but will remain available for other threads until they have passed
 134  * into RCU-released state.
 135  */
 136
 137 /* may be called with NULL mt to do non-MTYPE free() */
 138 #define rcu_free(mtype, ptr, field)                                            \
 139         do {                                                                   \
 140                 typeof(ptr) _ptr = (ptr);                                      \
 141                 if (!_ptr)                                                     \
 142                         break;                                                 \
 143                 struct rcu_head *_rcu_head = &_ptr->field;                     \
 144                 static const struct rcu_action _rcu_action = {                 \
 145                         .type = RCUA_FREE,                                     \
 146                         .u.free = {                                            \
 147                                 .mt = mtype,                                   \
 148                                 .offset = offsetof(typeof(*_ptr), field),      \
 149                         },                                                     \
 150                 };                                                             \
 151                 rcu_enqueue(_rcu_head, &_rcu_action);                          \
 152         } while (0)
 153
 154 /* use this sparingly, it runs on (and blocks) the RCU thread */
 155 #define rcu_call(func, ptr, field)                                             \
 156         do {                                                                   \
 157                 typeof(ptr) _ptr = (ptr);                                      \
 158                 void (*fptype)(typeof(ptr));                                   \
 159                 struct rcu_head *_rcu_head = &_ptr->field;                     \
 160                 static const struct rcu_action _rcu_action = {                 \
 161                         .type = RCUA_CALL,                                     \
 162                         .u.call = {                                            \
 163                                 .fptr = (void *)func,                          \
 164                                 .offset = offsetof(typeof(*_ptr), field),      \
 165                         },                                                     \
 166                 };                                                             \
 167                 (void)(_fptype = func);                                        \
 168                 rcu_enqueue(_rcu_head, &_rcu_action);                          \
 169         } while (0)
 170
 171 extern void rcu_close(struct rcu_head_close *head, int fd);
 172
 173 #endif /* _FRRCU_H */