source: mainline/uspace/lib/c/include/refcount.h@ b57ba05

/*
 * SPDX-FileCopyrightText: 2018 CZ.NIC, z.s.p.o.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

/*
 * Authors:
 *      Jiří Zárevúcky (jzr) <zarevucky.jiri@gmail.com>
 */

/*
 * Using atomics for reference counting efficiently is a little tricky,
 * so we define a unified API for this.
 */

#ifndef _LIBC_REFCOUNT_H_
#define _LIBC_REFCOUNT_H_

#include <assert.h>
#include <stdatomic.h>
#include <stdbool.h>

/* Wrapped in a structure to prevent direct manipulation. */
typedef struct atomic_refcount {
        volatile atomic_int __cnt;
} atomic_refcount_t;

static inline void refcount_init(atomic_refcount_t *rc)
{
        atomic_store_explicit(&rc->__cnt, 0, memory_order_relaxed);
}

/**
 * Increment a reference count.
 *
 * Calling this without already owning a reference is undefined behavior.
 * E.g. acquiring a reference through a shared mutable pointer requires that
 * the caller first locks the pointer itself (thereby acquiring the reference
 * inherent to the shared variable), and only then may call refcount_up().
 */
static inline void refcount_up(atomic_refcount_t *rc)
{
        // XXX: We can use relaxed operation because acquiring a reference
        //      implies no ordering relationships. A reference-counted object
        //      still needs to be synchronized independently of the refcount.

        int old = atomic_fetch_add_explicit(&rc->__cnt, 1,
            memory_order_relaxed);

        /* old < 0 indicates that the function is used incorrectly. */
        assert(old >= 0);
}

/**
 * Decrement a reference count. Caller must own the reference.
 *
 * If the function returns `false`, the caller no longer owns the reference and
 * must not access the reference counted object.
 *
 * If the function returns `true`, the caller is now the sole owner of the
 * reference counted object, and must deallocate it.
 */
static inline bool refcount_down(atomic_refcount_t *rc)
{
        // XXX: The decrementers don't need to synchronize with each other,
        //      but they do need to synchronize with the one doing deallocation.
        int old = atomic_fetch_sub_explicit(&rc->__cnt, 1,
            memory_order_release);

        assert(old >= 0);

        if (old == 0) {
                // XXX: We are holding the last reference, so we must now
                //      synchronize with all the other decrementers.

                int val = atomic_load_explicit(&rc->__cnt,
                    memory_order_acquire);
                assert(val == -1);

                /*
                 * The compiler probably wouldn't optimize the memory barrier
                 * away, but better safe than sorry.
                 */
                return val < 0;
        }

        return false;
}

#endif