1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-5127C80E-EACE-5524-9A75-A0EFB41C2226" xml:lang="en"><title>Circular

    13 Buffer structure</title><shortdesc>This document describes the structure of circular buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>"Circular Buffers" is a sub-API of the "Buffers and strings" API.</p>

    15 <p>A circular buffer provides a simple way of implementing a fixed length

    16 queue of fixed size objects where objects are added to the head of the queue

    17 while items are removed from the tail of the queue.</p>

    18 <p>Logically, the buffer is circular with no defined start or end. Objects

    19 are always added to the buffer head and are always removed from the buffer

    20 tail. The buffer head is always the next vacant slot into which an object

    21 is added. The buffer tail is always the slot from which the next object is

    22 removed. The tail always logically follows the head and the implementation

    23 ensures that the tail never overtakes the head.</p>

    24 <fig id="GUID-18737BF9-5382-5431-8B3E-68C7CCD3DF86">

    25 <image href="GUID-F057FFF8-EA6A-5719-BE6B-B37950A07A7B_d0e223645_href.png" placement="inline"/>

    26 </fig>

    27 <p>Physically, the buffer is a contiguous block of memory. The implementation

    28 provides the appearance of circularity.</p>

    29 <p>A circular buffer has a maximum capacity which must be set before the circular

    30 buffer can be used. The maximum capacity can be changed at any time but any

    31 existing data within the buffer is lost.</p>

    32 <p>The sub-API consists of three classes, two of which can be instantiated:</p>

    33 <ul>

    34 <li id="GUID-42FC2894-0995-578C-AE0D-0670CC63B242"><p>the templated class <codeph>CCirBuf&lt;class

    35 T&gt;</codeph> builds a circular buffer of general objects.</p> </li>

    36 <li id="GUID-C98B7B84-67D4-5616-A042-CFF16B26422F"><p>the <codeph>CCirBuffer</codeph> class

    37 builds a circular buffer of unsigned integers with values ranging from -128

    38 to +128.</p> </li>

    39 </ul>

    40 </conbody></concept>