/ Check-in [68d4f795]
Login
SQLite training in Houston TX on 2019-11-05 (details)
Part of the 2019 Tcl Conference

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Documentation and test-script updates. (CVS 5249)
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1: 68d4f7954108f5bf586c4706c8664d8333fb2230
User & Date: drh 2008-06-19 17:54:33
Context
2008-06-19
18:17
Move the malloc() failure simulation out of malloc.c and into a separate sqlite3_mem_methods interface. Still some related changes to come. (CVS 5250) check-in: d22cd2a5 user: danielk1977 tags: trunk
17:54
Documentation and test-script updates. (CVS 5249) check-in: 68d4f795 user: drh tags: trunk
16:07
Fix some minor compile problems. (CVS 5248) check-in: 7d38da3e user: drh tags: trunk
Changes
Hide Diffs Unified Diffs Ignore Whitespace Patch

Changes to src/sqlite.h.in.

26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
...
215
216
217
218
219
220
221
222



223
224
225









226
227
228
229
230
231
232
...
235
236
237
238
239
240
241




242
243
244
245
246
247
248
...
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.339 2008/06/19 08:51:24 danielk1977 Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
**
** This routine is the destructor for the [sqlite3] object.  
**
** Applications should [sqlite3_finalize | finalize] all
** [prepared statements] and
** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] 
** associated with the [sqlite3] object prior
** to attempting to close the [sqlite3] object.



**
** <todo>What happens to pending transactions?  Are they
** rolled back, or abandoned?</todo>









**
** INVARIANTS:
**
** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
**          allocated by a prior call to [sqlite3_open()],
**          [sqlite3_open16()], or [sqlite3_open_v2()].
**
................................................................................
**
** {F12013} If the database connection contains
**          [prepared statements] that have not been
**          finalized by [sqlite3_finalize()], then [sqlite3_close()]
**          returns [SQLITE_BUSY] and leaves the connection open.
**
** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.




**
** LIMITATIONS:
**
** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object
**          pointer previously obtained from [sqlite3_open()] or the 
**          equivalent, or NULL.
**
................................................................................
** without consequence.  Second and subsequent evaluations of
** sqlite3_initialize() are no-ops.  The sqlite3_initialize() routine
** only works the first time it is called for a process, or the first
** time it is called after sqlite3_shutdown().  In all other cases,
** sqlite3_initialize() returns SQLITE_OK without doing any real work.
**
** Among other things, sqlite3_initialize() shall invoke
** [sqlite3_mutex_init()] and sqlite3_os_init().  Similarly, sqlite3_shutdown()
** shall invoke [sqlite3_mutex_end()] and sqlite3_os_end().
**
** The sqlite3_initialize() routine returns SQLITE_OK on success.
** If for some reason, sqlite3_initialize() is unable to initialize
** the library (perhaps it is unable to allocate a needed resource such
** as a mutex) it returns an [error code] other than SQLITE_OK.
**
** The sqlite3_initialize() routine is called internally by many other







|







 







|
>
>
>

<
<
>
>
>
>
>
>
>
>
>







 







>
>
>
>







 







|
|







26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
...
215
216
217
218
219
220
221
222
223
224
225
226


227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
...
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
...
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
** on how SQLite interfaces are suppose to operate.
**
** The name of this file under configuration management is "sqlite.h.in".
** The makefile makes some minor changes to this file (such as inserting
** the version number) and changes its name to "sqlite3.h" as
** part of the build process.
**
** @(#) $Id: sqlite.h.in,v 1.340 2008/06/19 17:54:33 drh Exp $
*/
#ifndef _SQLITE3_H_
#define _SQLITE3_H_
#include <stdarg.h>     /* Needed for the definition of va_list */

/*
** Make sure we can call this stuff from C++.
................................................................................
**
** This routine is the destructor for the [sqlite3] object.  
**
** Applications should [sqlite3_finalize | finalize] all
** [prepared statements] and
** [sqlite3_blob_close | close] all [sqlite3_blob | BLOBs] 
** associated with the [sqlite3] object prior
** to attempting to close the [sqlite3] object.  The
** [sqlite3_next_stmt()] interface can be used to locate all
** [prepared statements] associated with a [database connection]
** if desired.  Typical code might look like this:
**


** <blockquote><pre>
** sqlite3_stmt *pStmt;
** while( (pStmt = sqlite3_next_stmt(db, 0))!=0 ){
** &nbsp;   sqlite3_finalize(pStmt);
** }
** </pre></blockquote>
**
** If [sqlite3_close()] is invoked while a transaction is opened,
** the transaction is automatically rolled back.
**
** INVARIANTS:
**
** {F12011} The [sqlite3_close()] interface destroys an [sqlite3] object
**          allocated by a prior call to [sqlite3_open()],
**          [sqlite3_open16()], or [sqlite3_open_v2()].
**
................................................................................
**
** {F12013} If the database connection contains
**          [prepared statements] that have not been
**          finalized by [sqlite3_finalize()], then [sqlite3_close()]
**          returns [SQLITE_BUSY] and leaves the connection open.
**
** {F12014} Giving sqlite3_close() a NULL pointer is a harmless no-op.
**
** {F12019} When [sqlite3_close()] is invoked on a [database connection]
**          that has a pending transaction, the transaction shall be
**          rolled back.
**
** LIMITATIONS:
**
** {U12015} The parameter to [sqlite3_close()] must be an [sqlite3] object
**          pointer previously obtained from [sqlite3_open()] or the 
**          equivalent, or NULL.
**
................................................................................
** without consequence.  Second and subsequent evaluations of
** sqlite3_initialize() are no-ops.  The sqlite3_initialize() routine
** only works the first time it is called for a process, or the first
** time it is called after sqlite3_shutdown().  In all other cases,
** sqlite3_initialize() returns SQLITE_OK without doing any real work.
**
** Among other things, sqlite3_initialize() shall invoke
** sqlite3_os_init().  Similarly, sqlite3_shutdown()
** shall invoke sqlite3_os_end().
**
** The sqlite3_initialize() routine returns SQLITE_OK on success.
** If for some reason, sqlite3_initialize() is unable to initialize
** the library (perhaps it is unable to allocate a needed resource such
** as a mutex) it returns an [error code] other than SQLITE_OK.
**
** The sqlite3_initialize() routine is called internally by many other

Changes to test/memsubsys1.test.

7
8
9
10
11
12
13
14
15
16
17

18
19
20
21
22
23
24
...
216
217
218
219
220
221
222
223

224
#    May you find forgiveness for yourself and forgive others.
#    May you share freely, never taking more than you give.
#
#***********************************************************************
#
# This file contains tests of the memory allocation subsystem
#
# $Id: memsubsys1.test,v 1.1 2008/06/19 00:16:08 drh Exp $

set testdir [file dirname $argv0]
source $testdir/tester.tcl


# This procedure constructs a new database in test.db.  It fills
# this database with many small records (enough to force multiple
# rebalance operations in the btree-layer and to require a large
# page cache), verifies correct results, then returns.
#
proc build_test_db {testname pragmas} {
................................................................................
do_test memsubsys1-7.6 {
  set s_used [lindex [sqlite3_status SQLITE_STATUS_SCRATCH_USED 0] 2]
} 1
do_test memsubsys1-7.7 {
  set s_ovfl [lindex [sqlite3_status SQLITE_STATUS_SCRATCH_OVERFLOW 0] 2]
} 0



finish_test







|



>







 







<
>

7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
...
217
218
219
220
221
222
223

224
225
#    May you find forgiveness for yourself and forgive others.
#    May you share freely, never taking more than you give.
#
#***********************************************************************
#
# This file contains tests of the memory allocation subsystem
#
# $Id: memsubsys1.test,v 1.2 2008/06/19 17:54:33 drh Exp $

set testdir [file dirname $argv0]
source $testdir/tester.tcl
sqlite3_reset_auto_extension

# This procedure constructs a new database in test.db.  It fills
# this database with many small records (enough to force multiple
# rebalance operations in the btree-layer and to require a large
# page cache), verifies correct results, then returns.
#
proc build_test_db {testname pragmas} {
................................................................................
do_test memsubsys1-7.6 {
  set s_used [lindex [sqlite3_status SQLITE_STATUS_SCRATCH_USED 0] 2]
} 1
do_test memsubsys1-7.7 {
  set s_ovfl [lindex [sqlite3_status SQLITE_STATUS_SCRATCH_OVERFLOW 0] 2]
} 0


autoinstall_test_functions
finish_test

Changes to test/mutex1.test.

5
6
7
8
9
10
11
12
13
14
15

16
17
18
19
20
21
22
...
123
124
125
126
127
128
129

130
131
#
#    May you do good and not evil.
#    May you find forgiveness for yourself and forgive others.
#    May you share freely, never taking more than you give.
#
#***********************************************************************
#
# $Id: mutex1.test,v 1.3 2008/06/18 17:59:04 danielk1977 Exp $

set testdir [file dirname $argv0]
source $testdir/tester.tcl


proc mutex_counters {varname} {
  upvar $varname var
  set var(total) 0
  foreach {name value} [read_mutex_counters] {
    set var($name) $value
    incr var(total) $value
................................................................................
  catch {db close}
  sqlite3_shutdown
  clear_mutex_counters
  install_mutex_counters 0
  sqlite3_initialize
} {SQLITE_OK}


finish_test








|



>







 







>

<
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
...
124
125
126
127
128
129
130
131
132

#
#    May you do good and not evil.
#    May you find forgiveness for yourself and forgive others.
#    May you share freely, never taking more than you give.
#
#***********************************************************************
#
# $Id: mutex1.test,v 1.4 2008/06/19 17:54:33 drh Exp $

set testdir [file dirname $argv0]
source $testdir/tester.tcl
sqlite3_reset_auto_extension

proc mutex_counters {varname} {
  upvar $varname var
  set var(total) 0
  foreach {name value} [read_mutex_counters] {
    set var($name) $value
    incr var(total) $value
................................................................................
  catch {db close}
  sqlite3_shutdown
  clear_mutex_counters
  install_mutex_counters 0
  sqlite3_initialize
} {SQLITE_OK}

autoinstall_test_functions
finish_test