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
  11  *      the variable.
  12  *
  13  * __free(name):
  14  *      variable attribute to add a scoped based cleanup to the variable.
  15  *
  16  * no_free_ptr(var):
  17  *      like a non-atomic xchg(var, NULL), such that the cleanup function will
  18  *      be inhibited -- provided it sanely deals with a NULL value.
  19  *
  20  * return_ptr(p):
  21  *      returns p while inhibiting the __free().
  22  *
  23  * Ex.
  24  *
  25  * DEFINE_FREE(kfree, void *, if (_T) kfree(_T))
  26  *
  27  *      struct obj *p __free(kfree) = kmalloc(...);
  28  *      if (!p)
  29  *              return NULL;
  30  *
  31  *      if (!init_obj(p))
  32  *              return NULL;
  33  *
  34  *      return_ptr(p);
  35  */
  36
  37 #define DEFINE_FREE(_name, _type, _free) \
  38         static inline void __free_##_name(void *p) { _type _T = *(_type *)p; _free; }
  39
  40 #define __free(_name)   __cleanup(__free_##_name)
  41
  42 #define no_free_ptr(p) \
  43         ({ __auto_type __ptr = (p); (p) = NULL; __ptr; })
  44
  45 #define return_ptr(p)   return no_free_ptr(p)
  46
  47
  48 /*
  49  * DEFINE_CLASS(name, type, exit, init, init_args...):
  50  *      helper to define the destructor and constructor for a type.
  51  *      @exit is an expression using '_T' -- similar to FREE above.
  52  *      @init is an expression in @init_args resulting in @type
  53  *
  54  * EXTEND_CLASS(name, ext, init, init_args...):
  55  *      extends class @name to @name@ext with the new constructor
  56  *
  57  * CLASS(name, var)(args...):
  58  *      declare the variable @var as an instance of the named class
  59  *
  60  * Ex.
  61  *
  62  * DEFINE_CLASS(fdget, struct fd, fdput(_T), fdget(fd), int fd)
  63  *
  64  *      CLASS(fdget, f)(fd);
  65  *      if (!f.file)
  66  *              return -EBADF;
  67  *
  68  *      // use 'f' without concern
  69  */
  70
  71 #define DEFINE_CLASS(_name, _type, _exit, _init, _init_args...)         \
  72 typedef _type class_##_name##_t;                                        \
  73 static inline void class_##_name##_destructor(_type *p)                 \
  74 { _type _T = *p; _exit; }                                               \
  75 static inline _type class_##_name##_constructor(_init_args)             \
  76 { _type t = _init; return t; }
  77
  78 #define EXTEND_CLASS(_name, ext, _init, _init_args...)                  \
  79 typedef class_##_name##_t class_##_name##ext##_t;                       \
  80 static inline void class_##_name##ext##_destructor(class_##_name##_t *p)\
  81 { class_##_name##_destructor(p); }                                      \
  82 static inline class_##_name##_t class_##_name##ext##_constructor(_init_args) \
  83 { class_##_name##_t t = _init; return t; }
  84
  85 #define CLASS(_name, var)                                               \
  86         class_##_name##_t var __cleanup(class_##_name##_destructor) =   \
  87                 class_##_name##_constructor
  88
  89
  90 /*
  91  * DEFINE_GUARD(name, type, lock, unlock):
  92  *      trivial wrapper around DEFINE_CLASS() above specifically
  93  *      for locks.
  94  *
  95  * guard(name):
  96  *      an anonymous instance of the (guard) class
  97  *
  98  * scoped_guard (name, args...) { }:
  99  *      similar to CLASS(name, scope)(args), except the variable (with the
 100  *      explicit name 'scope') is declard in a for-loop such that its scope is
 101  *      bound to the next (compound) statement.
 102  *
 103  */
 104
 105 #define DEFINE_GUARD(_name, _type, _lock, _unlock) \
 106         DEFINE_CLASS(_name, _type, _unlock, ({ _lock; _T; }), _type _T)
 107
 108 #define guard(_name) \
 109         CLASS(_name, __UNIQUE_ID(guard))
 110
 111 #define scoped_guard(_name, args...)                                    \
 112         for (CLASS(_name, scope)(args),                                 \
 113              *done = NULL; !done; done = (void *)1)
 114
 115 /*
 116  * Additional helper macros for generating lock guards with types, either for
 117  * locks that don't have a native type (eg. RCU, preempt) or those that need a
 118  * 'fat' pointer (eg. spin_lock_irqsave).
 119  *
 120  * DEFINE_LOCK_GUARD_0(name, lock, unlock, ...)
 121  * DEFINE_LOCK_GUARD_1(name, type, lock, unlock, ...)
 122  *
 123  * will result in the following type:
 124  *
 125  *   typedef struct {
 126  *      type *lock;             // 'type := void' for the _0 variant
 127  *      __VA_ARGS__;
 128  *   } class_##name##_t;
 129  *
 130  * As above, both _lock and _unlock are statements, except this time '_T' will
 131  * be a pointer to the above struct.
 132  */
 133
 134 #define __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, ...)               \
 135 typedef struct {                                                        \
 136         _type *lock;                                                    \
 137         __VA_ARGS__;                                                    \
 138 } class_##_name##_t;                                                    \
 139                                                                         \
 140 static inline void class_##_name##_destructor(class_##_name##_t *_T)    \
 141 {                                                                       \
 142         if (_T->lock) { _unlock; }                                      \
 143 }
 144
 145
 146 #define __DEFINE_LOCK_GUARD_1(_name, _type, _lock)                      \
 147 static inline class_##_name##_t class_##_name##_constructor(_type *l)   \
 148 {                                                                       \
 149         class_##_name##_t _t = { .lock = l }, *_T = &_t;                \
 150         _lock;                                                          \
 151         return _t;                                                      \
 152 }
 153
 154 #define __DEFINE_LOCK_GUARD_0(_name, _lock)                             \
 155 static inline class_##_name##_t class_##_name##_constructor(void)       \
 156 {                                                                       \
 157         class_##_name##_t _t = { .lock = (void*)1 },                    \
 158                          *_T __maybe_unused = &_t;                      \
 159         _lock;                                                          \
 160         return _t;                                                      \
 161 }
 162
 163 #define DEFINE_LOCK_GUARD_1(_name, _type, _lock, _unlock, ...)          \
 164 __DEFINE_UNLOCK_GUARD(_name, _type, _unlock, __VA_ARGS__)               \
 165 __DEFINE_LOCK_GUARD_1(_name, _type, _lock)
 166
 167 #define DEFINE_LOCK_GUARD_0(_name, _lock, _unlock, ...)                 \
 168 __DEFINE_UNLOCK_GUARD(_name, void, _unlock, __VA_ARGS__)                \
 169 __DEFINE_LOCK_GUARD_0(_name, _lock)
 170
 171 #endif /* __LINUX_GUARDS_H */