Reclamation and compaction, incrementally

diff -r 4816d766a08a -r f345bda72bc4 Symbian3/PDK/Source/GUID-34E19A27-F61D-5190-8709-151523CB0BE1.dita --- a/Symbian3/PDK/Source/GUID-34E19A27-F61D-5190-8709-151523CB0BE1.dita Tue Mar 30 11:42:04 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-34E19A27-F61D-5190-8709-151523CB0BE1.dita Tue Mar 30 11:56:28 2010 +0100 @@ -1,12 +1,48 @@ - - - - - -Reclamation and compaction, incrementally

Both space reclamation and compaction can be done incrementally, i.e. broken down into smaller steps. This allows an application to alternate reclamation and compaction with other processing and remain responsive to other events.

To do this, construct an object of type RStoreReclaim and call:

RStoreReclaim::OpenL() or RStoreReclaim::OpenLC() to prepare the RStoreReclaim object to perform space reclamation.
RStoreReclaim::CompactL() or RStoreReclaim::CompactLC() to prepare the RStoreReclaim object to perform compaction.

Each stage of space reclamation and compaction is performed or initiated by calling the appropriate variant of RStoreReclaim::Next() or RStoreReclaim::NextL(). The class provides both synchronous and asynchronous variants of these two functions. The asynchronous versions initiate the next stage of space reclamation and compaction.

At any time during space reclamation or compaction, the RStoreReclaim::Available() returns a running total of free space discovered so far.

Compaction and normal access to the store interact in the following ways:

if a compaction step is in progress, committing the store causes the compaction step to be abandoned and to complete or leave with KErrNotReady. All subsequent attempts to initiate a compaction step, complete or leave with KErrNotReady. Compaction can be restarted by first doing a reset, i.e. by calling ResetL().
a compaction step which needs to physically move a stream, completes or leaves with KErrInUse, if any stream within the store is open. The stream must be closed before initiating another compaction step.

Once compaction is complete, the store must be committed.

Doing an incremental space reclamation or compaction asynchronously requires the use of active objects.