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