国内WASDK WA实现层
view | history | commit | commitdiff
lpw
2024-06-12 09e73ac42fe2feb7925d954fed88a2eaa57697f7
commit | author | age
6e1425 1 //
H 2 //  FMDatabaseQueue.h
3 //  fmdb
4 //
5 //  Created by August Mueller on 6/22/11.
6 //  Copyright 2011 Flying Meat Inc. All rights reserved.
7 //
8
9 #import <Foundation/Foundation.h>
09e73a 10 #import "FMDatabase.h"
6e1425 11
09e73a 12 NS_ASSUME_NONNULL_BEGIN
6e1425 13
09e73a 14 /** To perform queries and updates on multiple threads, you'll want to use @c FMDatabaseQueue .
6e1425 15
09e73a 16  Using a single instance of @c FMDatabase from multiple threads at once is a bad idea.  It has always been OK to make a @c FMDatabase  object *per thread*.  Just don't share a single instance across threads, and definitely not across multiple threads at the same time.
6e1425 17
09e73a 18  Instead, use @c FMDatabaseQueue . Here's how to use it:
6e1425 19
H 20  First, make your queue.
21
09e73a 22 @code
L 23 FMDatabaseQueue *queue = [FMDatabaseQueue databaseQueueWithPath:aPath];
24 @endcode
6e1425 25
H 26  Then use it like so:
27
09e73a 28 @code
L 29 [queue inDatabase:^(FMDatabase *db) {
30     [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]];
31     [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]];
32     [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]];
6e1425 33
09e73a 34     FMResultSet *rs = [db executeQuery:@"select * from foo"];
L 35     while ([rs next]) {
36         //…
37     }
38 }];
39 @endcode
6e1425 40
H 41  An easy way to wrap things up in a transaction can be done like this:
42
09e73a 43 @code
L 44 [queue inTransaction:^(FMDatabase *db, BOOL *rollback) {
45     [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]];
46     [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]];
47     [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]];
6e1425 48
09e73a 49     // if (whoopsSomethingWrongHappened) {
L 50     //     *rollback = YES;
51     //     return;
52     // }
6e1425 53
09e73a 54     // etc…
L 55     [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:4]];
56 }];
57 @endcode
6e1425 58
09e73a 59  @c FMDatabaseQueue will run the blocks on a serialized queue (hence the name of the class).  So if you call @c FMDatabaseQueue 's methods from multiple threads at the same time, they will be executed in the order they are received.  This way queries and updates won't step on each other's toes, and every one is happy.
6e1425 60
09e73a 61  @warning Do not instantiate a single @c FMDatabase  object and use it across multiple threads. Use @c FMDatabaseQueue  instead.
6e1425 62  
09e73a 63  @warning The calls to @c FMDatabaseQueue 's methods are blocking.  So even though you are passing along blocks, they will **not** be run on another thread.
L 64
65  @sa FMDatabase
6e1425 66
H 67  */
68
09e73a 69 @interface FMDatabaseQueue : NSObject
6e1425 70
H 71 /** Path of database */
72
09e73a 73 @property (atomic, retain, nullable) NSString *path;
6e1425 74
H 75 /** Open flags */
76
77 @property (atomic, readonly) int openFlags;
09e73a 78
L 79 /**  Custom virtual file system name */
80
81 @property (atomic, copy, nullable) NSString *vfsName;
6e1425 82
H 83 ///----------------------------------------------------
84 /// @name Initialization, opening, and closing of queue
85 ///----------------------------------------------------
86
87 /** Create queue using path.
88  
89  @param aPath The file path of the database.
90  
09e73a 91  @return The @c FMDatabaseQueue  object. @c nil  on error.
6e1425 92  */
H 93
09e73a 94 + (nullable instancetype)databaseQueueWithPath:(NSString * _Nullable)aPath;
L 95
96 /** Create queue using file URL.
97  
98  @param url The file @c NSURL  of the database.
99  
100  @return The @c FMDatabaseQueue  object. @c nil  on error.
101  */
102
103 + (nullable instancetype)databaseQueueWithURL:(NSURL * _Nullable)url;
6e1425 104
H 105 /** Create queue using path and specified flags.
106  
107  @param aPath The file path of the database.
09e73a 108  @param openFlags Flags passed to the openWithFlags method of the database.
6e1425 109  
09e73a 110  @return The @c FMDatabaseQueue  object. @c nil  on error.
6e1425 111  */
09e73a 112 + (nullable instancetype)databaseQueueWithPath:(NSString * _Nullable)aPath flags:(int)openFlags;
L 113
114 /** Create queue using file URL and specified flags.
115  
116  @param url The file @c NSURL  of the database.
117  @param openFlags Flags passed to the openWithFlags method of the database.
118  
119  @return The @c FMDatabaseQueue  object. @c nil  on error.
120  */
121 + (nullable instancetype)databaseQueueWithURL:(NSURL * _Nullable)url flags:(int)openFlags;
6e1425 122
H 123 /** Create queue using path.
09e73a 124  
6e1425 125  @param aPath The file path of the database.
09e73a 126  
L 127  @return The @c FMDatabaseQueue  object. @c nil  on error.
6e1425 128  */
H 129
09e73a 130 - (nullable instancetype)initWithPath:(NSString * _Nullable)aPath;
L 131
132 /** Create queue using file URL.
133  
134  @param url The file `NSURL of the database.
135  
136  @return The @c FMDatabaseQueue  object. @c nil  on error.
137  */
138
139 - (nullable instancetype)initWithURL:(NSURL * _Nullable)url;
6e1425 140
H 141 /** Create queue using path and specified flags.
142  
143  @param aPath The file path of the database.
09e73a 144  @param openFlags Flags passed to the openWithFlags method of the database.
6e1425 145  
09e73a 146  @return The @c FMDatabaseQueue  object. @c nil  on error.
6e1425 147  */
H 148
09e73a 149 - (nullable instancetype)initWithPath:(NSString * _Nullable)aPath flags:(int)openFlags;
L 150
151 /** Create queue using file URL and specified flags.
152  
153  @param url The file path of the database.
154  @param openFlags Flags passed to the openWithFlags method of the database.
155  
156  @return The @c FMDatabaseQueue  object. @c nil  on error.
157  */
158
159 - (nullable instancetype)initWithURL:(NSURL * _Nullable)url flags:(int)openFlags;
6e1425 160
H 161 /** Create queue using path and specified flags.
162  
163  @param aPath The file path of the database.
164  @param openFlags Flags passed to the openWithFlags method of the database
165  @param vfsName The name of a custom virtual file system
166  
09e73a 167  @return The @c FMDatabaseQueue  object. @c nil  on error.
6e1425 168  */
H 169
09e73a 170 - (nullable instancetype)initWithPath:(NSString * _Nullable)aPath flags:(int)openFlags vfs:(NSString * _Nullable)vfsName;
L 171
172 /** Create queue using file URL and specified flags.
173  
174  @param url The file `NSURL of the database.
175  @param openFlags Flags passed to the openWithFlags method of the database
176  @param vfsName The name of a custom virtual file system
177  
178  @return The @c FMDatabaseQueue  object. @c nil  on error.
179  */
180
181 - (nullable instancetype)initWithURL:(NSURL * _Nullable)url flags:(int)openFlags vfs:(NSString * _Nullable)vfsName;
6e1425 182
H 183 /** Returns the Class of 'FMDatabase' subclass, that will be used to instantiate database object.
184  
185  Subclasses can override this method to return specified Class of 'FMDatabase' subclass.
186  
187  @return The Class of 'FMDatabase' subclass, that will be used to instantiate database object.
188  */
189
190 + (Class)databaseClass;
191
192 /** Close database used by queue. */
193
194 - (void)close;
195
09e73a 196 /** Interupt pending database operation. */
L 197
198 - (void)interrupt;
199
6e1425 200 ///-----------------------------------------------
H 201 /// @name Dispatching database operations to queue
202 ///-----------------------------------------------
203
204 /** Synchronously perform database operations on queue.
205  
09e73a 206  @param block The code to be run on the queue of @c FMDatabaseQueue 
6e1425 207  */
H 208
09e73a 209 - (void)inDatabase:(__attribute__((noescape)) void (^)(FMDatabase *db))block;
6e1425 210
H 211 /** Synchronously perform database operations on queue, using transactions.
212
09e73a 213  @param block The code to be run on the queue of @c FMDatabaseQueue 
L 214  
215  @warning    Unlike SQLite's `BEGIN TRANSACTION`, this method currently performs
216              an exclusive transaction, not a deferred transaction. This behavior
217              is likely to change in future versions of FMDB, whereby this method
218              will likely eventually adopt standard SQLite behavior and perform
219              deferred transactions. If you really need exclusive tranaction, it is
220              recommended that you use `inExclusiveTransaction`, instead, not only
221              to make your intent explicit, but also to future-proof your code.
222
6e1425 223  */
H 224
09e73a 225 - (void)inTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block;
6e1425 226
H 227 /** Synchronously perform database operations on queue, using deferred transactions.
09e73a 228  
L 229  @param block The code to be run on the queue of @c FMDatabaseQueue 
6e1425 230  */
H 231
09e73a 232 - (void)inDeferredTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block;
L 233
234 /** Synchronously perform database operations on queue, using exclusive transactions.
235  
236  @param block The code to be run on the queue of @c FMDatabaseQueue 
237  */
238
239 - (void)inExclusiveTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block;
240
241 /** Synchronously perform database operations on queue, using immediate transactions.
242
243  @param block The code to be run on the queue of @c FMDatabaseQueue 
244  */
245
246 - (void)inImmediateTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block;
6e1425 247
H 248 ///-----------------------------------------------
249 /// @name Dispatching database operations to queue
250 ///-----------------------------------------------
251
252 /** Synchronously perform database operations using save point.
253
09e73a 254  @param block The code to be run on the queue of @c FMDatabaseQueue 
6e1425 255  */
H 256
257 // NOTE: you can not nest these, since calling it will pull another database out of the pool and you'll get a deadlock.
258 // If you need to nest, use FMDatabase's startSavePointWithName:error: instead.
09e73a 259 - (NSError * _Nullable)inSavePoint:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block;
L 260
261 ///-----------------
262 /// @name Checkpoint
263 ///-----------------
264
265 /** Performs a WAL checkpoint
266  
267  @param checkpointMode The checkpoint mode for sqlite3_wal_checkpoint_v2
268  @param error The NSError corresponding to the error, if any.
269  @return YES on success, otherwise NO.
270  */
271 - (BOOL)checkpoint:(FMDBCheckpointMode)checkpointMode error:(NSError * _Nullable *)error;
272
273 /** Performs a WAL checkpoint
274  
275  @param checkpointMode The checkpoint mode for sqlite3_wal_checkpoint_v2
276  @param name The db name for sqlite3_wal_checkpoint_v2
277  @param error The NSError corresponding to the error, if any.
278  @return YES on success, otherwise NO.
279  */
280 - (BOOL)checkpoint:(FMDBCheckpointMode)checkpointMode name:(NSString * _Nullable)name error:(NSError * _Nullable *)error;
281
282 /** Performs a WAL checkpoint
283  
284  @param checkpointMode The checkpoint mode for sqlite3_wal_checkpoint_v2
285  @param name The db name for sqlite3_wal_checkpoint_v2
286  @param error The NSError corresponding to the error, if any.
287  @param logFrameCount If not NULL, then this is set to the total number of frames in the log file or to -1 if the checkpoint could not run because of an error or because the database is not in WAL mode.
288  @param checkpointCount If not NULL, then this is set to the total number of checkpointed frames in the log file (including any that were already checkpointed before the function was called) or to -1 if the checkpoint could not run due to an error or because the database is not in WAL mode.
289  @return YES on success, otherwise NO.
290  */
291 - (BOOL)checkpoint:(FMDBCheckpointMode)checkpointMode name:(NSString * _Nullable)name logFrameCount:(int * _Nullable)logFrameCount checkpointCount:(int * _Nullable)checkpointCount error:(NSError * _Nullable *)error;
6e1425 292
H 293 @end
294
09e73a 295 NS_ASSUME_NONNULL_END