Определенный приложением кэш страницы

typedef struct sqlite3_pcache_methods2 sqlite3_pcache_methods2;
struct sqlite3_pcache_methods2 {
  int iVersion;
  void *pArg;
  int (*xInit)(void*);
  void (*xShutdown)(void*);
  sqlite3_pcache *(*xCreate)(int szPage, int szExtra, int bPurgeable);
  void (*xCachesize)(sqlite3_pcache*, int nCachesize);
  int (*xPagecount)(sqlite3_pcache*);
  sqlite3_pcache_page *(*xFetch)(sqlite3_pcache*, unsigned key, int createFlag);
  void (*xUnpin)(sqlite3_pcache*, sqlite3_pcache_page*, int discard);
  void (*xRekey)(sqlite3_pcache*, sqlite3_pcache_page*,
      unsigned oldKey, unsigned newKey);
  void (*xTruncate)(sqlite3_pcache*, unsigned iLimit);
  void (*xDestroy)(sqlite3_pcache*);
  void (*xShrink)(sqlite3_pcache*);
};

sqlite3_config( SQLITE_CONFIG_PCACHE2, ...) может зарегистрировать альтернативное внедрение кэша страницы, передав в копию структуры sqlite3_pcache_methods2. Во многих запросах большая часть памяти кучи, ассигнованной SQLite, используется для кэша страницы. Осуществляя свой кэш страницы, используя этот API, приложение может лучше управлять объемом памяти, потребляемым SQLite, путем определения, как память ассигнована и освобождена и политикой, определяющей точно, какие части файла базы данных и как долго кэшировать.

Альтернативный механизм кэширования страницы это чрезвычайная мера, которая необходима только большинству требовательных приложений. Встроенный кэш страницы рекомендуется для большей части использования.

Содержание структуры sqlite3_pcache_methods2 копируется к внутреннему буферу SQLite в рамках вызова sqlite3_config. Следовательно применение может отказаться от параметра после вызова sqlite3_config().

Метод xInit() вызывают однажды для каждого эффективного запроса sqlite3_initialize() (обычно только однажды в течение целой жизни процесса). Метод xInit() передает копию значения sqlite3_pcache_methods2.pArg. Цель метода xInit() состоит в том, чтобы настроить глобальные структуры данных, требуемые внедрением кэша страницы. Если xInit() = NULL, то встроенный кэш страницы по умолчанию используется вместо определенного кэша страницы.

Метод xShutdown() вызван sqlite3_shutdown(). Это может использоваться, чтобы очистить любые ресурсы перед закрытием процесса при необходимости. Метод xShutdown() может быть NULL.

SQLite автоматически преобразовывает в последовательную форму вызовы xInit, так что xInit не должен быть ориентирован на многопоточное исполнение. Метод xShutdown вызывают только из sqlite3_shutdown() таким образом, это не должно быть ориентировано на многопоточное исполнение. Все другие методы должны быть ориентированы на многопоточное исполнение в многопоточных средах.

SQLite никогда не будет вызывать xInit() несколько раз без прошедшего xShutdown().

SQLite вызывает xCreate(), чтобы построить новый экземпляр кэша. SQLite будет, как правило, создавать один экземпляр кэша для каждого открытого файла базы данных, хотя это не гарантируется. Первый параметр, szPage, является размером в байтах страниц, которые должны быть ассигнованы кэшом. szPage всегда будет степенью 2. Второй параметр szExtra это число байт дополнительного хранения, связанного с каждой записью кэша страницы. szExtra параметр будет число меньше 250. SQLite будет использовать дополнительные szExtra байты на каждой странице, чтобы сохранить метаданные об основной странице базы данных на диске. Значение, переданное в szExtra, зависит от версии SQLite, целевой платформы и того, как SQLite был собран. Третий аргумент xCreate(), bPurgeable, будет true, если создаваемый кэш создан для страниц базы данных файла, хранимого на диске или false, если это будет использоваться для базы данных в памяти. Внедрение кэша не должно делать что-либо специальное со значением bPurgeable, это чисто консультативное. На кэше, где bPurgeable = false, SQLite никогда не будет вызывать xUnpin() кроме сознательного удаления страницы. Другими словами, xUnpin() на кэше с bPurgeable = false будут всегда устанавливать флаг в true. Следовательно, кэш, созданный с bPurgeable = false, никогда не будет содержать неприкрепленных страниц.

Метод xCachesize() SQLite может вызвать в любое время, чтобы установить предложенный максимальный размер кэша (число сохраненных страниц) экземпляра кэша, переданного как первый аргумент. Это формируемое использование значением SQLite "PRAGMA cache_size". Как с bPurgeable, не требуется делать что-либо с этим значением, это только консультативное.

Метод xPagecount() должен возвратить число страниц, в настоящее время хранимых в кэше, вместе прикрепленных и неприкрепленных.

Метод xFetch() определяет местонахождение страницы в кэше и возвращает указатель на объект sqlite3_pcache_page, связанный с той страницей или NULL. Элемент pBuf возвращенного объекта sqlite3_pcache_page будет указателем на буфер szPage байтов, используемых, чтобы сохранить содержание страницы единой базы данных. Элемент pExtra sqlite3_pcache_page будет указателем на szExtra байты дополнительного хранения, которое SQLite просил для каждой записи в кэше страницы.

Страница, которая будет получена, определяется ключом. Минимальное значение ключа равняется 1. После того, как это было получено, используя xFetch, страница считается "прикрепленной".

Если требуемая страница уже находится в кэше страницы, то внедрение кэша страницы должно возвратить указатель на буфер страницы с его неповрежденным содержанием. Если требуемая страница не находится в кэше, то внедрение кэша должно использовать значение createFlag, чтобы определить действие:

SQLite будет обычно вызывать xFetch() с createFlag = 0 или 1. SQLite будет использовать createFlag = 2 только после предшествующего вызова с createFlag = 1. При промежуточных вызовах xFetch() SQLite может попытаться не прикреплять одну или более страниц кэша, сбросив содержание прикрепленных страниц на диск и синхронизируя дисковый кэш операционной системы.

xUnpin() вызван SQLite с указателем на в настоящее время прикрепляемую страницу как ее второй аргумент. Если третий параметр discard не 0, то страница должна быть выселена из кэша. Если параметр discard = 0, то от страницы можно отказаться или сохранить на усмотрение внедрения кэша страницы. Внедрение кэша страницы может выселить неприкрепленные страницы в любое время.

Кэш не должен выполнять подсчет ссылок. Единственный запрос к xUnpin() не прикрепляет страницу независимо от количества предшествующих вызовов xFetch().

Метод xRekey() используется, чтобы изменить значение ключа, связанное со страницей, переданной как второй аргумент. Если кэш ранее содержит вход, связанный с newKey, от него нужно отказаться. Любая предшествующая запись кэша, связанная с newKey, как гарантируют, не будет прикреплена.

Когда SQLite вызывает xTruncate(), кэш должен отказаться от всех существующих записей кэша с номерами страниц (ключами) больше или равных iLimit, переданному xTruncate(). Если какая-либо из этих страниц прикреплена, они неявно не прикреплены, означая, что от них можно безопасно отказаться.

xDestroy() используется, чтобы удалить кэш, ассигнованный xCreate(). Должны быть освобождены все ресурсы, связанные с указанным кэшом. После запроса xDestroy() SQLite рассматривает обработчик sqlite3_pcache* как нгеправильный и не будет использовать его ни с какими другими функциями sqlite3_pcache_methods2.

SQLite вызывает xShrink(), когда это хочет освободить из кэша страницы как можно больше памяти кучи. Внедрение кэша страницы не обязано освободить память, но внедрения хорошего поведения должны приложить все усилия.