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-1F1A6FCD-DA06-5F8B-8F2C-0BAA08DE0041" xml:lang="en"><title>How to

    13 allocate buffers</title><shortdesc>Explains the functions to create and allocate flat and segmented

    14 buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p>Allocating buffers is simple: use the desired class’s static <codeph>NewL()</codeph> function.

    16 You must specify a <i>granularity</i>, whose meaning is particular to the

    17 buffer type.</p>

    18 <section id="GUID-35823578-F609-41ED-B4A3-00BAE20C4AAC"><title>Flat buffer</title> <p>To allocate a flat buffer, use <codeph>CFlatBuf::NewL()</codeph>.

    19 The granularity in this case means the number of bytes by which the buffer

    20 will be re-allocated, whenever expansion is necessary. If expansion by a greater

    21 amount than this is required, the next highest multiple of the granularity

    22 will be used.</p> <p>In this example, the buffer pointer is pushed to the

    23 cleanup stack for the lifetime of the buffer. If any operation involving the

    24 buffer should leave, the buffer will be destroyed. In real use, the buffer

    25 pointer would be stored as member data, and care should be taken to ensure

    26 that the consequences of a leave are not fatal to the application. For example,

    27 if the buffer is being used to store a word processor document, an attempt

    28 to add a character may fail due to lack of memory. This should never cause

    29 the entire document to be destroyed! Instead, the editing code should function

    30 in such a way that the update is either implemented successfully, or no change

    31 is made to the document.</p> <p>The function <codeph>StandardBufferStuffL()</codeph> is

    32 one which takes a <codeph>CBufBase</codeph> type.</p> <codeblock id="GUID-EF6F9CDB-0D9A-5AB8-9BBC-958DEE5C382E" xml:space="preserve"> // do flat buffer tests

    33  CBufFlat* flatBuf=CBufFlat::NewL(4);

    34  CleanupStack::PushL(flatBuf);

    35  StandardBufferStuffL(flatBuf);

    36  CleanupStack::PopAndDestroy();</codeblock> </section>

    37 <section id="GUID-0E671A5E-99A9-4ED6-9CA1-519BA5E3A8D9"><title>Segmented buffer</title> <p>A segmented buffer is allocated

    38 in a similar way to a flat buffer. The granularity in this case specifies

    39 the size of each segment. During buffer operations, each segment may contain

    40 less data than the granularity. After a compress, data is optimally distributed

    41 to segments, so that all segments except possibly the last one are full.</p> <p>During

    42 their lifetime, all standard buffer operations can be performed on either

    43 flat or segmented buffers. This is shown in the examples above by calling <codeph>standardBufferStuffL()</codeph> with

    44 both a flat and a segmented buffer pointer. The argument to this function

    45 is a <codeph>CBufBase*</codeph>.</p> <p>The granularities chosen for these

    46 examples are much smaller than would be used in most real applications. </p> <codeblock id="GUID-70676BB5-F806-5860-A96D-77EF0897FFA7" xml:space="preserve"> // do segmented buffer tests

    47  CBufSeg* segBuf=CBufSeg::NewL(4);

    48  CleanupStack::PushL(segBuf);

    49  standardBufferStuffL(segBuf);

    50  CleanupStack::PopAndDestroy();</codeblock> </section>

    51 </conbody><related-links>

    52 <link>

    53 <desc><xref href="GUID-E3DD768F-752F-5414-9E9A-86E046806903.dita">Space management

    54 and granularity</xref></desc>

    55 </link>

    56 </related-links></concept>