libkern/os/refcnt.h

   1 /*
   2  * Copyright (c) 2017 Apple Inc. All rights reserved.
   3  *
   4  * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. The rights granted to you under the License
  10  * may not be used to create, or enable the creation or redistribution of,
  11  * unlawful or unlicensed copies of an Apple operating system, or to
  12  * circumvent, violate, or enable the circumvention or violation of, any
  13  * terms of an Apple operating system software license agreement.
  14  *
  15  * Please obtain a copy of the License at
  16  * http://www.opensource.apple.com/apsl/ and read it before using this file.
  17  *
  18  * The Original Code and all software distributed under the License are
  19  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  20  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  21  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  22  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  23  * Please see the License for the specific language governing rights and
  24  * limitations under the License.
  25  *
  26  * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
  27  */
  28
  29 #ifndef _OS_REFCNT_H_
  30 #define _OS_REFCNT_H_
  31
  32 /*
  33  * os_refcnt reference counting API
  34  *
  35  * Two flavors are provided: atomic and locked. Atomic internally uses C11 atomic
  36  * operations and requires no external synchronization, whereas the locked flavor
  37  * assumes the refcnt object is locked by the caller. It is NOT safe to
  38  * mix-and-match locked and atomic calls.
  39  */
  40
  41 #include <stdatomic.h>
  42 #include <stdbool.h>
  43 #include <os/base.h>
  44
  45 struct os_refcnt;
  46 struct os_refgrp;
  47 typedef struct os_refcnt os_refcnt_t;
  48
  49 /* type of the internal counter */
  50 typedef uint32_t os_ref_count_t;
  51
  52 #if DEVELOPMENT || DEBUG
  53 # define OS_REFCNT_DEBUG 1
  54 #else
  55 # define OS_REFCNT_DEBUG 0
  56 #endif
  57
  58 /*
  59  * Debugging is keyed off ref_group, so leave that field for kexts so that the
  60  * combination of dev/debug kernel and release kext works.
  61  */
  62 #if XNU_KERNEL_PRIVATE
  63 # define OS_REFCNT_HAS_GROUP OS_REFCNT_DEBUG
  64 #else
  65 # define OS_REFCNT_HAS_GROUP 1
  66 #endif
  67
  68 struct os_refcnt {
  69         _Atomic os_ref_count_t ref_count;
  70 #if OS_REFCNT_HAS_GROUP
  71         struct os_refgrp *ref_group;
  72 #endif
  73 };
  74
  75 #if OS_REFCNT_DEBUG
  76 struct os_refgrp {
  77         const char *const grp_name;
  78         _Atomic os_ref_count_t grp_children; /* number of refcount objects in group */
  79         _Atomic os_ref_count_t grp_count;    /* current reference count of group */
  80         _Atomic uint64_t grp_retain_total;
  81         _Atomic uint64_t grp_release_total;
  82         struct os_refgrp *grp_parent;
  83         void *grp_log;                       /* refcount logging context */
  84 };
  85 #endif
  86
  87 #if __has_attribute(diagnose_if)
  88 # define os_error_if(cond, msg) __attribute__((diagnose_if((cond), (msg), "error")))
  89 #else
  90 # define os_error_if(...)
  91 #endif
  92
  93 __BEGIN_DECLS
  94
  95 /*
  96  * os_ref_init: initialize an os_refcnt with a count of 1
  97  * os_ref_init_count: initialize an os_refcnt with a specific count >= 1
  98  */
  99 #define os_ref_init(rc, grp) os_ref_init_count((rc), (grp), 1)
 100 void os_ref_init_count(struct os_refcnt *, struct os_refgrp *, os_ref_count_t count)
 101 os_error_if(count == 0, "Reference count must be non-zero initialized");
 102
 103 #if OS_REFCNT_DEBUG
 104 # define os_refgrp_decl(qual, var, name, parent) \
 105         qual struct os_refgrp __attribute__((section("__DATA,__refgrps"))) var = { \
 106                 .grp_name =          (name), \
 107                 .grp_children =      ATOMIC_VAR_INIT(0), \
 108                 .grp_count =         ATOMIC_VAR_INIT(0), \
 109                 .grp_retain_total =  ATOMIC_VAR_INIT(0), \
 110                 .grp_release_total = ATOMIC_VAR_INIT(0), \
 111                 .grp_parent =        (parent), \
 112                 .grp_log =           NULL, \
 113         }
 114
 115 /* Create a default group based on the init() callsite if no explicit group
 116  * is provided. */
 117 # define os_ref_init_count(rc, grp, count) ({ \
 118                 os_refgrp_decl(static, __grp, __func__, NULL); \
 119                 (os_ref_init_count)((rc), (grp) ? (grp) : &__grp, (count)); \
 120         })
 121 #else
 122 # define os_refgrp_decl(...)
 123 # define os_ref_init_count(rc, grp, count) (os_ref_init_count)((rc), NULL, (count))
 124 #endif /* OS_REFCNT_DEBUG */
 125
 126 /*
 127  * os_ref_retain: acquire a reference (increment reference count by 1) atomically.
 128  *
 129  * os_ref_release: release a reference (decrement reference count) atomically and
 130  *              return the new count. Memory is synchronized such that the dealloc block
 131  *              (i.e. code handling the final release() == 0 call) sees up-to-date memory
 132  *              with respect to all prior release()s on the same refcnt object. This
 133  *              memory ordering is sufficient for most use cases.
 134  *
 135  * os_ref_release_relaxed: same as release() but with weaker relaxed memory ordering.
 136  *              This can be used when the dealloc block is already synchronized with other
 137  *              accesses to the object (for example, with a lock).
 138  *
 139  * os_ref_release_live: release a reference that is guaranteed not to be the last one.
 140  */
 141 void os_ref_retain(struct os_refcnt *);
 142
 143 os_ref_count_t os_ref_release_explicit(struct os_refcnt *rc,
 144     memory_order release_order, memory_order dealloc_order) OS_WARN_RESULT;
 145
 146 static inline os_ref_count_t OS_WARN_RESULT
 147 os_ref_release(struct os_refcnt *rc)
 148 {
 149         return os_ref_release_explicit(rc, memory_order_release, memory_order_acquire);
 150 }
 151
 152 static inline os_ref_count_t OS_WARN_RESULT
 153 os_ref_release_relaxed(struct os_refcnt *rc)
 154 {
 155         return os_ref_release_explicit(rc, memory_order_relaxed, memory_order_relaxed);
 156 }
 157
 158 static inline void
 159 os_ref_release_live(struct os_refcnt *rc)
 160 {
 161         if (__improbable(os_ref_release_explicit(rc,
 162             memory_order_release, memory_order_relaxed) == 0)) {
 163                 panic("os_refcnt: unexpected release of final reference (rc=%p)\n", rc);
 164                 __builtin_unreachable();
 165         }
 166 }
 167
 168
 169 /*
 170  * os_ref_retain_try: a variant of atomic retain that fails for objects with a
 171  *              zero reference count. The caller must therefore ensure that the object
 172  *              remains alive for any possible retain_try() caller, usually by using a
 173  *              lock protecting both the retain and dealloc paths. This variant is useful
 174  *              for objects stored in a collection, because no lock is required on the
 175  *              release() side until the object is deallocated.
 176  */
 177 bool os_ref_retain_try(struct os_refcnt *) OS_WARN_RESULT;
 178
 179
 180 /*
 181  * os_ref_retain_locked: acquire a reference on an object protected by a held
 182  *              lock. The caller must ensure mutual exclusivity of retain_locked() and
 183  *              release_locked() calls on the same object.
 184  *
 185  * os_ref_release_locked: release a reference on an object protected by a held
 186  *              lock.
 187  */
 188 void os_ref_retain_locked(struct os_refcnt *);
 189 os_ref_count_t os_ref_release_locked(struct os_refcnt *) OS_WARN_RESULT;
 190
 191
 192 /*
 193  * os_ref_get_count: return the current reference count. This is unsafe for
 194  *              synchronization.
 195  */
 196 static inline os_ref_count_t
 197 os_ref_get_count(struct os_refcnt *rc)
 198 {
 199         return atomic_load_explicit(&rc->ref_count, memory_order_relaxed);
 200 }
 201
 202 __END_DECLS
 203
 204 #endif