blob: 20af7b30fb74e13aec7240c97ce75cd093f7b09e (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
|
.Dd January 24, 2024
.Dt SQLITE3_PROGRESS_HANDLER 3
.Os
.Sh NAME
.Nm sqlite3_progress_handler
.Nd query progress callbacks
.Sh SYNOPSIS
.In sqlite3.h
.Ft void
.Fo sqlite3_progress_handler
.Fa "sqlite3*"
.Fa "int"
.Fa "int(*)(void*)"
.Fa "void*"
.Fc
.Sh DESCRIPTION
The sqlite3_progress_handler(D,N,X,P) interface causes the callback
function X to be invoked periodically during long running calls to
.Fn sqlite3_step
and
.Fn sqlite3_prepare
and similar for database connection D.
An example use for this interface is to keep a GUI updated during a
large query.
.Pp
The parameter P is passed through as the only parameter to the callback
function X.
The parameter N is the approximate number of virtual machine instructions
that are evaluated between successive invocations of the callback X.
If N is less than one then the progress handler is disabled.
.Pp
Only a single progress handler may be defined at one time per database connection;
setting a new progress handler cancels the old one.
Setting parameter X to NULL disables the progress handler.
The progress handler is also disabled by setting N to a value less
than 1.
.Pp
If the progress callback returns non-zero, the operation is interrupted.
This feature can be used to implement a "Cancel" button on a GUI progress
dialog box.
.Pp
The progress handler callback must not do anything that will modify
the database connection that invoked the progress handler.
Note that
.Fn sqlite3_prepare_v2
and
.Fn sqlite3_step
both modify their database connections for the meaning of "modify"
in this paragraph.
.Pp
The progress handler callback would originally only be invoked from
the bytecode engine.
It still might be invoked during
.Fn sqlite3_prepare
and similar because those routines might force a reparse of the schema
which involves running the bytecode engine.
However, beginning with SQLite version 3.41.0, the progress handler
callback might also be invoked directly from
.Fn sqlite3_prepare
while analyzing and generating code for complex queries.
.Sh IMPLEMENTATION NOTES
These declarations were extracted from the
interface documentation at line 3421.
.Bd -literal
SQLITE_API void sqlite3_progress_handler(sqlite3*, int, int(*)(void*), void*);
.Ed
.Sh SEE ALSO
.Xr sqlite3 3 ,
.Xr sqlite3_prepare 3 ,
.Xr sqlite3_step 3
|
