--- a/Symbian3/SDK/Source/GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita Wed Mar 31 11:11:55 2010 +0100
+++ b/Symbian3/SDK/Source/GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita Fri Jun 11 12:39:03 2010 +0100
@@ -1,18 +1,18 @@
-<?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 xml:lang="en" id="GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13"><title>Overview</title><shortdesc>This topic describes memory management in the Communications Framework. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Introduction</title> <p>The Communications Framework preallocates memory area buffers to increase the performance of its Data Plane. When a Comms Data Plane component needs a buffer, it asks for one from its pond. The pond contains pools of buffers : each pool contains buffers of a different size, and all the buffers in a pool have the same size. If the pond doesn't have a big enough buffer, it will string together a chain of smaller buffers to meet the request. </p> <p>The Communications Framework uses shared buffers. The Data Plane has strong performance requirements, and using shared buffers helps to avoid the memory copy that occurs between the kernel memory context and the Communications stack. </p> </section> <section id="GUID-9D1B3001-1B30-5CCE-A664-D0EEB53A4A9A"><title>Definitions</title> <dl><dlentry><dt>Comms buffer (MBuf)</dt> <dd><p>A Comms buffer, or MBuf, is a contiguous memory area used to store data on the Data Plane. It is represented by an <xref href="GUID-E0ADB108-D3B2-3670-907D-2AE595BECE3F.dita"><apiname>RMBuf</apiname></xref> object, which combines a shared buffer with metadata. See <xref href="GUID-65C49B47-6C63-536E-9B31-1FFA518A63F1.dita">Shared buffers</xref> and <xref href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita">Comms Buffers (MBuf) and Comms Chains</xref>. </p> <fig id="GUID-6BD84148-1DC7-5FAD-A150-6FE4832A9420"><title>
- Comms buffer
- </title> <image href="GUID-6262B90B-3F91-517C-B2FA-749C84CE01DE_d0e113621_href.png" placement="inline"/></fig> </dd> </dlentry> <dlentry><dt>Comms buffer chain</dt> <dd><p>A Comms buffer chain links together one or more Comms buffers. This decreases memory consumption because there is no need to reserve space for temporary large buffers, which can be created from a chain of smaller buffers. The chain is represented by a <xref href="GUID-F024208C-ED19-3301-85C1-53F397C9910F.dita"><apiname>RMBufChain</apiname></xref> object. For more information, see <xref href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita">Comms Buffers (MBuf) and Comms Chains</xref>. </p> </dd> </dlentry> <dlentry><dt>Pool</dt> <dd><p>Pre-allocated collection of shared buffers. See <xref href="GUID-65C49B47-6C63-536E-9B31-1FFA518A63F1.dita">Shared buffers</xref>. </p> <p>The buffers of a pool all have the same size. Depending on the amount of used buffers, the pool dynamically grows and shrinks by a set number of buffers, which reduces the frequency of expensive memory allocation and reduces memory usage when possible. </p> </dd> </dlentry> <dlentry><dt>Pond</dt> <dd><p>The pond is a collection of pools. It is an <codeph>RCommsBufPond</codeph> object which keeps track of the memory available in the pools and allocates all the Comms buffer chains by taking buffers from the appropriate pools. </p> <p>The memory provided by the pond is available to all the layers of the Comms Framework as well as to the drivers underneath the lower layer. Therefore, the Comms Framework components and the drivers can exchange data without additional memory copies. </p> <p>At the moment, there is only one pond in the Comms Framework. </p> <p>For more information, see <xref href="GUID-81E532DF-4702-5881-9E1B-E6537425B4E2.dita">Advanced Pond Guide</xref>. </p> <fig id="GUID-D991B970-86AC-5970-B32E-08791791CCF5"><title>
- Pond contents
- </title> <image href="GUID-536B2F20-DB19-595C-A465-25CF2E421050_d0e113685_href.png" placement="inline"/></fig> </dd> </dlentry> </dl> </section> <section id="GUID-56ED5265-463D-5C47-9F74-1939E9D9051C"><title>Typical usage</title> <p>Depending on where your component is in the Data Plane, you handle Comms buffers in a different way: </p> <ul><li id="GUID-EE357CF1-1F05-5F86-9F8B-0E39F945617D"><p>Protocol plugins manipulate the data plane flow represented by buffer chains. They obtain a buffer chain from another layer (up or down), process the chain, and send the chain to the next layer in the stack. Link layer components belong to that category. </p> <p>See <xref href="GUID-FE3825C5-BDEE-5F18-9FFD-2E794E618FEC.dita">Data Access Example</xref>. </p> </li> <li id="GUID-7047B580-A3E9-5807-BB48-9AF60BFCE2DC"><p>Data source components, either at the top or at the bottom of the Comms Framework, create buffer chains and send them through the Data Plane. Device drivers belong to that category. </p> <p>See <xref href="GUID-F0891698-F714-55AA-A089-790BB0B07AE4.dita">Allocation Tutorial</xref> and <xref href="GUID-F2E86FB3-C634-5CF9-87B2-EAB18BF25C4B.dita">TLS Look-up Reduction Tutorial</xref>. </p> </li> </ul> <p>In order to increase performance and decrease memory consumption with Comms buffers, you need to configure the pond according to your memory usage. For more information, see <xref href="GUID-81E532DF-4702-5881-9E1B-E6537425B4E2.dita">Advanced Pond Guide</xref> and <xref href="GUID-6FEE5676-8BFB-53E6-A652-7178295C342E.dita">Pond Configuration Reference</xref>. </p> <p>To monitor the pond and its available memory, see <xref href="GUID-0995EBF6-D203-57B3-9F53-972AEB8F3D3C.dita">Memory Metrics</xref>. </p> </section> </conbody><related-links><link href="GUID-65C49B47-6C63-536E-9B31-1FFA518A63F1.dita"><linktext>Shared Buffers</linktext> </link> <link href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita"><linktext>Comms Buffers (MBuf)
- and Comms Chains</linktext> </link> <link href="GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita"><linktext>Advanced Pond
+<?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 xml:lang="en" id="GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13"><title>Overview</title><shortdesc>This topic describes memory management in the Communications Framework. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Introduction</title> <p>The Communications Framework preallocates memory area buffers to increase the performance of its Data Plane. When a Comms Data Plane component needs a buffer, it asks for one from its pond. The pond contains pools of buffers : each pool contains buffers of a different size, and all the buffers in a pool have the same size. If the pond doesn't have a big enough buffer, it will string together a chain of smaller buffers to meet the request. </p> <p>The Communications Framework uses shared buffers. The Data Plane has strong performance requirements, and using shared buffers helps to avoid the memory copy that occurs between the kernel memory context and the Communications stack. </p> </section> <section id="GUID-9D1B3001-1B30-5CCE-A664-D0EEB53A4A9A"><title>Definitions</title> <dl><dlentry><dt>Comms buffer (MBuf)</dt> <dd><p>A Comms buffer, or MBuf, is a contiguous memory area used to store data on the Data Plane. It is represented by an <xref href="GUID-E0ADB108-D3B2-3670-907D-2AE595BECE3F.dita"><apiname>RMBuf</apiname></xref> object, which combines a shared buffer with metadata. See <xref href="GUID-65C49B47-6C63-536E-9B31-1FFA518A63F1.dita">Shared buffers</xref> and <xref href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita">Comms Buffers (MBuf) and Comms Chains</xref>. </p> <fig id="GUID-6BD84148-1DC7-5FAD-A150-6FE4832A9420"><title>
+ Comms buffer
+ </title> <image href="GUID-6262B90B-3F91-517C-B2FA-749C84CE01DE_d0e107083_href.png" placement="inline"/></fig> </dd> </dlentry> <dlentry><dt>Comms buffer chain</dt> <dd><p>A Comms buffer chain links together one or more Comms buffers. This decreases memory consumption because there is no need to reserve space for temporary large buffers, which can be created from a chain of smaller buffers. The chain is represented by a <xref href="GUID-F024208C-ED19-3301-85C1-53F397C9910F.dita"><apiname>RMBufChain</apiname></xref> object. For more information, see <xref href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita">Comms Buffers (MBuf) and Comms Chains</xref>. </p> </dd> </dlentry> <dlentry><dt>Pool</dt> <dd><p>Pre-allocated collection of shared buffers. See <xref href="GUID-65C49B47-6C63-536E-9B31-1FFA518A63F1.dita">Shared buffers</xref>. </p> <p>The buffers of a pool all have the same size. Depending on the amount of used buffers, the pool dynamically grows and shrinks by a set number of buffers, which reduces the frequency of expensive memory allocation and reduces memory usage when possible. </p> </dd> </dlentry> <dlentry><dt>Pond</dt> <dd><p>The pond is a collection of pools. It is an <codeph>RCommsBufPond</codeph> object which keeps track of the memory available in the pools and allocates all the Comms buffer chains by taking buffers from the appropriate pools. </p> <p>The memory provided by the pond is available to all the layers of the Comms Framework as well as to the drivers underneath the lower layer. Therefore, the Comms Framework components and the drivers can exchange data without additional memory copies. </p> <p>At the moment, there is only one pond in the Comms Framework. </p> <p>For more information, see <xref href="GUID-81E532DF-4702-5881-9E1B-E6537425B4E2.dita">Advanced Pond Guide</xref>. </p> <fig id="GUID-D991B970-86AC-5970-B32E-08791791CCF5"><title>
+ Pond contents
+ </title> <image href="GUID-536B2F20-DB19-595C-A465-25CF2E421050_d0e107147_href.png" placement="inline"/></fig> </dd> </dlentry> </dl> </section> <section id="GUID-56ED5265-463D-5C47-9F74-1939E9D9051C"><title>Typical usage</title> <p>Depending on where your component is in the Data Plane, you handle Comms buffers in a different way: </p> <ul><li id="GUID-EE357CF1-1F05-5F86-9F8B-0E39F945617D"><p>Protocol plugins manipulate the data plane flow represented by buffer chains. They obtain a buffer chain from another layer (up or down), process the chain, and send the chain to the next layer in the stack. Link layer components belong to that category. </p> <p>See <xref href="GUID-FE3825C5-BDEE-5F18-9FFD-2E794E618FEC.dita">Data Access Example</xref>. </p> </li> <li id="GUID-7047B580-A3E9-5807-BB48-9AF60BFCE2DC"><p>Data source components, either at the top or at the bottom of the Comms Framework, create buffer chains and send them through the Data Plane. Device drivers belong to that category. </p> <p>See <xref href="GUID-F0891698-F714-55AA-A089-790BB0B07AE4.dita">Allocation Tutorial</xref> and <xref href="GUID-F2E86FB3-C634-5CF9-87B2-EAB18BF25C4B.dita">TLS Look-up Reduction Tutorial</xref>. </p> </li> </ul> <p>In order to increase performance and decrease memory consumption with Comms buffers, you need to configure the pond according to your memory usage. For more information, see <xref href="GUID-81E532DF-4702-5881-9E1B-E6537425B4E2.dita">Advanced Pond Guide</xref> and <xref href="GUID-6FEE5676-8BFB-53E6-A652-7178295C342E.dita">Pond Configuration Reference</xref>. </p> <p>To monitor the pond and its available memory, see <xref href="GUID-0995EBF6-D203-57B3-9F53-972AEB8F3D3C.dita">Memory Metrics</xref>. </p> </section> </conbody><related-links><link href="GUID-65C49B47-6C63-536E-9B31-1FFA518A63F1.dita"><linktext>Shared Buffers</linktext> </link> <link href="GUID-B4F15CA3-CAD4-5A87-9610-A656CA337B72.dita"><linktext>Comms Buffers (MBuf)
+ and Comms Chains</linktext> </link> <link href="GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita"><linktext>Advanced Pond
Guide</linktext> </link> </related-links></concept>
\ No newline at end of file