Clarify BusyHandler usage

[tedrog36]

I am setting Connection.busyTimeout and Connection.busyHandler but don't seem to be able to handle database locking in a particular scenario I am testing. I have two processes connecting to the database. If you look at the iOS device log entries below, I was expecting the times in the busyHandler to be separated by about 5 seconds in time but you can see that are almost all at the same instant. Am I setting this up wrong?

Here is the code for setting up the busyTimeout and busyHandler:

        dateFormatter = DateFormatter()
        dateFormatter.dateFormat = "y-MM-dd H:m:ss.SSSS"
        connection.busyTimeout = 5
        connection.busyHandler({ (tries) -> Bool in
            let date = self.dateFormatter.string(from: Date())
            self.logMessage("busyHandler: tries = \(tries) time = \(date)")
            if (tries >= 5) {
                return false
            }
            return true
        })

Here is what I see in the iOS device log:
Mar 29 09:59:33 FileProvider(libswiftFoundation.dylib)[2296] : busyHandler: tries = 0 time = 2018-03-29 9:59:33.6720
Mar 29 09:59:33 FileProvider(libswiftFoundation.dylib)[2296] : busyHandler: tries = 1 time = 2018-03-29 9:59:33.6720
Mar 29 09:59:33 FileProvider(libswiftFoundation.dylib)[2296] : busyHandler: tries = 2 time = 2018-03-29 9:59:33.6730
Mar 29 09:59:33 FileProvider(libswiftFoundation.dylib)[2296] : busyHandler: tries = 3 time = 2018-03-29 9:59:33.6730
Mar 29 09:59:33 FileProvider(libswiftFoundation.dylib)[2296] : busyHandler: tries = 4 time = 2018-03-29 9:59:33.6730
Mar 29 09:59:33 FileProvider(libswiftFoundation.dylib)[2296] : busyHandler: tries = 5 time = 2018-03-29 9:59:33.6730

Mar 29 09:59:33 FileProvider(libswiftCore.dylib)[2296] : Fatal error: 'try!' expression unexpectedly raised an error: database is locked (code: 5): file /BuildRoot/Library/Caches/com.apple.xbs/Sources/swiftlang/swiftlang-900.0.74.1/src/swift/stdlib/public/core/ErrorType.swift, line 181

[tedrog36]

As I have continued to test I realize that if I don't set a busyHandler, the busyTimeout seems to do the trick. My questions are:

1. How are you supposed to use the busyHandler?
2. Why does the database lock result in a fatal error?

[groue]

I can't speak for SQLite.swift, but generally in SQLite, busy timeouts are a kind of busy handler. So you have to chose: set a busy timeout, or set a custom busy handler. But you can't do both.

For more information, see https://www.sqlite.org/c3ref/busy_timeout.html

[jberkel]

There can only be a single busy handler for a particular database connection at any given moment. If another busy handler was defined (using sqlite3_busy_handler()) prior to calling this routine, that other busy handler is cleared.

Yes, they are two different things but only one is active at a time, this needs clarifying in the documentation