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 xml:lang="en" id="GUID-36718217-C9F7-5ACF-8DE7-7D83FBF435DB"><title>Store map cleanup support</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>The destructor of a <codeph>CStoreMap</codeph> object calls the <codeph>ResetAndDestroy()</codeph> member function. This function deletes from the store all streams whose stream IDs are currently held by the store map.</p> <p>This is of most use:</p> <ul><li id="GUID-1978575F-24D5-5B3A-8FED-5A067ACF5691"><p>in stores which do not support commit and revert, for example, the non-persistent in-memory store <codeph>CBufStore</codeph>.</p> </li> <li id="GUID-C8FBA74B-939B-576B-9443-D55AD9B798EC"><p>where the streams, whose IDs are in the store map, do not contain pointers to other streams.</p> </li> </ul> <p>This behaviour allows a partially complete set of streams to be deleted if a leave occurs part of the way through the building of the set.</p> <p>Note that this behaviour cannot be exploited by stores which do not support the deletion of streams, for example, the direct file store <codeph>CDirectFileStore</codeph>.</p> <p>Stores such as the permanent file store, <codeph>CPermanentFileStore</codeph>, can also use commit and revert to implement this kind of behaviour.</p> <p>Given the example class, <codeph>CCompound</codeph>, defined as:</p> <codeblock id="GUID-84E229C8-624C-5024-B25B-DB5957580775" xml:space="preserve">class CCompound : public CBase |
12 <concept id="GUID-36718217-C9F7-5ACF-8DE7-7D83FBF435DB" xml:lang="en"><title>Store |
|
13 map cleanup support</title><shortdesc>This document describes store map cleanup support.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The destructor of a <codeph>CStoreMap</codeph> object calls the <codeph>ResetAndDestroy()</codeph> member |
|
15 function. This function deletes from the store all streams whose stream IDs |
|
16 are currently held by the store map.</p> |
|
17 <p>This is of most use:</p> |
|
18 <ul> |
|
19 <li id="GUID-1978575F-24D5-5B3A-8FED-5A067ACF5691"><p>in stores which do not |
|
20 support commit and revert, for example, the non-persistent in-memory store <codeph>CBufStore</codeph>.</p> </li> |
|
21 <li id="GUID-C8FBA74B-939B-576B-9443-D55AD9B798EC"><p>where the streams, whose |
|
22 IDs are in the store map, do not contain pointers to other streams.</p> </li> |
|
23 </ul> |
|
24 <p>This behaviour allows a partially complete set of streams to be deleted |
|
25 if a leave occurs part of the way through the building of the set.</p> |
|
26 <p>Note that this behaviour cannot be exploited by stores which do not support |
|
27 the deletion of streams, for example, the direct file store <codeph>CDirectFileStore</codeph>.</p> |
|
28 <p>Stores such as the permanent file store, <codeph>CPermanentFileStore</codeph>, |
|
29 can also use commit and revert to implement this kind of behaviour.</p> |
|
30 <p>Given the example class, <codeph>CCompound</codeph>, defined as:</p> |
|
31 <codeblock id="GUID-84E229C8-624C-5024-B25B-DB5957580775" xml:space="preserve">class CCompound : public CBase |
13 { |
32 { |
14 ... |
33 ... |
15 TSwizzle<CClassA> iA; |
34 TSwizzle<CClassA> iA; |
16 TSwizzle<CClassB> iB; |
35 TSwizzle<CClassB> iB; |
17 TSwizzle<CClassC> iC; |
36 TSwizzle<CClassC> iC; |
18 ... |
37 ... |
19 }</codeblock> <p>the <codeph>CCompound</codeph> object is stored using its <codeph>StoreL()</codeph> function and the individual components are externalised by the <codeph>StoreComponentsL()</codeph> function:</p> <codeblock id="GUID-10BD78DC-C674-5C28-BECE-685A51324956" xml:space="preserve">TStreamId CCompound::StoreL(CStreamStore& aStore) |
38 }</codeblock> |
|
39 <p>the <codeph>CCompound</codeph> object is stored using its <codeph>StoreL()</codeph> function |
|
40 and the individual components are externalised by the <codeph>StoreComponentsL()</codeph> function:</p> |
|
41 <codeblock id="GUID-10BD78DC-C674-5C28-BECE-685A51324956" xml:space="preserve">TStreamId CCompound::StoreL(CStreamStore& aStore) |
20 { |
42 { |
21 CStoreMap* map=CStoreMap::NewLC(aStore); |
43 CStoreMap* map=CStoreMap::NewLC(aStore); |
22 StoreComponentsL(*map); |
44 StoreComponentsL(*map); |
23 RStoreWriteStream stream(*map); |
45 RStoreWriteStream stream(*map); |
24 TStreamId id=stream.CreateLC(aStore); |
46 TStreamId id=stream.CreateLC(aStore); |
25 ExternalizeL(stream); |
47 ExternalizeL(stream); |
26 stream.CommitL(); |
48 stream.CommitL(); |
27 map->Reset(); |
49 map->Reset(); |
28 CleanupStack::PopAndDestroy(2); |
50 CleanupStack::PopAndDestroy(2); |
29 return id; |
51 return id; |
30 }</codeblock> <codeblock id="GUID-8D249B61-5858-500D-A1A2-4C17FF9D0D63" xml:space="preserve">void CCompound::StoreComponentsL(CStoreMap& aMap) const |
52 }</codeblock> |
|
53 <codeblock id="GUID-8D249B61-5858-500D-A1A2-4C17FF9D0D63" xml:space="preserve">void CCompound::StoreComponentsL(CStoreMap& aMap) const |
31 { |
54 { |
32 TStreamId id; |
55 TStreamId id; |
33 ... |
56 ... |
34 id = iA->StoreL(iStore); |
57 id = iA->StoreL(iStore); |
35 aMap.BindL(iA,id); |
58 aMap.BindL(iA,id); |
38 aMap.BindL(iB,id); |
61 aMap.BindL(iB,id); |
39 ... |
62 ... |
40 id = iC->StoreL(iStore); |
63 id = iC->StoreL(iStore); |
41 aMap.BindL(iC,id); |
64 aMap.BindL(iC,id); |
42 ... |
65 ... |
43 }</codeblock> <p>Once the store map has been created, a cleanup item for it is placed onto the cleanupstack. This means that if, for example, the call to either:</p> <codeblock id="GUID-14BA383C-B2C5-5881-97E8-FD1196B8A459" xml:space="preserve">id = iC->StoreL(iStore);</codeblock> <p>or</p> <codeblock id="GUID-CFE924DF-2131-51D5-A3B6-DAC756B996CA" xml:space="preserve">aMap.BindL(iC,id);</codeblock> <p>were to fail, then the streams containing the <codeph>CClassA</codeph> and <codeph>CClassB</codeph> objects would be deleted from the store as part of the subsequent destruction of the store map.</p> <p>Once all three components have been successfully externalised and the <codeph>CCompound</codeph>'s other data has also been externalised to its own stream, and no further failure modes are possible, then the store map can be and must be reset, by calling its <codeph>Reset()</codeph> function.</p> <section><title>See also</title> <p><xref href="GUID-C9D8D913-C65F-5A69-A606-30F59BFB38E2.dita">File stores</xref> </p> <p><xref href="GUID-6EE0CB66-A759-5E0C-884D-90895F35F267.dita">Transactions</xref> </p> </section> </conbody></concept> |
66 }</codeblock> |
|
67 <p>Once the store map has been created, a cleanup item for it is placed onto |
|
68 the cleanupstack. This means that if, for example, the call to either:</p> |
|
69 <codeblock id="GUID-14BA383C-B2C5-5881-97E8-FD1196B8A459" xml:space="preserve">id = iC->StoreL(iStore);</codeblock> |
|
70 <p>or</p> |
|
71 <codeblock id="GUID-CFE924DF-2131-51D5-A3B6-DAC756B996CA" xml:space="preserve">aMap.BindL(iC,id);</codeblock> |
|
72 <p>were to fail, then the streams containing the <codeph>CClassA</codeph> and <codeph>CClassB</codeph> objects |
|
73 would be deleted from the store as part of the subsequent destruction of the |
|
74 store map.</p> |
|
75 <p>Once all three components have been successfully externalised and the <codeph>CCompound</codeph>'s |
|
76 other data has also been externalised to its own stream, and no further failure |
|
77 modes are possible, then the store map can be and must be reset, by calling |
|
78 its <codeph>Reset()</codeph> function.</p> |
|
79 <section id="GUID-ECDB6AB8-52D0-461F-A3AB-0DA42BEB26B3"><title>See also</title> <p><xref href="GUID-C9D8D913-C65F-5A69-A606-30F59BFB38E2.dita">File |
|
80 stores</xref> </p> <p><xref href="GUID-6EE0CB66-A759-5E0C-884D-90895F35F267.dita">Transactions</xref> </p> </section> |
|
81 </conbody></concept> |