Symbian3/SDK/Source/GUID-55E4D84B-1B90-5BA4-9CE0-6D26EA208F13.dita
changeset 8 ae94777fff8f
parent 7 51a74ef9ed63
child 13 48780e181b38
equal deleted inserted replaced
7:51a74ef9ed63 8:ae94777fff8f
     9 -->
     9 -->
    10 <!DOCTYPE concept
    10 <!DOCTYPE concept
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
    12 <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>
    12 <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>
    13                   Comms buffer 
    13                   Comms buffer 
    14                 </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>
    14                 </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>
    15                   Pond contents 
    15                   Pond contents 
    16                 </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)
    16                 </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)
    17                 and Comms Chains</linktext> </link> <link href="GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita"><linktext>Advanced Pond
    17                 and Comms Chains</linktext> </link> <link href="GUID-A467E933-C4B4-5518-96D6-471E44B216B3.dita"><linktext>Advanced Pond
    18                 Guide</linktext> </link> </related-links></concept>
    18                 Guide</linktext> </link> </related-links></concept>