Class RStoreReclaim

class RStoreReclaim;

Description

Performs space reclamation or compaction on a permanent file store in incremental steps.

Reclaiming unused space makes it available for re-use by the store. Compacting makes unused space available for re-use by the relevant system pool — for example, the filing system in the case of file-based stores.

Once compaction is complete, the store must be committed.

Notes:

Space reclamation and compaction are only supported by the file store CPermanentFileStore and are not supported by embedded or direct file stores.

Use active objects when implementing space reclamation or compaction asynchronously.

This class performs incremental compaction/reclamation. These operations can be performed in a possibly long running single step using CStreamStore functions.

Members

Defined in RStoreReclaim:

• Available()constReturns the amount of free space currently available within the store. The funct...
• Close()Stops space reclamation or compaction. All allocated resources are freed.
• CompactL(CStreamStore &,TInt &)Prepares the object to perform compaction.
• CompactLC(CStreamStore &,TInt &)Prepares the object to perform compaction, putting a cleanup item onto the clean...
• Next(TInt &)Performs the next space reclamation or compaction step synchronous, non-leaving....
• Next(TPckgBuf< TInt > &,TRequestStatus &)Initiates the next space reclamation or compaction step asynchronous, non-leavin...
• NextL(TInt &)Performs the next space reclamation or compaction step synchronous, leaves. The ...
• NextL(TPckgBuf< TInt > &,TRequestStatus &)Initiates the next space reclamation or compaction step asynchronous, leaving. T...
• OpenL(CStreamStore &,TInt &)Prepares the object to perform space reclamation.
• OpenLC(CStreamStore &,TInt &)Prepares the object to perform space reclamation and puts a pointer onto the cle...
• RStoreReclaim()
• Release()Releases allocated resources. Any space reclamation or compaction in progress is...
• ResetL(TInt &)Restarts space reclamation or compaction.

inline RStoreReclaim();

Description

IMPORT_C void OpenL(CStreamStore &aStore, TInt &aCount);

Description

Prepares the object to perform space reclamation.

Parameters

IMPORT_C void OpenLC(CStreamStore &aStore, TInt &aCount);

Description

Prepares the object to perform space reclamation and puts a pointer onto the cleanup stack.

Placing a cleanup item for the object onto the cleanup stack allows allocated resources to be cleaned up if a subsequent leave occurs.

Parameters

IMPORT_C void CompactL(CStreamStore &aStore, TInt &aCount);

Description

Prepares the object to perform compaction.

Streams must be closed before calling this function.

Parameters

IMPORT_C void CompactLC(CStreamStore &aStore, TInt &aCount);

Description

Prepares the object to perform compaction, putting a cleanup item onto the cleanup stack.

P lacing a cleanup item for the object onto the cleanup stack allows allocated resources to be cleaned up if a subsequent leave occurs.

Streams must be closed before calling this function.

Parameters

inline void Close();

Description

Stops space reclamation or compaction. All allocated resources are freed.

Notes:

If a cleanup item was placed on the cleanup stack when the RStoreReclaim object was prepared for space reclamation or compaction (i.e. by a call to RStoreReclaim::OpenLC(CStreamStore &,TInt &) or RStoreReclaim::CompactLC(CStreamStore &,TInt &)), then this function need not be called explicitly; clean up is implicitly done by CleanupStack::PopAndDestroy().

The RStoreReclaim::ResetL(TInt &) member function can be used to restart abandoned space reclamation or compaction activity.

IMPORT_C void Release();

Description

Releases allocated resources. Any space reclamation or compaction in progress is abandoned.

Notes:

If a cleanup item was placed on the cleanup stack when the RStoreReclaim object was prepared for space reclamation or compaction (i.e. by a call to RStoreReclaim::OpenLC(CStreamStore &,TInt &) or RStoreReclaim::CompactLC(CStreamStore &,TInt &)), then this function need not be called explicitly; clean up is implicitly done by CleanupStack::PopAndDestroy().

The RStoreReclaim::ResetL(TInt &) member function can be used to restart abandoned space reclamation or compaction activity.

IMPORT_C void ResetL(TInt &aCount);

Description

Restarts space reclamation or compaction.

The value in aCount must be:

that which was set by the most recent call to RStoreReclaim::Next(TPckgBuf< TInt > &,TRequestStatus &) or RStoreReclaim::NextL(TInt &), if space reclamation or compaction had been started.

that which was set by RStoreReclaim::OpenL(CStreamStore &,TInt &), RStoreReclaim::OpenLC(CStreamStore &,TInt &), RStoreReclaim::CompactL(CStreamStore &,TInt &) or RStoreReclaim::CompactLC(CStreamStore &,TInt &), if space reclamation or compaction had not been started.

Parameters

IMPORT_C void NextL(TInt &aStep);

Description

Performs the next space reclamation or compaction step synchronous, leaves. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step is performed synchronously, i.e. the function does not return until the step is complete.

Parameters

IMPORT_C void Next(TPckgBuf< TInt > &aStep, TRequestStatus &aStatus);

Description

Initiates the next space reclamation or compaction step asynchronous, non-leaving. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step itself is performed asynchronously.

Note:

The RStoreReclaim object should be made part of an active object to simplify the handling of the step completion event.

Parameters

IMPORT_C void NextL(TPckgBuf< TInt > &aStep, TRequestStatus &aStatus);

Description

Initiates the next space reclamation or compaction step asynchronous, leaving. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step itself is performed asynchronously.

Note:

The RStoreReclaim object should be made part of an active object to simplify the handling of the step completion event.

Parameters

IMPORT_C TInt Next(TInt &aStep);

Description

Performs the next space reclamation or compaction step synchronous, non-leaving. The function updates the value in aStep, and should only be called while aStep is non-zero. Once this value is zero, no further calls should be made.

The step is performed synchronously, i.e. the function does not return until the step is complete.

Parameters

Return value

inline TInt Available() const;

Description

Returns the amount of free space currently available within the store. The function may be called at any time during space reclamation or compaction.

Return value