Data cleanup

Updated at:

The mPaaS Data Center module provides automatic and user-triggered cache cleanup to keep your app's storage footprint under control without blocking the main thread.

How it works

The module provides two complementary cache management mechanisms:

  • Purgeable cache directories: Time-based or size-limited directories that are automatically cleaned at each app startup. Use these for files your app can regenerate — downloaded assets, temporary processing files, or pre-fetched content.

  • User-triggered cache cleaning: An asynchronous API that runs a configured list of cleanup tasks and reports progress. Use this to implement a "Clear cache" button in your app's settings screen.

Both mechanisms operate in the background and never block the main thread.

API overview

API

Description

APPurgeablePath(path)

Returns a purgeable path with manual cleanup only

APPurgeablePathType(path, type)

Returns a purgeable path with a time-based cleanup policy

APPurgeablePathTypeSize(path, type, size)

Returns a purgeable path with a time-based policy and a size limit

ResetAllPurgeablePaths()

Clears and resets all registered purgeable directories

APUserCacheCleaner +execute:

Runs the cleanup tasks defined in PurgeableCache.plist asynchronously

Automatically cleaned cache directories

Use APPurgeablePathTypeSize (or its simpler variants) to register a sandbox directory as purgeable. At each app start, the module checks all registered directories in a background process and deletes files according to each directory's configured policy.

Cleanup types

The APPurgeableType enum controls when files in a directory are deleted:

Value

Raw value

Behavior

APPurgeableTypeManual

0

Files are deleted only when the user triggers a manual cache clean

APPurgeableTypeThreeDays

3

Files older than 3 days are automatically deleted

APPurgeableTypeOneWeek

7

Files older than 1 week are automatically deleted

APPurgeableTypeTwoWeeks

14

Files older than 2 weeks are automatically deleted

APPurgeableTypeOneMonth

30

Files older than 1 month are automatically deleted

Size limit and eviction policy

Pass a non-zero size value (in MB) to APPurgeablePathTypeSize to cap how much disk space a directory can use. A value of 0 means no limit.

Important

When a directory reaches its size limit, the module deletes the earliest files first until the directory's total size drops to half the configured limit. For example, a 200 MB limit triggers eviction when 200 MB is reached, and cleanup stops when the directory is back at 100 MB.

API reference

#import <Foundation/Foundation.h>

typedef NS_ENUM(NSUInteger, APPurgeableType)
{
    APPurgeableTypeManual = 0,          // Clear the data when user manually clear the cache.
    APPurgeableTypeThreeDays = 3,       // Automatically delete the data that was generated three days ago.
    APPurgeableTypeOneWeek = 7,         // Automatically delete the data that was generated one week ago.
    APPurgeableTypeTwoWeeks = 14,       // Automatically delete the data that was generated two weeks ago.
    APPurgeableTypeOneMonth = 30,         // Automatically delete the data that was generated one month ago.
};

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

    /**
     * Return a cleanable storage path based on the user's input, and automatically determine whether the directory exists. If not, create one.
     *
     * @param userPath: The user-specified path. For example, the path is previously concatenated by using "Documents/SomePath" and is now obtained conveniently by using APPurgeableStoragePath(@"Documents/SomePath").
     * @param type: Specify a cleaning type, which can be manual, every week, or every three days.
     * @param size: Specify a maximum data size in MB. Earlier data is cleared when the maximum size is reached. 0 indicates that there is no upper limit.
     *
     * @return Target path
     */
    NSString* APPurgeablePath(NSString* path);
    NSString* APPurgeablePathType(NSString* path, APPurgeableType type);
    NSString* APPurgeablePathTypeSize(NSString* path, APPurgeableType type, NSUInteger size /* MB */);

    /**
     * Clear and reset all registered directories.
     */
    void ResetAllPurgeablePaths();

#ifdef __cplusplus
}
#endif // __cplusplus

Cache cleaning API

APUserCacheCleaner reads cleanup tasks from PurgeableCache.plist and runs them asynchronously. Deliver this file in the app's main bundle. Progress callbacks are always dispatched on the main thread, so you can safely update the UI from within the callback.

Cleanup phases

The APCacheCleanPhase enum tracks the cleaner's state as it runs:

Phase

Description

APCacheCleanPhasePreCalculating

Scanning the sandbox to measure its current size

APCacheCleanPhaseCleaning

Actively deleting cached files

APCacheCleanPhasePostCalculating

Scanning the sandbox again after cleanup

APCacheCleanPhaseDone

Cleanup complete

During APCacheCleanPhasePreCalculating, APCacheCleanPhaseCleaning, and APCacheCleanPhasePostCalculating, the progress parameter is a value from 0.0 to 1.0 representing real-time progress. When phase is APCacheCleanPhaseDone, progress contains the total amount of data cleaned, in MB.

API reference

#import <Foundation/Foundation.h>

typedef NS_ENUM(NSUInteger, APCacheCleanPhase)
{
    APCacheCleanPhasePreCalculating = 0,    // Scan the sandbox size before cleaning.
    APCacheCleanPhaseCleaning,              // Cleaning
    APCacheCleanPhasePostCalculating,       // Scan the sandbox size after cleaning is completed.
    APCacheCleanPhaseDone,                  // Cleaned
};

@interface APUserCacheCleaner : NSObject

/**
 * Perform cleaning asynchronously. A callback method must be transferred.
 * progress indicates the real progress when phase returns APCacheCleanPhasePreCalculating, APCacheCleanPhaseCleaning, or APCacheCleanPhasePostCalculating. The maximum value is 1.0.
 * progress returns the amount of cleaned data in MB when phase is APCacheCleanPhaseDone.
 *
 * @param callback: Callback method.
 */
+ (void)execute:(void(^)(APCacheCleanPhase phase, float progress))callback;

@end

Configure PurgeableCache.plist

PurgeableCache.plist defines the cleanup tasks that APUserCacheCleaner runs. Place this file in the app's main bundle.image

Each entry in the plist supports the following fields:

Field

Description

Path

The file or directory path. Accepts a relative path within the sandbox.

Entries

Files or subdirectories under Path to delete when Path is a directory. Supports the * wildcard.

Class

The class that defines the callback method.

Selectors

The class methods on Class to call. Must be class methods (+), not instance methods (-).