<?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>
</conbody></concept>