diff options
Diffstat (limited to 'static/netbsd/man3/sqlite3changeset_apply_strm.3')
| -rw-r--r-- | static/netbsd/man3/sqlite3changeset_apply_strm.3 | 281 |
1 files changed, 281 insertions, 0 deletions
diff --git a/static/netbsd/man3/sqlite3changeset_apply_strm.3 b/static/netbsd/man3/sqlite3changeset_apply_strm.3 new file mode 100644 index 00000000..919858c9 --- /dev/null +++ b/static/netbsd/man3/sqlite3changeset_apply_strm.3 @@ -0,0 +1,281 @@ +.Dd January 24, 2024 +.Dt SQLITE3CHANGESET_APPLY_STRM 3 +.Os +.Sh NAME +.Nm sqlite3changeset_apply_strm , +.Nm sqlite3changeset_apply_v2_strm , +.Nm sqlite3changeset_concat_strm , +.Nm sqlite3changeset_invert_strm , +.Nm sqlite3changeset_start_strm , +.Nm sqlite3changeset_start_v2_strm , +.Nm sqlite3session_changeset_strm , +.Nm sqlite3session_patchset_strm , +.Nm sqlite3changegroup_add_strm , +.Nm sqlite3changegroup_output_strm , +.Nm sqlite3rebaser_rebase_strm +.Nd streaming versions of API functions +.Sh SYNOPSIS +.In sqlite3.h +.Ft int +.Fo sqlite3changeset_apply_strm +.Fa "sqlite3 *db" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int(*xFilter)( void *pCtx,const char *zTab)" +.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" +.Fa "void *pCtx" +.Fc +.Ft int +.Fo sqlite3changeset_apply_v2_strm +.Fa "sqlite3 *db" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int(*xFilter)( void *pCtx,const char *zTab)" +.Fa "int(*xConflict)( void *pCtx,int eConflict,sqlite3_changeset_iter *p)" +.Fa "void *pCtx" +.Fa "void **ppRebase" +.Fa "int *pnRebase" +.Fa "int flags" +.Fc +.Ft int +.Fo sqlite3changeset_concat_strm +.Fa "int (*xInputA)(void *pIn, void *pData, int *pnData)" +.Fa "void *pInA" +.Fa "int (*xInputB)(void *pIn, void *pData, int *pnData)" +.Fa "void *pInB" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3changeset_invert_strm +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3changeset_start_strm +.Fa "sqlite3_changeset_iter **pp" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fc +.Ft int +.Fo sqlite3changeset_start_v2_strm +.Fa "sqlite3_changeset_iter **pp" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int flags" +.Fc +.Ft int +.Fo sqlite3session_changeset_strm +.Fa "sqlite3_session *pSession" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3session_patchset_strm +.Fa "sqlite3_session *pSession" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3changegroup_add_strm +.Fa "sqlite3_changegroup*" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fc +.Ft int +.Fo sqlite3changegroup_output_strm +.Fa "sqlite3_changegroup*" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Ft int +.Fo sqlite3rebaser_rebase_strm +.Fa "sqlite3_rebaser *pRebaser" +.Fa "int (*xInput)(void *pIn, void *pData, int *pnData)" +.Fa "void *pIn" +.Fa "int (*xOutput)(void *pOut, const void *pData, int nData)" +.Fa "void *pOut" +.Fc +.Sh DESCRIPTION +The six streaming API xxx_strm() functions serve similar purposes to +the corresponding non-streaming API functions: +.Pp + Streaming function Non-streaming equivalent + sqlite3changeset_apply_strm sqlite3changeset_apply + sqlite3changeset_apply_strm_v2 sqlite3changeset_apply_v2 + sqlite3changeset_concat_strm sqlite3changeset_concat + sqlite3changeset_invert_strm sqlite3changeset_invert + sqlite3changeset_start_strm sqlite3changeset_start + sqlite3session_changeset_strm sqlite3session_changeset + sqlite3session_patchset_strm sqlite3session_patchset +.Pp +Non-streaming functions that accept changesets (or patchsets) as input +require that the entire changeset be stored in a single buffer in memory. +Similarly, those that return a changeset or patchset do so by returning +a pointer to a single large buffer allocated using sqlite3_malloc(). +Normally this is convenient. +However, if an application running in a low-memory environment is required +to handle very large changesets, the large contiguous memory allocations +required can become onerous. +.Pp +In order to avoid this problem, instead of a single large buffer, input +is passed to a streaming API functions by way of a callback function +that the sessions module invokes to incrementally request input data +as it is required. +In all cases, a pair of API function parameters such as +.Bd -literal + int nChangeset, void *pChangeset, +.Ed +.Pp +Is replaced by: +.Bd -literal + int (*xInput)(void *pIn, void *pData, int *pnData), void +*pIn, +.Ed +.Pp +Each time the xInput callback is invoked by the sessions module, the +first argument passed is a copy of the supplied pIn context pointer. +The second argument, pData, points to a buffer (*pnData) bytes in size. +Assuming no error occurs the xInput method should copy up to (*pnData) +bytes of data into the buffer and set (*pnData) to the actual number +of bytes copied before returning SQLITE_OK. +If the input is completely exhausted, (*pnData) should be set to zero +to indicate this. +Or, if an error occurs, an SQLite error code should be returned. +In all cases, if an xInput callback returns an error, all processing +is abandoned and the streaming API function returns a copy of the error +code to the caller. +.Pp +In the case of sqlite3changeset_start_strm(), the xInput callback may +be invoked by the sessions module at any point during the lifetime +of the iterator. +If such an xInput callback returns an error, the iterator enters an +error state, whereby all subsequent calls to iterator functions immediately +fail with the same error code as returned by xInput. +.Pp +Similarly, streaming API functions that return changesets (or patchsets) +return them in chunks by way of a callback function instead of via +a pointer to a single large buffer. +In this case, a pair of parameters such as: +.Bd -literal + int *pnChangeset, void **ppChangeset, +.Ed +.Pp +Is replaced by: +.Bd -literal + int (*xOutput)(void *pOut, const void *pData, int nData), +void *pOut +.Ed +.Pp +The xOutput callback is invoked zero or more times to return data to +the application. +The first parameter passed to each call is a copy of the pOut pointer +supplied by the application. +The second parameter, pData, points to a buffer nData bytes in size +containing the chunk of output data being returned. +If the xOutput callback successfully processes the supplied data, it +should return SQLITE_OK to indicate success. +Otherwise, it should return some other SQLite error code. +In this case processing is immediately abandoned and the streaming +API function returns a copy of the xOutput error code to the application. +.Pp +The sessions module never invokes an xOutput callback with the third +parameter set to a value less than or equal to zero. +Other than this, no guarantees are made as to the size of the chunks +of data returned. +.Sh IMPLEMENTATION NOTES +These declarations were extracted from the +interface documentation at line 12507. +.Bd -literal +SQLITE_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 */ +); +SQLITE_API 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 +); +SQLITE_API 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 +); +SQLITE_API 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 +); +SQLITE_API int sqlite3changeset_start_strm( + sqlite3_changeset_iter **pp, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +SQLITE_API int sqlite3changeset_start_v2_strm( + sqlite3_changeset_iter **pp, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn, + int flags +); +SQLITE_API int sqlite3session_changeset_strm( + sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlite3session_patchset_strm( + sqlite3_session *pSession, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API int sqlite3changegroup_add_strm(sqlite3_changegroup*, + int (*xInput)(void *pIn, void *pData, int *pnData), + void *pIn +); +SQLITE_API int sqlite3changegroup_output_strm(sqlite3_changegroup*, + int (*xOutput)(void *pOut, const void *pData, int nData), + void *pOut +); +SQLITE_API 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 +); +.Ed +.Sh SEE ALSO +.Xr sqlite3changeset_apply 3 , +.Xr sqlite3changeset_concat 3 , +.Xr sqlite3changeset_invert 3 , +.Xr sqlite3changeset_start 3 , +.Xr sqlite3session_changeset 3 , +.Xr sqlite3session_patchset 3 |