【原】FMDB源码阅读（一）

NSString* docsdir = [NSSearchPathForDirectoriesInDomains( NSDocumentDirectory, NSUserDomainMask, YES) lastObject];

// 将user.sqlite放到Documents文件夹下，并生成user.sqlite的绝对路径
NSString* dbpath = [docsdir stringByAppendingPathComponent:@"user.sqlite"];

// 根据user.sqlite的绝对路径获取到一个FMDatabase对象，其实就是一个封装了的SQLite数据库对象
FMDatabase* db = [FMDatabase databaseWithPath:dbpath];

// 打开该数据库
[db open];

// 执行SQL语句 - select * from people
FMResultSet *rs = [db

executeQuery

:@"select * from people"];

// 利用next函数，循环输出结果
while ([rs next]) {
NSLog(@"%@ %@",
[rs stringForColumn:@"firstname"],
[rs stringForColumn:@"lastname"]);
}

// 关闭该数据库
[db close];

// 核心其实还是调用了+[FMDataBase initWithPath:]函数，下面会详解
+ (instancetype)databaseWithPath:(NSString*)aPath {
// FMDBReturnAutoReleased是为了让FMDB兼容MRC和ARC，具体细节看下其宏定义就明白了
return FMDBReturnAutoreleased([[self alloc] initWithPath:aPath]);
}/** 初始化一个FMDataBase对象
根据path（aPath）来创建一个SQLite数据库。对应的aPath参数有三种情形: 1. 数据库文件路径：不为空字符串，不为nil。如果该文件路径不存在，那么SQLite会给你新建一个

2. 空字符串@""：将在外存临时给你创建一个空的数据库，并且如果该数据库连接释放，那么对应数据库会自动删除

3. nil：会在内存中创建数据库，随着该数据库连接的释放，也会释放该数据库。
*/
- (instancetype)initWithPath:(NSString*)aPath {
// SQLite支持三种线程模式，sqlite3_threadsafe()函数的返回值可以确定编译时指定的线程模式。

// 三种模式分别为1.单线程模式 2.多线程模式 3.串行模式 其中对于单线程模式，sqlite3_threadsafe()返回false

// 对于另外两个模式，则返回true。这是因为单线程模式下没有进行互斥（mutex），所以多线程下是不安全的
assert(sqlite3_threadsafe());
self = [super init];
// 很多属性后面再提。不过这里值得注意的是_db居然赋值为nil，也就是说真正构建_db不是在initWithPath:这个函数中，这里透露下，其实作者是将构建部分代码放到了open函数中if (self) {
_databasePath = [aPath copy];
_openResultSets = [[NSMutableSet alloc] init];
_db = nil;
_logsErrors = YES;
_crashOnErrors = NO;
_maxBusyRetryTimeInterval = ;
} return self;
}

- (BOOL)open {
if (_db) {
return YES;
} int err = sqlite3_open([self sqlitePath], (sqlite3**)&_db );
if(err != SQLITE_OK) {
NSLog(@"error opening!: %d", err);
return NO;
}
// 若_maxBusyRetryTimeInterval大于0，那么就调用setMaxBusyRetryTimeInterval:函数
// setMaxBusyRetryTimeInterval:函数主要是调用sqlite3_busy_handler来处理其他线程已经在操作数据库的情况，默认_maxBusyRetryTimeInterval为2。

// 具体该参数有什么用，下面在FMDBDatabaseBusyHandler函数中会详解。
if (_maxBusyRetryTimeInterval > 0.0) {
[self setMaxBusyRetryTimeInterval:_maxBusyRetryTimeInterval];
} return YES;
}- (void)setMaxBusyRetryTimeInterval:(NSTimeInterval)timeout { _maxBusyRetryTimeInterval = timeout; if (!_db) {
return;
}
// 处理的handler设置为FMDBDatabaseBusyHandler这个函数
if (timeout > ) {
sqlite3_busy_handler(_db, &FMDBDatabaseBusyHandler, (__bridge void *)(self));
}
else {
// 不使用任何busy handler处理
sqlite3_busy_handler(_db, nil, nil);
}
}

// 注意：appledoc（生成文档的软件）中，对于有具体实现的C函数，比如下面这个函数，
// 是有bug的。所以你在生成文档时，忽略.m文件。// 该函数就是简单调用sqlite3_sleep来挂起进程
static int FMDBDatabaseBusyHandler(void *f, int count) {
FMDatabase *self = (__bridge FMDatabase*)f;
// 如果count为0，表示的第一次执行回调函数
// 初始化self->_startBusyRetryTime，供后面计算delta使用
if (count == ) {
self->_startBusyRetryTime = [NSDate timeIntervalSinceReferenceDate];
return ;
}
// 使用delta变量控制执行回调函数的次数，每次挂起50~100ms
// 所以maxBusyRetryTimeInterval的作用就在这体现出来了
// 当挂起的时长大于maxBusyRetryTimeInterval，就返回0，并停止执行该回调函数了
NSTimeInterval delta = [NSDate timeIntervalSinceReferenceDate] - (self->_startBusyRetryTime); if (delta < [self maxBusyRetryTimeInterval]) {
// 使用sqlite3_sleep每次当前线程挂起50~100ms
int requestedSleepInMillseconds = (int) arc4random_uniform() + ;
int actualSleepInMilliseconds = sqlite3_sleep(requestedSleepInMillseconds);
// 如果实际挂起的时长与想要挂起的时长不一致，可能是因为构建SQLite时没将HAVE_USLEEP置为1
if (actualSleepInMilliseconds != requestedSleepInMillseconds) {
NSLog(@"WARNING: Requested sleep of %i milliseconds, but SQLite returned %i. Maybe SQLite wasn't built with HAVE_USLEEP=1?", requestedSleepInMillseconds, actualSleepInMilliseconds);
}
return ;
} return ;
}

- (FMResultSet *)executeQuery:(NSString *)sql withArgumentsInArray:(NSArray*)arrayArgs orDictionary:(NSDictionary *)dictionaryArgs orVAList:(va_list)args {
// 判断当前是否存在数据库以供操作
if (![self databaseExists]) {
return 0x00;
}
// 如果当前线程已经在使用数据库了，那就输出正在使用的警告
if (_isExecutingStatement) {
[self warnInUse];
return 0x00;
} _isExecutingStatement = YES; int rc = 0x00;
sqlite3_stmt *pStmt = 0x00; // sqlite的prepared语句类型
FMStatement *statement = 0x00; // 对sqlite3_stmt的简单封装，在实际应用中，你不应直接操作FMStatement对象
FMResultSet *rs = 0x00; // FMResultSet对象是用来获取最终查询结果的
// 需要追踪sql执行状态的话，输出执行状态
if (_traceExecution && sql) {
NSLog(@"%@ executeQuery: %@", self, sql);
}
// 调用sql语句之前，首先要将sql字符串预处理一下，转化为SQLite可用的prepared语句（预处理语句）
// 使用sqlite3_prepare_v2来生成sql对应的prepare语句（即pStmt）代价很大
// 所以建议使用缓存机制来减少对sqlite3_prepare_v2的使用
if (_shouldCacheStatements) {
// 获取到缓存中的prepared语句
statement = [self cachedStatementForQuery:sql];
pStmt = statement ? [statement statement] : 0x00;
// prepared语句可以被重置（调用sqlite3_reset函数），然后可以重新绑定参数以便重新执行。
[statement reset];
}
// 如果缓存中没有sql对应的prepared语句，那么只能使用sqlite3_prepare_v2函数进行预处理
if (!pStmt) { rc = sqlite3_prepare_v2(_db, [sql UTF8String], -, &pStmt, );
// 如果生成prepared语句出错，那么就根据是否需要打印错误信息(_logsErrors)以及是否遇到错误直接中止程序执行(_crashOnErrors)来执行出错处理。
// 最后调用sqlite3_finalize函数释放所有的内部资源和sqlite3_stmt数据结构，有效删除prepared语句。
if (SQLITE_OK != rc) {
if (_logsErrors) {
NSLog(@"DB Error: %d \"%@\"", [self lastErrorCode], [self lastErrorMessage]);
NSLog(@"DB Query: %@", sql);
NSLog(@"DB Path: %@", _databasePath);
} if (_crashOnErrors) {
NSAssert(false, @"DB Error: %d \"%@\"", [self lastErrorCode], [self lastErrorMessage]);
// abort()函数表示中止程序执行，直接从调用的地方跳出。
abort();
} sqlite3_finalize(pStmt);
_isExecutingStatement = NO;
return nil;
}
} id obj;
int idx = ;
// 获取到pStmt中需要绑定的参数个数
int queryCount = sqlite3_bind_parameter_count(pStmt); // pointed out by Dominic Yu (thanks!) // 举一个使用dictionaryArgs的例子

/**

NSMutableDictionary

*dictionaryArgs = [NSMutableDictionary dictionary]; [dictionaryArgs setObject:@"Text1" forKey:@"a"]; [db executeQuery:@"select * from namedparamcounttest where a = :a" withParameterDictionary:dictionaryArgs]; // 注意类似:AAA前面有冒号的就是参数 // 其他的参数形式如："?", "?NNN", ":AAA", "$AAA", 或 "@AAA" */

if (dictionaryArgs) { for (NSString *dictionaryKey in [dictionaryArgs allKeys]) { // 在每个dictionaryKey之前加上冒号，比如上面的a -> :a，方便获取参数在prepared语句中的索引
NSString *parameterName = [[NSString alloc] initWithFormat:@":%@", dictionaryKey];
// 查看执行状况
if (_traceExecution) {
NSLog(@"%@ = %@", parameterName, [dictionaryArgs objectForKey:dictionaryKey]);
} // 在prepared语句中查找对应parameterName的参数索引值namedIdx
int namedIdx = sqlite3_bind_parameter_index(pStmt, [parameterName UTF8String]); FMDBRelease(parameterName);
// 可以利用索引namedIdx获取对应参数，再使用bindObject:函数将dictionaryArgs保存的value绑定给对应参数
if (namedIdx > ) {
[self bindObject:[dictionaryArgs objectForKey:dictionaryKey] toColumn:namedIdx inStatement:pStmt];
// 使用这个idx来判断sql中的所有参数值是否都绑定上了
idx++;
}
else {
NSLog(@"Could not find index for %@", dictionaryKey);
}
}
}
else { while (idx < queryCount) {
// 使用arrayArgs的例子
/**
[db executeQuery:@"insert into testOneHundredTwelvePointTwo values (?, ?)" withArgumentsInArray:[NSArray arrayWithObjects:@"one", [NSNumber numberWithInteger:2], nil]];
*/
if (arrayArgs && idx < (int)[arrayArgs count]) {
obj = [arrayArgs objectAtIndex:(NSUInteger)idx];
}
// 使用args的例子，使用args其实就是调用- (FMResultSet *)executeQuery:(NSString*)sql, ...;
/**
FMResultSet *rs = [db executeQuery:@"select rowid,* from test where a = ?", @"hi'"];
*/
else if (args) {
obj = va_arg(args, id);
}
else {
break;
} if (_traceExecution) {
if ([obj isKindOfClass:[NSData class]]) {
NSLog(@"data: %ld bytes", (unsigned long)[(NSData*)obj length]);
}
else {
NSLog(@"obj: %@", obj);
}
} idx++;
// 绑定参数值
[self bindObject:obj toColumn:idx inStatement:pStmt];
}
}
// 如果绑定的参数数目不对，认为出错，并释放资源
if (idx != queryCount) {
NSLog(@"Error: the bind count is not correct for the # of variables (executeQuery)");
sqlite3_finalize(pStmt);
_isExecutingStatement = NO;
return nil;
} FMDBRetain(statement); // to balance the release below
// statement不为空，进行缓存
if (!statement) {
statement = [[FMStatement alloc] init];
[statement setStatement:pStmt];
// 使用sql作为key来缓存statement（即sql对应的prepare语句）
if (_shouldCacheStatements && sql) {
[self setCachedStatement:statement forQuery:sql];
}
} // 根据statement和self（FMDatabase对象）构建一个FMResultSet对象，此函数中仅仅是构建该对象，还没使用next等函数获取查询结果
// 注意FMResultSet中含有以下成员（除了最后一个，其他成员均在此处初始化过了）
/**
@interface FMResultSet : NSObject {
FMDatabase *_parentDB; // 表示该对象查询的数据库，主要是为了能在FMResultSet自己的函数中索引到正在操作的FMDatabase对象
FMStatement *_statement; // prepared语句 NSString *_query; // 对应的sql查询语句
NSMutableDictionary *_columnNameToIndexMap;
}
*/
rs = [FMResultSet resultSetWithStatement:statement usingParentDatabase:self];
[rs setQuery:sql];
// 将此时的FMResultSet对象添加_openResultSets，主要是为了调试
NSValue *openResultSet = [NSValue valueWithNonretainedObject:rs];
[_openResultSets addObject:openResultSet];
// 并设置statement的使用数目useCount加1，暂时不清楚此成员有何作用，感觉也是用于调试
[statement setUseCount:[statement useCount] + ]; FMDBRelease(statement);
// 生成statement的操作已经结束
_isExecutingStatement = NO; return rs;
}

// 返回YES表示从数据库中获取到了下一行数据
- (BOOL)nextWithError:(NSError **)outErr {
// 尝试步进到下一行
int rc = sqlite3_step([_statement statement]); // 对返回结果rc进行处理 /**
SQLITE_BUSY 数据库文件有锁
SQLITE_LOCKED 数据库中的某张表有锁
SQLITE_DONE sqlite3_step()执行完毕
SQLITE_ROW sqlite3_step()获取到下一行数据
SQLITE_ERROR 一般用于没有特别指定错误码的错误，就是说函数在执行过程中发生了错误，但无法知道错误发生的原因。
SQLITE_MISUSE 没有正确使用SQLite接口，比如一条语句在sqlite3_step函数执行之后，没有被重置之前，再次给其绑定参数，这时bind函数就会返回SQLITE_MISUSE。
*/
if (SQLITE_BUSY == rc || SQLITE_LOCKED == rc) {
NSLog(@"%s:%d Database busy (%@)", __FUNCTION__, __LINE__, [_parentDB databasePath]);
NSLog(@"Database busy");
if (outErr) {
// lastError使用sqlite3_errcode获取到错误码，封装成NSError对象返回
*outErr = [_parentDB lastError];
}
}
else if (SQLITE_DONE == rc || SQLITE_ROW == rc) {
// all is well, let's return.
}
else if (SQLITE_ERROR == rc) {
// sqliteHandle就是获取到对应FMDatabase对象，然后使用sqlite3_errmsg来获取错误码的字符串
NSLog(@"Error calling sqlite3_step (%d: %s) rs", rc, sqlite3_errmsg([_parentDB sqliteHandle]));
if (outErr) {
*outErr = [_parentDB lastError];
}
}
else if (SQLITE_MISUSE == rc) {
// uh oh.
NSLog(@"Error calling sqlite3_step (%d: %s) rs", rc, sqlite3_errmsg([_parentDB sqliteHandle]));
if (outErr) {
if (_parentDB) {
*outErr = [_parentDB lastError];
}
else {
// 如果next和nextWithError函数是在当前的FMResultSet关闭之后调用的
// 这时输出的错误信息应该是parentDB不存在
NSDictionary* errorMessage = [NSDictionary dictionaryWithObject:@"parentDB does not exist" forKey:NSLocalizedDescriptionKey];
*outErr = [NSError errorWithDomain:@"FMDatabase" code:SQLITE_MISUSE userInfo:errorMessage];
} }
}
else {
// wtf?
NSLog(@"Unknown error calling sqlite3_step (%d: %s) rs", rc, sqlite3_errmsg([_parentDB sqliteHandle]));
if (outErr) {
*outErr = [_parentDB lastError];
}
} // 如果不是读取下一行数据，那么就关闭数据库
if (rc != SQLITE_ROW) {
[self close];
} return (rc == SQLITE_ROW);
}

- (BOOL)close {
// 清除缓存的prepared语句，下面会详解
[self clearCachedStatements];
// 关闭所有打开的FMResultSet对象，目前看来这个_openResultSets大概也是用来调试的
[self closeOpenResultSets]; if (!_db) {
return YES;
} int rc;
BOOL retry;
BOOL triedFinalizingOpenStatements = NO; do {
retry = NO;

// 调用sqlite3_close来尝试关闭数据库
rc = sqlite3_close(_db);

//如果当前数据库上锁，那么就先尝试重新关闭（置retry为YES） // 同时还尝试释放数据库中的prepared语句资源

if (SQLITE_BUSY == rc || SQLITE_LOCKED == rc) {
if (!triedFinalizingOpenStatements) {
triedFinalizingOpenStatements = YES;
sqlite3_stmt *pStmt;

// sqlite3_next_stmt(sqlite3 *pDb, sqlite3_stmt *pStmt

)表示从数据库pDb中对应的pStmt语句开始一个个往下找出相应prepared语句，如果pStmt为nil，那么就从pDb的第一个prepared语句开始。

// 此处迭代找到数据库中所有prepared语句，释放其资源。
while ((pStmt = sqlite3_next_stmt(_db, nil)) !=) {
NSLog(@"Closing leaked statement");
sqlite3_finalize(pStmt);
retry = YES;
}
}
}

// 关闭出错，输出错误码
else if (SQLITE_OK != rc) {
NSLog(@"error closing!: %d", rc);
}
}
while (retry); _db = nil;
return YES;
}// _cachedStatements是用来缓存prepared语句的，所以清空_cachedStatements就是将每个缓存的prepared语句释放

// 具体实现就是使用下面那个close函数，close函数中调用了sqlite_finalize函数释放资源
- (void)clearCachedStatements { for (NSMutableSet *statements in [_cachedStatements objectEnumerator]) {
// makeObjectsPerformSelector会并发执行同一件事，所以效率比for循环一个个执行要快很多
[statements makeObjectsPerformSelector:@selector(close)];
} [_cachedStatements removeAllObjects];
}
// 注意：此为FMResultSet的close函数
- (void)close {
if (_statement) {
sqlite3_finalize(_statement);
_statement = 0x00;
} _inUse = NO;
}

// 清除_openResultSets

- (void)closeOpenResultSets {
//Copy the set so we don't get mutation errors
NSSet *openSetCopy = FMDBReturnAutoreleased([_openResultSets copy]);

// 迭代关闭_openResultSets中的FMResultSet对象
for (NSValue *rsInWrappedInATastyValueMeal in openSetCopy) {
FMResultSet *rs = (FMResultSet *)[rsInWrappedInATastyValueMeal pointerValue];
// 清除FMResultSet的操作
[rs setParentDB:nil];
[rs close]; [_openResultSets removeObject:rsInWrappedInATastyValueMeal];
}
}