Data cleanup
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 |
|
|
Returns a purgeable path with manual cleanup only |
|
|
Returns a purgeable path with a time-based cleanup policy |
|
|
Returns a purgeable path with a time-based policy and a size limit |
|
|
Clears and resets all registered purgeable directories |
|
|
Runs the cleanup tasks defined in |
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 |
|
|
|
Files are deleted only when the user triggers a manual cache clean |
|
|
|
Files older than 3 days are automatically deleted |
|
|
|
Files older than 1 week are automatically deleted |
|
|
|
Files older than 2 weeks are automatically deleted |
|
|
|
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.
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 |
|
|
Scanning the sandbox to measure its current size |
|
|
Actively deleting cached files |
|
|
Scanning the sandbox again after cleanup |
|
|
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.
Each entry in the plist supports the following fields:
|
Field |
Description |
|
|
The file or directory path. Accepts a relative path within the sandbox. |
|
|
Files or subdirectories under |
|
|
The class that defines the callback method. |
|
|
The class methods on |