| commit | author | age | ||
| 6e1425 | 1 | // |
| H | 2 | // FMDatabasePool.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> | |
| 10 | ||
| 09e73a | 11 | NS_ASSUME_NONNULL_BEGIN |
| L | 12 | |
| 6e1425 | 13 | @class FMDatabase; |
| H | 14 | |
| 09e73a | 15 | /** Pool of @c FMDatabase objects. |
| 6e1425 | 16 | |
| 09e73a | 17 | See also |
| 6e1425 | 18 | |
| 09e73a | 19 | - @c FMDatabaseQueue |
| L | 20 | - @c FMDatabase |
| 6e1425 | 21 | |
| 09e73a | 22 | @warning Before using @c FMDatabasePool , please consider using @c FMDatabaseQueue instead. |
| 6e1425 | 23 | |
| 09e73a | 24 | If you really really really know what you're doing and @c FMDatabasePool is what |
| 6e1425 | 25 | you really really need (ie, you're using a read only database), OK you can use |
| H | 26 | it. But just be careful not to deadlock! |
| 27 | ||
| 28 | For an example on deadlocking, search for: | |
| 29 | `ONLY_USE_THE_POOL_IF_YOU_ARE_DOING_READS_OTHERWISE_YOULL_DEADLOCK_USE_FMDATABASEQUEUE_INSTEAD` | |
| 30 | in the main.m file. | |
| 31 | */ | |
| 32 | ||
| 09e73a | 33 | @interface FMDatabasePool : NSObject |
| 6e1425 | 34 | |
| H | 35 | /** Database path */ |
| 36 | ||
| 09e73a | 37 | @property (atomic, copy, nullable) NSString *path; |
| 6e1425 | 38 | |
| H | 39 | /** Delegate object */ |
| 40 | ||
| 09e73a | 41 | @property (atomic, unsafe_unretained, nullable) id delegate; |
| 6e1425 | 42 | |
| H | 43 | /** Maximum number of databases to create */ |
| 44 | ||
| 45 | @property (atomic, assign) NSUInteger maximumNumberOfDatabasesToCreate; | |
| 46 | ||
| 47 | /** Open flags */ | |
| 48 | ||
| 49 | @property (atomic, readonly) int openFlags; | |
| 50 | ||
| 09e73a | 51 | /** Custom virtual file system name */ |
| L | 52 | |
| 53 | @property (atomic, copy, nullable) NSString *vfsName; | |
| 54 | ||
| 6e1425 | 55 | |
| H | 56 | ///--------------------- |
| 57 | /// @name Initialization | |
| 58 | ///--------------------- | |
| 59 | ||
| 60 | /** Create pool using path. | |
| 09e73a | 61 | |
| 6e1425 | 62 | @param aPath The file path of the database. |
| 09e73a | 63 | |
| L | 64 | @return The @c FMDatabasePool object. @c nil on error. |
| 6e1425 | 65 | */ |
| H | 66 | |
| 09e73a | 67 | + (instancetype)databasePoolWithPath:(NSString * _Nullable)aPath; |
| L | 68 | |
| 69 | /** Create pool using file URL. | |
| 70 | ||
| 71 | @param url The file @c NSURL of the database. | |
| 72 | ||
| 73 | @return The @c FMDatabasePool object. @c nil on error. | |
| 74 | */ | |
| 75 | ||
| 76 | + (instancetype)databasePoolWithURL:(NSURL * _Nullable)url; | |
| 6e1425 | 77 | |
| H | 78 | /** Create pool using path and specified flags |
| 09e73a | 79 | |
| 6e1425 | 80 | @param aPath The file path of the database. |
| 09e73a | 81 | @param openFlags Flags passed to the openWithFlags method of the database. |
| L | 82 | |
| 83 | @return The @c FMDatabasePool object. @c nil on error. | |
| 6e1425 | 84 | */ |
| H | 85 | |
| 09e73a | 86 | + (instancetype)databasePoolWithPath:(NSString * _Nullable)aPath flags:(int)openFlags; |
| L | 87 | |
| 88 | /** Create pool using file URL and specified flags | |
| 89 | ||
| 90 | @param url The file @c NSURL of the database. | |
| 91 | @param openFlags Flags passed to the openWithFlags method of the database. | |
| 92 | ||
| 93 | @return The @c FMDatabasePool object. @c nil on error. | |
| 94 | */ | |
| 95 | ||
| 96 | + (instancetype)databasePoolWithURL:(NSURL * _Nullable)url flags:(int)openFlags; | |
| 6e1425 | 97 | |
| H | 98 | /** Create pool using path. |
| 09e73a | 99 | |
| 6e1425 | 100 | @param aPath The file path of the database. |
| 09e73a | 101 | |
| L | 102 | @return The @c FMDatabasePool object. @c nil on error. |
| 6e1425 | 103 | */ |
| H | 104 | |
| 09e73a | 105 | - (instancetype)initWithPath:(NSString * _Nullable)aPath; |
| L | 106 | |
| 107 | /** Create pool using file URL. | |
| 108 | ||
| 109 | @param url The file `NSURL of the database. | |
| 110 | ||
| 111 | @return The @c FMDatabasePool object. @c nil on error. | |
| 112 | */ | |
| 113 | ||
| 114 | - (instancetype)initWithURL:(NSURL * _Nullable)url; | |
| 6e1425 | 115 | |
| H | 116 | /** Create pool using path and specified flags. |
| 09e73a | 117 | |
| 6e1425 | 118 | @param aPath The file path of the database. |
| H | 119 | @param openFlags Flags passed to the openWithFlags method of the database |
| 09e73a | 120 | |
| L | 121 | @return The @c FMDatabasePool object. @c nil on error. |
| 6e1425 | 122 | */ |
| H | 123 | |
| 09e73a | 124 | - (instancetype)initWithPath:(NSString * _Nullable)aPath flags:(int)openFlags; |
| L | 125 | |
| 126 | /** Create pool using file URL and specified flags. | |
| 127 | ||
| 128 | @param url The file @c NSURL of the database. | |
| 129 | @param openFlags Flags passed to the openWithFlags method of the database | |
| 130 | ||
| 131 | @return The @c FMDatabasePool object. @c nil on error. | |
| 132 | */ | |
| 133 | ||
| 134 | - (instancetype)initWithURL:(NSURL * _Nullable)url flags:(int)openFlags; | |
| 135 | ||
| 136 | /** Create pool using path and specified flags. | |
| 137 | ||
| 138 | @param aPath The file path of the database. | |
| 139 | @param openFlags Flags passed to the openWithFlags method of the database | |
| 140 | @param vfsName The name of a custom virtual file system | |
| 141 | ||
| 142 | @return The @c FMDatabasePool object. @c nil on error. | |
| 143 | */ | |
| 144 | ||
| 145 | - (instancetype)initWithPath:(NSString * _Nullable)aPath flags:(int)openFlags vfs:(NSString * _Nullable)vfsName; | |
| 146 | ||
| 147 | /** Create pool using file URL and specified flags. | |
| 148 | ||
| 149 | @param url The file @c NSURL of the database. | |
| 150 | @param openFlags Flags passed to the openWithFlags method of the database | |
| 151 | @param vfsName The name of a custom virtual file system | |
| 152 | ||
| 153 | @return The @c FMDatabasePool object. @c nil on error. | |
| 154 | */ | |
| 155 | ||
| 156 | - (instancetype)initWithURL:(NSURL * _Nullable)url flags:(int)openFlags vfs:(NSString * _Nullable)vfsName; | |
| 157 | ||
| 158 | /** Returns the Class of 'FMDatabase' subclass, that will be used to instantiate database object. | |
| 159 | ||
| 160 | Subclasses can override this method to return specified Class of 'FMDatabase' subclass. | |
| 161 | ||
| 162 | @return The Class of 'FMDatabase' subclass, that will be used to instantiate database object. | |
| 163 | */ | |
| 164 | ||
| 165 | + (Class)databaseClass; | |
| 6e1425 | 166 | |
| H | 167 | ///------------------------------------------------ |
| 168 | /// @name Keeping track of checked in/out databases | |
| 169 | ///------------------------------------------------ | |
| 170 | ||
| 171 | /** Number of checked-in databases in pool | |
| 172 | */ | |
| 173 | ||
| 09e73a | 174 | @property (nonatomic, readonly) NSUInteger countOfCheckedInDatabases; |
| 6e1425 | 175 | |
| H | 176 | /** Number of checked-out databases in pool |
| 177 | */ | |
| 178 | ||
| 09e73a | 179 | @property (nonatomic, readonly) NSUInteger countOfCheckedOutDatabases; |
| 6e1425 | 180 | |
| H | 181 | /** Total number of databases in pool |
| 182 | */ | |
| 183 | ||
| 09e73a | 184 | @property (nonatomic, readonly) NSUInteger countOfOpenDatabases; |
| 6e1425 | 185 | |
| H | 186 | /** Release all databases in pool */ |
| 187 | ||
| 188 | - (void)releaseAllDatabases; | |
| 189 | ||
| 190 | ///------------------------------------------ | |
| 191 | /// @name Perform database operations in pool | |
| 192 | ///------------------------------------------ | |
| 193 | ||
| 194 | /** Synchronously perform database operations in pool. | |
| 195 | ||
| 09e73a | 196 | @param block The code to be run on the @c FMDatabasePool pool. |
| 6e1425 | 197 | */ |
| H | 198 | |
| 09e73a | 199 | - (void)inDatabase:(__attribute__((noescape)) void (^)(FMDatabase *db))block; |
| 6e1425 | 200 | |
| H | 201 | /** Synchronously perform database operations in pool using transaction. |
| 09e73a | 202 | |
| L | 203 | @param block The code to be run on the @c FMDatabasePool pool. |
| 204 | ||
| 205 | @warning Unlike SQLite's `BEGIN TRANSACTION`, this method currently performs | |
| 206 | an exclusive transaction, not a deferred transaction. This behavior | |
| 207 | is likely to change in future versions of FMDB, whereby this method | |
| 208 | will likely eventually adopt standard SQLite behavior and perform | |
| 209 | deferred transactions. If you really need exclusive tranaction, it is | |
| 210 | recommended that you use `inExclusiveTransaction`, instead, not only | |
| 211 | to make your intent explicit, but also to future-proof your code. | |
| 212 | */ | |
| 6e1425 | 213 | |
| 09e73a | 214 | - (void)inTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; |
| L | 215 | |
| 216 | /** Synchronously perform database operations in pool using exclusive transaction. | |
| 217 | ||
| 218 | @param block The code to be run on the @c FMDatabasePool pool. | |
| 6e1425 | 219 | */ |
| H | 220 | |
| 09e73a | 221 | - (void)inExclusiveTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; |
| 6e1425 | 222 | |
| H | 223 | /** Synchronously perform database operations in pool using deferred transaction. |
| 224 | ||
| 09e73a | 225 | @param block The code to be run on the @c FMDatabasePool pool. |
| 6e1425 | 226 | */ |
| H | 227 | |
| 09e73a | 228 | - (void)inDeferredTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; |
| L | 229 | |
| 230 | /** Synchronously perform database operations on queue, using immediate transactions. | |
| 231 | ||
| 232 | @param block The code to be run on the queue of @c FMDatabaseQueue | |
| 233 | */ | |
| 234 | ||
| 235 | - (void)inImmediateTransaction:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; | |
| 6e1425 | 236 | |
| H | 237 | /** Synchronously perform database operations in pool using save point. |
| 238 | ||
| 09e73a | 239 | @param block The code to be run on the @c FMDatabasePool pool. |
| 6e1425 | 240 | |
| 09e73a | 241 | @return @c NSError object if error; @c nil if successful. |
| 6e1425 | 242 | |
| 09e73a | 243 | @warning You can not nest these, since calling it will pull another database out of the pool and you'll get a deadlock. If you need to nest, use @c startSavePointWithName:error: instead. |
| 6e1425 | 244 | */ |
| H | 245 | |
| 09e73a | 246 | - (NSError * _Nullable)inSavePoint:(__attribute__((noescape)) void (^)(FMDatabase *db, BOOL *rollback))block; |
| 6e1425 | 247 | |
| H | 248 | @end |
| 249 | ||
| 250 | ||
| 251 | /** FMDatabasePool delegate category | |
| 252 | ||
| 253 | This is a category that defines the protocol for the FMDatabasePool delegate | |
| 254 | */ | |
| 255 | ||
| 256 | @interface NSObject (FMDatabasePoolDelegate) | |
| 257 | ||
| 258 | /** Asks the delegate whether database should be added to the pool. | |
| 259 | ||
| 09e73a | 260 | @param pool The @c FMDatabasePool object. |
| L | 261 | @param database The @c FMDatabase object. |
| 6e1425 | 262 | |
| 09e73a | 263 | @return @c YES if it should add database to pool; @c NO if not. |
| 6e1425 | 264 | |
| H | 265 | */ |
| 266 | ||
| 267 | - (BOOL)databasePool:(FMDatabasePool*)pool shouldAddDatabaseToPool:(FMDatabase*)database; | |
| 268 | ||
| 269 | /** Tells the delegate that database was added to the pool. | |
| 270 | ||
| 09e73a | 271 | @param pool The @c FMDatabasePool object. |
| L | 272 | @param database The @c FMDatabase object. |
| 6e1425 | 273 | |
| H | 274 | */ |
| 275 | ||
| 276 | - (void)databasePool:(FMDatabasePool*)pool didAddDatabase:(FMDatabase*)database; | |
| 277 | ||
| 278 | @end | |
| 279 | ||
| 09e73a | 280 | NS_ASSUME_NONNULL_END |
