Store +map cleanup support

diff -r 43e37759235e -r 51a74ef9ed63 Symbian3/SDK/Source/GUID-36718217-C9F7-5ACF-8DE7-7D83FBF435DB.dita --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/Symbian3/SDK/Source/GUID-36718217-C9F7-5ACF-8DE7-7D83FBF435DB.dita Wed Mar 31 11:11:55 2010 +0100 @@ -0,0 +1,81 @@ + + + + + +Store +map cleanup supportThis document describes store map cleanup support. +

The destructor of a CStoreMap object calls the ResetAndDestroy() member +function. This function deletes from the store all streams whose stream IDs +are currently held by the store map.

This is of most use:

in stores which do not +support commit and revert, for example, the non-persistent in-memory store CBufStore.
where the streams, whose +IDs are in the store map, do not contain pointers to other streams.

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.

Note that this behaviour cannot be exploited by stores which do not support +the deletion of streams, for example, the direct file store CDirectFileStore.

Stores such as the permanent file store, CPermanentFileStore, +can also use commit and revert to implement this kind of behaviour.

Given the example class, CCompound, defined as:

+class CCompound : public CBase + { + ... + TSwizzle<CClassA> iA; + TSwizzle<CClassB> iB; + TSwizzle<CClassC> iC; + ... + } +

the CCompound object is stored using its StoreL() function +and the individual components are externalised by the StoreComponentsL() function:

+TStreamId CCompound::StoreL(CStreamStore& aStore) + { + CStoreMap* map=CStoreMap::NewLC(aStore); + StoreComponentsL(*map); + RStoreWriteStream stream(*map); + TStreamId id=stream.CreateLC(aStore); + ExternalizeL(stream); + stream.CommitL(); + map->Reset(); + CleanupStack::PopAndDestroy(2); + return id; + } +void CCompound::StoreComponentsL(CStoreMap& aMap) const + { + TStreamId id; + ... + id = iA->StoreL(iStore); + aMap.BindL(iA,id); + ... + id = iB->StoreL(iStore); + aMap.BindL(iB,id); + ... + id = iC->StoreL(iStore); + aMap.BindL(iC,id); + ... + } +

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:

+id = iC->StoreL(iStore); +

+aMap.BindL(iC,id); +

were to fail, then the streams containing the CClassA and CClassB objects +would be deleted from the store as part of the subsequent destruction of the +store map.

Once all three components have been successfully externalised and the CCompound'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 Reset() function.