*** DRAFT ***

SQLite Requirement Matrix Details
pcache_methods2.html

Index Summary Markup Original

R-26704-30334-42154-41889-16850-21412-27655-04243 tcl slt th3 src

The sqlite3_config(SQLITE_CONFIG_PCACHE2, ...) interface can register an alternative page cache implementation by passing in an instance of the sqlite3_pcache_methods2 structure.

/* IMP: R-26704-30334 */

# EVIDENCE-OF: R-26704-30334 The sqlite3_config(SQLITE_CONFIG_PCACHE2,
# ...) interface can register an alternative page cache implementation
# by passing in an instance of the sqlite3_pcache_methods2 structure.

R-44617-07829-03757-45608-53499-18988-55260-02741 tcl slt th3 src

The contents of the sqlite3_pcache_methods2 structure are copied to an internal buffer by SQLite within the call to sqlite3_config. Hence the application may discard the parameter after the call to sqlite3_config() returns.

/* IMP: R-44617-07829 */

# EVIDENCE-OF: R-44617-07829 The contents of the sqlite3_pcache_methods2
# structure are copied to an internal buffer by SQLite within the call
# to sqlite3_config. Hence the application may discard the parameter
# after the call to sqlite3_config() returns.

R-58778-10776-22890-25642-31473-47803-35763-23177 tcl slt th3 src

The xInit() method is called once for each effective call to sqlite3_initialize()

th3/th3pcache.c:50

/* IMP: R-58778-10776 */

# EVIDENCE-OF: R-58778-10776 The xInit() method is called once for each
# effective call to sqlite3_initialize()

R-25963-03527-53793-34841-03007-31919-23816-21204 tcl slt th3 src

The xInit() method is passed a copy of the sqlite3_pcache_methods2.pArg value.

th3/th3pcache.c:46

/* IMP: R-25963-03527 */

# EVIDENCE-OF: R-25963-03527 The xInit() method is passed a copy of the
# sqlite3_pcache_methods2.pArg value.

R-26801-64137-39079-48164-16524-44855-40563-04540 tcl slt th3 src

If the xInit() method is NULL, then the built-in default page cache is used instead of the application defined page cache.

src/pcache.c:288

/* IMP: R-26801-64137 */

# EVIDENCE-OF: R-26801-64137 If the xInit() method is NULL, then the
# built-in default page cache is used instead of the application defined
# page cache.

R-08161-44559-11294-25208-33337-24402-63584-35626 tcl slt th3 src

The xShutdown() method is called by sqlite3_shutdown().

/* IMP: R-08161-44559 */

# EVIDENCE-OF: R-08161-44559 The xShutdown() method is called by
# sqlite3_shutdown().

R-26000-56589-64657-09406-12178-15033-38154-19492 tcl slt th3 src

The xShutdown() method may be NULL.

src/pcache.c:298

/* IMP: R-26000-56589 */

# EVIDENCE-OF: R-26000-56589 The xShutdown() method may be NULL.

R-00140-37445-57377-20863-40395-21152-20469-25306 tcl slt th3 src

SQLite automatically serializes calls to the xInit method, so the xInit method need not be threadsafe.

src/main.c:280

/* IMP: R-00140-37445 */

# EVIDENCE-OF: R-00140-37445 SQLite automatically serializes calls to
# the xInit method, so the xInit method need not be threadsafe.

R-14854-58090-42318-16758-11511-55845-43125-55221 tcl slt th3 src

The xShutdown method is only called from sqlite3_shutdown() so it does not need to be threadsafe either.

/* IMP: R-14854-58090 */

# EVIDENCE-OF: R-14854-58090 The xShutdown method is only called from
# sqlite3_shutdown() so it does not need to be threadsafe either.

R-25048-46581-04940-52749-02967-51891-39439-41238 tcl slt th3 src

SQLite will never invoke xInit() more than once without an intervening call to xShutdown().

th3/th3pcache.c:53

/* IMP: R-25048-46581 */

# EVIDENCE-OF: R-25048-46581 SQLite will never invoke xInit() more than
# once without an intervening call to xShutdown().

R-61888-49680-38370-22600-14954-58148-33546-00932 tcl slt th3 src

SQLite invokes the xCreate() method to construct a new cache instance.

/* IMP: R-61888-49680 */

# EVIDENCE-OF: R-61888-49680 SQLite invokes the xCreate() method to
# construct a new cache instance.

R-33368-33178-21159-57347-39405-35254-59100-49447 tcl slt th3 src

The first parameter, szPage, is the size in bytes of the pages that must be allocated by the cache.

th3/th3pcache.c:183

/* IMP: R-33368-33178 */

# EVIDENCE-OF: R-33368-33178 The first parameter, szPage, is the size in
# bytes of the pages that must be allocated by the cache.

R-11062-21931-47759-21146-52801-65238-28754-37817 tcl slt th3 src

szPage will always a power of two.

/* IMP: R-11062-21931 */

# EVIDENCE-OF: R-11062-21931 szPage will always a power of two.

R-42757-24221-43746-48434-02480-64556-26113-38051 tcl slt th3 src

The second parameter szExtra is a number of bytes of extra storage associated with each page cache entry.

/* IMP: R-42757-24221 */

# EVIDENCE-OF: R-42757-24221 The second parameter szExtra is a number of
# bytes of extra storage associated with each page cache entry.

R-38989-21359-13709-49366-18905-24783-41677-06526 tcl slt th3 src

The szExtra parameter will a number less than 250.

/* IMP: R-38989-21359 */

# EVIDENCE-OF: R-38989-21359 The szExtra parameter will a number less
# than 250.

R-39086-42574-52066-34566-03603-26293-15630-13712 tcl slt th3 src

The third argument to xCreate(), bPurgeable, is true if the cache being created will be used to cache database pages of a file stored on disk, or false if it is used for an in-memory database.

/* IMP: R-39086-42574 */

# EVIDENCE-OF: R-39086-42574 The third argument to xCreate(),
# bPurgeable, is true if the cache being created will be used to cache
# database pages of a file stored on disk, or false if it is used for an
# in-memory database.

R-39150-60222-54489-42043-19266-00482-07233-17932 tcl slt th3 src

On a cache where bPurgeable is false, SQLite will never invoke xUnpin() except to deliberately delete a page.

th3/th3pcache.c:395

/* IMP: R-39150-60222 */

# EVIDENCE-OF: R-39150-60222 On a cache where bPurgeable is false,
# SQLite will never invoke xUnpin() except to deliberately delete a
# page.

R-38083-64261-20639-49699-39897-18481-13344-23243 tcl slt th3 src

In other words, calls to xUnpin() on a cache with bPurgeable set to false will always have the "discard" flag set to true.

/* IMP: R-38083-64261 */

# EVIDENCE-OF: R-38083-64261 In other words, calls to xUnpin() on a
# cache with bPurgeable set to false will always have the "discard" flag
# set to true.

R-18962-08090-15768-27249-44223-08875-09432-04987 tcl slt th3 src

Hence, a cache created with bPurgeable false will never contain any unpinned pages.

/* IMP: R-18962-08090 */

# EVIDENCE-OF: R-18962-08090 Hence, a cache created with bPurgeable
# false will never contain any unpinned pages.

R-54971-39725-56830-50400-02582-07563-61018-15429 tcl slt th3 src

The xCachesize() method may be called at any time by SQLite to set the suggested maximum cache-size (number of pages stored by) the cache instance passed as the first argument. This is the value configured using the SQLite "PRAGMA cache_size" command.

/* IMP: R-54971-39725 */

# EVIDENCE-OF: R-54971-39725 The xCachesize() method may be called at
# any time by SQLite to set the suggested maximum cache-size (number of
# pages stored by) the cache instance passed as the first argument. This
# is the value configured using the SQLite "PRAGMA cache_size" command.

R-54020-18969-35305-43404-58494-09530-16898-08730 tcl slt th3 src

The minimum key value is 1.

th3/th3pcache.c:298

/* IMP: R-54020-18969 */

# EVIDENCE-OF: R-54020-18969 The minimum key value is 1.

R-65343-41028-54070-29515-00373-53952-30391-17078 tcl slt th3 src

SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite will only use a createFlag of 2 after a prior call with a createFlag of 1 failed.

/* IMP: R-65343-41028 */

# EVIDENCE-OF: R-65343-41028 SQLite will normally invoke xFetch() with a
# createFlag of 0 or 1. SQLite will only use a createFlag of 2 after a
# prior call with a createFlag of 1 failed.

R-01587-15367-52926-43879-39292-01582-45706-36467 tcl slt th3 src

xUnpin() is called by SQLite with a pointer to a currently pinned page as its second argument.

/* IMP: R-01587-15367 */

# EVIDENCE-OF: R-01587-15367 xUnpin() is called by SQLite with a pointer
# to a currently pinned page as its second argument.

R-09782-32948-24767-08594-36498-62288-40921-54378 tcl slt th3 src

If the discard parameter is zero, then the page may be discarded or retained at the discretion of page cache implementation.

/* IMP: R-09782-32948 */

# EVIDENCE-OF: R-09782-32948 If the discard parameter is zero, then the
# page may be discarded or retained at the discretion of page cache
# implementation.

R-48333-48208-51802-16528-34605-32533-04815-58648 tcl slt th3 src

The page cache implementation may choose to evict unpinned pages at any time.

/* IMP: R-48333-48208 */

# EVIDENCE-OF: R-48333-48208 The page cache implementation may choose to
# evict unpinned pages at any time.

R-27935-58314-00156-50891-26988-61472-07043-33985 tcl slt th3 src

Any prior cache entry associated with newKey is guaranteed not to be pinned.

/* IMP: R-27935-58314 */

# EVIDENCE-OF: R-27935-58314 Any prior cache entry associated with
# newKey is guaranteed not to be pinned.

R-19808-29370-64330-18475-42910-48751-21092-02221 tcl slt th3 src

The xDestroy() method is used to delete a cache allocated by xCreate().

th3/th3pcache.c:533

/* IMP: R-19808-29370 */

# EVIDENCE-OF: R-19808-29370 The xDestroy() method is used to delete a
# cache allocated by xCreate().

R-30617-11336-33984-38056-06680-32424-07593-35065 tcl slt th3 src

After calling the xDestroy() method, SQLite considers the sqlite3_pcache* handle invalid, and will not use it with any other sqlite3_pcache_methods2 functions.

th3/th3pcache.c:542

/* IMP: R-30617-11336 */

# EVIDENCE-OF: R-30617-11336 After calling the xDestroy() method, SQLite
# considers the sqlite3_pcache* handle invalid, and will not use it with
# any other sqlite3_pcache_methods2 functions.

R-44990-49065-20422-08324-27654-16812-49799-14821 tcl slt th3 src

SQLite invokes the xShrink() method when it wants the page cache to free up as much of heap memory as possible.

/* IMP: R-44990-49065 */

# EVIDENCE-OF: R-44990-49065 SQLite invokes the xShrink() method when it
# wants the page cache to free up as much of heap memory as possible.

SQLite Requirement Matrix Details pcache_methods2.html

Index Summary Markup Original

SQLite Requirement Matrix Details
pcache_methods2.html