include/linux/cleanup.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef __LINUX_GUARDS_H
   3 #define __LINUX_GUARDS_H
   4
   5 #include <linux/compiler.h>
   6
   7 /*
   8  * DEFINE_FREE(name, type, free):
   9  *      simple helper macro that defines the required wrapper for a __free()
  10  *      based cleanup function. @free is an expression using '_T' to access the
  11  *      variable. @free should typically include a NULL test before calling a
  12  *      function, see the example below.
  13  *
  14  * __free(name):
  15  *      variable attribute to add a scoped based cleanup to the variable.
  16  *
  17  * no_free_ptr(var):
  18  *      like a non-atomic xchg(var, NULL), such that the cleanup function will
  19  *      be inhibited -- provided it sanely deals with a NULL value.
  20  *
  21  *      NOTE: this has __must_check semantics so that it is harder to accidentally
  22  *      leak the resource.
  23  *
  24  * return_ptr(p):
  25  *      returns p while inhibiting the __free().
  26  *
  27  * Ex.
  28  *
  29  * DEFINE_FREE(kfree, void *, if (_T) kfree(_T))
  30  *
  31  * void *alloc_obj(...)
  32  * {
  33  *      struct obj *p __free(kfree) = kmalloc(...);
  34  *      if (!p)
  35  *              return NULL;
  36  *
  37  *      if (!init_obj(p))
  38  *              return NULL;
  39  *
  40  *      return_ptr(p);
  41  * }
  42  *
  43  * NOTE: the DEFINE_FREE()'s @free expression includes a NULL test even though
  44  * kfree() is fine to be called with a NULL value. This is on purpose. This way
  45  * the compiler sees the end of our alloc_obj() function as:
  46  *
  47  *      tmp = p;
  48  *      p = NULL;
  49  *      if (p)
  50  *              kfree(p);
  51  *      return tmp;
  52  *
  53  * And through the magic of value-propagation and dead-code-elimination, it
  54  * eliminates the actual cleanup call and compiles into:
  55  *
  56  *      return p;
  57  *
  58  * Without the NULL test it turns into a mess and the compiler can't help us.
  59  */
  60
  61 #define DEFINE_FREE(_name, _type, _free) \
  62         static inline void __free_##_name(void *p) { _type _T = *(_type *)p; _free; }
  63
  64 #define __free(_name)   __cleanup(__free_##_name)
  65
  66 #define __get_and_null_ptr(p) \
  67         ({ __auto_type __ptr = &(p); \
  68            __auto_type __val = *__ptr; \
  69            *__ptr = NULL;  __val; })
  70
  71 static inline __must_check
  72 const volatile void * __must_check_fn(const volatile void *val)
  73 { return val; }
  74
  75 #define no_free_ptr(p) \
  76         ((typeof(p)) __must_check_fn(__get_and_null_ptr(p)))
  77
  78 #define return_ptr(p)   return no_free_ptr(p)
  79
  80
  81 /*
  82  * DEFINE_CLASS(name, type, exit, init, init_args...):
  83  *      helper to define the destructor and constructor for a type.
  84  *      @exit is an expression using '_T' -- similar to FREE above.
  85  *      @init is an expression in @init_args resulting in @type
  86  *
  87  * EXTEND_CLASS(name, ext, init, init_args...):
  88  *      extends class @name to @name@ext with the new constructor
  89  *
  90  * CLASS(name, var)(args...):
  91  *      declare the variable @var as an instance of the named class
  92  *
  93  * Ex.
  94  *
  95  * DEFINE_CLASS(fdget, struct fd, fdput(_T), fdget(fd), int fd)
  96  *
  97  *      CLASS(fdget, f)(fd);
  98  *      if (!f.file)
  99  *              return -EBADF;
 100  *
 101  *      // use 'f' without concern
 102  */
 103
 104 #define DEFINE_CLASS(_name, _type, _exit, _init, _init_args...)         \
 105 typedef _type class_##_name##_t;                                        \
 106 static inline void class_##_name##_destructor(_type *p)                 \
 107 { _type _T = *p; _exit; }                                               \
 108 static inline _type class_##_name##_constructor(_init_args)             \
 109 { _type t = _init; return t; }
 110
 111 #define EXTEND_CLASS(_name, ext, _init, _init_args...)                  \
 112 typedef class_##_name##_t class_##_name##ext##_t;                       \
 113 static inline void class_##_name##ext##_destructor(class_##_name##_t *p)\
 114 { class_##_name##_destructor(p); }                                      \
 115 static inline class_##_name##_t class_##_name##ext##_constructor(_init_args) \
 116 { class_##_name##_t t = _init; return t; }
 117
 118 #define CLASS(_name, var)                                               \
 119         class_##_name##_t var __cleanup(class_##_name##_destructor) =   \
 120                 class_##_name##_constructor
 121
 122
 123 /*
 124  * DEFINE_GUARD(name, type, lock, unlock):
 125  *      trivial wrapper around DEFINE_CLASS() above specifically
 126  *      for locks.
 127  *
 128  * DEFINE_GUARD_COND(name, ext, condlock)
 129  *      wrapper around EXTEND_CLASS above to add conditional lock
 130  *      variants to a base class, eg. mutex_trylock() or
 131  *      mutex_lock_interruptible().
 132  *
 133  * guard(name):
 134  *      an anonymous instance of the (guard) class, not recommended for
 135  *      conditional locks.
 136  *
 137  * scoped_guard (name, args...) { }:
 138  *      similar to CLASS(name, scope)(args), except the variable (with the
 139  *      explicit name 'scope') is declard in a for-loop such that its scope is
 140  *      bound to the next (compound) statement.
 141  *
 142  *      for conditional locks the loop body is skipped when the lock is not
 143  *      acquired.
 144  *
 145  * scoped_cond_guard (name, fail, args...) { }:
 146  *      similar to scoped_guard(), except it does fail when the lock
 147  *      acquire fails.
 148  *
 149  */
 150
 151 #define DEFINE_GUARD(_name, _type, _lock, _unlock) \
 152         DEFINE_CLASS(_name, _type, if (_T) { _unlock; }, ({ _lock; _T; }), _type _T); \
 153         static inline void * class_##_name##_lock_ptr(class_##_name##_t *_T) \
 154         { return *_T; }
 155
 156 #define DEFINE_GUARD_COND(_name, _ext, _condlock) \
 157         EXTEND_CLASS(_name, _ext, \
 158                      ({ void *_t = _T; if (_T && !(_condlock)) _t = NULL; _t; }), \
 159                      class_##_name##_t _T) \
 160         static inline void * class_##_name##_ext##_lock_ptr(class_##_name##_t *_T) \
 161         { return class_##_name##_lock_ptr(_T); }
 162
 163 #define guard(_name) \
 164         CLASS(_name, __UNIQUE_ID(guard))
 165
 166 #define __guard_ptr(_name) class_##_name##_lock_ptr
 167
 168 #define scoped_guard(_name, args...)                                    \
 169         for (CLASS(_name, scope)(args),                                 \
 170              *done = NULL; __guard_ptr(_name)(&scope) && !done; done = (void *)1)
 171
 172 #define scoped_cond_guard(_name, _fail, args...) \
 173         for (CLASS(_name, scope)(args), \
 174              *done = NULL; !done; done = (void *)1) \
 175                 if (!__guard_ptr(_name)(&scope)) _fail; \
 176                 else
 177
 178 /*
 179  * Additional helper macros for generating lock guards with types, either for
 180  * locks that don't have a native type (eg. RCU, preempt) or those that need a
 181  * 'fat' pointer (eg. spin_lock_irqsave).
 182  *
 183  * DEFINE_LOCK_GUARD_0(name, lock, unlock, ...)
 184  * DEFINE_LOCK_GUARD_1(name, type, lock, unlock, ...)
 185  * DEFINE_LOCK_GUARD_1_COND(name, ext, condlock)
 186  *
 187  * will result in the following type:
 188  *
 189  *   typedef struct {
 190  *      type *lock;             // 'type := void' for the _0 variant
 191  *      __VA_ARGS__;
 192  *   } class_##name##_t;
 193  *
 194  * As above, both _lock and _unlock are statements, except this time '_T' will
 195  * be a pointer to the above struct.
 196  */
 197
 198 #define __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, ...)               \
 199 typedef struct {                                                        \
 200         _type *lock;                                                    \
 201         __VA_ARGS__;                                                    \
 202 } class_##_name##_t;                                                    \
 203                                                                         \
 204 static inline void class_##_name##_destructor(class_##_name##_t *_T)    \
 205 {                                                                       \
 206         if (_T->lock) { _unlock; }                                      \
 207 }                                                                       \
 208                                                                         \
 209 static inline void *class_##_name##_lock_ptr(class_##_name##_t *_T)     \
 210 {                                                                       \
 211         return _T->lock;                                                \
 212 }
 213
 214
 215 #define __DEFINE_LOCK_GUARD_1(_name, _type, _lock)                      \
 216 static inline class_##_name##_t class_##_name##_constructor(_type *l)   \
 217 {                                                                       \
 218         class_##_name##_t _t = { .lock = l }, *_T = &_t;                \
 219         _lock;                                                          \
 220         return _t;                                                      \
 221 }
 222
 223 #define __DEFINE_LOCK_GUARD_0(_name, _lock)                             \
 224 static inline class_##_name##_t class_##_name##_constructor(void)       \
 225 {                                                                       \
 226         class_##_name##_t _t = { .lock = (void*)1 },                    \
 227                          *_T __maybe_unused = &_t;                      \
 228         _lock;                                                          \
 229         return _t;                                                      \
 230 }
 231
 232 #define DEFINE_LOCK_GUARD_1(_name, _type, _lock, _unlock, ...)          \
 233 __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, __VA_ARGS__)               \
 234 __DEFINE_LOCK_GUARD_1(_name, _type, _lock)
 235
 236 #define DEFINE_LOCK_GUARD_0(_name, _lock, _unlock, ...)                 \
 237 __DEFINE_UNLOCK_GUARD(_name, void, _unlock, __VA_ARGS__)                \
 238 __DEFINE_LOCK_GUARD_0(_name, _lock)
 239
 240 #define DEFINE_LOCK_GUARD_1_COND(_name, _ext, _condlock)                \
 241         EXTEND_CLASS(_name, _ext,                                       \
 242                      ({ class_##_name##_t _t = { .lock = l }, *_T = &_t;\
 243                         if (_T->lock && !(_condlock)) _T->lock = NULL;  \
 244                         _t; }),                                         \
 245                      typeof_member(class_##_name##_t, lock) l)          \
 246         static inline void * class_##_name##_ext##_lock_ptr(class_##_name##_t *_T) \
 247         { return class_##_name##_lock_ptr(_T); }
 248
 249
 250 #endif /* __LINUX_GUARDS_H */