Потоковые версии функций 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_apply_v3_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() */
    sqlite3_changeset_iter *p
  ),
  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 не в одном большом буфере, а через функцию обратного вызова, которую модуль sessions вызывает для поэтапного запроса данных по мере необходимости. Во всех случаях пара параметров функции API, таких как

       int nChangeset,
       void *pChangeset,
 

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

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

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

В случае sqlite3changeset_start_strm() модуль sessions может вызвать функцию обратного вызова 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.

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

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