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-596ADF23-FC69-5415-AAC6-EF565F75D0B1" xml:lang="en"><title>Choices

    13 with buffers</title><shortdesc>Explains when to use dynamic buffers and whether to select flat

    14 or segmented type of buffer.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>Dynamic buffers present two choices to potential users:</p>

    16 <ol id="GUID-9759CE0C-F6E9-50E5-BA88-CC900ADB9D97">

    17 <li id="GUID-434CA252-2933-5C7C-B122-84D7130F0FA8"><p>is it worth using dynamic

    18 buffers at all?</p> </li>

    19 <li id="GUID-A069A411-61D4-5A27-8C96-589005AA77E6"><p>if so, is it better

    20 to use flat or segmented buffers?</p> </li>

    21 </ol>

    22 <section id="GUID-1384B166-534A-4E97-8736-A5F9F7FEF44C"><title>Dynamic buffers or other storage?</title> <p>Use a more conventional

    23 scheme, such as a descriptor if:</p> <ul>

    24 <li id="GUID-CAB88D90-0052-5AC5-A92B-6889ACC4B80B"><p>the exact size of your

    25 data is known at compile time, or in any case before the data begins to be

    26 read into memory</p> </li>

    27 <li id="GUID-0B860F24-1053-5FAC-864B-EF017251E0AF"><p>the exact size is not

    28 known, but its maximum limit is known, and that limit is sufficiently small

    29 that it involves little waste</p> </li>

    30 <li id="GUID-8BCE0EAE-9BDE-5C7F-959E-1F0F1732DB6A"><p>the functions you require

    31 are provided by the descriptor classes</p> </li>

    32 </ul> <p>On the other hand, use dynamic buffers if:</p> <ul>

    33 <li id="GUID-010F488A-1D0B-5971-AFB0-A3324F0B170D"><p>the exact size of your

    34 data is not known and it’s possible that the data may grow significantly during

    35 its lifetime</p> </li>

    36 <li id="GUID-B812CBBD-924D-5B55-8F2D-26572285B30E"><p>the class you are working

    37 with requires the use of buffers — for example, the array classes derived

    38 from <codeph>CArrayFixBase</codeph>, <codeph>CArrayVarBase</codeph> and <codeph>CArrayPakBase</codeph> use

    39 buffers in their implementation.</p> </li>

    40 </ul> <p>The dynamic buffer classes are a general solution for requirements

    41 such as these. In some quite specialised cases, the particular requirements

    42 of the problem are more exacting than those met by dynamic buffers, and a

    43 specialised buffer scheme may be necessary.</p> </section>

    44 <section id="GUID-E11053B5-A588-42F7-B143-483414108CE2"><title>Flat or segmented buffers?</title> <p>If dynamic buffers are

    45 appropriate, use flat buffers if:</p> <ul>

    46 <li id="GUID-799B7113-F676-5AF2-A0A9-F3D7A0069F9B"><p>efficiency in transforming

    47 between buffer position and memory address is very important</p> </li>

    48 <li id="GUID-150BC797-DA33-58F2-A62D-6568992F1289"><p>the re-allocations needed

    49 to extend the buffer are sufficiently rare that they do not cause intolerable

    50 amounts of data copying or heap fragmentation</p> </li>

    51 <li id="GUID-1C634D8F-4566-5C21-8EB5-350C453C6AC5"><p>there is an upper bound

    52 on the size limit, and can reserve sufficient room, using <codeph>SetReserveL()</codeph> before

    53 inserting (this is typically followed by call to <codeph>InsertL()</codeph>).</p> </li>

    54 </ul> <p>On the other hand, use segmented buffers:</p> <ul>

    55 <li id="GUID-7B3DA8E1-86BD-5252-B4B4-6F6D69EADC77"><p>to minimise the heap

    56 thrashing and copying that can be associated with re-allocating a single flat

    57 buffer</p> </li>

    58 <li id="GUID-D0843F86-B168-576B-9E73-AB017DAABFFB"><p>if there is a concern

    59 about the performance of frequent insertions and deletions, which even without

    60 much heap allocation, can be better with segmented buffers as not all data

    61 after the insertion/deletion point needs to be shuffled to complete the operation.</p> </li>

    62 </ul> </section>

    63 </conbody></concept>