7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
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 id="GUID-1F1A6FCD-DA06-5F8B-8F2C-0BAA08DE0041" xml:lang="en"><title>How to |
12 <concept id="GUID-1F1A6FCD-DA06-5F8B-8F2C-0BAA08DE0041" xml:lang="en"><title>How to allocate buffers</title><shortdesc>Explains the functions to create and allocate flat and |
13 allocate buffers</title><shortdesc>Explains the functions to create and allocate flat and segmented |
13 segmented buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 buffers.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
14 <p>Allocating buffers is simple: use the desired class’s static <codeph>NewL()</codeph> function. You must specify a <i>granularity</i>, |
15 <p>Allocating buffers is simple: use the desired class’s static <codeph>NewL()</codeph> function. |
15 whose meaning is particular to the buffer type.</p> |
16 You must specify a <i>granularity</i>, whose meaning is particular to the |
16 <section id="GUID-35823578-F609-41ED-B4A3-00BAE20C4AAC"><title>Flat |
17 buffer type.</p> |
17 buffer</title> <p>To allocate a flat buffer, use <codeph>CFlatBuf::NewL()</codeph>. The granularity in this case means the number of bytes by which |
18 <section id="GUID-35823578-F609-41ED-B4A3-00BAE20C4AAC"><title>Flat buffer</title> <p>To allocate a flat buffer, use <codeph>CFlatBuf::NewL()</codeph>. |
18 the buffer will be re-allocated, whenever expansion is necessary. |
19 The granularity in this case means the number of bytes by which the buffer |
19 If expansion by a greater amount than this is required, the next highest |
20 will be re-allocated, whenever expansion is necessary. If expansion by a greater |
20 multiple of the granularity will be used.</p> <p>In this example, |
21 amount than this is required, the next highest multiple of the granularity |
21 the buffer pointer is pushed to the cleanup stack for the lifetime |
22 will be used.</p> <p>In this example, the buffer pointer is pushed to the |
22 of the buffer. If any operation involving the buffer should leave, |
23 cleanup stack for the lifetime of the buffer. If any operation involving the |
23 the buffer will be destroyed. In real use, the buffer pointer would |
24 buffer should leave, the buffer will be destroyed. In real use, the buffer |
24 be stored as member data, and care should be taken to ensure that |
25 pointer would be stored as member data, and care should be taken to ensure |
25 the consequences of a leave are not fatal to the application. For |
26 that the consequences of a leave are not fatal to the application. For example, |
26 example, if the buffer is being used to store a word processor document, |
27 if the buffer is being used to store a word processor document, an attempt |
27 an attempt to add a character may fail due to lack of memory. This |
28 to add a character may fail due to lack of memory. This should never cause |
28 should never cause the entire document to be destroyed! Instead, the |
29 the entire document to be destroyed! Instead, the editing code should function |
29 editing code should function in such a way that the update is either |
30 in such a way that the update is either implemented successfully, or no change |
30 implemented successfully, or no change is made to the document.</p> <p>The function <codeph>StandardBufferStuffL()</codeph> is one which |
31 is made to the document.</p> <p>The function <codeph>StandardBufferStuffL()</codeph> is |
31 takes a <codeph>CBufBase</codeph> type.</p> <codeblock id="GUID-EF6F9CDB-0D9A-5AB8-9BBC-958DEE5C382E" xml:space="preserve"> // do flat buffer tests |
32 one which takes a <codeph>CBufBase</codeph> type.</p> <codeblock id="GUID-EF6F9CDB-0D9A-5AB8-9BBC-958DEE5C382E" xml:space="preserve"> // do flat buffer tests |
|
33 CBufFlat* flatBuf=CBufFlat::NewL(4); |
32 CBufFlat* flatBuf=CBufFlat::NewL(4); |
34 CleanupStack::PushL(flatBuf); |
33 CleanupStack::PushL(flatBuf); |
35 StandardBufferStuffL(flatBuf); |
34 StandardBufferStuffL(flatBuf); |
36 CleanupStack::PopAndDestroy();</codeblock> </section> |
35 CleanupStack::PopAndDestroy();</codeblock> </section> |
37 <section id="GUID-0E671A5E-99A9-4ED6-9CA1-519BA5E3A8D9"><title>Segmented buffer</title> <p>A segmented buffer is allocated |
36 <section id="GUID-0E671A5E-99A9-4ED6-9CA1-519BA5E3A8D9"><title>Segmented |
38 in a similar way to a flat buffer. The granularity in this case specifies |
37 buffer</title> <p>A segmented buffer is allocated in a similar way |
39 the size of each segment. During buffer operations, each segment may contain |
38 to a flat buffer. The granularity in this case specifies the size |
40 less data than the granularity. After a compress, data is optimally distributed |
39 of each segment. During buffer operations, each segment may contain |
41 to segments, so that all segments except possibly the last one are full.</p> <p>During |
40 less data than the granularity. After a compress, data is optimally |
42 their lifetime, all standard buffer operations can be performed on either |
41 distributed to segments, so that all segments except possibly the |
43 flat or segmented buffers. This is shown in the examples above by calling <codeph>standardBufferStuffL()</codeph> with |
42 last one are full.</p> <p>During their lifetime, all standard buffer |
44 both a flat and a segmented buffer pointer. The argument to this function |
43 operations can be performed on either flat or segmented buffers. This |
45 is a <codeph>CBufBase*</codeph>.</p> <p>The granularities chosen for these |
44 is shown in the examples above by calling <codeph>standardBufferStuffL()</codeph> with both a flat and a segmented buffer pointer. The argument to |
46 examples are much smaller than would be used in most real applications. </p> <codeblock id="GUID-70676BB5-F806-5860-A96D-77EF0897FFA7" xml:space="preserve"> // do segmented buffer tests |
45 this function is a <codeph>CBufBase*</codeph>.</p> <p>The granularities |
|
46 chosen for these examples are much smaller than would be used in most |
|
47 real applications. </p> <codeblock id="GUID-70676BB5-F806-5860-A96D-77EF0897FFA7" xml:space="preserve"> // do segmented buffer tests |
47 CBufSeg* segBuf=CBufSeg::NewL(4); |
48 CBufSeg* segBuf=CBufSeg::NewL(4); |
48 CleanupStack::PushL(segBuf); |
49 CleanupStack::PushL(segBuf); |
49 standardBufferStuffL(segBuf); |
50 standardBufferStuffL(segBuf); |
50 CleanupStack::PopAndDestroy();</codeblock> </section> |
51 CleanupStack::PopAndDestroy();</codeblock> </section> |
51 </conbody><related-links> |
52 </conbody><related-links> |
52 <link> |
53 <link href="GUID-E3DD768F-752F-5414-9E9A-86E046806903.dita"> |
53 <desc><xref href="GUID-E3DD768F-752F-5414-9E9A-86E046806903.dita">Space management |
54 <linktext>Space management and granularity</linktext></link> |
54 and granularity</xref></desc> |
|
55 </link> |
|
56 </related-links></concept> |
55 </related-links></concept> |