SQLite Forum

Documentation improvement: sqlite3_close_v2

Documentation improvement: sqlite3_close_v2

(1) By anonymous on 2020-04-30 23:39:44 [link] [source]

To the kind sqlite3 community,

It is written that:
"If sqlite3_close_v2() is called on a database connection that still has outstanding prepared statements, BLOB handles, and/or sqlite3_backup objects then it returns SQLITE_OK and the deallocation of resources is deferred until all prepared statements, BLOB handles, and sqlite3_backup objects are also destroyed."
-- https://www.sqlite.org/c3ref/close.html

The question here is: does sqlite3_close_v2() hang until these resources are cleaned up? Or does it immediately return and should I wait before terminating my program (via exit() or otherwise)?

Key takeaways from this seem to be:
* The documentation should be improved to state the blocking policy of sqlite3_close_v2() under "outstanding prepared statements" conditions.
* Perhaps the documentation may benefit from more traditional manpage-like "return value" sections? (Wiser minds may correct this one.)

Kind regards,

(2.1) By Larry Brasfield (LarryBrasfield) on 2020-05-01 00:34:26 edited from 2.0 in reply to 1 [source]

I see no ambiguity in the language you quoted. There are API routines for disposing of the objects (sqlite3_blob_close(), sqlite3_finalize(), sqlite3_backup_finish()), and when those are eventually called on all such objects associated with a connection, the library will, in addition to deallocating those specific resources (or resource holders), do what sqlite3_close_v2() would have done if those objects had not been outstanding. That's the promise, as I read it.

It is a convenience that the order in which those 4 done-with-this routines are called is not forced. And in some environments, (such as C++ where the resources are often held in objects and released upon destructor calls), the order of release can be tedious or difficult to arrange.

The document you quote would be lying if sqlite3_close_v2() were to simply hang until, presumably, some other thread got around to disposing of those other objects.

What do you think would make that return promise more clear, without going into the implementation details that have no place in interface documentation?

Your obligations, (assuming you wish to avoid leaking memory and file handles), are simple: for each created instance of those 4 object types, (connection, blob handle, statement, backup object), call their associated done-with-this routine, in any order you like, without using them afterward. No such call will hang.

(3) By Larry Brasfield (LarryBrasfield) on 2020-05-01 18:54:51 in reply to 1 [link] [source]

You might take a look at this recent clarification of the documentation, which should soon make its way into the published docs.