include/linux/cleanup.h

   1 /* SPDX-License-Identifier: GPL-2.0 */
   2 #ifndef _LINUX_CLEANUP_H
   3 #define _LINUX_CLEANUP_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(p, nullvalue)   \
  67         ({                                  \
  68                 __auto_type __ptr = &(p);   \
  69                 __auto_type __val = *__ptr; \
  70                 *__ptr = nullvalue;         \
  71                 __val;                      \
  72         })
  73
  74 static inline __must_check
  75 const volatile void * __must_check_fn(const volatile void *val)
  76 { return val; }
  77
  78 #define no_free_ptr(p) \
  79         ((typeof(p)) __must_check_fn(__get_and_null(p, NULL)))
  80
  81 #define return_ptr(p)   return no_free_ptr(p)
  82
  83
  84 /*
  85  * DEFINE_CLASS(name, type, exit, init, init_args...):
  86  *      helper to define the destructor and constructor for a type.
  87  *      @exit is an expression using '_T' -- similar to FREE above.
  88  *      @init is an expression in @init_args resulting in @type
  89  *
  90  * EXTEND_CLASS(name, ext, init, init_args...):
  91  *      extends class @name to @name@ext with the new constructor
  92  *
  93  * CLASS(name, var)(args...):
  94  *      declare the variable @var as an instance of the named class
  95  *
  96  * Ex.
  97  *
  98  * DEFINE_CLASS(fdget, struct fd, fdput(_T), fdget(fd), int fd)
  99  *
 100  *      CLASS(fdget, f)(fd);
 101  *      if (!f.file)
 102  *              return -EBADF;
 103  *
 104  *      // use 'f' without concern
 105  */
 106
 107 #define DEFINE_CLASS(_name, _type, _exit, _init, _init_args...)         \
 108 typedef _type class_##_name##_t;                                        \
 109 static inline void class_##_name##_destructor(_type *p)                 \
 110 { _type _T = *p; _exit; }                                               \
 111 static inline _type class_##_name##_constructor(_init_args)             \
 112 { _type t = _init; return t; }
 113
 114 #define EXTEND_CLASS(_name, ext, _init, _init_args...)                  \
 115 typedef class_##_name##_t class_##_name##ext##_t;                       \
 116 static inline void class_##_name##ext##_destructor(class_##_name##_t *p)\
 117 { class_##_name##_destructor(p); }                                      \
 118 static inline class_##_name##_t class_##_name##ext##_constructor(_init_args) \
 119 { class_##_name##_t t = _init; return t; }
 120
 121 #define CLASS(_name, var)                                               \
 122         class_##_name##_t var __cleanup(class_##_name##_destructor) =   \
 123                 class_##_name##_constructor
 124
 125
 126 /*
 127  * DEFINE_GUARD(name, type, lock, unlock):
 128  *      trivial wrapper around DEFINE_CLASS() above specifically
 129  *      for locks.
 130  *
 131  * DEFINE_GUARD_COND(name, ext, condlock)
 132  *      wrapper around EXTEND_CLASS above to add conditional lock
 133  *      variants to a base class, eg. mutex_trylock() or
 134  *      mutex_lock_interruptible().
 135  *
 136  * guard(name):
 137  *      an anonymous instance of the (guard) class, not recommended for
 138  *      conditional locks.
 139  *
 140  * scoped_guard (name, args...) { }:
 141  *      similar to CLASS(name, scope)(args), except the variable (with the
 142  *      explicit name 'scope') is declard in a for-loop such that its scope is
 143  *      bound to the next (compound) statement.
 144  *
 145  *      for conditional locks the loop body is skipped when the lock is not
 146  *      acquired.
 147  *
 148  * scoped_cond_guard (name, fail, args...) { }:
 149  *      similar to scoped_guard(), except it does fail when the lock
 150  *      acquire fails.
 151  *
 152  */
 153
 154 #define DEFINE_GUARD(_name, _type, _lock, _unlock) \
 155         DEFINE_CLASS(_name, _type, if (_T) { _unlock; }, ({ _lock; _T; }), _type _T); \
 156         static inline void * class_##_name##_lock_ptr(class_##_name##_t *_T) \
 157         { return *_T; }
 158
 159 #define DEFINE_GUARD_COND(_name, _ext, _condlock) \
 160         EXTEND_CLASS(_name, _ext, \
 161                      ({ void *_t = _T; if (_T && !(_condlock)) _t = NULL; _t; }), \
 162                      class_##_name##_t _T) \
 163         static inline void * class_##_name##_ext##_lock_ptr(class_##_name##_t *_T) \
 164         { return class_##_name##_lock_ptr(_T); }
 165
 166 #define guard(_name) \
 167         CLASS(_name, __UNIQUE_ID(guard))
 168
 169 #define __guard_ptr(_name) class_##_name##_lock_ptr
 170
 171 #define scoped_guard(_name, args...)                                    \
 172         for (CLASS(_name, scope)(args),                                 \
 173              *done = NULL; __guard_ptr(_name)(&scope) && !done; done = (void *)1)
 174
 175 #define scoped_cond_guard(_name, _fail, args...) \
 176         for (CLASS(_name, scope)(args), \
 177              *done = NULL; !done; done = (void *)1) \
 178                 if (!__guard_ptr(_name)(&scope)) _fail; \
 179                 else
 180
 181 /*
 182  * Additional helper macros for generating lock guards with types, either for
 183  * locks that don't have a native type (eg. RCU, preempt) or those that need a
 184  * 'fat' pointer (eg. spin_lock_irqsave).
 185  *
 186  * DEFINE_LOCK_GUARD_0(name, lock, unlock, ...)
 187  * DEFINE_LOCK_GUARD_1(name, type, lock, unlock, ...)
 188  * DEFINE_LOCK_GUARD_1_COND(name, ext, condlock)
 189  *
 190  * will result in the following type:
 191  *
 192  *   typedef struct {
 193  *      type *lock;             // 'type := void' for the _0 variant
 194  *      __VA_ARGS__;
 195  *   } class_##name##_t;
 196  *
 197  * As above, both _lock and _unlock are statements, except this time '_T' will
 198  * be a pointer to the above struct.
 199  */
 200
 201 #define __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, ...)               \
 202 typedef struct {                                                        \
 203         _type *lock;                                                    \
 204         __VA_ARGS__;                                                    \
 205 } class_##_name##_t;                                                    \
 206                                                                         \
 207 static inline void class_##_name##_destructor(class_##_name##_t *_T)    \
 208 {                                                                       \
 209         if (_T->lock) { _unlock; }                                      \
 210 }                                                                       \
 211                                                                         \
 212 static inline void *class_##_name##_lock_ptr(class_##_name##_t *_T)     \
 213 {                                                                       \
 214         return _T->lock;                                                \
 215 }
 216
 217
 218 #define __DEFINE_LOCK_GUARD_1(_name, _type, _lock)                      \
 219 static inline class_##_name##_t class_##_name##_constructor(_type *l)   \
 220 {                                                                       \
 221         class_##_name##_t _t = { .lock = l }, *_T = &_t;                \
 222         _lock;                                                          \
 223         return _t;                                                      \
 224 }
 225
 226 #define __DEFINE_LOCK_GUARD_0(_name, _lock)                             \
 227 static inline class_##_name##_t class_##_name##_constructor(void)       \
 228 {                                                                       \
 229         class_##_name##_t _t = { .lock = (void*)1 },                    \
 230                          *_T __maybe_unused = &_t;                      \
 231         _lock;                                                          \
 232         return _t;                                                      \
 233 }
 234
 235 #define DEFINE_LOCK_GUARD_1(_name, _type, _lock, _unlock, ...)          \
 236 __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, __VA_ARGS__)               \
 237 __DEFINE_LOCK_GUARD_1(_name, _type, _lock)
 238
 239 #define DEFINE_LOCK_GUARD_0(_name, _lock, _unlock, ...)                 \
 240 __DEFINE_UNLOCK_GUARD(_name, void, _unlock, __VA_ARGS__)                \
 241 __DEFINE_LOCK_GUARD_0(_name, _lock)
 242
 243 #define DEFINE_LOCK_GUARD_1_COND(_name, _ext, _condlock)                \
 244         EXTEND_CLASS(_name, _ext,                                       \
 245                      ({ class_##_name##_t _t = { .lock = l }, *_T = &_t;\
 246                         if (_T->lock && !(_condlock)) _T->lock = NULL;  \
 247                         _t; }),                                         \
 248                      typeof_member(class_##_name##_t, lock) l)          \
 249         static inline void * class_##_name##_ext##_lock_ptr(class_##_name##_t *_T) \
 250         { return class_##_name##_lock_ptr(_T); }
 251
 252
 253 #endif /* _LINUX_CLEANUP_H */