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

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

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

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

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

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

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

<concept id="GUID-E3DD768F-752F-5414-9E9A-86E046806903" xml:lang="en"><title>Space

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

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

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

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

in multiples of this granularity.</p>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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