sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget//translations/zh_CN/core-api/refcount-vs-atomicmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/zh_TW/core-api/refcount-vs-atomicmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/it_IT/core-api/refcount-vs-atomicmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/ja_JP/core-api/refcount-vs-atomicmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/ko_KR/core-api/refcount-vs-atomicmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/pt_BR/core-api/refcount-vs-atomicmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget//translations/sp_SP/core-api/refcount-vs-atomicmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h#refcount_t API compared to atomic_th]h#refcount_t API compared to atomic_t}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhI/var/lib/git/docbuild/linux/Documentation/core-api/refcount-vs-atomic.rsthKubhtopic)}(hhh]h bullet_list)}(hhh](h list_item)}(hhh]h paragraph)}(hhh]h reference)}(hhh]h Introduction}(hhhhhNhNubah}(h]id1ah ]h"]h$]h&]refid introductionuh1hhhubah}(h]h ]h"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]uh1hhhubh)}(hhh]h)}(hhh]h)}(hhh]h!Relevant types of memory ordering}(hjhhhNhNubah}(h]id2ah ]h"]h$]h&]refid!relevant-types-of-memory-orderinguh1hhjubah}(h]h ]h"]h$]h&]uh1hhhubah}(h]h ]h"]h$]h&]uh1hhhubh)}(hhh](h)}(hhh]h)}(hhh]hComparison of functions}(hj%hhhNhNubah}(h]id3ah ]h"]h$]h&]refidcomparison-of-functionsuh1hhj"ubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hhh](h)}(hhh]h)}(hhh]h)}(hhh]h/case 1) - non-“Read/Modify/Write” (RMW) ops}(hjDhhhNhNubah}(h]id4ah ]h"]h$]h&]refid$case-1-non-read-modify-write-rmw-opsuh1hhjAubah}(h]h ]h"]h$]h&]uh1hhj>ubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]hEcase 2) - non-“Read/Modify/Write” (RMW) ops with release ordering}(hjfhhhNhNubah}(h]id5ah ]h"]h$]h&]refid:case-2-non-read-modify-write-rmw-ops-with-release-orderinguh1hhjcubah}(h]h ]h"]h$]h&]uh1hhj`ubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]h2case 3) - increment-based ops that return no value}(hjhhhNhNubah}(h]id6ah ]h"]h$]h&]refid/case-3-increment-based-ops-that-return-no-valueuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]h6case 4) - decrement-based RMW ops that return no value}(hjhhhNhNubah}(h]id7ah ]h"]h$]h&]refid3case-4-decrement-based-rmw-ops-that-return-no-valueuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]h5case 5) - increment-based RMW ops that return a value}(hjhhhNhNubah}(h]id8ah ]h"]h$]h&]refid2case-5-increment-based-rmw-ops-that-return-a-valueuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]hKcase 6) - increment-based RMW ops with acquire ordering that return a value}(hjhhhNhNubah}(h]id9ah ]h"]h$]h&]refidHcase-6-increment-based-rmw-ops-with-acquire-ordering-that-return-a-valueuh1hhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]hEcase 7) - generic dec/sub decrement-based RMW ops that return a value}(hjhhhNhNubah}(h]id10ah ]h"]h$]h&]refidBcase-7-generic-dec-sub-decrement-based-rmw-ops-that-return-a-valueuh1hhj ubah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]h9case 8) other decrement-based RMW ops that return a value}(hj2hhhNhNubah}(h]id11ah ]h"]h$]h&]refid8case-8-other-decrement-based-rmw-ops-that-return-a-valueuh1hhj/ubah}(h]h ]h"]h$]h&]uh1hhj,ubah}(h]h ]h"]h$]h&]uh1hhj;ubh)}(hhh]h)}(hhh]h)}(hhh]hcase 9) - lock-based RMW}(hjThhhNhNubah}(h]id12ah ]h"]h$]h&]refidcase-9-lock-based-rmwuh1hhjQubah}(h]h ]h"]h$]h&]uh1hhjNubah}(h]h ]h"]h$]h&]uh1hhj;ubeh}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]uh1hhhubeh}(h]h ]h"]h$]h&]uh1hhhhhhNhNubah}(h]contentsah ](contentslocaleh"]contentsah$]h&]uh1hhhhKhhhhubh)}(hhh](h)}(h Introductionh]h Introduction}(hjhhhNhNubah}(h]h ]h"]h$]h&]refidhuh1hhjhhhhhKubh)}(hXThe 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.h](hXThe 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 }(hjhhhNhNubhliteral)}(h``refcount_*()``h]h refcount_*()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh and }(hjhhhNhNubj)}(h``atomic_*()``h]h atomic_*()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh 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.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK hjhhubh)}(hThe terms used through this document try to follow the formal LKMM defined in tools/memory-model/Documentation/explanation.txt.h]hThe terms used through this document try to follow the formal LKMM defined in tools/memory-model/Documentation/explanation.txt.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hmemory-barriers.txt and atomic_t.txt provide more background to the memory ordering in general and for atomic operations specifically.h]hmemory-barriers.txt and atomic_t.txt provide more background to the memory ordering in general and for atomic operations specifically.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]hah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h!Relevant types of memory orderingh]h!Relevant types of memory ordering}(hjhhhNhNubah}(h]h ]h"]h$]h&]jj uh1hhjhhhhhKubhnote)}(hThe 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.h]h)}(hThe 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.h]hThe 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.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubh)}(hXIn 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.h](hIn 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 }(hj hhhNhNubj)}(h``atomic_*()``h]h atomic_*()}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh and }(hj hhhNhNubj)}(h``refcount_*()``h]h refcount_*()}(hj:hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh 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.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK!hjhhubh)}(hXA 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().h]hXA 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().}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK)hjhhubh)}(hXA 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().h]hXA 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().}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjhhubh)}(hXWAn 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().h]hXWAn 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().}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK9hjhhubh)}(hXA 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.h]hXA 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.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK@hjhhubeh}(h]jah ]h"]!relevant types of memory orderingah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hComparison of functionsh]hComparison of functions}(hjhhhNhNubah}(h]h ]h"]h$]h&]jj.uh1hhjhhhhhKJubh)}(hhh](h)}(h+case 1) - non-"Read/Modify/Write" (RMW) opsh]h/case 1) - non-“Read/Modify/Write” (RMW) ops}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjMuh1hhjhhhhhKMubh)}(hFunction changes:h]hFunction changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjhhubh block_quote)}(hF* atomic_set() --> refcount_set() * atomic_read() --> refcount_read() h]h)}(hhh](h)}(hatomic_set() --> refcount_set()h]h)}(hjh]hatomic_set() --> refcount_set()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h"atomic_read() --> refcount_read() h]h)}(h!atomic_read() --> refcount_read()h]h!atomic_read() --> refcount_read()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKRhjubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]bullet*uh1hhhhKQhjubah}(h]h ]h"]h$]h&]uh1jhhhKQhjhhubh)}(h"Memory ordering guarantee changes:h]h"Memory ordering guarantee changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThjhhubj)}(h* none (both fully unordered) h]h)}(hhh]h)}(hnone (both fully unordered) h]h)}(hnone (both fully unordered)h]hnone (both fully unordered)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKVhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jjuh1hhhhKVhjubah}(h]h ]h"]h$]h&]uh1jhhhKVhjhhubeh}(h]jSah ]h"]+case 1) - non-"read/modify/write" (rmw) opsah$]h&]uh1hhjhhhhhKMubh)}(hhh](h)}(hAcase 2) - non-"Read/Modify/Write" (RMW) ops with release orderingh]hEcase 2) - non-“Read/Modify/Write” (RMW) ops with release ordering}(hjJhhhNhNubah}(h]h ]h"]h$]h&]jjouh1hhjGhhhhhKZubh)}(hFunction changes:h]hFunction changes:}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK\hjGhhubj)}(h2* atomic_set_release() --> refcount_set_release() h]h)}(hhh]h)}(h0atomic_set_release() --> refcount_set_release() h]h)}(h/atomic_set_release() --> refcount_set_release()h]h/atomic_set_release() --> refcount_set_release()}(hjqhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK^hjmubah}(h]h ]h"]h$]h&]uh1hhjjubah}(h]h ]h"]h$]h&]jjuh1hhhhK^hjfubah}(h]h ]h"]h$]h&]uh1jhhhK^hjGhhubh)}(h"Memory ordering guarantee changes:h]h"Memory ordering guarantee changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK`hjGhhubj)}(h(* none (both provide RELEASE ordering) h]h)}(hhh]h)}(h&none (both provide RELEASE ordering) h]h)}(h$none (both provide RELEASE ordering)h]h$none (both provide RELEASE ordering)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKbhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jjuh1hhhhKbhjubah}(h]h ]h"]h$]h&]uh1jhhhKbhjGhhubeh}(h]juah ]h"]Acase 2) - non-"read/modify/write" (rmw) ops with release orderingah$]h&]uh1hhjhhhhhKZubh)}(hhh](h)}(h2case 3) - increment-based ops that return no valueh]h2case 3) - increment-based ops that return no value}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjhhhhhKfubh)}(hFunction changes:h]hFunction changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhjhhubj)}(hD* atomic_inc() --> refcount_inc() * atomic_add() --> refcount_add() h]h)}(hhh](h)}(hatomic_inc() --> refcount_inc()h]h)}(hjh]hatomic_inc() --> refcount_inc()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKjhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h atomic_add() --> refcount_add() h]h)}(hatomic_add() --> refcount_add()h]hatomic_add() --> refcount_add()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKkhjubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhKjhjubah}(h]h ]h"]h$]h&]uh1jhhhKjhjhhubh)}(h"Memory ordering guarantee changes:h]h"Memory ordering guarantee changes:}(hj2hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhjhhubj)}(h* none (both fully unordered) h]h)}(hhh]h)}(hnone (both fully unordered) h]h)}(hnone (both fully unordered)h]hnone (both fully unordered)}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKohjGubah}(h]h ]h"]h$]h&]uh1hhjDubah}(h]h ]h"]h$]h&]jjuh1hhhhKohj@ubah}(h]h ]h"]h$]h&]uh1jhhhKohjhhubeh}(h]jah ]h"]2case 3) - increment-based ops that return no valueah$]h&]uh1hhjhhhhhKfubh)}(hhh](h)}(h6case 4) - decrement-based RMW ops that return no valueh]h6case 4) - decrement-based RMW ops that return no value}(hjuhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjrhhhhhKrubh)}(hFunction changes:h]hFunction changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKthjrhhubj)}(h"* atomic_dec() --> refcount_dec() h]h)}(hhh]h)}(h atomic_dec() --> refcount_dec() h]h)}(hatomic_dec() --> refcount_dec()h]hatomic_dec() --> refcount_dec()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKvhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jjuh1hhhhKvhjubah}(h]h ]h"]h$]h&]uh1jhhhKvhjrhhubh)}(h"Memory ordering guarantee changes:h]h"Memory ordering guarantee changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKxhjrhhubj)}(h(* fully unordered --> RELEASE ordering h]h)}(hhh]h)}(h&fully unordered --> RELEASE ordering h]h)}(h$fully unordered --> RELEASE orderingh]h$fully unordered --> RELEASE ordering}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKzhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jjuh1hhhhKzhjubah}(h]h ]h"]h$]h&]uh1jhhhKzhjrhhubeh}(h]jah ]h"]6case 4) - decrement-based rmw ops that return no valueah$]h&]uh1hhjhhhhhKrubh)}(hhh](h)}(h5case 5) - increment-based RMW ops that return a valueh]h5case 5) - increment-based RMW ops that return a value}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjhhhhhK~ubh)}(hFunction changes:h]hFunction changes:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hh* atomic_inc_not_zero() --> refcount_inc_not_zero() * no atomic counterpart --> refcount_add_not_zero() h]h)}(hhh](h)}(h1atomic_inc_not_zero() --> refcount_inc_not_zero()h]h)}(hj$h]h1atomic_inc_not_zero() --> refcount_inc_not_zero()}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj"ubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h2no atomic counterpart --> refcount_add_not_zero() h]h)}(h1no atomic counterpart --> refcount_add_not_zero()h]h1no atomic counterpart --> refcount_add_not_zero()}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj9ubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(h#Memory ordering guarantees changes:h]h#Memory ordering guarantees changes:}(hj]hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h=* fully ordered --> control dependency on success for stores h]h)}(hhh]h)}(h;fully ordered --> control dependency on success for stores h]h)}(h:fully ordered --> control dependency on success for storesh]h:fully ordered --> control dependency on success for stores}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjrubah}(h]h ]h"]h$]h&]uh1hhjoubah}(h]h ]h"]h$]h&]jjuh1hhhhKhjkubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(hiWe really assume here that necessary ordering is provided as a result of obtaining pointer to the object!h]h)}(hiWe really assume here that necessary ordering is provided as a result of obtaining pointer to the object!h]hiWe really assume here that necessary ordering is provided as a result of obtaining pointer to the object!}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]jah ]h"]5case 5) - increment-based rmw ops that return a valueah$]h&]uh1hhjhhhhhK~ubh)}(hhh](h)}(hKcase 6) - increment-based RMW ops with acquire ordering that return a valueh]hKcase 6) - increment-based RMW ops with acquire ordering that return a value}(hjhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjhhhhhKubh)}(hFunction changes:h]hFunction changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hx* atomic_inc_not_zero() --> refcount_inc_not_zero_acquire() * no atomic counterpart --> refcount_add_not_zero_acquire() h]h)}(hhh](h)}(h9atomic_inc_not_zero() --> refcount_inc_not_zero_acquire()h]h)}(hjh]h9atomic_inc_not_zero() --> refcount_inc_not_zero_acquire()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h:no atomic counterpart --> refcount_add_not_zero_acquire() h]h)}(h9no atomic counterpart --> refcount_add_not_zero_acquire()h]h9no atomic counterpart --> refcount_add_not_zero_acquire()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(h#Memory ordering guarantees changes:h]h#Memory ordering guarantees changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h1* fully ordered --> ACQUIRE ordering on success h]h)}(hhh]h)}(h/fully ordered --> ACQUIRE ordering on success h]h)}(h-fully ordered --> ACQUIRE ordering on successh]h-fully ordered --> ACQUIRE ordering on success}(hj/hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj+ubah}(h]h ]h"]h$]h&]uh1hhj(ubah}(h]h ]h"]h$]h&]jjuh1hhhhKhj$ubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]jah ]h"]Kcase 6) - increment-based rmw ops with acquire ordering that return a valueah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hEcase 7) - generic dec/sub decrement-based RMW ops that return a valueh]hEcase 7) - generic dec/sub decrement-based RMW ops that return a value}(hjYhhhNhNubah}(h]h ]h"]h$]h&]jjuh1hhjVhhhhhKubh)}(hFunction changes:h]hFunction changes:}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubj)}(hh* atomic_dec_and_test() --> refcount_dec_and_test() * atomic_sub_and_test() --> refcount_sub_and_test() h]h)}(hhh](h)}(h1atomic_dec_and_test() --> refcount_dec_and_test()h]h)}(hj~h]h1atomic_dec_and_test() --> refcount_dec_and_test()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj|ubah}(h]h ]h"]h$]h&]uh1hhjyubh)}(h2atomic_sub_and_test() --> refcount_sub_and_test() h]h)}(h1atomic_sub_and_test() --> refcount_sub_and_test()h]h1atomic_sub_and_test() --> refcount_sub_and_test()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjyubeh}(h]h ]h"]h$]h&]jjuh1hhhhKhjuubah}(h]h ]h"]h$]h&]uh1jhhhKhjVhhubh)}(h#Memory ordering guarantees changes:h]h#Memory ordering guarantees changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjVhhubj)}(hD* fully ordered --> RELEASE ordering + ACQUIRE ordering on success h]h)}(hhh]h)}(hBfully ordered --> RELEASE ordering + ACQUIRE ordering on success h]h)}(h@fully ordered --> RELEASE ordering + ACQUIRE ordering on successh]h@fully ordered --> RELEASE ordering + ACQUIRE ordering on success}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jjuh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjVhhubeh}(h]jah ]h"]Ecase 7) - generic dec/sub decrement-based rmw ops that return a valueah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(h9case 8) other decrement-based RMW ops that return a valueh]h9case 8) other decrement-based RMW ops that return a value}(hjhhhNhNubah}(h]h ]h"]h$]h&]jj;uh1hhjhhhhhKubh)}(hFunction changes:h]hFunction changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hz* no atomic counterpart --> refcount_dec_if_one() * ``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` h]h)}(hhh](h)}(h/no atomic counterpart --> refcount_dec_if_one()h]h)}(hjh]h/no atomic counterpart --> refcount_dec_if_one()}(hj!hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(hF``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)`` h]h)}(hE``atomic_add_unless(&var, -1, 1)`` --> ``refcount_dec_not_one(&var)``h](j)}(h"``atomic_add_unless(&var, -1, 1)``h]hatomic_add_unless(&var, -1, 1)}(hj<hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubh --> }(hj8hhhNhNubj)}(h``refcount_dec_not_one(&var)``h]hrefcount_dec_not_one(&var)}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubeh}(h]h ]h"]h$]h&]uh1hhhhKhj4ubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(h#Memory ordering guarantees changes:h]h#Memory ordering guarantees changes:}(hjthhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h:* fully ordered --> RELEASE ordering + control dependency h]h)}(hhh]h)}(h8fully ordered --> RELEASE ordering + control dependency h]h)}(h7fully ordered --> RELEASE ordering + control dependencyh]h7fully ordered --> RELEASE ordering + control dependency}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubah}(h]h ]h"]h$]h&]jjuh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubj)}(h8atomic_add_unless() only provides full order on success.h]h)}(hjh]h8atomic_add_unless() only provides full order on success.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhjhhhhhNubeh}(h]jAah ]h"]9case 8) other decrement-based rmw ops that return a valueah$]h&]uh1hhjhhhhhKubh)}(hhh](h)}(hcase 9) - lock-based RMWh]hcase 9) - lock-based RMW}(hjhhhNhNubah}(h]h ]h"]h$]h&]jj]uh1hhjhhhhhKubh)}(hFunction changes:h]hFunction changes:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(ht* atomic_dec_and_lock() --> refcount_dec_and_lock() * atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock() h]h)}(hhh](h)}(h1atomic_dec_and_lock() --> refcount_dec_and_lock()h]h)}(hjh]h1atomic_dec_and_lock() --> refcount_dec_and_lock()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhjubh)}(h>atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock() h]h)}(h=atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock()h]h=atomic_dec_and_mutex_lock() --> refcount_dec_and_mutex_lock()}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhjubeh}(h]h ]h"]h$]h&]jjuh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubh)}(h#Memory ordering guarantees changes:h]h#Memory ordering guarantees changes:}(hj, hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hY* fully ordered --> RELEASE ordering + control dependency + hold spin_lock() on successh]h)}(hhh]h)}(hUfully ordered --> RELEASE ordering + control dependency + hold spin_lock() on successh]h)}(hUfully ordered --> RELEASE ordering + control dependency + hold spin_lock() on successh]hUfully ordered --> RELEASE ordering + control dependency + hold spin_lock() on success}(hjE hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjA ubah}(h]h ]h"]h$]h&]uh1hhj> ubah}(h]h ]h"]h$]h&]jjuh1hhhhKhj: ubah}(h]h ]h"]h$]h&]uh1jhhhKhjhhubeh}(h]jcah ]h"]case 9) - lock-based rmwah$]h&]uh1hhjhhhhhKubeh}(h]j4ah ]h"]comparison of functionsah$]h&]uh1hhhhhhhhKJubeh}(h]#refcount-t-api-compared-to-atomic-tah ]h"]#refcount_t api compared to atomic_tah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerj error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jx ju jjjhjjjp j4jDjSjjujojjjjjjSjjjjjAji jcu nametypes}(jx jjjjp jDjjojjjSjjji uh}(ju hjhhjjjj4jjSjjujGjjjjrjjjjjjVjAjjcjhhj jj.j%jMjDjojfjjjjjjjjjjj;j2j]jTu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}j K sRparse_messages]transform_messages] transformerN include_log] decorationNhhub.