Many hyperlinks are disabled.
Use anonymous login
to enable hyperlinks.
Overview
Comment: | Clarify how the SQLITE_OK_LOAD_PERMANENTLY return value should be used. |
---|---|
Downloads: | Tarball | ZIP archive |
Timelines: | family | ancestors | descendants | both | trunk |
Files: | files | file ages | folders |
SHA3-256: |
8182293dd874305f0c08b5ae1cdf89bb |
User & Date: | drh 2019-02-12 12:27:17.149 |
Context
2019-02-12
| ||
13:54 | Fix a typo in loadext.html. (check-in: 4efb429d19 user: drh tags: trunk) | |
12:27 | Clarify how the SQLITE_OK_LOAD_PERMANENTLY return value should be used. (check-in: 8182293dd8 user: drh tags: trunk) | |
2019-02-11
| ||
13:24 | Fix "asterix" typo in fts5.in. (check-in: 569262e571 user: dan tags: trunk) | |
Changes
Changes to pages/loadext.in.
︙ | ︙ | |||
263 264 265 266 267 268 269 270 271 272 273 274 275 276 | [sqlite3_load_extension()] closes. (In other words, the xDlUnload method of the [sqlite3_vfs] object is called for all extensions when a database connection closes.) However, if the initialization procedure returns [SQLITE_OK_LOAD_PERMANENTLY] instead of SQLITE_OK, then the extension will not be unloaded (xDlClose will not be invoked) and the extension will remain in process memory indefinitely. The SQLITE_OK_LOAD_PERMANENTLY return value is useful for extensions that want to register new [VFSes]. <h1>Statically Linking A Run-Time Loadable Extension</h1> <p>The exact same source code can be used for both a run-time loadable shared library or DLL and as a module that is statically linked with your application. This provides flexibility and allows you to reuse the same code in different ways.</p> | > > > > > > > > > > > > > > > > > > > > > > > > | 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 | [sqlite3_load_extension()] closes. (In other words, the xDlUnload method of the [sqlite3_vfs] object is called for all extensions when a database connection closes.) However, if the initialization procedure returns [SQLITE_OK_LOAD_PERMANENTLY] instead of SQLITE_OK, then the extension will not be unloaded (xDlClose will not be invoked) and the extension will remain in process memory indefinitely. The SQLITE_OK_LOAD_PERMANENTLY return value is useful for extensions that want to register new [VFSes]. <p>To clarify: an extension for which the initialization function returns SQLITE_OK_LOAD_PERMANENTLY continues to exist in memory after the database connection closes. However, the extension is <em>not</em> automatically registered with subsequent database connections. This make it possible to load extensions that implement new [VFSes]. To persistently load and register an extension that implements new SQL functions, collating sequences, and/or virtual tables, such that those added capabilities are available to all subsequent database connections, then the initialization routine should also invoke [sqlite3_auto_extension()] on a subfunction that will register those services. <p>The [https://sqlite.org/src/file/ext/misc/vfsstat.c|vfsstat.c] extension show an example of a loadable extension that persistently registers both a new VFS and a new virtual table. The [https://sqlite.org/src/info/77b5b4235c9f7f11?ln=801-819|sqlite3_vfsstat_init()] initialization routine in that extension is called only once, when the extension is first loaded. It registers the new "vfslog" VFS just that one time, and it returns SQLITE_OK_LOAD_PERMANENTLY so that the code used to implement the "vfslog" VFS will remain in memory. The initialization routine also invokes [sqlite3_auto_extension()] on a pointer to the "vstatRegister()" function so that all subsequent database connections will invoke the "vstatRegister()" function as they start up, and hence register the "vfsstat" virtual table. <h1>Statically Linking A Run-Time Loadable Extension</h1> <p>The exact same source code can be used for both a run-time loadable shared library or DLL and as a module that is statically linked with your application. This provides flexibility and allows you to reuse the same code in different ways.</p> |
︙ | ︙ | |||
292 293 294 295 296 297 298 | connection separately, you might want to consider using the [sqlite3_auto_extension()] interface to register your extensions and to cause them to be automatically started as each database connection is opened. You only have to register each extension once, and you can do so near the beginning of your main() routine. Using the [sqlite3_auto_extension()] interface to register your extensions makes your extensions work as if they were built into the core SQLite - they | | | 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 | connection separately, you might want to consider using the [sqlite3_auto_extension()] interface to register your extensions and to cause them to be automatically started as each database connection is opened. You only have to register each extension once, and you can do so near the beginning of your main() routine. Using the [sqlite3_auto_extension()] interface to register your extensions makes your extensions work as if they were built into the core SQLite - they automatically exist whenever you open a new database connection without needing to be initialized. Just be sure to complete any configuration you need to accomplish using [sqlite3_config()] before registering your extensions, since the [sqlite3_auto_extension()] interface implicitly calls [sqlite3_initialize()].</p> <h1>Implementation Details</h1> |
︙ | ︙ |