€•(„      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ-/translations/zh_CN/core-api/circular-buffers”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/zh_TW/core-api/circular-buffers”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/it_IT/core-api/circular-buffers”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ja_JP/core-api/circular-buffers”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/ko_KR/core-api/circular-buffers”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒPortuguese (Brazilian)”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/pt_BR/core-api/circular-buffers”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh–sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ-/translations/sp_SP/core-api/circular-buffers”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒCircular Buffers”h]”hŒCircular Buffers”…””}”(hh¼h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhh·h²hh³ŒG/var/lib/git/docbuild/linux/Documentation/core-api/circular-buffers.rst”h´KubhŒ
field_list”“”)”}”(hhh]”(hŒfield”“”)”}”(hhh]”(hŒ
field_name”“”)”}”(hŒAuthor”h]”hŒAuthor”…””}”(hh×h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhhÒh³hÊh´K ubhŒ
field_body”“”)”}”(hŒ#David Howells <dhowells@redhat.com>”h]”hŒ	paragraph”“”)”}”(hhéh]”(hŒDavid Howells <”…””}”(hhíh²hh³Nh´NubhŒ	reference”“”)”}”(hŒdhowells@redhat.com”h]”hŒdhowells@redhat.com”…””}”(hhöh²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:dhowells@redhat.com”uh1hôhhíubhŒ>”…””}”(hhíh²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Khhçubah}”(h]”h ]”h"]”h$]”h&]”uh1håhhÒubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÐh³hÊh´KhhÍh²hubhÑ)”}”(hhh]”(hÖ)”}”(hŒAuthor”h]”hŒAuthor”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÕhj  h³hÊh´K ubhæ)”}”(hŒ*Paul E. McKenney <paulmck@linux.ibm.com>

”h]”hì)”}”(hŒ(Paul E. McKenney <paulmck@linux.ibm.com>”h]”(hŒPaul E. McKenney <”…””}”(hj1  h²hh³Nh´Nubhõ)”}”(hŒpaulmck@linux.ibm.com”h]”hŒpaulmck@linux.ibm.com”…””}”(hj9  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:paulmck@linux.ibm.com”uh1hôhj1  ubhŒ>”…””}”(hj1  h²hh³Nh´Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Khj-  ubah}”(h]”h ]”h"]”h$]”h&]”uh1håhj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÐh³hÊh´KhhÍh²hubeh}”(h]”h ]”h"]”h$]”h&]”uh1hËhh·h²hh³hÊh´Kubhì)”}”(hŒ{Linux provides a number of features that can be used to implement circular
buffering.  There are two sets of such features:”h]”hŒ{Linux provides a number of features that can be used to implement circular
buffering.  There are two sets of such features:”…””}”(hje  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K	hh·h²hubhŒblock_quote”“”)”}”(hŒÏ(1) Convenience functions for determining information about power-of-2 sized
    buffers.

(2) Memory barriers for when the producer and the consumer of objects in the
    buffer don't want to share a lock.
”h]”hŒenumerated_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒRConvenience functions for determining information about power-of-2 sized
buffers.
”h]”hì)”}”(hŒQConvenience functions for determining information about power-of-2 sized
buffers.”h]”hŒQConvenience functions for determining information about power-of-2 sized
buffers.”…””}”(hj„  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Khj€  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj{  ubj  )”}”(hŒlMemory barriers for when the producer and the consumer of objects in the
buffer don't want to share a lock.
”h]”hì)”}”(hŒkMemory barriers for when the producer and the consumer of objects in the
buffer don't want to share a lock.”h]”hŒmMemory barriers for when the producer and the consumer of objects in the
buffer donâ€™t want to share a lock.”…””}”(hjœ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Khj˜  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj{  ubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”Œ(”Œsuffix”Œ)”uh1jy  hju  ubah}”(h]”h ]”h"]”h$]”h&]”uh1js  h³hÊh´Khh·h²hubhì)”}”(hŒßTo use these facilities, as discussed below, there needs to be just one
producer and just one consumer.  It is possible to handle multiple producers by
serialising them, and to handle multiple consumers by serialising them.”h]”hŒßTo use these facilities, as discussed below, there needs to be just one
producer and just one consumer.  It is possible to handle multiple producers by
serialising them, and to handle multiple consumers by serialising them.”…””}”(hjÂ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Khh·h²hubhŒcomment”“”)”}”(hŒ¦Contents:

(*) What is a circular buffer?

(*) Measuring power-of-2 buffers.

(*) Using memory barriers with circular buffers.
    - The producer.
    - The consumer.”h]”hŒ¦Contents:

(*) What is a circular buffer?

(*) Measuring power-of-2 buffers.

(*) Using memory barriers with circular buffers.
    - The producer.
    - The consumer.”…””}”hjÒ  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jÐ  hh·h²hh³hÊh´K"ubh¶)”}”(hhh]”(h»)”}”(hŒWhat is a circular buffer?”h]”hŒWhat is a circular buffer?”…””}”(hjå  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjâ  h²hh³hÊh´K$ubhì)”}”(hŒFirst of all, what is a circular buffer?  A circular buffer is a buffer of
fixed, finite size into which there are two indices:”h]”hŒFirst of all, what is a circular buffer?  A circular buffer is a buffer of
fixed, finite size into which there are two indices:”…””}”(hjó  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K&hjâ  h²hubjt  )”}”(hŒµ(1) A 'head' index - the point at which the producer inserts items into the
    buffer.

(2) A 'tail' index - the point at which the consumer finds the next item in
    the buffer.
”h]”jz  )”}”(hhh]”(j  )”}”(hŒPA 'head' index - the point at which the producer inserts items into the
buffer.
”h]”hì)”}”(hŒOA 'head' index - the point at which the producer inserts items into the
buffer.”h]”hŒSA â€˜headâ€™ index - the point at which the producer inserts items into the
buffer.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K)hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj  ubj  )”}”(hŒTA 'tail' index - the point at which the consumer finds the next item in
the buffer.
”h]”hì)”}”(hŒSA 'tail' index - the point at which the consumer finds the next item in
the buffer.”h]”hŒWA â€˜tailâ€™ index - the point at which the consumer finds the next item in
the buffer.”…””}”(hj$  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K,hj   ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”j¶  j·  j¸  j¹  jº  j»  uh1jy  hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1js  h³hÊh´K)hjâ  h²hubhì)”}”(hŒ¢Typically when the tail pointer is equal to the head pointer, the buffer is
empty; and the buffer is full when the head pointer is one less than the tail
pointer.”h]”hŒ¢Typically when the tail pointer is equal to the head pointer, the buffer is
empty; and the buffer is full when the head pointer is one less than the tail
pointer.”…””}”(hjD  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K/hjâ  h²hubhì)”}”(hX$  The head index is incremented when items are added, and the tail index when
items are removed.  The tail index should never jump the head index, and both
indices should be wrapped to 0 when they reach the end of the buffer, thus
allowing an infinite amount of data to flow through the buffer.”h]”hX$  The head index is incremented when items are added, and the tail index when
items are removed.  The tail index should never jump the head index, and both
indices should be wrapped to 0 when they reach the end of the buffer, thus
allowing an infinite amount of data to flow through the buffer.”…””}”(hjR  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K3hjâ  h²hubhì)”}”(hX­  Typically, items will all be of the same unit size, but this isn't strictly
required to use the techniques below.  The indices can be increased by more
than 1 if multiple items or variable-sized items are to be included in the
buffer, provided that neither index overtakes the other.  The implementer must
be careful, however, as a region more than one unit in size may wrap the end of
the buffer and be broken into two segments.”h]”hX¯  Typically, items will all be of the same unit size, but this isnâ€™t strictly
required to use the techniques below.  The indices can be increased by more
than 1 if multiple items or variable-sized items are to be included in the
buffer, provided that neither index overtakes the other.  The implementer must
be careful, however, as a region more than one unit in size may wrap the end of
the buffer and be broken into two segments.”…””}”(hj`  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K8hjâ  h²hubeh}”(h]”Œwhat-is-a-circular-buffer”ah ]”h"]”Œwhat is a circular buffer?”ah$]”h&]”uh1hµhh·h²hh³hÊh´K$ubh¶)”}”(hhh]”(h»)”}”(hŒMeasuring power-of-2 buffers”h]”hŒMeasuring power-of-2 buffers”…””}”(hjy  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjv  h²hh³hÊh´K@ubhì)”}”(hX)  Calculation of the occupancy or the remaining capacity of an arbitrarily sized
circular buffer would normally be a slow operation, requiring the use of a
modulus (divide) instruction.  However, if the buffer is of a power-of-2 size,
then a much quicker bitwise-AND instruction can be used instead.”h]”hX)  Calculation of the occupancy or the remaining capacity of an arbitrarily sized
circular buffer would normally be a slow operation, requiring the use of a
modulus (divide) instruction.  However, if the buffer is of a power-of-2 size,
then a much quicker bitwise-AND instruction can be used instead.”…””}”(hj‡  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KBhjv  h²hubhì)”}”(hŒgLinux provides a set of macros for handling power-of-2 circular buffers.  These
can be made use of by::”h]”hŒfLinux provides a set of macros for handling power-of-2 circular buffers.  These
can be made use of by:”…””}”(hj•  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KGhjv  h²hubhŒliteral_block”“”)”}”(hŒ#include <linux/circ_buf.h>”h]”hŒ#include <linux/circ_buf.h>”…””}”hj¥  sbah}”(h]”h ]”h"]”h$]”h&]”jà  já  uh1j£  h³hÊh´KJhjv  h²hubhì)”}”(hŒThe macros are:”h]”hŒThe macros are:”…””}”(hj³  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KLhjv  h²hubjt  )”}”(hXÂ  (#) Measure the remaining capacity of a buffer::

       CIRC_SPACE(head_index, tail_index, buffer_size);

    This returns the amount of space left in the buffer[1] into which items
    can be inserted.


(#) Measure the maximum consecutive immediate space in a buffer::

       CIRC_SPACE_TO_END(head_index, tail_index, buffer_size);

    This returns the amount of consecutive space left in the buffer[1] into
    which items can be immediately inserted without having to wrap back to the
    beginning of the buffer.


(#) Measure the occupancy of a buffer::

       CIRC_CNT(head_index, tail_index, buffer_size);

    This returns the number of items currently occupying a buffer[2].


(#) Measure the non-wrapping occupancy of a buffer::

       CIRC_CNT_TO_END(head_index, tail_index, buffer_size);

    This returns the number of consecutive items[2] that can be extracted from
    the buffer without having to wrap back to the beginning of the buffer.

”h]”jz  )”}”(hhh]”(j  )”}”(hŒ½Measure the remaining capacity of a buffer::

   CIRC_SPACE(head_index, tail_index, buffer_size);

This returns the amount of space left in the buffer[1] into which items
can be inserted.

”h]”(hì)”}”(hŒ,Measure the remaining capacity of a buffer::”h]”hŒ+Measure the remaining capacity of a buffer:”…””}”(hjÌ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KNhjÈ  ubj¤  )”}”(hŒ0CIRC_SPACE(head_index, tail_index, buffer_size);”h]”hŒ0CIRC_SPACE(head_index, tail_index, buffer_size);”…””}”hjÚ  sbah}”(h]”h ]”h"]”h$]”h&]”jà  já  uh1j£  h³hÊh´KPhjÈ  ubhì)”}”(hŒXThis returns the amount of space left in the buffer[1] into which items
can be inserted.”h]”hŒXThis returns the amount of space left in the buffer[1] into which items
can be inserted.”…””}”(hjè  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KRhjÈ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjÅ  ubj  )”}”(hX(  Measure the maximum consecutive immediate space in a buffer::

   CIRC_SPACE_TO_END(head_index, tail_index, buffer_size);

This returns the amount of consecutive space left in the buffer[1] into
which items can be immediately inserted without having to wrap back to the
beginning of the buffer.

”h]”(hì)”}”(hŒ=Measure the maximum consecutive immediate space in a buffer::”h]”hŒ<Measure the maximum consecutive immediate space in a buffer:”…””}”(hj   h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KVhjü  ubj¤  )”}”(hŒ7CIRC_SPACE_TO_END(head_index, tail_index, buffer_size);”h]”hŒ7CIRC_SPACE_TO_END(head_index, tail_index, buffer_size);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jà  já  uh1j£  h³hÊh´KXhjü  ubhì)”}”(hŒ«This returns the amount of consecutive space left in the buffer[1] into
which items can be immediately inserted without having to wrap back to the
beginning of the buffer.”h]”hŒ«This returns the amount of consecutive space left in the buffer[1] into
which items can be immediately inserted without having to wrap back to the
beginning of the buffer.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KZhjü  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjÅ  ubj  )”}”(hŒ›Measure the occupancy of a buffer::

   CIRC_CNT(head_index, tail_index, buffer_size);

This returns the number of items currently occupying a buffer[2].

”h]”(hì)”}”(hŒ#Measure the occupancy of a buffer::”h]”hŒ"Measure the occupancy of a buffer:”…””}”(hj4  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K_hj0  ubj¤  )”}”(hŒ.CIRC_CNT(head_index, tail_index, buffer_size);”h]”hŒ.CIRC_CNT(head_index, tail_index, buffer_size);”…””}”hjB  sbah}”(h]”h ]”h"]”h$]”h&]”jà  já  uh1j£  h³hÊh´Kahj0  ubhì)”}”(hŒAThis returns the number of items currently occupying a buffer[2].”h]”hŒAThis returns the number of items currently occupying a buffer[2].”…””}”(hjP  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Kchj0  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjÅ  ubj  )”}”(hŒÿMeasure the non-wrapping occupancy of a buffer::

   CIRC_CNT_TO_END(head_index, tail_index, buffer_size);

This returns the number of consecutive items[2] that can be extracted from
the buffer without having to wrap back to the beginning of the buffer.

”h]”(hì)”}”(hŒ0Measure the non-wrapping occupancy of a buffer::”h]”hŒ/Measure the non-wrapping occupancy of a buffer:”…””}”(hjh  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Kfhjd  ubj¤  )”}”(hŒ5CIRC_CNT_TO_END(head_index, tail_index, buffer_size);”h]”hŒ5CIRC_CNT_TO_END(head_index, tail_index, buffer_size);”…””}”hjv  sbah}”(h]”h ]”h"]”h$]”h&]”jà  já  uh1j£  h³hÊh´Khhjd  ubhì)”}”(hŒ‘This returns the number of consecutive items[2] that can be extracted from
the buffer without having to wrap back to the beginning of the buffer.”h]”hŒ‘This returns the number of consecutive items[2] that can be extracted from
the buffer without having to wrap back to the beginning of the buffer.”…””}”(hj„  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Kjhjd  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjÅ  ubeh}”(h]”h ]”h"]”h$]”h&]”j¶  j·  j¸  j¹  jº  j»  uh1jy  hjÁ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1js  h³hÊh´KNhjv  h²hubhì)”}”(hŒXEach of these macros will nominally return a value between 0 and buffer_size-1,
however:”h]”hŒXEach of these macros will nominally return a value between 0 and buffer_size-1,
however:”…””}”(hj¤  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Knhjv  h²hubjt  )”}”(hXä  (1) CIRC_SPACE*() are intended to be used in the producer.  To the producer
    they will return a lower bound as the producer controls the head index,
    but the consumer may still be depleting the buffer on another CPU and
    moving the tail index.

    To the consumer it will show an upper bound as the producer may be busy
    depleting the space.

(2) CIRC_CNT*() are intended to be used in the consumer.  To the consumer they
    will return a lower bound as the consumer controls the tail index, but the
    producer may still be filling the buffer on another CPU and moving the
    head index.

    To the producer it will show an upper bound as the consumer may be busy
    emptying the buffer.

(3) To a third party, the order in which the writes to the indices by the
    producer and consumer become visible cannot be guaranteed as they are
    independent and may be made on different CPUs - so the result in such a
    situation will merely be a guess, and may even be negative.
”h]”jz  )”}”(hhh]”(j  )”}”(hXK  CIRC_SPACE*() are intended to be used in the producer.  To the producer
they will return a lower bound as the producer controls the head index,
but the consumer may still be depleting the buffer on another CPU and
moving the tail index.

To the consumer it will show an upper bound as the producer may be busy
depleting the space.
”h]”(hì)”}”(hŒìCIRC_SPACE*() are intended to be used in the producer.  To the producer
they will return a lower bound as the producer controls the head index,
but the consumer may still be depleting the buffer on another CPU and
moving the tail index.”h]”hŒìCIRC_SPACE*() are intended to be used in the producer.  To the producer
they will return a lower bound as the producer controls the head index,
but the consumer may still be depleting the buffer on another CPU and
moving the tail index.”…””}”(hj½  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Kqhj¹  ubhì)”}”(hŒ\To the consumer it will show an upper bound as the producer may be busy
depleting the space.”h]”hŒ\To the consumer it will show an upper bound as the producer may be busy
depleting the space.”…””}”(hjË  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Kvhj¹  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj¶  ubj  )”}”(hXG  CIRC_CNT*() are intended to be used in the consumer.  To the consumer they
will return a lower bound as the consumer controls the tail index, but the
producer may still be filling the buffer on another CPU and moving the
head index.

To the producer it will show an upper bound as the consumer may be busy
emptying the buffer.
”h]”(hì)”}”(hŒèCIRC_CNT*() are intended to be used in the consumer.  To the consumer they
will return a lower bound as the consumer controls the tail index, but the
producer may still be filling the buffer on another CPU and moving the
head index.”h]”hŒèCIRC_CNT*() are intended to be used in the consumer.  To the consumer they
will return a lower bound as the consumer controls the tail index, but the
producer may still be filling the buffer on another CPU and moving the
head index.”…””}”(hjã  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Kyhjß  ubhì)”}”(hŒ\To the producer it will show an upper bound as the consumer may be busy
emptying the buffer.”h]”hŒ\To the producer it will show an upper bound as the consumer may be busy
emptying the buffer.”…””}”(hjñ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K~hjß  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj¶  ubj  )”}”(hX  To a third party, the order in which the writes to the indices by the
producer and consumer become visible cannot be guaranteed as they are
independent and may be made on different CPUs - so the result in such a
situation will merely be a guess, and may even be negative.
”h]”hì)”}”(hX  To a third party, the order in which the writes to the indices by the
producer and consumer become visible cannot be guaranteed as they are
independent and may be made on different CPUs - so the result in such a
situation will merely be a guess, and may even be negative.”h]”hX  To a third party, the order in which the writes to the indices by the
producer and consumer become visible cannot be guaranteed as they are
independent and may be made on different CPUs - so the result in such a
situation will merely be a guess, and may even be negative.”…””}”(hj	  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hj¶  ubeh}”(h]”h ]”h"]”h$]”h&]”j¶  j·  j¸  j¹  jº  j»  uh1jy  hj²  ubah}”(h]”h ]”h"]”h$]”h&]”uh1js  h³hÊh´Kqhjv  h²hubeh}”(h]”Œmeasuring-power-of-2-buffers”ah ]”h"]”Œmeasuring power-of-2 buffers”ah$]”h&]”uh1hµhh·h²hh³hÊh´K@ubh¶)”}”(hhh]”(h»)”}”(hŒ+Using memory barriers with circular buffers”h]”hŒ+Using memory barriers with circular buffers”…””}”(hj4  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj1  h²hh³hÊh´K‡ubhì)”}”(hŒYBy using memory barriers in conjunction with circular buffers, you can avoid
the need to:”h]”hŒYBy using memory barriers in conjunction with circular buffers, you can avoid
the need to:”…””}”(hjB  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K‰hj1  h²hubjt  )”}”(hŒ³(1) use a single lock to govern access to both ends of the buffer, thus
    allowing the buffer to be filled and emptied at the same time; and

(2) use atomic counter operations.
”h]”jz  )”}”(hhh]”(j  )”}”(hŒ‡use a single lock to govern access to both ends of the buffer, thus
allowing the buffer to be filled and emptied at the same time; and
”h]”hì)”}”(hŒ†use a single lock to govern access to both ends of the buffer, thus
allowing the buffer to be filled and emptied at the same time; and”h]”hŒ†use a single lock to govern access to both ends of the buffer, thus
allowing the buffer to be filled and emptied at the same time; and”…””}”(hj[  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KŒhjW  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjT  ubj  )”}”(hŒuse atomic counter operations.
”h]”hì)”}”(hŒuse atomic counter operations.”h]”hŒuse atomic counter operations.”…””}”(hjs  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Khjo  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j~  hjT  ubeh}”(h]”h ]”h"]”h$]”h&]”j¶  j·  j¸  j¹  jº  j»  uh1jy  hjP  ubah}”(h]”h ]”h"]”h$]”h&]”uh1js  h³hÊh´KŒhj1  h²hubhì)”}”(hX  There are two sides to this: the producer that fills the buffer, and the
consumer that empties it.  Only one thing should be filling a buffer at any one
time, and only one thing should be emptying a buffer at any one time, but the
two sides can operate simultaneously.”h]”hX  There are two sides to this: the producer that fills the buffer, and the
consumer that empties it.  Only one thing should be filling a buffer at any one
time, and only one thing should be emptying a buffer at any one time, but the
two sides can operate simultaneously.”…””}”(hj“  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K‘hj1  h²hubh¶)”}”(hhh]”(h»)”}”(hŒThe producer”h]”hŒThe producer”…””}”(hj¤  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhj¡  h²hh³hÊh´K˜ubhì)”}”(hŒ,The producer will look something like this::”h]”hŒ+The producer will look something like this:”…””}”(hj²  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´Kšhj¡  h²hubj¤  )”}”(hX_  spin_lock(&producer_lock);

unsigned long head = buffer->head;
/* The spin_unlock() and next spin_lock() provide needed ordering. */
unsigned long tail = READ_ONCE(buffer->tail);

if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
        /* insert one item into the buffer */
        struct item *item = buffer[head];

        produce_item(item);

        smp_store_release(buffer->head,
                          (head + 1) & (buffer->size - 1));

        /* wake_up() will make sure that the head is committed before
         * waking anyone up */
        wake_up(consumer);
}

spin_unlock(&producer_lock);”h]”hX_  spin_lock(&producer_lock);

unsigned long head = buffer->head;
/* The spin_unlock() and next spin_lock() provide needed ordering. */
unsigned long tail = READ_ONCE(buffer->tail);

if (CIRC_SPACE(head, tail, buffer->size) >= 1) {
        /* insert one item into the buffer */
        struct item *item = buffer[head];

        produce_item(item);

        smp_store_release(buffer->head,
                          (head + 1) & (buffer->size - 1));

        /* wake_up() will make sure that the head is committed before
         * waking anyone up */
        wake_up(consumer);
}

spin_unlock(&producer_lock);”…””}”hjÀ  sbah}”(h]”h ]”h"]”h$]”h&]”jà  já  uh1j£  h³hÊh´Kœhj¡  h²hubhì)”}”(hŒêThis will instruct the CPU that the contents of the new item must be written
before the head index makes it available to the consumer and then instructs the
CPU that the revised head index must be written before the consumer is woken.”h]”hŒêThis will instruct the CPU that the contents of the new item must be written
before the head index makes it available to the consumer and then instructs the
CPU that the revised head index must be written before the consumer is woken.”…””}”(hjÎ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K²hj¡  h²hubhì)”}”(hXP  Note that wake_up() does not guarantee any sort of barrier unless something
is actually awakened.  We therefore cannot rely on it for ordering.  However,
there is always one element of the array left empty.  Therefore, the
producer must produce two elements before it could possibly corrupt the
element currently being read by the consumer.  Therefore, the unlock-lock
pair between consecutive invocations of the consumer provides the necessary
ordering between the read of the index indicating that the consumer has
vacated a given element and the write by the producer to that same element.”h]”hXP  Note that wake_up() does not guarantee any sort of barrier unless something
is actually awakened.  We therefore cannot rely on it for ordering.  However,
there is always one element of the array left empty.  Therefore, the
producer must produce two elements before it could possibly corrupt the
element currently being read by the consumer.  Therefore, the unlock-lock
pair between consecutive invocations of the consumer provides the necessary
ordering between the read of the index indicating that the consumer has
vacated a given element and the write by the producer to that same element.”…””}”(hjÜ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´K¶hj¡  h²hubeh}”(h]”Œthe-producer”ah ]”h"]”Œthe producer”ah$]”h&]”uh1hµhj1  h²hh³hÊh´K˜ubh¶)”}”(hhh]”(h»)”}”(hŒThe Consumer”h]”hŒThe Consumer”…””}”(hjõ  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjò  h²hh³hÊh´KÁubhì)”}”(hŒ,The consumer will look something like this::”h]”hŒ+The consumer will look something like this:”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KÃhjò  h²hubj¤  )”}”(hX  spin_lock(&consumer_lock);

/* Read index before reading contents at that index. */
unsigned long head = smp_load_acquire(buffer->head);
unsigned long tail = buffer->tail;

if (CIRC_CNT(head, tail, buffer->size) >= 1) {

        /* extract one item from the buffer */
        struct item *item = buffer[tail];

        consume_item(item);

        /* Finish reading descriptor before incrementing tail. */
        smp_store_release(buffer->tail,
                          (tail + 1) & (buffer->size - 1));
}

spin_unlock(&consumer_lock);”h]”hX  spin_lock(&consumer_lock);

/* Read index before reading contents at that index. */
unsigned long head = smp_load_acquire(buffer->head);
unsigned long tail = buffer->tail;

if (CIRC_CNT(head, tail, buffer->size) >= 1) {

        /* extract one item from the buffer */
        struct item *item = buffer[tail];

        consume_item(item);

        /* Finish reading descriptor before incrementing tail. */
        smp_store_release(buffer->tail,
                          (tail + 1) & (buffer->size - 1));
}

spin_unlock(&consumer_lock);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jà  já  uh1j£  h³hÊh´KÅhjò  h²hubhì)”}”(hŒàThis will instruct the CPU to make sure the index is up to date before reading
the new item, and then it shall make sure the CPU has finished reading the item
before it writes the new tail pointer, which will erase the item.”h]”hŒàThis will instruct the CPU to make sure the index is up to date before reading
the new item, and then it shall make sure the CPU has finished reading the item
before it writes the new tail pointer, which will erase the item.”…””}”(hj  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KÙhjò  h²hubhì)”}”(hXu  Note the use of READ_ONCE() and smp_load_acquire() to read the
opposition index.  This prevents the compiler from discarding and
reloading its cached value.  This isn't strictly needed if you can
be sure that the opposition index will _only_ be used the once.
The smp_load_acquire() additionally forces the CPU to order against
subsequent memory references.  Similarly, smp_store_release() is used
in both algorithms to write the thread's index.  This documents the
fact that we are writing to something that can be read concurrently,
prevents the compiler from tearing the store, and enforces ordering
against previous accesses.”h]”hXy  Note the use of READ_ONCE() and smp_load_acquire() to read the
opposition index.  This prevents the compiler from discarding and
reloading its cached value.  This isnâ€™t strictly needed if you can
be sure that the opposition index will _only_ be used the once.
The smp_load_acquire() additionally forces the CPU to order against
subsequent memory references.  Similarly, smp_store_release() is used
in both algorithms to write the threadâ€™s index.  This documents the
fact that we are writing to something that can be read concurrently,
prevents the compiler from tearing the store, and enforces ordering
against previous accesses.”…””}”(hj-  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KÝhjò  h²hubeh}”(h]”Œthe-consumer”ah ]”h"]”Œthe consumer”ah$]”h&]”uh1hµhj1  h²hh³hÊh´KÁubeh}”(h]”Œ+using-memory-barriers-with-circular-buffers”ah ]”h"]”Œ+using memory barriers with circular buffers”ah$]”h&]”uh1hµhh·h²hh³hÊh´K‡ubh¶)”}”(hhh]”(h»)”}”(hŒFurther reading”h]”hŒFurther reading”…””}”(hjN  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hºhjK  h²hh³hÊh´Kêubhì)”}”(hŒbSee also Documentation/memory-barriers.txt for a description of Linux's memory
barrier facilities.”h]”hŒdSee also Documentation/memory-barriers.txt for a description of Linuxâ€™s memory
barrier facilities.”…””}”(hj\  h²hh³Nh´Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hëh³hÊh´KìhjK  h²hubeh}”(h]”Œfurther-reading”ah ]”h"]”Œfurther reading”ah$]”h&]”uh1hµhh·h²hh³hÊh´Kêubeh}”(h]”Œcircular-buffers”ah ]”h"]”Œcircular buffers”ah$]”h&]”uh1hµhhh²hh³hÊh´Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”hÊuh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(hºNŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”hÊŒ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jw  jt  js  jp  j.  j+  jH  jE  jï  jì  j@  j=  jo  jl  uŒ	nametypes”}”(jw  ‰js  ‰j.  ‰jH  ‰jï  ‰j@  ‰jo  ‰uh}”(jt  h·jp  jâ  j+  jv  jE  j1  jì  j¡  j=  jò  jl  jK  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nh²hub.