xref: /aosp_15_r20/external/executorch/backends/apple/coreml/runtime/delegate/ETCoreMLAssetManager.h (revision 523fa7a60841cd1ecfb9cc4201f1ca8b03ed023a)
1 //
2 // ETCoreMLAssetManager.h
3 //
4 // Copyright © 2024 Apple Inc. All rights reserved.
5 //
6 // Please refer to the license found in the LICENSE file in the root directory of the source tree.
7 
8 #import <Foundation/Foundation.h>
9 
10 #import <database.hpp>
11 
12 @class ETCoreMLAsset;
13 
14 NS_ASSUME_NONNULL_BEGIN
15 
16 /// A class responsible for managing the assets created by the delegate.
17 @interface ETCoreMLAssetManager : NSObject
18 
19 - (instancetype)init NS_UNAVAILABLE;
20 
21 + (instancetype)new NS_UNAVAILABLE;
22 
23 /// Constructs an `ETCoreMLAssetManager` instance.
24 ///
25 /// @param database The sqlite database that will be used to keep track of assets.
26 /// @param assetsDirectoryURL The directory URL where the assets will be stored.
27 /// @param trashDirectoryURL   The directory URL where the assets will be moved before deletion.
28 /// @param maxAssetsSizeInBytes   The maximum assets size in bytes.
29 /// @param error   On failure, error is filled with the failure information.
30 - (nullable instancetype)initWithDatabase:(const std::shared_ptr<executorchcoreml::sqlite::Database>&)database
31                        assetsDirectoryURL:(NSURL*)assetsDirectoryURL
32                         trashDirectoryURL:(NSURL*)trashDirectoryURL
33                      maxAssetsSizeInBytes:(NSInteger)maxAssetsSizeInBytes
34                                     error:(NSError* __autoreleasing*)error NS_DESIGNATED_INITIALIZER;
35 
36 /// Constructs an `ETCoreMLAssetManager` instance.
37 ///
38 /// @param databaseURL The URL to the database that will be used to keep track of assets.
39 /// @param assetsDirectoryURL The directory URL where the assets will be stored.
40 /// @param trashDirectoryURL   The directory URL where the assets will be moved before deletion.
41 /// @param maxAssetsSizeInBytes   The maximum assets size in bytes.
42 /// @param error   On failure, error is filled with the failure information.
43 - (nullable instancetype)initWithDatabaseURL:(NSURL*)databaseURL
44                           assetsDirectoryURL:(NSURL*)assetsDirectoryURL
45                            trashDirectoryURL:(NSURL*)trashDirectoryURL
46                         maxAssetsSizeInBytes:(NSInteger)maxAssetsSizeInBytes
47                                        error:(NSError* __autoreleasing*)error;
48 
49 /// Stores an asset at the url. The contents of the url are moved to the assets directory and it's
50 /// lifecycle is managed by the`ETCoreMLAssetManager`.
51 ///
52 /// @param url The URL to the directory.
53 /// @param identifier An unique identifier to associate the asset with.
54 /// @param error   On failure, error is filled with the failure information.
55 /// @retval The `ETCoreMLAsset` instance representing the asset if the store was successful
56 /// otherwise `nil`.
57 - (nullable ETCoreMLAsset*)storeAssetAtURL:(NSURL*)url
58                             withIdentifier:(NSString*)identifier
59                                      error:(NSError* __autoreleasing*)error;
60 
61 /// Returns the asset associated with the identifier.
62 ///
63 /// @param identifier The asset identifier.
64 /// @param error   On failure, error is filled with the failure information.
65 /// @retval The `ETCoreMLAsset` instance representing the asset if the retrieval was successful
66 /// otherwise `nil`.
67 - (nullable ETCoreMLAsset*)assetWithIdentifier:(NSString*)identifier error:(NSError* __autoreleasing*)error;
68 
69 /// Removes an asset associated with the identifier.
70 ///
71 /// @param identifier The asset identifier.
72 /// @param error   On failure, error is filled with the failure information.
73 /// @retval `YES` is the asset was removed or didn't exist otherwise `NO`.
74 - (BOOL)removeAssetWithIdentifier:(NSString*)identifier error:(NSError* __autoreleasing*)error;
75 
76 /// Checks if the asset associated with the identifier exists.
77 ///
78 /// @param identifier The asset identifier.
79 /// @param error   On failure, error is filled with the failure information.
80 /// @retval `YES` is the asset exists otherwise `NO`.
81 - (BOOL)hasAssetWithIdentifier:(NSString*)identifier error:(NSError* __autoreleasing*)error;
82 
83 /// Returns an array of most recently used assets. Assets are sorted in descending order by their
84 /// access time and the first `maxCount` assets are returned. The access time of an asset is updated
85 /// when the asset is stored or retrieved.
86 ///
87 /// @param maxCount The max count of assets to return.
88 /// @param error   On failure, error is filled with the failure information.
89 /// @retval An array of most recently used assets
90 - (nullable NSArray<ETCoreMLAsset*>*)mostRecentlyUsedAssetsWithMaxCount:(NSUInteger)maxCount
91                                                                   error:(NSError* __autoreleasing*)error;
92 
93 /// Compacts the assets storage. The assets are moved to the trash directory and are asynchronously
94 /// deleted.
95 ///
96 /// @param sizeInBytes The maximum size of the assets storage that the compaction should achieve.
97 /// @param error   On failure, error is filled with the failure information.
98 /// @retval The size of the assets store after the compaction.
99 - (NSUInteger)compact:(NSUInteger)sizeInBytes error:(NSError* __autoreleasing*)error;
100 
101 
102 /// Purges the assets storage. The assets are moved to the trash directory and are asynchronously
103 /// deleted.
104 ///
105 /// @param error   On failure, error is filled with the failure information.
106 /// @retval `YES` is the assets are purged otherwise `NO`.
107 - (BOOL)purgeAndReturnError:(NSError* __autoreleasing*)error;
108 
109 /// The estimated size of the assets store. The returned value might not correct if the asset
110 /// directory is tampered externally.
111 @property (assign, readonly, atomic) NSInteger estimatedSizeInBytes;
112 
113 /// The maximum size of the assets store.
114 @property (assign, readonly, nonatomic) NSInteger maxAssetsSizeInBytes;
115 
116 /// The trash directory URL, the assets before removal are moved to this directory. The directory
117 /// contents are deleted asynchronously.
118 @property (copy, readonly, nonatomic) NSURL* trashDirectoryURL;
119 
120 /// The file manager.
121 @property (strong, readonly, nonatomic) NSFileManager* fileManager;
122 
123 @end
124 
125 NS_ASSUME_NONNULL_END
126