Потоковые версии функций API

Потоковые версии функций API

int sqlite3changeset_apply_strm(
  sqlite3 *db,                    /* Apply change to "main" db of this handle */
  int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
  void *pIn,                                          /* First arg for xInput */
  int(*xFilter)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    const char *zTab              /* Table name */
  ),
  int(*xConflict)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
    sqlite3_changeset_iter *p     /* Handle describing change and conflict */
  ),
  void *pCtx                      /* First argument passed to xConflict */
);
int sqlite3changeset_apply_v2_strm(
  sqlite3 *db,                    /* Apply change to "main" db of this handle */
  int (*xInput)(void *pIn, void *pData, int *pnData), /* Input function */
  void *pIn,                                          /* First arg for xInput */
  int(*xFilter)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    const char *zTab              /* Table name */
  ),
  int(*xConflict)(
    void *pCtx,                   /* Copy of sixth arg to _apply() */
    int eConflict,                /* DATA, MISSING, CONFLICT, CONSTRAINT */
    sqlite3_changeset_iter *p     /* Handle describing change and conflict */
  ),
  void *pCtx,                     /* First argument passed to xConflict */
  void **ppRebase, int *pnRebase,
  int flags
);
int sqlite3changeset_concat_strm(
  int (*xInputA)(void *pIn, void *pData, int *pnData),
  void *pInA,
  int (*xInputB)(void *pIn, void *pData, int *pnData),
  void *pInB,
  int (*xOutput)(void *pOut, const void *pData, int nData),
  void *pOut
);
int sqlite3changeset_invert_strm(
  int (*xInput)(void *pIn, void *pData, int *pnData),
  void *pIn,
  int (*xOutput)(void *pOut, const void *pData, int nData),
  void *pOut
);
int sqlite3changeset_start_strm(
  sqlite3_changeset_iter **pp,
  int (*xInput)(void *pIn, void *pData, int *pnData),
  void *pIn
);
int sqlite3changeset_start_v2_strm(
  sqlite3_changeset_iter **pp,
  int (*xInput)(void *pIn, void *pData, int *pnData),
  void *pIn,
  int flags
);
int sqlite3session_changeset_strm(
  sqlite3_session *pSession,
  int (*xOutput)(void *pOut, const void *pData, int nData),
  void *pOut
);
int sqlite3session_patchset_strm(
  sqlite3_session *pSession,
  int (*xOutput)(void *pOut, const void *pData, int nData),
  void *pOut
);
int sqlite3changegroup_add_strm(sqlite3_changegroup*, 
    int (*xInput)(void *pIn, void *pData, int *pnData),
    void *pIn
);
int sqlite3changegroup_output_strm(sqlite3_changegroup*,
    int (*xOutput)(void *pOut, const void *pData, int nData), 
    void *pOut
);
int sqlite3rebaser_rebase_strm(
  sqlite3_rebaser *pRebaser,
  int (*xInput)(void *pIn, void *pData, int *pnData),
  void *pIn,
  int (*xOutput)(void *pOut, const void *pData, int nData),
  void *pOut
);

Шесть потоковых функций API xxx_strm() выполняют аналогичные задачи, что и соответствующие непотоковые функции API:

Непотоковые функции, принимающие изменения (или наборы изменений) в качестве входных данных, требуют, чтобы весь набор изменений хранился в одном буфере в памяти. Аналогично, функции, возвращающие набор изменений или набор изменений, делают это, возвращая указатель на один большой буфер, выделенный с помощью sqlite3_malloc(). Обычно это удобно. Однако, если приложение, работающее в среде с ограниченной памятью, должно обрабатывать очень большие наборы изменений, необходимые большие непрерывные выделения памяти могут стать обременительными.

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

       int nChangeset,
       void *pChangeset,
 

Заменяется на:

       int (*xInput)(void *pIn, void *pData, int *pnData),
       void *pIn,
 

Каждый раз, когда модуль сеансов вызывает функцию обратного вызова xInput, первый аргумент, передаваемый, является копией переданного указателя контекста pIn. Второй аргумент, pData, указывает на буфер размером (*pnData) байт. При отсутствии ошибок метод xInput должен скопировать не более (*pnData) байт данных в буфер и установить (*pnData) на фактическое количество скопированных байт перед возвратом SQLITE_OK. Если входные данные полностью исчерпаны, (*pnData) должно быть установлено в ноль, чтобы указать это. В противном случае, если произошла ошибка, должен быть возвращён код ошибки SQLite. Во всех случаях, если функция обратного вызова xInput возвращает ошибку, вся обработка прекращается, и потоковая функция API возвращает копию кода ошибки вызывающей стороне.

В случае sqlite3changeset_start_strm() функция обратного вызова xInput может быть вызвана модулем сеансов в любой момент во время существования итератора. Если такая функция обратного вызова xInput возвращает ошибку, итератор переходит в состояние ошибки, при этом все последующие вызовы функций итератора немедленно завершаются с тем же кодом ошибки, что и возвращённый функцией xInput.

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

       int *pnChangeset,
       void **ppChangeset,
 

Заменяется на:

       int (*xOutput)(void *pOut, const void *pData, int nData),
       void *pOut
 

Функция обратного вызова xOutput вызывается ноль или более раз, чтобы вернуть данные приложению. Первый параметр, передаваемый при каждом вызове, является копией указателя pOut, предоставленного приложением. Второй параметр, pData, указывает на буфер размером nData байт, содержащий часть возвращаемых выходных данных. Если функция обратного вызова xOutput успешно обработала предоставленные данные, она должна вернуть SQLITE_OK, чтобы указать на успех. В противном случае она должна вернуть другой код ошибки SQLite. В этом случае обработка немедленно прекращается, и потоковая функция API возвращает копию кода ошибки xOutput приложению.

Модуль сеансов никогда не вызывает функцию обратного вызова xOutput с третьим параметром, установленным на значение, меньшее или равное нулю. Помимо этого, никаких гарантий относительно размера возвращаемых частей данных не даётся.

См. также списки Объектов, Констант и Функций.