diff options
Diffstat (limited to 'src/fmdb/FMDatabaseQueue.h')
| -rwxr-xr-x | src/fmdb/FMDatabaseQueue.h | 102 |
1 files changed, 54 insertions, 48 deletions
diff --git a/src/fmdb/FMDatabaseQueue.h b/src/fmdb/FMDatabaseQueue.h index 27f4012..b3dcf41 100755 --- a/src/fmdb/FMDatabaseQueue.h +++ b/src/fmdb/FMDatabaseQueue.h @@ -11,57 +11,63 @@ NS_ASSUME_NONNULL_BEGIN -/** To perform queries and updates on multiple threads, you'll want to use `FMDatabaseQueue`. +/** To perform queries and updates on multiple threads, you'll want to use @c FMDatabaseQueue . - Using a single instance of `<FMDatabase>` from multiple threads at once is a bad idea. It has always been OK to make a `<FMDatabase>` object *per thread*. Just don't share a single instance across threads, and definitely not across multiple threads at the same time. + 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. - Instead, use `FMDatabaseQueue`. Here's how to use it: + Instead, use @c FMDatabaseQueue . Here's how to use it: First, make your queue. - FMDatabaseQueue *queue = [FMDatabaseQueue databaseQueueWithPath:aPath]; +@code +FMDatabaseQueue *queue = [FMDatabaseQueue databaseQueueWithPath:aPath]; +@endcode Then use it like so: - [queue inDatabase:^(FMDatabase *db) { - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]]; +@code +[queue inDatabase:^(FMDatabase *db) { + [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]]; + [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]]; + [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]]; - FMResultSet *rs = [db executeQuery:@"select * from foo"]; - while ([rs next]) { - //… - } - }]; + FMResultSet *rs = [db executeQuery:@"select * from foo"]; + while ([rs next]) { + //… + } +}]; +@endcode An easy way to wrap things up in a transaction can be done like this: - [queue inTransaction:^(FMDatabase *db, BOOL *rollback) { - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]]; - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]]; +@code +[queue inTransaction:^(FMDatabase *db, BOOL *rollback) { + [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:1]]; + [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:2]]; + [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:3]]; - if (whoopsSomethingWrongHappened) { - *rollback = YES; - return; - } - // etc… - [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:4]]; - }]; + // if (whoopsSomethingWrongHappened) { + // *rollback = YES; + // return; + // } - `FMDatabaseQueue` will run the blocks on a serialized queue (hence the name of the class). So if you call `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. + // etc… + [db executeUpdate:@"INSERT INTO myTable VALUES (?)", [NSNumber numberWithInt:4]]; +}]; +@endcode - ### See also + @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. - - `<FMDatabase>` - - @warning Do not instantiate a single `<FMDatabase>` object and use it across multiple threads. Use `FMDatabaseQueue` instead. + @warning Do not instantiate a single @c FMDatabase object and use it across multiple threads. Use @c FMDatabaseQueue instead. - @warning The calls to `FMDatabaseQueue`'s methods are blocking. So even though you are passing along blocks, they will **not** be run on another thread. + @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. + + @sa FMDatabase */ @interface FMDatabaseQueue : NSObject + /** Path of database */ @property (atomic, retain, nullable) NSString *path; @@ -82,16 +88,16 @@ NS_ASSUME_NONNULL_BEGIN @param aPath The file path of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ + (nullable instancetype)databaseQueueWithPath:(NSString * _Nullable)aPath; /** Create queue using file URL. - @param url The file `NSURL` of the database. + @param url The file @c NSURL of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ + (nullable instancetype)databaseQueueWithURL:(NSURL * _Nullable)url; @@ -101,16 +107,16 @@ NS_ASSUME_NONNULL_BEGIN @param aPath The file path of the database. @param openFlags Flags passed to the openWithFlags method of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ + (nullable instancetype)databaseQueueWithPath:(NSString * _Nullable)aPath flags:(int)openFlags; /** Create queue using file URL and specified flags. - @param url The file `NSURL` of the database. + @param url The file @c NSURL of the database. @param openFlags Flags passed to the openWithFlags method of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ + (nullable instancetype)databaseQueueWithURL:(NSURL * _Nullable)url flags:(int)openFlags; @@ -118,7 +124,7 @@ NS_ASSUME_NONNULL_BEGIN @param aPath The file path of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ - (nullable instancetype)initWithPath:(NSString * _Nullable)aPath; @@ -127,7 +133,7 @@ NS_ASSUME_NONNULL_BEGIN @param url The file `NSURL of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ - (nullable instancetype)initWithURL:(NSURL * _Nullable)url; @@ -137,7 +143,7 @@ NS_ASSUME_NONNULL_BEGIN @param aPath The file path of the database. @param openFlags Flags passed to the openWithFlags method of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ - (nullable instancetype)initWithPath:(NSString * _Nullable)aPath flags:(int)openFlags; @@ -147,7 +153,7 @@ NS_ASSUME_NONNULL_BEGIN @param url The file path of the database. @param openFlags Flags passed to the openWithFlags method of the database. - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ - (nullable instancetype)initWithURL:(NSURL * _Nullable)url flags:(int)openFlags; @@ -158,7 +164,7 @@ NS_ASSUME_NONNULL_BEGIN @param openFlags Flags passed to the openWithFlags method of the database @param vfsName The name of a custom virtual file system - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ - (nullable instancetype)initWithPath:(NSString * _Nullable)aPath flags:(int)openFlags vfs:(NSString * _Nullable)vfsName; @@ -169,7 +175,7 @@ NS_ASSUME_NONNULL_BEGIN @param openFlags Flags passed to the openWithFlags method of the database @param vfsName The name of a custom virtual file system - @return The `FMDatabaseQueue` object. `nil` on error. + @return The @c FMDatabaseQueue object. @c nil on error. */ - (nullable instancetype)initWithURL:(NSURL * _Nullable)url flags:(int)openFlags vfs:(NSString * _Nullable)vfsName; @@ -197,14 +203,14 @@ NS_ASSUME_NONNULL_BEGIN /** Synchronously perform database operations on queue. - @param block The code to be run on the queue of `FMDatabaseQueue` + @param block The code to be run on the queue of @c FMDatabaseQueue */ - (void)inDatabase:(__attribute__((noescape)) void (^)(FMDatabase *db))block; /** Synchronously perform database operations on queue, using transactions. - @param block The code to be run on the queue of `FMDatabaseQueue` + @param block The code to be run on the queue of @c FMDatabaseQueue @warning Unlike SQLite's `BEGIN TRANSACTION`, this method currently performs an exclusive transaction, not a deferred transaction. This behavior @@ -220,21 +226,21 @@ NS_ASSUME_NONNULL_BEGIN /** Synchronously perform database operations on queue, using deferred transactions. - @param block The code to be run on the queue of `FMDatabaseQueue` + @param block The code to be run on the queue of @c FMDatabaseQueue */ - (void)inDeferredTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; /** Synchronously perform database operations on queue, using exclusive transactions. - @param block The code to be run on the queue of `FMDatabaseQueue` + @param block The code to be run on the queue of @c FMDatabaseQueue */ - (void)inExclusiveTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; /** Synchronously perform database operations on queue, using immediate transactions. - @param block The code to be run on the queue of `FMDatabaseQueue` + @param block The code to be run on the queue of @c FMDatabaseQueue */ - (void)inImmediateTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; @@ -245,7 +251,7 @@ NS_ASSUME_NONNULL_BEGIN /** Synchronously perform database operations using save point. - @param block The code to be run on the queue of `FMDatabaseQueue` + @param block The code to be run on the queue of @c FMDatabaseQueue */ // NOTE: you can not nest these, since calling it will pull another database out of the pool and you'll get a deadlock. |