<?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 task
  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-F0891698-F714-55AA-A089-790BB0B07AE4" xml:lang="en"><title> Allocation
Tutorial</title><shortdesc>This tutorial describes how to allocate MBufs (for data source
components in the Data Plane). </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<context><p>The <xref href="GUID-F024208C-ED19-3301-85C1-53F397C9910F.dita#GUID-F024208C-ED19-3301-85C1-53F397C9910F/GUID-691909D5-39E1-366C-9951-4D7C21AAF0EE"><apiname>RMBufChain::Alloc()</apiname></xref> function allocates
the specified amount of memory as a chain of one or several <xref href="GUID-E0ADB108-D3B2-3670-907D-2AE595BECE3F.dita"><apiname>RMBuf</apiname></xref> objects
from the Comms pond. If the pond cannot provide the memory area as a single
buffer, the chain contains as many <codeph>RMBuf</codeph> s linked together
as necessary to fulfil the allocation request. </p> </context>
<steps id="GUID-E1D71A3A-4FB3-5BBA-843C-6BA687E7D82A">
<step id="GUID-1E1B4EAB-D562-54D0-ADD8-0A33AF03DC1A"><cmd>Create an instance
of <xref href="GUID-F024208C-ED19-3301-85C1-53F397C9910F.dita"><apiname>RMBufChain</apiname></xref>. </cmd>
</step>
<step id="GUID-3587DC5B-F80B-5BE5-B48C-F4F983839F9C"><cmd>Call <xref href="GUID-F024208C-ED19-3301-85C1-53F397C9910F.dita#GUID-F024208C-ED19-3301-85C1-53F397C9910F/GUID-691909D5-39E1-366C-9951-4D7C21AAF0EE"><apiname>RMBufChain::Alloc()</apiname></xref>.</cmd>
<info>You should use the allocation methods of the parent class (<xref href="GUID-107ADE6D-7AFF-3B07-9606-BCA33A3B63EF.dita"><apiname>RCommsBufChain</apiname></xref>):
see the<xref href="GUID-F2E86FB3-C634-5CF9-87B2-EAB18BF25C4B.dita"> TLS Look-up
Reduction Tutorial</xref>. </info>
<info>Note: some of the overloaded <codeph>Alloc()</codeph> methods specify
minimum and maximum values. See <xref href="GUID-E4D47AED-5FCA-535B-9B8B-3267A4CD01C2.dita">Allocation
Strategy</xref>. </info>
</step>
<step id="GUID-C4B0AB75-15FD-5141-B9FE-5A046E8A8F95"><cmd>Check the return
value for errors. </cmd>
<info>The <codeph>Alloc()</codeph> methods return <xref href="GUID-6CA4F1ED-7947-3087-B618-D35858FAA3BC.dita"><apiname>KErrNone</apiname></xref> if
the memory is available as <codeph>RMBuf</codeph> in the <codeph>RMBufChain</codeph>. </info>
</step>
<step id="GUID-26B5D1D0-9009-5637-83B3-94CF8F6F49B8"><cmd>Use the allocated
buffer (see <xref href="GUID-FE3825C5-BDEE-5F18-9FFD-2E794E618FEC.dita">Data Access
Example</xref>). </cmd>
</step>
</steps>
<example><title>Examples</title> <p>The following example requests 1,800 bytes
to the Comms pond. <codeph>iAllocator</codeph> is an <codeph>RMBufAllocator</codeph> member
of the class implementing this example. </p> <codeblock id="GUID-939E5930-6C8B-5E90-8159-128CA6177A2B" xml:space="preserve">
RMBufChain aChain;

TInt err = chain.Alloc(1800, iAllocator);
</codeblock> <p>The following example requests 1,200 bytes and specifies a
minimum and a maximum size of 1,600 bytes. If there are no available 1,600-byte
buffers in the pond then an error is returned. </p> <codeblock id="GUID-6C2588A5-2561-509A-BDCD-62AC3064383C" xml:space="preserve">
RMBufChain chain;

Tint err = chain.Alloc(1200, 1600, 1600, iAllocator);
</codeblock> </example>
</taskbody><related-links>
<link href="GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita"><linktext>Overview</linktext>
</link>
<link href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita"><linktext>Comms Buffers
(MBuf)                 and Comms Chains</linktext></link>
<link href="GUID-F2E86FB3-C634-5CF9-87B2-EAB18BF25C4B.dita"><linktext>TLS Look-up
Reduction                 Tutorial</linktext></link>
<link href="GUID-E4D47AED-5FCA-535B-9B8B-3267A4CD01C2.dita"><linktext>Allocation
Strategy</linktext></link>
</related-links></task>