<?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>