Sq3LiteC_Modify_Wal_C_API

Sq3LiteC - functions related to index 'Modify' and doc 'Wal' … More...

Collaboration diagram for Sq3LiteC_Modify_Wal_C_API:

Functions
static enum MkErrorE	Sq3LiteWalAutocheckpoint (SQ3_LITE db, MK_I32 N)
	Configure an auto-checkpoint …
static enum MkErrorE	Sq3LiteWalCheckpointV2 (SQ3_LITE db, MK_STRN zDb, MK_I32 eMode, MK_I32 *pnLog, MK_I32 *pnCkpt)
	Checkpoint a database …

Sq3LiteC - Sq3LiteC_Modify_Wal_C_API - function
enum MkErrorE	Sq3LiteWalAutocheckpointP (SQ3_LITE db, MK_I32 N)
	Non-inline replacement for Sq3LiteWalAutocheckpoint …
enum MkErrorE	Sq3LiteWalCheckpointV2P (SQ3_LITE db, MK_STRN zDb, MK_I32 eMode, MK_I32 *pnLog, MK_I32 *pnCkpt)
	Non-inline replacement for Sq3LiteWalCheckpointV2 …

Sq3LiteC - Sq3LiteC_Modify_Wal_C_API - overload
#define	Sq3LiteWalAutocheckpoint_E(...)
#define	Sq3LiteWalAutocheckpoint_C(...)
#define	Sq3LiteWalCheckpointV2_E(...)
#define	Sq3LiteWalCheckpointV2_C(...)

Detailed Description

Sq3LiteC - functions related to index 'Modify' and doc 'Wal' …

Configure an auto-checkpoint:

• Sq3LiteWalAutocheckpoint

Checkpoint a database:

• Sq3LiteWalCheckpointV2

Reference code from sqlite3:

// Configure an auto-checkpoint:
SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);
 
// Checkpoint a database:
SQLITE_API int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    // Database handle 
  const char *zDb,                // Name of attached database (or NULL) 
  int eMode,                      // SQLITE_CHECKPOINT_* value 
  int *pnLog,                     // OUT: Size of WAL log in frames 
  int *pnCkpt                     // OUT: Total number of frames checkpointed 
);

Macro Definition Documentation

Sq3LiteWalAutocheckpoint_C

#define Sq3LiteWalAutocheckpoint_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LiteWalAutocheckpoint(__VA_ARGS__)))

Definition at line 484 of file sqlite3_overload_sq3.h.

Sq3LiteWalAutocheckpoint_E

#define Sq3LiteWalAutocheckpoint_E

(

...

)

Value:

MkErrorCheck(Sq3LiteWalAutocheckpoint(__VA_ARGS__))

Definition at line 483 of file sqlite3_overload_sq3.h.

Sq3LiteWalCheckpointV2_C

#define Sq3LiteWalCheckpointV2_C

(

...

)

Value:

if (MkErrorCheckI(Sq3LiteWalCheckpointV2(__VA_ARGS__)))

Definition at line 488 of file sqlite3_overload_sq3.h.

Sq3LiteWalCheckpointV2_E

#define Sq3LiteWalCheckpointV2_E

(

...

)

Value:

MkErrorCheck(Sq3LiteWalCheckpointV2(__VA_ARGS__))

Definition at line 487 of file sqlite3_overload_sq3.h.

Function Documentation

Sq3LiteWalAutocheckpoint()

static enum MkErrorE Sq3LiteWalAutocheckpoint ( SQ3_LITE db, MK_I32 N )

inlinestatic

Configure an auto-checkpoint …

The Sq3LiteWalAutocheckpoint (D,N) is a wrapper around sqlite3_wal_hook () that causes any database on database connection D to automatically checkpoint after committing a transaction if there are N or more frames in the write-ahead log file. Passing zero or a negative value as the nFrame parameter disables automatic checkpoints entirely.

The callback registered by this function replaces any existing callback registered using sqlite3_wal_hook (). Likewise, registering a callback using sqlite3_wal_hook () disables the automatic checkpoint mechanism configured by this function.

The wal_autocheckpoint pragma can be used to invoke this interface from SQL.

Checkpoints initiated by this mechanism are PASSIVE.

Every new database connection defaults to having the auto-checkpoint enabled with a threshold of 1000 or SQLITE_DEFAULT_WAL_AUTOCHECKPOINT pages. The use of this interface is only necessary if the default setting is found to be suboptimal for a particular application.

Reference code from sqlite3:

SQLITE_API int sqlite3_wal_autocheckpoint(sqlite3 *db, int N);

Definition at line 458 of file Sq3LiteC_sq3.h.

                                                                           {
    SQ3_INSTANCE_HDL(db);
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_wal_autocheckpoint(db->nat, N);
    Sq3ErrorE_Check(db, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3LiteWalAutocheckpointP()

enum MkErrorE Sq3LiteWalAutocheckpointP	(	SQ3_LITE	db,
		MK_I32	N )

Non-inline replacement for Sq3LiteWalAutocheckpoint …

Sq3LiteWalCheckpointV2()

static enum MkErrorE Sq3LiteWalCheckpointV2 ( SQ3_LITE db, MK_STRN zDb, MK_I32 eMode, MK_I32 * pnLog, MK_I32 * pnCkpt )

inlinestatic

Checkpoint a database …

The Sq3LiteWalCheckpointV2(D,X,M,L,C) interface runs a checkpoint operation on database X of database connection D in mode M. Status information is written back into integers pointed to by L and C. The M parameter must be a valid checkpoint mode:

SQ3_CHECKPOINT_PASSIVE

Checkpoint as many frames as possible without waiting for any database readers or writers to finish, then sync the database file if all frames in the log were checkpointed. The busy-handler callback is never invoked in the SQ3_CHECKPOINT_PASSIVE mode. On the other hand, passive mode might leave the checkpoint unfinished if there are concurrent readers or writers.

SQ3_CHECKPOINT_FULL

This mode blocks (it invokes the busy-handler callback) until there is no database writer and all readers are reading from the most recent database snapshot. It then checkpoints all frames in the log file and syncs the database file. This mode blocks new database writers while it is pending, but new database readers are allowed to continue unimpeded.

SQ3_CHECKPOINT_RESTART

This mode works the same way as SQ3_CHECKPOINT_FULL with the addition that after checkpointing the log file it blocks (calls the busy-handler callback) until all readers are reading from the database file only. This ensures that the next writer will restart the log file from the beginning. Like SQ3_CHECKPOINT_FULL, this mode blocks new database writer attempts while it is pending, but does not impede readers.

SQ3_CHECKPOINT_TRUNCATE

This mode works the same way as SQ3_CHECKPOINT_RESTART with the addition that it also truncates the log file to zero bytes just prior to a successful return.

If pnLog is not NULL, then *pnLog is set to the total number of frames in the log file or to -1 if the checkpoint could not run because of an error or because the database is not in WAL mode. If pnCkpt is not NULL,then *pnCkpt is set to the total number of checkpointed frames in the log file (including any that were already checkpointed before the function was called) or to -1 if the checkpoint could not run due to an error or because the database is not in WAL mode. Note that upon successful completion of an SQ3_CHECKPOINT_TRUNCATE, the log file will have been truncated to zero bytes and so both *pnLog and *pnCkpt will be set to zero.

All calls obtain an exclusive "checkpoint" lock on the database file. If any other process is running a checkpoint operation at the same time, the lock cannot be obtained and SQ3_RESULT_BUSY is returned. Even if there is a busy-handler configured, it will not be invoked in this case.

The SQ3_CHECKPOINT_FULL, RESTART and TRUNCATE modes also obtain the exclusive "writer" lock on the database file. If the writer lock cannot be obtained immediately, and a busy-handler is configured, it is invoked and the writer lock retried until either the busy-handler returns 0 or the lock is successfully obtained. The busy-handler is also invoked while waiting for database readers as described above. If the busy-handler returns 0 before the writer lock is obtained or while waiting for database readers, the checkpoint operation proceeds from that point in the same way as SQ3_CHECKPOINT_PASSIVE - checkpointing as many frames as possible without blocking any further. SQ3_RESULT_BUSY is returned in this case.

If parameter zDb is NULL or points to a zero length string, then the specified operation is attempted on all WAL databases attached to database connection db. In this case the values written to output parameters *pnLog and *pnCkpt are undefined. If an SQ3_RESULT_BUSY error is encountered when processing one or more of the attached WAL databases, the operation is still attempted on any remaining attached databases and SQ3_RESULT_BUSY is returned at the end. If any other error occurs while processing an attached database, processing is abandoned and the error code is returned to the caller immediately. If no error (SQ3_RESULT_BUSY or otherwise) is encountered while processing the attached databases, SQ3_RESULT_OK is returned.

If database zDb is the name of an attached database that is not in WAL mode, SQ3_RESULT_OK is returned and both *pnLog and *pnCkpt set to -1. If zDb is not NULL (or a zero length string) and is not the name of any attached database, SQ3_RESULT_ERROR is returned to the caller.

Unless it returns SQ3_RESULT_MISUSE, the Sq3LiteWalCheckpointV2() interface sets the error information that is queried by Sq3LiteErrCode () and Sq3LiteErrMsg ().

The PRAGMA wal_checkpoint command can be used to invoke this interface from SQL.

Reference code from sqlite3:

SQLITE_API int sqlite3_wal_checkpoint_v2(
  sqlite3 *db,                    // Database handle 
  const char *zDb,                // Name of attached database (or NULL) 
  int eMode,                      // SQLITE_CHECKPOINT_* value 
  int *pnLog,                     // OUT: Size of WAL log in frames 
  int *pnCkpt                     // OUT: Total number of frames checkpointed 
);

Definition at line 470 of file Sq3LiteC_sq3.h.

                                                                                                                         {
    SQ3_INSTANCE_HDL(db);
    enum Sq3ErrorE errVal = (enum Sq3ErrorE)sqlite3_wal_checkpoint_v2(db->nat, zDb, eMode, pnLog, pnCkpt);
    Sq3ErrorE_Check(db, errVal);
    return MK_OK;
  error:
    return MK_ERROR;
  }

Here is the caller graph for this function:

Sq3LiteWalCheckpointV2P()

enum MkErrorE Sq3LiteWalCheckpointV2P	(	SQ3_LITE	db,
		MK_STRN	zDb,
		MK_I32	eMode,
		MK_I32 *	pnLog,
		MK_I32 *	pnCkpt )

Non-inline replacement for Sq3LiteWalCheckpointV2 …