**
** ^The xMutexInit method defined by this structure is invoked as
** part of system initialization by the sqlite3_initialize() function.
-** ^The xMutexInit routine is calle by SQLite exactly once for each
+** ^The xMutexInit routine is called by SQLite exactly once for each
** effective call to [sqlite3_initialize()].
**
** ^The xMutexEnd method defined by this structure is invoked as
**
** ^(The [sqlite3_config]([SQLITE_CONFIG_PCACHE], ...) interface can
** register an alternative page cache implementation by passing in an
-** instance of the sqlite3_pcache_methods structure.)^ The majority of the
-** heap memory used by SQLite is used by the page cache to cache data read
-** from, or ready to be written to, the database file. By implementing a
-** custom page cache using this API, an application can control more
-** precisely the amount of memory consumed by SQLite, the way in which
+** instance of the sqlite3_pcache_methods structure.)^
+** In many applications, most of the heap memory allocated by
+** SQLite is used for the page cache.
+** By implementing a
+** custom page cache using this API, an application can better control
+** the amount of memory consumed by SQLite, the way in which
** that memory is allocated and released, and the policies used to
** determine exactly which parts of a database file are cached and for
** how long.
**
+** The alternative page cache mechanism is an
+** extreme measure that is only needed by the most demanding applications.
+** The built-in page cache is recommended for most uses.
+**
** ^(The contents of the sqlite3_pcache_methods 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.)^
**
-** ^The xInit() method is called once for each call to [sqlite3_initialize()]
+** ^(The xInit() method is called once for each effective
+** call to [sqlite3_initialize()])^
** (usually only once during the lifetime of the process). ^(The xInit()
** method is passed a copy of the sqlite3_pcache_methods.pArg value.)^
-** ^The xInit() method can set up up global structures and/or any mutexes
+** The intent of the xInit() method is to set up global data structures
** required by the custom page cache implementation.
+** ^(If the xInit() method is NULL, then the call to
+** [sqlite3_config]([SQLITE_CONFIG_PCACHE],...) will install the
+** built-in default page cache.)^
**
-** ^The xShutdown() method is called from within [sqlite3_shutdown()],
-** if the application invokes this API. It can be used to clean up
+** ^The xShutdown() method is called by [sqlite3_shutdown()].
+** It can be used to clean up
** any outstanding resources before process shutdown, if required.
+** ^The xShutdown() method may be NULL.
**
-** ^SQLite holds a [SQLITE_MUTEX_RECURSIVE] mutex when it invokes
-** the xInit method, so the xInit method need not be threadsafe. ^The
+** ^SQLite automatically serializes calls to the xInit method,
+** so the xInit method need not be threadsafe. ^The
** xShutdown method is only called from [sqlite3_shutdown()] so it does
** not need to be threadsafe either. All other methods must be threadsafe
** in multithreaded applications.
** ^SQLite will never invoke xInit() more than once without an intervening
** call to xShutdown().
**
-** ^The xCreate() method is used to construct a new cache instance. SQLite
-** will typically create one cache instance for each open database file,
+** ^SQLite invokes the xCreate() method to construct a new cache instance.
+** SQLite will typically create one cache instance for each open database file,
** though this is not guaranteed. ^The
** first parameter, szPage, is the size in bytes of the pages that must
** be allocated by the cache. ^szPage will not be a power of two. ^szPage
** will the page size of the database file that is to be cached plus an
-** increment (here called "R") of about 100 or 200. ^SQLite will use the
+** increment (here called "R") of about 100 or 200. SQLite will use the
** extra R bytes on each page to store metadata about the underlying
** database page on disk. The value of R depends
** on the SQLite version, the target platform, and how SQLite was compiled.
** ^R is constant for a particular build of SQLite. ^The second 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. ^The cache implementation
+** false if it is used for an in-memory database. The cache implementation
** does not have to do anything special based with the value of bPurgeable;
** it is purely advisory. ^On a cache where bPurgeable is false, SQLite will
** never invoke xUnpin() except to deliberately delete a page.
-** ^In other words, a cache created with bPurgeable set to false will
+** ^In other words, calls to xUnpin() on a cache with bPurgeable set to
+** false will always have the "discard" flag set to true.
+** ^Hence, a cache created with bPurgeable false will
** never contain any unpinned pages.
**
** ^(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.)^ ^As with the bPurgeable
+** the SQLite "[PRAGMA cache_size]" command.)^ As with the bPurgeable
** parameter, the implementation is not required to do anything with this
** value; it is advisory only.
**
-** ^The xPagecount() method should return the number of pages currently
-** stored in the cache.
+** ^The xPagecount() method must return the number of pages currently
+** stored in the cache, both pinned and unpinned.
**
-** ^The xFetch() method is used to fetch a page and return a pointer to it.
+** ^The xFetch() method locates a page in the cache and returns a pointer to
+** the page, or a NULL pointer.
** ^A 'page', in this context, is a buffer of szPage bytes aligned at an
** 8-byte boundary. ^The page to be fetched is determined by the key. ^The
-** mimimum key value is 1. After it has been retrieved using xFetch, the page
+** mimimum key value is 1. ^After it has been retrieved using xFetch, the page
** is considered to be "pinned".
**
** ^If the requested page is already in the page cache, then the page cache
** </table>)^
**
** SQLite will normally invoke xFetch() with a createFlag of 0 or 1. If
-** a call to xFetch() with createFlag==1 returns NULL, then SQLite will
+** a call to xFetch() with createFlag==1 returns NULL, then SQLite may
** attempt to unpin one or more cache pages by spilling the content of
** pinned pages to disk and synching the operating system disk cache. After
-** attempting to unpin pages, the xFetch() method will be invoked again with
+** attempting to unpin pages, the xFetch() method may be invoked again with
** a createFlag of 2.
**
** ^xUnpin() is called by SQLite with a pointer to a currently pinned page
** as its second argument. ^(If the third parameter, discard, is non-zero,
** then the page should be evicted from the cache. In this case SQLite
** assumes that the next time the page is retrieved from the cache using
-** the xFetch() method, it will be zeroed.)^ ^If the discard parameter is
-** zero, then the page is considered to be unpinned. ^The cache implementation
+** the xFetch() method, it will be zeroed.)^ If the discard parameter is
+** zero, then the page may be discarded or retained at the discretion of
+** page cache implementation. The page cache implementation
** may choose to evict unpinned pages at any time.
**
-** ^(The cache is not required to perform any reference counting. A single
+** ^(The cache must not perform any reference counting. A single
** call to xUnpin() unpins the page regardless of the number of prior calls
** to xFetch().)^
**
** ^The xRekey() method is used to change the key value associated with the
-** page passed as the second argument from oldKey to newKey. ^If the cache
-** previously contains an entry associated with newKey, it should be
+** page passed as the second argument. ^If the cache
+** previously contains an entry associated with newKey, it must be
** discarded. ^Any prior cache entry associated with newKey is guaranteed not
** to be pinned.
**
projects / thirdparty / sqlite.git / commitdiff
