// | createFlag | Behavior when page is not already in cache
// |
|---|
| 0 | Do not allocate a new page. Return NULL.
// |
| 1 | Allocate a new page if it easy and convenient to do so.
//
// Otherwise return NULL.
//
// |
| 2 | Make every effort to allocate a new page. Only return
//
// NULL if allocating a new page is effectively impossible.
//
// |
//
// ^(SQLite will normally invoke xFetch() with a createFlag of 0 or 1. SQLite
// will only use a createFlag of 2 after a prior call with a createFlag of 1
// failed.)^ In between the xFetch() calls, 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.
//
// [[the xUnpin() page cache method]]
// ^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 must be evicted from the cache.
// ^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 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() page cache methods]]
// The xRekey() method is used to change the key value associated with the
// 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.
//
// When SQLite calls the xTruncate() method, the cache must discard all
// existing cache entries with page numbers (keys) greater than or equal
// to the value of the iLimit parameter passed to xTruncate(). If any
// of these pages are pinned, they are implicitly unpinned, meaning that
// they can be safely discarded.
//
// [[the xDestroy() page cache method]]
// ^The xDestroy() method is used to delete a cache allocated by xCreate().
// All resources associated with the specified cache should be freed. ^After
// calling the xDestroy() method, SQLite considers the [sqlite3_pcache*]
// handle invalid, and will not use it with any other sqlite3_pcache_methods2
// functions.
//
// [[the xShrink() page cache method]]
// ^SQLite invokes the xShrink() method when it wants the page cache to
// free up as much of heap memory as possible. The page cache implementation
// is not obligated to free any memory, but well-behaved implementations should
// do their best.
type Sqlite3_pcache_methods2 = sqlite3_pcache_methods2
type sqlite3_pcache_methods = struct {
FpArg uintptr
FxInit uintptr
FxShutdown uintptr
FxCreate uintptr
FxCachesize uintptr
FxPagecount uintptr
FxFetch uintptr
FxUnpin uintptr
FxRekey uintptr
FxTruncate uintptr
FxDestroy uintptr
}
// This is the obsolete pcache_methods object that has now been replaced
// by sqlite3_pcache_methods2. This object is not used by SQLite. It is
// retained in the header file for backwards compatibility only.
type Sqlite3_pcache_methods = sqlite3_pcache_methods
type sqlite3_backup = struct {
FpDestDb uintptr
FpDest uintptr
FiDestSchema U32
FbDestLocked int32
FiNext Pgno
FpSrcDb uintptr
FpSrc uintptr
Frc int32
FnRemaining Pgno
FnPagecount Pgno
FisAttached int32
FpNext uintptr
}
// CAPI3REF: Online Backup Object
//
// The sqlite3_backup object records state information about an ongoing
// online backup operation. ^The sqlite3_backup object is created by
// a call to [sqlite3_backup_init()] and is destroyed by a call to
// [sqlite3_backup_finish()].
//
// See Also: [Using the SQLite Online Backup API]
type Sqlite3_backup = sqlite3_backup
type sqlite3_snapshot = struct{ Fhidden [48]uint8 }
// CAPI3REF: Database Snapshot
// KEYWORDS: {snapshot} {sqlite3_snapshot}
//
// An instance of the snapshot object records the state of a [WAL mode]
// database for some specific point in history.
//
// In [WAL mode], multiple [database connections] that are open on the
// same database file can each be reading a different historical version
// of the database file. When a [database connection] begins a read
// transaction, that connection sees an unchanging copy of the database
// as it existed for the point in time when the transaction first started.
// Subsequent changes to the database from other connections are not seen
// by the reader until a new read transaction is started.
//
// The sqlite3_snapshot object records state information about an historical
// version of the database file so that it is possible to later open a new read
// transaction that sees that historical version of the database rather than
// the most recent version.
type Sqlite3_snapshot = sqlite3_snapshot
type sqlite3_rtree_geometry = struct {
FpContext uintptr
FnParam int32
FaParam uintptr
FpUser uintptr
FxDelUser uintptr
}
type Sqlite3_rtree_geometry = sqlite3_rtree_geometry
type sqlite3_rtree_query_info = struct {
FpContext uintptr
FnParam int32
FaParam uintptr
FpUser uintptr
FxDelUser uintptr
FaCoord uintptr
FanQueue uintptr
FnCoord int32
FiLevel int32
FmxLevel int32
FiRowid Sqlite3_int64
FrParentScore Sqlite3_rtree_dbl
FeParentWithin int32
FeWithin int32
FrScore Sqlite3_rtree_dbl
FapSqlParam uintptr
F__ccgo_pad1 [4]byte
}
type Sqlite3_rtree_query_info = sqlite3_rtree_query_info
// The double-precision datatype used by RTree depends on the
// SQLITE_RTREE_INT_ONLY compile-time option.
type Sqlite3_rtree_dbl = float64
type sqlite3_session = struct {
Fdb uintptr
FzDb uintptr
FbEnableSize int32
FbEnable int32
FbIndirect int32
FbAutoAttach int32
Frc int32
FpFilterCtx uintptr
FxTableFilter uintptr
F__ccgo_pad1 [4]byte
FnMalloc I64
FnMaxChangesetSize I64
FpZeroBlob uintptr
FpNext uintptr
FpTable uintptr
Fhook SessionHook
}
// CAPI3REF: Session Object Handle
//
// An instance of this object is a [session] that can be used to
// record changes to a database.
type Sqlite3_session = sqlite3_session
type sqlite3_changeset_iter = struct {
Fin SessionInput
Ftblhdr SessionBuffer
FbPatchset int32
FbInvert int32
FbSkipEmpty int32
Frc int32
FpConflict uintptr
FzTab uintptr
FnCol int32
Fop int32
FbIndirect int32
FabPK uintptr
FapValue uintptr
}
// CAPI3REF: Changeset Iterator Handle
//
// An instance of this object acts as a cursor for iterating
// over the elements of a [changeset] or [patchset].
type Sqlite3_changeset_iter = sqlite3_changeset_iter
type sqlite3_changegroup = struct {
Frc int32
FbPatch int32
FpList uintptr
}
// CAPI3REF: Changegroup Handle
//
// A changegroup is an object used to combine two or more
// [changesets] or [patchsets]
type Sqlite3_changegroup = sqlite3_changegroup
type sqlite3_rebaser = struct{ Fgrp Sqlite3_changegroup }
// CAPI3REF: Rebasing changesets
// EXPERIMENTAL
//
// Suppose there is a site hosting a database in state S0. And that
// modifications are made that move that database to state S1 and a
// changeset recorded (the "local" changeset). Then, a changeset based
// on S0 is received from another site (the "remote" changeset) and
// applied to the database. The database is then in state
// (S1+"remote"), where the exact state depends on any conflict
// resolution decisions (OMIT or REPLACE) made while applying "remote".
// Rebasing a changeset is to update it to take those conflict
// resolution decisions into account, so that the same conflicts
// do not have to be resolved elsewhere in the network.
//
// For example, if both the local and remote changesets contain an
// INSERT of the same key on "CREATE TABLE t1(a PRIMARY KEY, b)":
//
// local: INSERT INTO t1 VALUES(1, 'v1');
// remote: INSERT INTO t1 VALUES(1, 'v2');
//
// and the conflict resolution is REPLACE, then the INSERT change is
// removed from the local changeset (it was overridden). Or, if the
// conflict resolution was "OMIT", then the local changeset is modified
// to instead contain:
//
// UPDATE t1 SET b = 'v2' WHERE a=1;
//
// Changes within the local changeset are rebased as follows:
//
//