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  * guard(name):
 129  *      an anonymous instance of the (guard) class
 130  *
 131  * scoped_guard (name, args...) { }:
 132  *      similar to CLASS(name, scope)(args), except the variable (with the
 133  *      explicit name 'scope') is declard in a for-loop such that its scope is
 134  *      bound to the next (compound) statement.
 135  *
 136  */
 137
 138 #define DEFINE_GUARD(_name, _type, _lock, _unlock) \
 139         DEFINE_CLASS(_name, _type, _unlock, ({ _lock; _T; }), _type _T)
 140
 141 #define guard(_name) \
 142         CLASS(_name, __UNIQUE_ID(guard))
 143
 144 #define scoped_guard(_name, args...)                                    \
 145         for (CLASS(_name, scope)(args),                                 \
 146              *done = NULL; !done; done = (void *)1)
 147
 148 /*
 149  * Additional helper macros for generating lock guards with types, either for
 150  * locks that don't have a native type (eg. RCU, preempt) or those that need a
 151  * 'fat' pointer (eg. spin_lock_irqsave).
 152  *
 153  * DEFINE_LOCK_GUARD_0(name, lock, unlock, ...)
 154  * DEFINE_LOCK_GUARD_1(name, type, lock, unlock, ...)
 155  *
 156  * will result in the following type:
 157  *
 158  *   typedef struct {
 159  *      type *lock;             // 'type := void' for the _0 variant
 160  *      __VA_ARGS__;
 161  *   } class_##name##_t;
 162  *
 163  * As above, both _lock and _unlock are statements, except this time '_T' will
 164  * be a pointer to the above struct.
 165  */
 166
 167 #define __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, ...)               \
 168 typedef struct {                                                        \
 169         _type *lock;                                                    \
 170         __VA_ARGS__;                                                    \
 171 } class_##_name##_t;                                                    \
 172                                                                         \
 173 static inline void class_##_name##_destructor(class_##_name##_t *_T)    \
 174 {                                                                       \
 175         if (_T->lock) { _unlock; }                                      \
 176 }
 177
 178
 179 #define __DEFINE_LOCK_GUARD_1(_name, _type, _lock)                      \
 180 static inline class_##_name##_t class_##_name##_constructor(_type *l)   \
 181 {                                                                       \
 182         class_##_name##_t _t = { .lock = l }, *_T = &_t;                \
 183         _lock;                                                          \
 184         return _t;                                                      \
 185 }
 186
 187 #define __DEFINE_LOCK_GUARD_0(_name, _lock)                             \
 188 static inline class_##_name##_t class_##_name##_constructor(void)       \
 189 {                                                                       \
 190         class_##_name##_t _t = { .lock = (void*)1 },                    \
 191                          *_T __maybe_unused = &_t;                      \
 192         _lock;                                                          \
 193         return _t;                                                      \
 194 }
 195
 196 #define DEFINE_LOCK_GUARD_1(_name, _type, _lock, _unlock, ...)          \
 197 __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, __VA_ARGS__)               \
 198 __DEFINE_LOCK_GUARD_1(_name, _type, _lock)
 199
 200 #define DEFINE_LOCK_GUARD_0(_name, _lock, _unlock, ...)                 \
 201 __DEFINE_UNLOCK_GUARD(_name, void, _unlock, __VA_ARGS__)                \
 202 __DEFINE_LOCK_GUARD_0(_name, _lock)
 203
 204 #endif /* __LINUX_GUARDS_H */