mirror of https://github.com/Qortal/Brooklyn
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
168 lines
5.6 KiB
168 lines
5.6 KiB
=================================== |
|
refcount_t API compared to atomic_t |
|
=================================== |
|
|
|
.. contents:: :local: |
|
|
|
Introduction |
|
============ |
|
|
|
The goal of refcount_t API is to provide a minimal API for implementing |
|
an object's reference counters. While a generic architecture-independent |
|
implementation from lib/refcount.c uses atomic operations underneath, |
|
there are a number of differences between some of the ``refcount_*()`` and |
|
``atomic_*()`` functions with regards to the memory ordering guarantees. |
|
This document outlines the differences and provides respective examples |
|
in order to help maintainers validate their code against the change in |
|
these memory ordering guarantees. |
|
|
|
The terms used through this document try to follow the formal LKMM defined in |
|
tools/memory-model/Documentation/explanation.txt. |
|
|
|
memory-barriers.txt and atomic_t.txt provide more background to the |
|
memory ordering in general and for atomic operations specifically. |
|
|
|
Relevant types of memory ordering |
|
================================= |
|
|
|
.. note:: The following section only covers some of the memory |
|
ordering types that are relevant for the atomics and reference |
|
counters and used through this document. For a much broader picture |
|
please consult memory-barriers.txt document. |
|
|
|
In the absence of any memory ordering guarantees (i.e. fully unordered) |
|
atomics & refcounters only provide atomicity and |
|
program order (po) relation (on the same CPU). It guarantees that |
|
each ``atomic_*()`` and ``refcount_*()`` operation is atomic and instructions |
|
are executed in program order on a single CPU. |
|
This is implemented using READ_ONCE()/WRITE_ONCE() and |
|
compare-and-swap primitives. |
|
|
|
A strong (full) memory ordering guarantees that all prior loads and |
|
stores (all po-earlier instructions) on the same CPU are completed |
|
before any po-later instruction is executed on the same CPU. |
|
It also guarantees that all po-earlier stores on the same CPU |
|
and all propagated stores from other CPUs must propagate to all |
|
other CPUs before any po-later instruction is executed on the original |
|
CPU (A-cumulative property). This is implemented using smp_mb(). |
|
|
|
A RELEASE memory ordering guarantees that all prior loads and |
|
stores (all po-earlier instructions) on the same CPU are completed |
|
before the operation. It also guarantees that all po-earlier |
|
stores on the same CPU and all propagated stores from other CPUs |
|
must propagate to all other CPUs before the release operation |
|
(A-cumulative property). This is implemented using |
|
smp_store_release(). |
|
|
|
An ACQUIRE memory ordering guarantees that all post loads and |
|
stores (all po-later instructions) on the same CPU are |
|
completed after the acquire operation. It also guarantees that all |
|
po-later stores on the same CPU must propagate to all other CPUs |
|
after the acquire operation executes. This is implemented using |
|
smp_acquire__after_ctrl_dep(). |
|
|
|
A control dependency (on success) for refcounters guarantees that |
|
if a reference for an object was successfully obtained (reference |
|
counter increment or addition happened, function returned true), |
|
then further stores are ordered against this operation. |
|
Control dependency on stores are not implemented using any explicit |
|
barriers, but rely on CPU not to speculate on stores. This is only |
|
a single CPU relation and provides no guarantees for other CPUs. |
|
|
|
|
|
Comparison of functions |
|
======================= |
|
|
|
case 1) - non-"Read/Modify/Write" (RMW) ops |
|
------------------------------------------- |
|
|
|
Function changes: |
|
|
|
* atomic_set() --> refcount_set() |
|
* atomic_read() --> refcount_read() |
|
|
|
Memory ordering guarantee changes: |
|
|
|
* none (both fully unordered) |
|
|
|
|
|
case 2) - increment-based ops that return no value |
|
-------------------------------------------------- |
|
|
|
Function changes: |
|
|
|
* atomic_inc() --> refcount_inc() |
|
* atomic_add() --> refcount_add() |
|
|
|
Memory ordering guarantee changes: |
|
|
|
* none (both fully unordered) |
|
|
|
case 3) - decrement-based RMW ops that return no value |
|
------------------------------------------------------ |
|
|
|
Function changes: |
|
|
|
* atomic_dec() --> refcount_dec() |
|
|
|
Memory ordering guarantee changes: |
|
|
|
* fully unordered --> RELEASE ordering |
|
|
|
|
|
case 4) - increment-based RMW ops that return a value |
|
----------------------------------------------------- |
|
|
|
Function changes: |
|
|
|
* atomic_inc_not_zero() --> refcount_inc_not_zero() |
|
* no atomic counterpart --> refcount_add_not_zero() |
|
|
|
Memory ordering guarantees changes: |
|
|
|
* fully ordered --> control dependency on success for stores |
|
|
|
.. note:: We really assume here that necessary ordering is provided as a |
|
result of obtaining pointer to the object! |
|
|
|
|
|
case 5) - generic dec/sub decrement-based RMW ops that return a value |
|
--------------------------------------------------------------------- |
|
|
|
Function changes: |
|
|
|
* atomic_dec_and_test() --> refcount_dec_and_test() |
|
* atomic_sub_and_test() --> refcount_sub_and_test() |
|
|
|
Memory ordering guarantees changes: |
|
|
|
* fully ordered --> RELEASE ordering + ACQUIRE ordering on success |
|
|
|
|
|
case 6) other decrement-based RMW ops that return a value |
|
--------------------------------------------------------- |
|
|
|
Function changes: |
|
|
|
* no atomic counterpart --> refcount_dec_if_one() |
|
* ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` |
|
|
|
Memory ordering guarantees changes: |
|
|
|
* fully ordered --> RELEASE ordering + control dependency |
|
|
|
.. note:: atomic_add_unless() only provides full order on success. |
|
|
|
|
|
case 7) - lock-based RMW |
|
------------------------ |
|
|
|
Function changes: |
|
|
|
* atomic_dec_and_lock() --> refcount_dec_and_lock() |
|
* atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock() |
|
|
|
Memory ordering guarantees changes: |
|
|
|
* fully ordered --> RELEASE ordering + control dependency + hold |
|
spin_lock() on success
|
|
|