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-E3DD768F-752F-5414-9E9A-86E046806903" xml:lang="en"><title>Space

    13 management and granularity</title><shortdesc>Explains how to manage space and granularity in dynamic buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <p>As the buffer expands, extra space must be allocated. As it contracts,

    15 space may be released. In order to tune the management of space, a <i>granularity</i> is

    16 specified to the buffer’s constructor. Space is always allocated and freed

    17 in multiples of this granularity.</p>

    18 <p>The granularity should be carefully chosen. Too small a value will result

    19 in too many re-allocations with a cost in time and, due to fragmentation and

    20 segmentation overheads, some waste of space also. Too large a value will result

    21 in over-allocation of space: the extent of the waste of space depends on the

    22 type of data in the buffer: decisions must be made on a case-by-case basis.</p>

    23 <p>For flat buffers, the buffer’s single alloc cell is guaranteed to be a

    24 multiple of the granularity in length. When the buffer must be extended, just

    25 sufficient space is allocated to cover the immediate space need (rounded up,

    26 if necessary, to the nearest multiple of the granularity). When data is deleted,

    27 no automatic space reclamation is performed. The <codeph>Compress()</codeph> function

    28 may be used to compress the allocation to the smallest possible multiple of

    29 the granularity necessary for the data currently held in the buffer.</p>

    30 <p>For segmented buffers, the granularity is the number of data bytes in each

    31 segment. Segments additionally have a 16-byte overhead. Therefore, the granularity

    32 of segmented buffers should always be considerably greater than 16, to avoid

    33 significant space waste. When a segmented buffer is extended, enough extra

    34 segments are allocated to contain all the data. When data is deleted from

    35 a segmented buffer, segments are deleted if they contain no data. Segments

    36 whose content is partially deleted may be amalgamated with neighbouring segments,

    37 but usually they are left partially full. If the pattern of insertions and

    38 deletions into a segmented buffer is arbitrary, nothing can be said about

    39 the extent of <i>data</i> in each segment: it may range from a single byte

    40 up to the entire segment length — which is the granularity of the buffer.

    41 The <codeph>Compress()</codeph> function may be used with segmented buffers

    42 to cause a more efficient allocation of space to its segments.</p>

    43 </conbody></concept>