Documentation Source Text

Hex Artifact Content
Login

Artifact dbaedfd7f3309d878e461e70774322d70f30786eecd981c7c5e5b70d4afd85e1:


0000: 3c 74 69 74 6c 65 3e 44 79 6e 61 6d 69 63 20 4d  <title>Dynamic M
0010: 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
0020: 20 49 6e 20 53 51 4c 69 74 65 3c 2f 74 69 74 6c   In SQLite</titl
0030: 65 3e 0a 0a 3c 74 61 62 6c 65 5f 6f 66 5f 63 6f  e>..<table_of_co
0040: 6e 74 65 6e 74 73 3e 0a 3c 74 63 6c 3e 68 64 5f  ntents>.<tcl>hd_
0050: 6b 65 79 77 6f 72 64 73 20 7b 6d 65 6d 6f 72 79  keywords {memory
0060: 20 61 6c 6c 6f 63 61 74 69 6f 6e 7d 3c 2f 74 63   allocation}</tc
0070: 6c 3e 0a 0a 3c 68 31 20 73 74 79 6c 65 3d 22 6d  l>..<h1 style="m
0080: 61 72 67 69 6e 2d 6c 65 66 74 3a 31 2e 30 65 6d  argin-left:1.0em
0090: 22 20 6e 6f 74 6f 63 20 69 64 3d 6f 76 65 72 76  " notoc id=overv
00a0: 69 65 77 3e 20 4f 76 65 72 76 69 65 77 3c 2f 68  iew> Overview</h
00b0: 31 3e 20 0a 0a 3c 70 3e 53 51 4c 69 74 65 20 75  1> ..<p>SQLite u
00c0: 73 65 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f  ses dynamic memo
00d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
00e0: 20 6f 62 74 61 69 6e 0a 6d 65 6d 6f 72 79 20 66   obtain.memory f
00f0: 6f 72 20 73 74 6f 72 69 6e 67 20 76 61 72 69 6f  or storing vario
0100: 75 73 20 6f 62 6a 65 63 74 73 0a 28 65 78 3a 20  us objects.(ex: 
0110: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
0120: 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70  tions] and [prep
0130: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
0140: 29 20 61 6e 64 20 74 6f 20 62 75 69 6c 64 0a 61  ) and to build.a
0150: 20 6d 65 6d 6f 72 79 20 63 61 63 68 65 20 6f 66   memory cache of
0160: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
0170: 6c 65 20 61 6e 64 20 74 6f 20 68 6f 6c 64 20 74  le and to hold t
0180: 68 65 20 72 65 73 75 6c 74 73 20 6f 66 20 71 75  he results of qu
0190: 65 72 69 65 73 2e 0a 4d 75 63 68 20 65 66 66 6f  eries..Much effo
01a0: 72 74 20 68 61 73 20 67 6f 6e 65 20 69 6e 74 6f  rt has gone into
01b0: 20 6d 61 6b 69 6e 67 20 74 68 65 20 64 79 6e 61   making the dyna
01c0: 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  mic memory alloc
01d0: 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 0a  ation subsystem.
01e0: 6f 66 20 53 51 4c 69 74 65 20 72 65 6c 69 61 62  of SQLite reliab
01f0: 6c 65 2c 20 70 72 65 64 69 63 74 61 62 6c 65 2c  le, predictable,
0200: 20 72 6f 62 75 73 74 2c 20 73 65 63 75 72 65 2c   robust, secure,
0210: 20 61 6e 64 20 65 66 66 69 63 69 65 6e 74 2e 3c   and efficient.<
0220: 2f 70 3e 0a 0a 3c 70 3e 54 68 69 73 20 64 6f 63  /p>..<p>This doc
0230: 75 6d 65 6e 74 20 70 72 6f 76 69 64 65 73 20 61  ument provides a
0240: 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20 64 79  n overview of dy
0250: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  namic memory all
0260: 6f 63 61 74 69 6f 6e 20 77 69 74 68 69 6e 20 0a  ocation within .
0270: 53 51 4c 69 74 65 2e 20 20 54 68 65 20 74 61 72  SQLite.  The tar
0280: 67 65 74 20 61 75 64 69 65 6e 63 65 20 69 73 20  get audience is 
0290: 73 6f 66 74 77 61 72 65 20 65 6e 67 69 6e 65 65  software enginee
02a0: 72 73 20 77 68 6f 20 61 72 65 20 74 75 6e 69 6e  rs who are tunin
02b0: 67 20 74 68 65 69 72 0a 75 73 65 20 6f 66 20 53  g their.use of S
02c0: 51 4c 69 74 65 20 66 6f 72 20 70 65 61 6b 20 70  QLite for peak p
02d0: 65 72 66 6f 72 6d 61 6e 63 65 20 69 6e 20 64 65  erformance in de
02e0: 6d 61 6e 64 69 6e 67 20 65 6e 76 69 72 6f 6e 6d  manding environm
02f0: 65 6e 74 73 2e 0a 4e 6f 74 68 69 6e 67 20 69 6e  ents..Nothing in
0300: 20 74 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 69   this document i
0310: 73 20 72 65 71 75 69 72 65 64 20 6b 6e 6f 77 6c  s required knowl
0320: 65 64 67 65 20 66 6f 72 20 75 73 69 6e 67 20 53  edge for using S
0330: 51 4c 69 74 65 2e 20 20 54 68 65 0a 64 65 66 61  QLite.  The.defa
0340: 75 6c 74 20 73 65 74 74 69 6e 67 73 20 61 6e 64  ult settings and
0350: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66   configuration f
0360: 6f 72 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 77  or SQLite will w
0370: 6f 72 6b 20 77 65 6c 6c 20 69 6e 20 6d 6f 73 74  ork well in most
0380: 0a 61 70 70 6c 69 63 61 74 69 6f 6e 73 2e 20 20  .applications.  
0390: 48 6f 77 65 76 65 72 2c 20 74 68 65 20 69 6e 66  However, the inf
03a0: 6f 72 6d 61 74 69 6f 6e 20 63 6f 6e 74 61 69 6e  ormation contain
03b0: 65 64 20 69 6e 20 74 68 69 73 20 64 6f 63 75 6d  ed in this docum
03c0: 65 6e 74 20 6d 61 79 0a 62 65 20 75 73 65 66 75  ent may.be usefu
03d0: 6c 20 74 6f 20 65 6e 67 69 6e 65 65 72 73 20 77  l to engineers w
03e0: 68 6f 20 61 72 65 20 74 75 6e 69 6e 67 20 53 51  ho are tuning SQ
03f0: 4c 69 74 65 20 74 6f 20 63 6f 6d 70 6c 79 20 77  Lite to comply w
0400: 69 74 68 20 73 70 65 63 69 61 6c 0a 72 65 71 75  ith special.requ
0410: 69 72 65 6d 65 6e 74 73 20 6f 72 20 74 6f 20 72  irements or to r
0420: 75 6e 20 75 6e 64 65 72 20 75 6e 75 73 75 61 6c  un under unusual
0430: 20 63 69 72 63 75 6d 73 74 61 6e 63 65 73 2e 3c   circumstances.<
0440: 2f 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 66 65  /p>..<a name="fe
0450: 61 74 75 72 65 73 22 3e 3c 2f 61 3e 0a 3c 68 31  atures"></a>.<h1
0460: 3e 20 46 65 61 74 75 72 65 73 3c 2f 68 31 3e 0a  > Features</h1>.
0470: 0a 3c 70 3e 54 68 65 20 53 51 4c 69 74 65 20 63  .<p>The SQLite c
0480: 6f 72 65 20 61 6e 64 20 69 74 73 20 6d 65 6d 6f  ore and its memo
0490: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75  ry allocation su
04a0: 62 73 79 73 74 65 6d 20 70 72 6f 76 69 64 65 73  bsystem provides
04b0: 20 74 68 65 20 0a 66 6f 6c 6c 6f 77 69 6e 67 20   the .following 
04c0: 63 61 70 61 62 69 6c 69 74 69 65 73 3a 3c 2f 70  capabilities:</p
04d0: 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a  >..<ul>.<li><p>.
04e0: 3c 62 3e 52 6f 62 75 73 74 20 61 67 61 69 6e 73  <b>Robust agains
04f0: 74 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  t allocation fai
0500: 6c 75 72 65 73 2e 3c 2f 62 3e 0a 49 66 20 61 20  lures.</b>.If a 
0510: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
0520: 6e 20 65 76 65 72 20 66 61 69 6c 73 20 28 74 68  n ever fails (th
0530: 61 74 20 69 73 20 74 6f 20 73 61 79 2c 20 0a 69  at is to say, .i
0540: 66 20 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 72 65  f malloc() or re
0550: 61 6c 6c 6f 63 28 29 20 65 76 65 72 20 72 65 74  alloc() ever ret
0560: 75 72 6e 20 4e 55 4c 4c 29 0a 74 68 65 6e 20 53  urn NULL).then S
0570: 51 4c 69 74 65 20 77 69 6c 6c 20 72 65 63 6f 76  QLite will recov
0580: 65 72 20 67 72 61 63 65 66 75 6c 6c 79 2e 20 20  er gracefully.  
0590: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 66 69 72   SQLite will fir
05a0: 73 74 20 61 74 74 65 6d 70 74 0a 74 6f 20 66 72  st attempt.to fr
05b0: 65 65 20 6d 65 6d 6f 72 79 20 66 72 6f 6d 20 75  ee memory from u
05c0: 6e 70 69 6e 6e 65 64 20 63 61 63 68 65 20 70 61  npinned cache pa
05d0: 67 65 73 20 74 68 65 6e 20 72 65 74 72 79 20 74  ges then retry t
05e0: 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 72 65  he allocation.re
05f0: 71 75 65 73 74 2e 20 20 0a 46 61 69 6c 69 6e 67  quest.  .Failing
0600: 20 74 68 61 74 2c 20 53 51 4c 69 74 65 20 77 69   that, SQLite wi
0610: 6c 6c 20 65 69 74 68 65 72 20 73 74 6f 70 20 77  ll either stop w
0620: 68 61 74 0a 69 74 20 69 73 20 64 6f 69 6e 67 20  hat.it is doing 
0630: 61 6e 64 20 72 65 74 75 72 6e 20 74 68 65 0a 5b  and return the.[
0640: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72  SQLITE_NOMEM] er
0650: 72 6f 72 20 63 6f 64 65 20 62 61 63 6b 20 75 70  ror code back up
0660: 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
0670: 69 6f 6e 20 6f 72 20 69 74 20 77 69 6c 6c 0a 6d  ion or it will.m
0680: 61 6b 65 20 64 6f 20 77 69 74 68 6f 75 74 20 74  ake do without t
0690: 68 65 20 72 65 71 75 65 73 74 65 64 20 6d 65 6d  he requested mem
06a0: 6f 72 79 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a  ory..</p></li>..
06b0: 3c 6c 69 3e 3c 70 3e 0a 3c 62 3e 4e 6f 20 6d 65  <li><p>.<b>No me
06c0: 6d 6f 72 79 20 6c 65 61 6b 73 2e 3c 2f 62 3e 0a  mory leaks.</b>.
06d0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
06e0: 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
06f0: 6f 72 20 64 65 73 74 72 6f 79 69 6e 67 20 61 6e  or destroying an
0700: 79 20 6f 62 6a 65 63 74 73 20 69 74 20 61 6c 6c  y objects it all
0710: 6f 63 61 74 65 73 2e 0a 28 46 6f 72 20 65 78 61  ocates..(For exa
0720: 6d 70 6c 65 2c 20 74 68 65 20 61 70 70 6c 69 63  mple, the applic
0730: 61 74 69 6f 6e 20 6d 75 73 74 20 75 73 65 20 5b  ation must use [
0740: 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
0750: 28 29 5d 20 6f 6e 20 0a 65 76 65 72 79 20 5b 70  ()] on .every [p
0760: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
0770: 74 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  t] and [sqlite3_
0780: 63 6c 6f 73 65 28 29 5d 20 6f 6e 20 65 76 65 72  close()] on ever
0790: 79 20 0a 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  y .[database con
07a0: 6e 65 63 74 69 6f 6e 5d 2e 29 20 20 20 42 75 74  nection].)   But
07b0: 20 61 73 20 6c 6f 6e 67 20 61 73 0a 74 68 65 20   as long as.the 
07c0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 6f 70  application coop
07d0: 65 72 61 74 65 73 2c 20 53 51 4c 69 74 65 20 77  erates, SQLite w
07e0: 69 6c 6c 20 6e 65 76 65 72 20 6c 65 61 6b 20 6d  ill never leak m
07f0: 65 6d 6f 72 79 2e 20 20 54 68 69 73 20 69 73 0a  emory.  This is.
0800: 74 72 75 65 20 65 76 65 6e 20 69 6e 20 74 68 65  true even in the
0810: 20 66 61 63 65 20 6f 66 20 6d 65 6d 6f 72 79 20   face of memory 
0820: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
0830: 72 65 73 20 6f 72 20 6f 74 68 65 72 20 73 79 73  res or other sys
0840: 74 65 6d 0a 65 72 72 6f 72 73 2e 0a 3c 2f 70 3e  tem.errors..</p>
0850: 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 3c  </li>..<li><p>.<
0860: 62 3e 4d 65 6d 6f 72 79 20 75 73 61 67 65 20 6c  b>Memory usage l
0870: 69 6d 69 74 73 2e 3c 2f 62 3e 0a 54 68 65 20 5b  imits.</b>.The [
0880: 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
0890: 70 5f 6c 69 6d 69 74 36 34 28 29 5d 20 6d 65 63  p_limit64()] mec
08a0: 68 61 6e 69 73 6d 20 61 6c 6c 6f 77 73 20 74 68  hanism allows th
08b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f  e application to
08c0: 0a 73 65 74 20 61 20 6d 65 6d 6f 72 79 20 75 73  .set a memory us
08d0: 61 67 65 20 6c 69 6d 69 74 20 74 68 61 74 20 53  age limit that S
08e0: 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
08f0: 20 73 74 61 79 20 62 65 6c 6f 77 2e 20 20 53 51   stay below.  SQ
0900: 4c 69 74 65 0a 77 69 6c 6c 20 61 74 74 65 6d 70  Lite.will attemp
0910: 74 20 74 6f 20 72 65 75 73 65 20 6d 65 6d 6f 72  t to reuse memor
0920: 79 20 66 72 6f 6d 20 69 74 73 20 63 61 63 68 65  y from its cache
0930: 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 61 6c  s rather than al
0940: 6c 6f 63 61 74 69 6e 67 20 6e 65 77 0a 6d 65 6d  locating new.mem
0950: 6f 72 79 20 61 73 20 69 74 20 61 70 70 72 6f 61  ory as it approa
0960: 63 68 65 73 20 74 68 65 20 73 6f 66 74 20 6c 69  ches the soft li
0970: 6d 69 74 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a  mit..</p></li>..
0980: 3c 6c 69 3e 3c 70 3e 0a 3c 62 3e 5a 65 72 6f 2d  <li><p>.<b>Zero-
0990: 6d 61 6c 6c 6f 63 20 6f 70 74 69 6f 6e 2e 3c 2f  malloc option.</
09a0: 62 3e 0a 54 68 65 20 61 70 70 6c 69 63 61 74 69  b>.The applicati
09b0: 6f 6e 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c  on can optionall
09c0: 79 20 70 72 6f 76 69 64 65 20 53 51 4c 69 74 65  y provide SQLite
09d0: 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 62 75   with several bu
09e0: 66 66 65 72 73 20 6f 66 20 62 75 6c 6b 20 6d 65  ffers of bulk me
09f0: 6d 6f 72 79 0a 61 74 20 73 74 61 72 74 75 70 20  mory.at startup 
0a00: 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  and SQLite will 
0a10: 74 68 65 6e 20 75 73 65 20 74 68 6f 73 65 20 70  then use those p
0a20: 72 6f 76 69 64 65 64 20 62 75 66 66 65 72 73 20  rovided buffers 
0a30: 66 6f 72 20 61 6c 6c 20 6f 66 0a 69 74 73 20 6d  for all of.its m
0a40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
0a50: 20 6e 65 65 64 73 20 61 6e 64 20 6e 65 76 65 72   needs and never
0a60: 20 63 61 6c 6c 20 73 79 73 74 65 6d 20 6d 61 6c   call system mal
0a70: 6c 6f 63 28 29 20 6f 72 20 66 72 65 65 28 29 2e  loc() or free().
0a80: 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e  .</p></li>..<li>
0a90: 3c 70 3e 0a 3c 62 3e 41 70 70 6c 69 63 61 74 69  <p>.<b>Applicati
0aa0: 6f 6e 2d 73 75 70 70 6c 69 65 64 20 6d 65 6d 6f  on-supplied memo
0ab0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 2e 3c 2f  ry allocators.</
0ac0: 62 3e 0a 54 68 65 20 61 70 70 6c 69 63 61 74 69  b>.The applicati
0ad0: 6f 6e 20 63 61 6e 20 70 72 6f 76 69 64 65 20 53  on can provide S
0ae0: 51 4c 69 74 65 20 77 69 74 68 20 70 6f 69 6e 74  QLite with point
0af0: 65 72 73 20 74 6f 20 61 6c 74 65 72 6e 61 74 69  ers to alternati
0b00: 76 65 20 0a 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ve .memory alloc
0b10: 61 74 6f 72 73 20 61 74 20 73 74 61 72 74 2d 74  ators at start-t
0b20: 69 6d 65 2e 20 20 54 68 65 20 61 6c 74 65 72 6e  ime.  The altern
0b30: 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  ative memory all
0b40: 6f 63 61 74 6f 72 0a 77 69 6c 6c 20 62 65 20 75  ocator.will be u
0b50: 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  sed in place of 
0b60: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
0b70: 61 6e 64 20 66 72 65 65 28 29 2e 0a 3c 2f 70 3e  and free()..</p>
0b80: 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 3c  </li>..<li><p>.<
0b90: 62 3e 50 72 6f 6f 66 20 61 67 61 69 6e 73 74 20  b>Proof against 
0ba0: 62 72 65 61 6b 64 6f 77 6e 20 61 6e 64 20 66 72  breakdown and fr
0bb0: 61 67 6d 65 6e 74 61 74 69 6f 6e 2e 3c 2f 62 3e  agmentation.</b>
0bc0: 0a 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20 63  .SQLite can be c
0bd0: 6f 6e 66 69 67 75 72 65 64 20 73 6f 20 74 68 61  onfigured so tha
0be0: 74 2c 20 73 75 62 6a 65 63 74 20 74 6f 20 63 65  t, subject to ce
0bf0: 72 74 61 69 6e 20 75 73 61 67 65 20 63 6f 6e 73  rtain usage cons
0c00: 74 72 61 69 6e 74 73 0a 64 65 74 61 69 6c 65 64  traints.detailed
0c10: 20 62 65 6c 6f 77 2c 20 69 74 20 69 73 20 67 75   below, it is gu
0c20: 61 72 61 6e 74 65 65 64 20 74 6f 20 6e 65 76 65  aranteed to neve
0c30: 72 20 66 61 69 6c 20 61 20 6d 65 6d 6f 72 79 20  r fail a memory 
0c40: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 6f 72 20 66 72  allocation.or fr
0c50: 61 67 6d 65 6e 74 20 74 68 65 20 68 65 61 70 2e  agment the heap.
0c60: 0a 54 68 69 73 20 70 72 6f 70 65 72 74 79 20 69  .This property i
0c70: 73 20 69 6d 70 6f 72 74 61 6e 74 20 74 6f 20 6c  s important to l
0c80: 6f 6e 67 2d 72 75 6e 6e 69 6e 67 2c 20 68 69 67  ong-running, hig
0c90: 68 2d 72 65 6c 69 61 62 69 6c 69 74 79 0a 65 6d  h-reliability.em
0ca0: 62 65 64 64 65 64 20 73 79 73 74 65 6d 73 20 77  bedded systems w
0cb0: 68 65 72 65 20 61 20 6d 65 6d 6f 72 79 20 61 6c  here a memory al
0cc0: 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 63  location error c
0cd0: 6f 75 6c 64 20 63 6f 6e 74 72 69 62 75 74 65 0a  ould contribute.
0ce0: 74 6f 20 61 6e 20 6f 76 65 72 61 6c 6c 20 73 79  to an overall sy
0cf0: 73 74 65 6d 20 66 61 69 6c 75 72 65 2e 0a 3c 2f  stem failure..</
0d00: 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e  p></li>..<li><p>
0d10: 0a 3c 62 3e 4d 65 6d 6f 72 79 20 75 73 61 67 65  .<b>Memory usage
0d20: 20 73 74 61 74 69 73 74 69 63 73 2e 3c 2f 62 3e   statistics.</b>
0d30: 0a 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 63 61  .Applications ca
0d40: 6e 20 73 65 65 20 68 6f 77 20 6d 75 63 68 20 6d  n see how much m
0d50: 65 6d 6f 72 79 20 74 68 65 79 20 61 72 65 20 75  emory they are u
0d60: 73 69 6e 67 20 61 6e 64 20 64 65 74 65 63 74 20  sing and detect 
0d70: 77 68 65 6e 0a 6d 65 6d 6f 72 79 20 75 73 61 67  when.memory usag
0d80: 65 20 69 73 20 61 70 70 72 6f 61 63 68 69 6e 67  e is approaching
0d90: 20 6f 72 20 65 78 63 65 65 64 69 6e 67 20 64 65   or exceeding de
0da0: 73 69 67 6e 20 62 6f 75 6e 64 61 72 69 65 73 2e  sign boundaries.
0db0: 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 61 20 6e  .</p></li>..<a n
0dc0: 61 6d 65 3d 22 70 77 77 6f 22 3e 3c 2f 61 3e 0a  ame="pwwo"></a>.
0dd0: 3c 6c 69 3e 3c 70 3e 0a 3c 62 3e 50 6c 61 79 73  <li><p>.<b>Plays
0de0: 20 77 65 6c 6c 20 77 69 74 68 20 6d 65 6d 6f 72   well with memor
0df0: 79 20 64 65 62 75 67 67 65 72 73 2e 3c 2f 62 3e  y debuggers.</b>
0e00: 0a 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69  .Memory allocati
0e10: 6f 6e 20 69 6e 20 53 51 4c 69 74 65 20 69 73 20  on in SQLite is 
0e20: 73 74 72 75 63 74 75 72 65 64 20 73 6f 20 74 68  structured so th
0e30: 61 74 20 73 74 61 6e 64 61 72 64 0a 74 68 69 72  at standard.thir
0e40: 64 2d 70 61 72 74 79 20 6d 65 6d 6f 72 79 20 64  d-party memory d
0e50: 65 62 75 67 67 65 72 73 20 28 73 75 63 68 20 61  ebuggers (such a
0e60: 73 20 5b 68 74 74 70 3a 2f 2f 64 6d 61 6c 6c 6f  s [http://dmallo
0e70: 63 2e 63 6f 6d 20 7c 20 64 6d 61 6c 6c 6f 63 5d  c.com | dmalloc]
0e80: 20 6f 72 20 0a 5b 68 74 74 70 3a 2f 2f 76 61 6c   or .[http://val
0e90: 67 72 69 6e 64 2e 6f 72 67 20 7c 20 76 61 6c 67  grind.org | valg
0ea0: 72 69 6e 64 5d 29 20 63 61 6e 20 62 65 20 75 73  rind]) can be us
0eb0: 65 64 20 74 6f 20 76 65 72 69 66 79 20 63 6f 72  ed to verify cor
0ec0: 72 65 63 74 0a 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rect.memory allo
0ed0: 63 61 74 69 6f 6e 20 62 65 68 61 76 69 6f 72 2e  cation behavior.
0ee0: 3c 2f 70 3e 0a 0a 3c 6c 69 3e 3c 70 3e 0a 3c 62  </p>..<li><p>.<b
0ef0: 3e 4d 69 6e 69 6d 61 6c 20 63 61 6c 6c 73 20 74  >Minimal calls t
0f00: 6f 20 74 68 65 20 61 6c 6c 6f 63 61 74 6f 72 2e  o the allocator.
0f10: 3c 2f 62 3e 0a 54 68 65 20 73 79 73 74 65 6d 20  </b>.The system 
0f20: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
0f30: 65 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  e() implementati
0f40: 6f 6e 73 20 61 72 65 20 69 6e 65 66 66 69 63 69  ons are ineffici
0f50: 65 6e 74 0a 6f 6e 20 6d 61 6e 79 20 73 79 73 74  ent.on many syst
0f60: 65 6d 73 2e 20 20 53 51 4c 69 74 65 20 73 74 72  ems.  SQLite str
0f70: 69 76 65 73 20 74 6f 20 72 65 64 75 63 65 20 6f  ives to reduce o
0f80: 76 65 72 61 6c 6c 20 70 72 6f 63 65 73 73 69 6e  verall processin
0f90: 67 20 74 69 6d 65 0a 62 79 20 6d 69 6e 69 6d 69  g time.by minimi
0fa0: 7a 69 6e 67 20 69 74 73 20 75 73 65 20 6f 66 20  zing its use of 
0fb0: 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65  malloc() and fre
0fc0: 65 28 29 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a  e()..</p></li>..
0fd0: 3c 6c 69 3e 3c 70 3e 0a 3c 62 3e 4f 70 65 6e 20  <li><p>.<b>Open 
0fe0: 61 63 63 65 73 73 2e 3c 2f 62 3e 0a 50 6c 75 67  access.</b>.Plug
0ff0: 67 61 62 6c 65 20 53 51 4c 69 74 65 20 65 78 74  gable SQLite ext
1000: 65 6e 73 69 6f 6e 73 20 6f 72 20 65 76 65 6e 20  ensions or even 
1010: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1020: 69 74 73 65 6c 66 20 63 61 6e 20 0a 61 63 63 65  itself can .acce
1030: 73 73 20 74 6f 20 74 68 65 20 73 61 6d 65 20 75  ss to the same u
1040: 6e 64 65 72 6c 79 69 6e 67 20 6d 65 6d 6f 72 79  nderlying memory
1050: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 72 6f 75 74   allocation.rout
1060: 69 6e 65 73 20 75 73 65 64 20 62 79 20 53 51 4c  ines used by SQL
1070: 69 74 65 20 74 68 72 6f 75 67 68 20 74 68 65 0a  ite through the.
1080: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
1090: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  )], [sqlite3_rea
10a0: 6c 6c 6f 63 28 29 5d 2c 20 61 6e 64 20 5b 73 71  lloc()], and [sq
10b0: 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 6e  lite3_free()] in
10c0: 74 65 72 66 61 63 65 73 2e 0a 3c 2f 70 3e 3c 2f  terfaces..</p></
10d0: 6c 69 3e 0a 0a 3c 2f 75 6c 3e 0a 0a 3c 61 20 6e  li>..</ul>..<a n
10e0: 61 6d 65 3d 22 74 65 73 74 69 6e 67 22 3e 3c 2f  ame="testing"></
10f0: 61 3e 0a 3c 68 31 3e 20 54 65 73 74 69 6e 67 3c  a>.<h1> Testing<
1100: 2f 68 31 3e 0a 0a 3c 70 3e 4d 6f 73 74 20 6f 66  /h1>..<p>Most of
1110: 20 74 68 65 20 63 6f 64 65 20 69 6e 20 74 68 65   the code in the
1120: 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74   SQLite source t
1130: 72 65 65 20 69 73 20 64 65 76 6f 74 65 64 20 70  ree is devoted p
1140: 75 72 65 6c 79 20 74 6f 20 0a 5b 74 65 73 74 69  urely to .[testi
1150: 6e 67 20 7c 20 74 65 73 74 69 6e 67 20 61 6e 64  ng | testing and
1160: 20 76 65 72 69 66 69 63 61 74 69 6f 6e 5d 2e 20   verification]. 
1170: 20 52 65 6c 69 61 62 69 6c 69 74 79 20 69 73 20   Reliability is 
1180: 69 6d 70 6f 72 74 61 6e 74 20 74 6f 20 53 51 4c  important to SQL
1190: 69 74 65 2e 0a 41 6d 6f 6e 67 20 74 68 65 20 74  ite..Among the t
11a0: 61 73 6b 73 20 6f 66 20 74 68 65 20 74 65 73 74  asks of the test
11b0: 20 69 6e 66 72 61 73 74 72 75 63 74 75 72 65 20   infrastructure 
11c0: 69 73 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61  is to ensure tha
11d0: 74 0a 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f  t.SQLite does no
11e0: 74 20 6d 69 73 75 73 65 20 64 79 6e 61 6d 69 63  t misuse dynamic
11f0: 61 6c 6c 79 20 61 6c 6c 6f 63 61 74 65 64 20 6d  ally allocated m
1200: 65 6d 6f 72 79 2c 20 74 68 61 74 20 53 51 4c 69  emory, that SQLi
1210: 74 65 0a 64 6f 65 73 20 6e 6f 74 20 6c 65 61 6b  te.does not leak
1220: 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 74 68 61   memory, and tha
1230: 74 20 53 51 4c 69 74 65 20 72 65 73 70 6f 6e 64  t SQLite respond
1240: 73 0a 63 6f 72 72 65 63 74 6c 79 20 74 6f 20 61  s.correctly to a
1250: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
1260: 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75  allocation failu
1270: 72 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20  re.</p>..<p>The 
1280: 74 65 73 74 20 69 6e 66 72 61 73 74 72 75 63 74  test infrastruct
1290: 75 72 65 20 76 65 72 69 66 69 65 73 20 74 68 61  ure verifies tha
12a0: 74 20 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f  t SQLite does no
12b0: 74 20 6d 69 73 75 73 65 0a 64 79 6e 61 6d 69 63  t misuse.dynamic
12c0: 61 6c 6c 79 20 61 6c 6c 6f 63 61 74 65 64 20 6d  ally allocated m
12d0: 65 6d 6f 72 79 20 62 79 20 75 73 69 6e 67 20 61  emory by using a
12e0: 20 73 70 65 63 69 61 6c 6c 79 20 69 6e 73 74 72   specially instr
12f0: 75 6d 65 6e 74 65 64 0a 6d 65 6d 6f 72 79 20 61  umented.memory a
1300: 6c 6c 6f 63 61 74 6f 72 2e 20 20 54 68 65 20 69  llocator.  The i
1310: 6e 73 74 72 75 6d 65 6e 74 65 64 20 6d 65 6d 6f  nstrumented memo
1320: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20  ry allocator is 
1330: 65 6e 61 62 6c 65 64 0a 61 74 20 63 6f 6d 70 69  enabled.at compi
1340: 6c 65 2d 74 69 6d 65 20 75 73 69 6e 67 20 74 68  le-time using th
1350: 65 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42  e [SQLITE_MEMDEB
1360: 55 47 5d 20 6f 70 74 69 6f 6e 2e 20 20 54 68 65  UG] option.  The
1370: 20 69 6e 73 74 72 75 6d 65 6e 74 65 64 0a 6d 65   instrumented.me
1380: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 69  mory allocator i
1390: 73 20 6d 75 63 68 20 73 6c 6f 77 65 72 20 74 68  s much slower th
13a0: 61 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  an the default m
13b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
13c0: 61 6e 64 0a 73 6f 20 69 74 73 20 75 73 65 20 69  and.so its use i
13d0: 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
13e0: 64 20 69 6e 20 70 72 6f 64 75 63 74 69 6f 6e 2e  d in production.
13f0: 20 20 42 75 74 20 77 68 65 6e 0a 65 6e 61 62 6c    But when.enabl
1400: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
1410: 67 2c 20 0a 74 68 65 20 69 6e 73 74 72 75 6d 65  g, .the instrume
1420: 6e 74 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  nted memory allo
1430: 63 61 74 6f 72 20 70 65 72 66 6f 72 6d 73 20 74  cator performs t
1440: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 68 65  he following che
1450: 63 6b 73 3a 3c 2f 70 3e 0a 0a 3c 75 6c 3e 0a 3c  cks:</p>..<ul>.<
1460: 6c 69 3e 3c 70 3e 3c 62 3e 42 6f 75 6e 64 73 20  li><p><b>Bounds 
1470: 63 68 65 63 6b 69 6e 67 2e 3c 2f 62 3e 0a 54 68  checking.</b>.Th
1480: 65 20 69 6e 73 74 72 75 6d 65 6e 74 65 64 20 6d  e instrumented m
1490: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
14a0: 70 6c 61 63 65 73 20 73 65 6e 74 69 6e 65 6c 20  places sentinel 
14b0: 76 61 6c 75 65 73 20 61 74 20 62 6f 74 68 20 65  values at both e
14c0: 6e 64 73 0a 6f 66 20 65 61 63 68 20 6d 65 6d 6f  nds.of each memo
14d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
14e0: 20 76 65 72 69 66 79 20 74 68 61 74 20 6e 6f 74   verify that not
14f0: 68 69 6e 67 20 77 69 74 68 69 6e 20 53 51 4c 69  hing within SQLi
1500: 74 65 20 77 72 69 74 65 73 0a 6f 75 74 73 69 64  te writes.outsid
1510: 65 20 74 68 65 20 62 6f 75 6e 64 73 20 6f 66 20  e the bounds of 
1520: 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 3c  the allocation.<
1530: 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70  /p></li>..<li><p
1540: 3e 3c 62 3e 55 73 65 20 6f 66 20 6d 65 6d 6f 72  ><b>Use of memor
1550: 79 20 61 66 74 65 72 20 66 72 65 65 69 6e 67 2e  y after freeing.
1560: 3c 2f 62 3e 0a 57 68 65 6e 20 65 61 63 68 20 62  </b>.When each b
1570: 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 69  lock of memory i
1580: 73 20 66 72 65 65 64 2c 20 65 76 65 72 79 20 62  s freed, every b
1590: 79 74 65 20 69 73 20 6f 76 65 72 77 72 69 74 74  yte is overwritt
15a0: 65 6e 20 77 69 74 68 20 61 0a 6e 6f 6e 73 65 6e  en with a.nonsen
15b0: 73 65 20 62 69 74 20 70 61 74 74 65 72 6e 2e 20  se bit pattern. 
15c0: 20 54 68 69 73 20 68 65 6c 70 73 20 74 6f 20 65   This helps to e
15d0: 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20 6d 65  nsure that no me
15e0: 6d 6f 72 79 20 69 73 20 65 76 65 72 0a 75 73 65  mory is ever.use
15f0: 64 20 61 66 74 65 72 20 68 61 76 69 6e 67 20 62  d after having b
1600: 65 65 6e 20 66 72 65 65 64 2e 3c 2f 70 3e 3c 2f  een freed.</p></
1610: 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70 3e 3c 62 3e 46  li>..<li><p><b>F
1620: 72 65 65 69 6e 67 20 6d 65 6d 6f 72 79 20 6e 6f  reeing memory no
1630: 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  t obtained from 
1640: 6d 61 6c 6c 6f 63 2e 3c 2f 62 3e 0a 45 61 63 68  malloc.</b>.Each
1650: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1660: 6f 6e 20 66 72 6f 6d 20 74 68 65 20 69 6e 73 74  on from the inst
1670: 72 75 6d 65 6e 74 65 64 20 6d 65 6d 6f 72 79 20  rumented memory 
1680: 61 6c 6c 6f 63 61 74 6f 72 20 63 6f 6e 74 61 69  allocator contai
1690: 6e 73 0a 73 65 6e 74 69 6e 65 6c 73 20 75 73 65  ns.sentinels use
16a0: 64 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74  d to verify that
16b0: 20 65 76 65 72 79 20 61 6c 6c 6f 63 61 74 69 6f   every allocatio
16c0: 6e 20 66 72 65 65 64 20 63 61 6d 65 0a 66 72 6f  n freed came.fro
16d0: 6d 20 70 72 69 6f 72 20 6d 61 6c 6c 6f 63 2e 3c  m prior malloc.<
16e0: 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e 3c 70  /p></li>..<li><p
16f0: 3e 3c 62 3e 55 6e 69 6e 69 74 69 61 6c 69 7a 65  ><b>Uninitialize
1700: 64 20 6d 65 6d 6f 72 79 2e 3c 2f 62 3e 0a 54 68  d memory.</b>.Th
1710: 65 20 69 6e 73 74 72 75 6d 65 6e 74 65 64 20 6d  e instrumented m
1720: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
1730: 69 6e 69 74 69 61 6c 69 7a 65 73 20 65 61 63 68  initializes each
1740: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1750: 6f 6e 0a 74 6f 20 61 20 6e 6f 6e 73 65 6e 73 65  on.to a nonsense
1760: 20 62 69 74 20 70 61 74 74 65 72 6e 20 74 6f 20   bit pattern to 
1770: 68 65 6c 70 20 65 6e 73 75 72 65 20 74 68 61 74  help ensure that
1780: 20 74 68 65 20 75 73 65 72 20 6d 61 6b 65 73 20   the user makes 
1790: 6e 6f 0a 61 73 73 75 6d 70 74 69 6f 6e 73 20 61  no.assumptions a
17a0: 62 6f 75 74 20 74 68 65 20 63 6f 6e 74 65 6e 74  bout the content
17b0: 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d   of allocation m
17c0: 65 6d 6f 72 79 2e 3c 2f 70 3e 3c 2f 6c 69 3e 0a  emory.</p></li>.
17d0: 3c 2f 75 6c 3e 0a 0a 3c 70 3e 52 65 67 61 72 64  </ul>..<p>Regard
17e0: 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
17f0: 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 73 74 72  or not the instr
1800: 75 6d 65 6e 74 65 64 20 6d 65 6d 6f 72 79 20 61  umented memory a
1810: 6c 6c 6f 63 61 74 6f 72 20 69 73 0a 75 73 65 64  llocator is.used
1820: 2c 20 53 51 4c 69 74 65 20 6b 65 65 70 73 20 74  , SQLite keeps t
1830: 72 61 63 6b 20 6f 66 20 68 6f 77 20 6d 75 63 68  rack of how much
1840: 20 6d 65 6d 6f 72 79 20 69 73 20 63 75 72 72 65   memory is curre
1850: 6e 74 6c 79 20 63 68 65 63 6b 65 64 20 6f 75 74  ntly checked out
1860: 2e 0a 54 68 65 72 65 20 61 72 65 20 68 75 6e 64  ..There are hund
1870: 72 65 64 73 20 6f 66 20 74 65 73 74 20 73 63 72  reds of test scr
1880: 69 70 74 73 20 75 73 65 64 20 66 6f 72 20 74 65  ipts used for te
1890: 73 74 69 6e 67 20 53 51 4c 69 74 65 2e 20 20 41  sting SQLite.  A
18a0: 74 20 74 68 65 0a 65 6e 64 20 6f 66 20 65 61 63  t the.end of eac
18b0: 68 20 73 63 72 69 70 74 2c 20 61 6c 6c 20 6f 62  h script, all ob
18c0: 6a 65 63 74 73 20 61 72 65 20 64 65 73 74 72 6f  jects are destro
18d0: 79 65 64 20 61 6e 64 20 61 20 74 65 73 74 20 69  yed and a test i
18e0: 73 20 6d 61 64 65 20 74 6f 0a 65 6e 73 75 72 65  s made to.ensure
18f0: 20 74 68 61 74 20 61 6c 6c 20 20 6d 65 6d 6f 72   that all  memor
1900: 79 20 68 61 73 20 62 65 65 6e 20 66 72 65 65 64  y has been freed
1910: 2e 20 20 54 68 69 73 20 69 73 20 68 6f 77 20 6d  .  This is how m
1920: 65 6d 6f 72 79 0a 6c 65 61 6b 73 20 61 72 65 20  emory.leaks are 
1930: 64 65 74 65 63 74 65 64 2e 20 20 4e 6f 74 69 63  detected.  Notic
1940: 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 6c 65  e that memory le
1950: 61 6b 20 64 65 74 65 63 74 69 6f 6e 20 69 73 20  ak detection is 
1960: 69 6e 20 66 6f 72 63 65 20 61 74 0a 61 6c 6c 20  in force at.all 
1970: 74 69 6d 65 73 2c 20 64 75 72 69 6e 67 20 74 65  times, during te
1980: 73 74 20 62 75 69 6c 64 73 20 61 6e 64 20 64 75  st builds and du
1990: 72 69 6e 67 20 70 72 6f 64 75 63 74 69 6f 6e 20  ring production 
19a0: 62 75 69 6c 64 73 2e 20 20 57 68 65 6e 65 76 65  builds.  Wheneve
19b0: 72 0a 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 76  r.one of the dev
19c0: 65 6c 6f 70 65 72 73 20 72 75 6e 73 20 61 6e 79  elopers runs any
19d0: 20 69 6e 64 69 76 69 64 75 61 6c 20 74 65 73 74   individual test
19e0: 20 73 63 72 69 70 74 2c 20 6d 65 6d 6f 72 79 20   script, memory 
19f0: 6c 65 61 6b 0a 64 65 74 65 63 74 69 6f 6e 20 69  leak.detection i
1a00: 73 20 61 63 74 69 76 65 2e 20 20 48 65 6e 63 65  s active.  Hence
1a10: 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 20 74 68   memory leaks th
1a20: 61 74 20 64 6f 20 61 72 69 73 65 20 64 75 72 69  at do arise duri
1a30: 6e 67 20 64 65 76 65 6c 6f 70 6d 65 6e 74 0a 61  ng development.a
1a40: 72 65 20 71 75 69 63 6b 6c 79 20 64 65 74 65 63  re quickly detec
1a50: 74 65 64 20 61 6e 64 20 66 69 78 65 64 2e 3c 2f  ted and fixed.</
1a60: 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 6f 6f 6d  p>..<a name="oom
1a70: 74 65 73 74 69 6e 67 22 3e 3c 2f 61 3e 0a 3c 70  testing"></a>.<p
1a80: 3e 54 68 65 20 72 65 73 70 6f 6e 73 65 20 6f 66  >The response of
1a90: 20 53 51 4c 69 74 65 20 74 6f 20 6f 75 74 2d 6f   SQLite to out-o
1aa0: 66 2d 6d 65 6d 6f 72 79 20 28 4f 4f 4d 29 20 65  f-memory (OOM) e
1ab0: 72 72 6f 72 73 20 69 73 20 74 65 73 74 65 64 20  rrors is tested 
1ac0: 75 73 69 6e 67 0a 61 20 73 70 65 63 69 61 6c 69  using.a speciali
1ad0: 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  zed memory alloc
1ae0: 61 74 6f 72 20 6f 76 65 72 6c 61 79 20 74 68 61  ator overlay tha
1af0: 74 20 63 61 6e 20 73 69 6d 75 6c 61 74 65 20 6d  t can simulate m
1b00: 65 6d 6f 72 79 20 66 61 69 6c 75 72 65 73 2e 0a  emory failures..
1b10: 54 68 65 20 6f 76 65 72 6c 61 79 20 69 73 20 61  The overlay is a
1b20: 20 6c 61 79 65 72 20 74 68 61 74 20 69 73 20 69   layer that is i
1b30: 6e 73 65 72 74 65 64 20 69 6e 20 62 65 74 77 65  nserted in betwe
1b40: 65 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  en the memory al
1b50: 6c 6f 63 61 74 6f 72 0a 61 6e 64 20 74 68 65 20  locator.and the 
1b60: 72 65 73 74 20 6f 66 20 53 51 4c 69 74 65 2e 20  rest of SQLite. 
1b70: 20 54 68 65 20 6f 76 65 72 6c 61 79 20 70 61 73   The overlay pas
1b80: 73 65 73 20 6d 6f 73 74 20 6d 65 6d 6f 72 79 20  ses most memory 
1b90: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 72 65 71 75 65  allocation.reque
1ba0: 73 74 73 20 73 74 72 61 69 67 68 74 20 74 68 72  sts straight thr
1bb0: 6f 75 67 68 20 74 6f 20 74 68 65 20 75 6e 64 65  ough to the unde
1bc0: 72 6c 79 69 6e 67 20 61 6c 6c 6f 63 61 74 6f 72  rlying allocator
1bd0: 20 61 6e 64 20 70 61 73 73 65 73 20 74 68 65 0a   and passes the.
1be0: 72 65 73 75 6c 74 73 20 62 61 63 6b 20 75 70 20  results back up 
1bf0: 74 6f 20 74 68 65 20 72 65 71 75 65 73 74 65 72  to the requester
1c00: 2e 20 20 42 75 74 20 74 68 65 20 6f 76 65 72 6c  .  But the overl
1c10: 61 79 20 63 61 6e 20 62 65 20 73 65 74 20 74 6f  ay can be set to
1c20: 20 0a 63 61 75 73 65 20 74 68 65 20 4e 74 68 20   .cause the Nth 
1c30: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1c40: 6e 20 74 6f 20 66 61 69 6c 2e 20 20 54 6f 20 72  n to fail.  To r
1c50: 75 6e 20 61 6e 20 4f 4f 4d 20 74 65 73 74 2c 20  un an OOM test, 
1c60: 74 68 65 20 6f 76 65 72 6c 61 79 0a 69 73 20 66  the overlay.is f
1c70: 69 72 73 74 20 73 65 74 20 74 6f 20 66 61 69 6c  irst set to fail
1c80: 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20 61 6c   on the first al
1c90: 6c 6f 63 61 74 69 6f 6e 20 61 74 74 65 6d 70 74  location attempt
1ca0: 2e 20 20 54 68 65 6e 20 73 6f 6d 65 20 74 65 73  .  Then some tes
1cb0: 74 0a 73 63 72 69 70 74 20 69 73 20 72 75 6e 20  t.script is run 
1cc0: 61 6e 64 20 76 65 72 69 66 69 63 61 74 69 6f 6e  and verification
1cd0: 20 74 68 61 74 20 74 68 65 20 61 6c 6c 6f 63 61   that the alloca
1ce0: 74 69 6f 6e 20 77 61 73 20 63 6f 72 72 65 63 74  tion was correct
1cf0: 6c 79 20 63 61 75 67 68 74 0a 61 6e 64 20 68 61  ly caught.and ha
1d00: 6e 64 6c 65 64 20 69 73 20 6d 61 64 65 2e 20 20  ndled is made.  
1d10: 54 68 65 6e 20 74 68 65 20 6f 76 65 72 6c 61 79  Then the overlay
1d20: 20 69 73 20 73 65 74 20 74 6f 20 66 61 69 6c 20   is set to fail 
1d30: 6f 6e 20 74 68 65 20 73 65 63 6f 6e 64 0a 61 6c  on the second.al
1d40: 6c 6f 63 61 74 69 6f 6e 20 61 6e 64 20 74 68 65  location and the
1d50: 20 74 65 73 74 20 72 65 70 65 61 74 73 2e 20 20   test repeats.  
1d60: 54 68 65 20 66 61 69 6c 75 72 65 20 70 6f 69 6e  The failure poin
1d70: 74 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20 61  t continues to a
1d80: 64 76 61 6e 63 65 0a 6f 6e 65 20 61 6c 6c 6f 63  dvance.one alloc
1d90: 61 74 69 6f 6e 20 61 74 20 61 20 74 69 6d 65 20  ation at a time 
1da0: 75 6e 74 69 6c 20 74 68 65 20 65 6e 74 69 72 65  until the entire
1db0: 20 74 65 73 74 20 70 72 6f 63 65 64 75 72 65 20   test procedure 
1dc0: 72 75 6e 73 20 74 6f 0a 63 6f 6d 70 6c 65 74 69  runs to.completi
1dd0: 6f 6e 20 77 69 74 68 6f 75 74 20 68 69 74 74 69  on without hitti
1de0: 6e 67 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ng a memory allo
1df0: 63 61 74 69 6f 6e 20 65 72 72 6f 72 2e 20 20 54  cation error.  T
1e00: 68 69 73 20 77 68 6f 6c 65 0a 74 65 73 74 20 73  his whole.test s
1e10: 65 71 75 65 6e 63 65 20 72 75 6e 20 74 77 69 63  equence run twic
1e20: 65 2e 20 20 4f 6e 20 74 68 65 20 66 69 72 73 74  e.  On the first
1e30: 20 70 61 73 73 2c 20 74 68 65 0a 6f 76 65 72 6c   pass, the.overl
1e40: 61 79 20 69 73 20 73 65 74 20 74 6f 20 66 61 69  ay is set to fai
1e50: 6c 20 6f 6e 6c 79 20 74 68 65 20 4e 74 68 20 61  l only the Nth a
1e60: 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 4f 6e 20 74  llocation.  On t
1e70: 68 65 20 73 65 63 6f 6e 64 20 70 61 73 73 2c 0a  he second pass,.
1e80: 74 68 65 20 6f 76 65 72 6c 61 79 20 69 73 20 73  the overlay is s
1e90: 65 74 20 74 6f 20 66 61 69 6c 20 74 68 65 20 4e  et to fail the N
1ea0: 74 68 20 61 6e 64 20 61 6c 6c 20 73 75 62 73 65  th and all subse
1eb0: 71 75 65 6e 74 20 61 6c 6c 6f 63 61 74 69 6f 6e  quent allocation
1ec0: 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4e 6f 74 65 20  s.</p>..<p>Note 
1ed0: 74 68 61 74 20 74 68 65 20 6d 65 6d 6f 72 79 20  that the memory 
1ee0: 6c 65 61 6b 20 64 65 74 65 63 74 69 6f 6e 20 6c  leak detection l
1ef0: 6f 67 69 63 20 63 6f 6e 74 69 6e 75 65 73 20 74  ogic continues t
1f00: 6f 20 77 6f 72 6b 20 65 76 65 6e 0a 77 68 65 6e  o work even.when
1f10: 20 74 68 65 20 4f 4f 4d 20 6f 76 65 72 6c 61 79   the OOM overlay
1f20: 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 2e 20   is being used. 
1f30: 20 54 68 69 73 20 76 65 72 69 66 69 65 73 20 74   This verifies t
1f40: 68 61 74 20 53 51 4c 69 74 65 0a 64 6f 65 73 20  hat SQLite.does 
1f50: 6e 6f 74 20 6c 65 61 6b 20 6d 65 6d 6f 72 79 20  not leak memory 
1f60: 65 76 65 6e 20 77 68 65 6e 20 69 74 20 65 6e 63  even when it enc
1f70: 6f 75 6e 74 65 72 73 20 6d 65 6d 6f 72 79 20 61  ounters memory a
1f80: 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73  llocation errors
1f90: 2e 0a 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ..Note also that
1fa0: 20 74 68 65 20 4f 4f 4d 20 6f 76 65 72 6c 61 79   the OOM overlay
1fb0: 20 63 61 6e 20 77 6f 72 6b 20 77 69 74 68 20 61   can work with a
1fc0: 6e 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 6d 65  ny underlying me
1fd0: 6d 6f 72 79 0a 61 6c 6c 6f 63 61 74 6f 72 2c 20  mory.allocator, 
1fe0: 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 69 6e  including the in
1ff0: 73 74 72 75 6d 65 6e 74 65 64 20 6d 65 6d 6f 72  strumented memor
2000: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
2010: 20 63 68 65 63 6b 73 0a 66 6f 72 20 6d 65 6d 6f   checks.for memo
2020: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6d 69  ry allocation mi
2030: 73 75 73 65 2e 20 20 49 6e 20 74 68 69 73 20 77  suse.  In this w
2040: 61 79 20 69 74 20 69 73 20 76 65 72 69 66 69 65  ay it is verifie
2050: 64 20 74 68 61 74 20 0a 4f 4f 4d 20 65 72 72 6f  d that .OOM erro
2060: 72 73 20 64 6f 20 6e 6f 74 20 69 6e 64 75 63 65  rs do not induce
2070: 20 6f 74 68 65 72 20 6b 69 6e 64 73 20 6f 66 20   other kinds of 
2080: 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 65 72 72  memory usage err
2090: 6f 72 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 46 69 6e  ors.</p>..<p>Fin
20a0: 61 6c 6c 79 2c 20 77 65 20 6f 62 73 65 72 76 65  ally, we observe
20b0: 20 74 68 61 74 20 74 68 65 20 69 6e 73 74 72 75   that the instru
20c0: 6d 65 6e 74 65 64 20 6d 65 6d 6f 72 79 20 61 6c  mented memory al
20d0: 6c 6f 63 61 74 6f 72 20 61 6e 64 20 74 68 65 0a  locator and the.
20e0: 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 64 65 74 65  memory leak dete
20f0: 63 74 6f 72 20 62 6f 74 68 20 77 6f 72 6b 20 6f  ctor both work o
2100: 76 65 72 20 74 68 65 20 65 6e 74 69 72 65 20 53  ver the entire S
2110: 51 4c 69 74 65 20 74 65 73 74 20 73 75 69 74 65  QLite test suite
2120: 20 61 6e 64 0a 74 68 65 20 5b 54 43 4c 20 74 65   and.the [TCL te
2130: 73 74 20 73 75 69 74 65 5d 20 70 72 6f 76 69 64  st suite] provid
2140: 65 73 20 6f 76 65 72 20 39 39 25 20 73 74 61 74  es over 99% stat
2150: 65 6d 65 6e 74 20 74 65 73 74 20 63 6f 76 65 72  ement test cover
2160: 61 67 65 20 61 6e 64 20 74 68 61 74 0a 74 68 65  age and that.the
2170: 20 5b 54 48 33 5d 20 74 65 73 74 20 68 61 72 6e   [TH3] test harn
2180: 65 73 73 20 70 72 6f 76 69 64 65 73 20 5b 74 65  ess provides [te
2190: 73 74 20 63 6f 76 65 72 61 67 65 20 7c 20 31 30  st coverage | 10
21a0: 30 25 20 62 72 61 6e 63 68 20 74 65 73 74 20 63  0% branch test c
21b0: 6f 76 65 72 61 67 65 5d 0a 77 69 74 68 20 6e 6f  overage].with no
21c0: 20 6c 65 61 6b 20 6c 65 61 6b 73 2e 20 54 68 69   leak leaks. Thi
21d0: 73 20 69 73 0a 73 74 72 6f 6e 67 20 65 76 69 64  s is.strong evid
21e0: 65 6e 63 65 20 74 68 61 74 20 64 79 6e 61 6d 69  ence that dynami
21f0: 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  c memory allocat
2200: 69 6f 6e 20 69 73 20 75 73 65 64 20 63 6f 72 72  ion is used corr
2210: 65 63 74 6c 79 0a 65 76 65 72 79 77 68 65 72 65  ectly.everywhere
2220: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 2e 3c   within SQLite.<
2230: 2f 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 61 6c  /p>..<a name="al
2240: 6c 6f 63 61 72 72 61 79 22 3e 3c 2f 61 3e 0a 3c  locarray"></a>.<
2250: 68 32 3e 20 55 73 65 20 6f 66 20 72 65 61 6c 6c  h2> Use of reall
2260: 6f 63 61 72 72 61 79 28 29 3c 2f 68 32 3e 0a 0a  ocarray()</h2>..
2270: 3c 70 3e 54 68 65 20 72 65 61 6c 6c 6f 63 61 72  <p>The reallocar
2280: 72 61 79 28 29 20 69 6e 74 65 72 66 61 63 65 20  ray() interface 
2290: 69 73 20 61 20 72 65 63 65 6e 74 20 69 6e 6e 6f  is a recent inno
22a0: 76 61 74 69 6f 6e 20 28 63 69 72 63 61 20 32 30  vation (circa 20
22b0: 31 34 29 0a 66 72 6f 6d 20 74 68 65 20 4f 70 65  14).from the Ope
22c0: 6e 42 53 44 20 63 6f 6d 6d 75 6e 69 74 79 20 74  nBSD community t
22d0: 68 61 74 20 67 72 6f 77 20 6f 75 74 20 6f 66 20  hat grow out of 
22e0: 65 66 66 6f 72 74 73 20 74 6f 20 70 72 65 76 65  efforts to preve
22f0: 6e 74 20 74 68 65 0a 6e 65 78 74 20 5b 68 74 74  nt the.next [htt
2300: 70 3a 2f 2f 68 65 61 72 74 62 6c 65 65 64 2e 63  p://heartbleed.c
2310: 6f 6d 20 7c 20 22 68 65 61 72 74 62 6c 65 65 64  om | "heartbleed
2320: 22 20 62 75 67 5d 20 62 79 20 61 76 6f 69 64 69  " bug] by avoidi
2330: 6e 67 20 33 32 2d 62 69 74 20 69 6e 74 65 67 65  ng 32-bit intege
2340: 72 0a 61 72 69 74 68 6d 65 74 69 63 20 6f 76 65  r.arithmetic ove
2350: 72 66 6c 6f 77 20 6f 6e 20 6d 65 6d 6f 72 79 20  rflow on memory 
2360: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
2370: 63 6f 6d 70 75 74 61 74 69 6f 6e 73 2e 20 20 54  computations.  T
2380: 68 65 0a 72 65 61 6c 6c 6f 63 61 72 72 61 79 28  he.reallocarray(
2390: 29 20 66 75 6e 63 74 69 6f 6e 20 68 61 73 20 62  ) function has b
23a0: 6f 74 68 20 75 6e 69 74 2d 73 69 7a 65 20 61 6e  oth unit-size an
23b0: 64 20 63 6f 75 6e 74 20 70 61 72 61 6d 65 74 65  d count paramete
23c0: 72 73 2e 0a 54 6f 20 61 6c 6c 6f 63 61 74 65 20  rs..To allocate 
23d0: 6d 65 6d 6f 72 79 20 73 75 66 66 69 63 69 65 6e  memory sufficien
23e0: 74 20 74 6f 20 68 6f 6c 64 20 61 6e 20 61 72 72  t to hold an arr
23f0: 61 79 20 6f 66 20 4e 20 65 6c 65 6d 65 6e 74 73  ay of N elements
2400: 20 65 61 63 68 20 58 2d 62 79 74 65 73 0a 69 6e   each X-bytes.in
2410: 20 73 69 7a 65 2c 20 6f 6e 65 20 63 61 6c 6c 73   size, one calls
2420: 20 22 72 65 61 6c 6c 6f 63 61 72 72 61 79 28 30   "reallocarray(0
2430: 2c 58 2c 4e 29 22 2e 20 20 54 68 69 73 20 69 73  ,X,N)".  This is
2440: 20 70 72 65 66 65 72 72 65 64 20 6f 76 65 72 0a   preferred over.
2450: 74 68 65 20 74 72 61 64 69 74 69 6f 6e 61 6c 20  the traditional 
2460: 74 65 63 68 6e 69 71 75 65 20 6f 66 20 69 6e 76  technique of inv
2470: 6f 6b 69 6e 67 20 22 6d 61 6c 6c 6f 63 28 58 2a  oking "malloc(X*
2480: 4e 29 22 20 61 73 20 72 65 61 6c 6c 6f 63 61 72  N)" as reallocar
2490: 72 61 79 28 29 0a 65 6c 69 6d 69 6e 61 74 65 73  ray().eliminates
24a0: 20 74 68 65 20 72 69 73 6b 20 74 68 61 74 20 74   the risk that t
24b0: 68 65 20 58 2a 4e 20 6d 75 6c 74 69 70 6c 69 63  he X*N multiplic
24c0: 61 74 69 6f 6e 20 77 69 6c 6c 20 6f 76 65 72 66  ation will overf
24d0: 6c 6f 77 20 61 6e 64 0a 63 61 75 73 65 20 6d 61  low and.cause ma
24e0: 6c 6c 6f 63 28 29 20 74 6f 20 72 65 74 75 72 6e  lloc() to return
24f0: 20 61 20 62 75 66 66 65 72 20 74 68 61 74 20 69   a buffer that i
2500: 73 20 61 20 64 69 66 66 65 72 65 6e 74 20 73 69  s a different si
2510: 7a 65 20 66 72 6f 6d 20 77 68 61 74 0a 74 68 65  ze from what.the
2520: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 65 78 70   application exp
2530: 65 63 74 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 53  ected.</p>..<p>S
2540: 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 75  QLite does not u
2550: 73 65 20 72 65 61 6c 6c 6f 63 61 72 72 61 79 28  se reallocarray(
2560: 29 2e 20 20 54 68 65 20 72 65 61 73 6f 6e 20 69  ).  The reason i
2570: 73 20 74 68 61 74 20 72 65 61 6c 6c 6f 63 61 72  s that reallocar
2580: 72 61 79 28 29 0a 69 73 20 6e 6f 74 20 75 73 65  ray().is not use
2590: 66 75 6c 20 74 6f 20 53 51 4c 69 74 65 2e 20 20  ful to SQLite.  
25a0: 49 74 20 74 75 72 6e 73 20 6f 75 74 20 74 68 61  It turns out tha
25b0: 74 20 53 51 4c 69 74 65 20 6e 65 76 65 72 20 64  t SQLite never d
25c0: 6f 65 73 20 6d 65 6d 6f 72 79 0a 61 6c 6c 6f 63  oes memory.alloc
25d0: 61 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ations that are 
25e0: 74 68 65 20 73 69 6d 70 6c 65 20 70 72 6f 64 75  the simple produ
25f0: 63 74 20 6f 66 20 74 77 6f 20 69 6e 74 65 67 65  ct of two intege
2600: 72 73 2e 20 20 49 6e 73 74 65 61 64 2c 20 53 51  rs.  Instead, SQ
2610: 4c 69 74 65 0a 64 6f 65 73 20 61 6c 6c 6f 63 61  Lite.does alloca
2620: 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 66 6f 72  tions of the for
2630: 6d 20 22 58 2b 43 22 20 6f 72 20 22 4e 2a 58 2b  m "X+C" or "N*X+
2640: 43 22 20 6f 72 20 22 4d 2a 4e 2a 58 2b 43 22 20  C" or "M*N*X+C" 
2650: 6f 72 0a 22 4e 2a 58 2b 4d 2a 59 2b 43 22 2c 20  or."N*X+M*Y+C", 
2660: 61 6e 64 20 73 6f 20 66 6f 72 74 68 2e 20 20 54  and so forth.  T
2670: 68 65 20 72 65 61 6c 6c 6f 63 61 72 72 61 79 28  he reallocarray(
2680: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
2690: 6f 74 20 68 65 6c 70 66 75 6c 0a 69 6e 20 61 76  ot helpful.in av
26a0: 6f 69 64 69 6e 67 20 69 6e 74 65 67 65 72 20 6f  oiding integer o
26b0: 76 65 72 66 6c 6f 77 20 69 6e 20 74 68 6f 73 65  verflow in those
26c0: 20 63 61 73 65 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e   cases.</p>..<p>
26d0: 4e 65 76 65 72 74 68 65 6c 65 73 73 2c 20 69 6e  Nevertheless, in
26e0: 74 65 67 65 72 20 6f 76 65 72 66 6c 6f 77 20 69  teger overflow i
26f0: 6e 20 74 68 65 20 63 6f 6d 70 75 74 61 74 69 6f  n the computatio
2700: 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
2710: 63 61 74 69 6f 6e 0a 73 69 7a 65 73 20 69 73 20  cation.sizes is 
2720: 61 20 63 6f 6e 63 65 72 6e 20 74 68 61 74 20 53  a concern that S
2730: 51 4c 69 74 65 20 77 6f 75 6c 64 20 6c 69 6b 65  QLite would like
2740: 20 74 6f 20 64 65 61 6c 20 77 69 74 68 2e 20 20   to deal with.  
2750: 54 6f 20 70 72 65 76 65 6e 74 0a 70 72 6f 62 6c  To prevent.probl
2760: 65 6d 73 2c 20 61 6c 6c 20 53 51 4c 69 74 65 20  ems, all SQLite 
2770: 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20  internal memory 
2780: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
2790: 72 20 75 73 69 6e 67 20 74 68 69 6e 20 77 72 61  r using thin wra
27a0: 70 70 65 72 0a 66 75 6e 63 74 69 6f 6e 73 20 74  pper.functions t
27b0: 68 61 74 20 74 61 6b 65 20 61 20 73 69 67 6e 65  hat take a signe
27c0: 64 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65 72  d 64-bit integer
27d0: 20 73 69 7a 65 20 70 61 72 61 6d 65 74 65 72 2e   size parameter.
27e0: 20 20 54 68 65 20 53 51 4c 69 74 65 20 0a 73 6f    The SQLite .so
27f0: 75 72 63 65 20 63 6f 64 65 20 69 73 20 61 75 64  urce code is aud
2800: 69 74 65 64 20 74 6f 20 65 6e 73 75 72 65 20 74  ited to ensure t
2810: 68 61 74 20 61 6c 6c 20 73 69 7a 65 20 63 6f 6d  hat all size com
2820: 70 75 74 61 74 69 6f 6e 73 20 61 72 65 20 63 61  putations are ca
2830: 72 72 69 65 64 20 0a 6f 75 74 20 75 73 69 6e 67  rried .out using
2840: 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69   64-bit signed i
2850: 6e 74 65 67 65 72 73 20 61 73 20 77 65 6c 6c 2e  ntegers as well.
2860: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 72 65    SQLite will.re
2870: 66 75 73 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65  fuse to allocate
2880: 20 6d 6f 72 65 20 74 68 61 6e 20 61 62 6f 75 74   more than about
2890: 20 32 47 42 20 6f 66 20 6d 65 6d 6f 72 79 20 61   2GB of memory a
28a0: 74 20 6f 6e 65 20 67 6f 2e 20 20 28 49 6e 20 63  t one go.  (In c
28b0: 6f 6d 6d 6f 6e 0a 75 73 65 2c 20 53 51 4c 69 74  ommon.use, SQLit
28c0: 65 20 73 65 6c 64 6f 6d 20 65 76 65 72 20 61 6c  e seldom ever al
28d0: 6c 6f 63 61 74 65 73 20 6d 6f 72 65 20 74 68 61  locates more tha
28e0: 6e 20 61 62 6f 75 74 20 38 4b 42 20 6f 66 20 6d  n about 8KB of m
28f0: 65 6d 6f 72 79 20 61 74 20 61 20 74 69 6d 65 0a  emory at a time.
2900: 73 6f 20 61 20 32 47 42 20 61 6c 6c 6f 63 61 74  so a 2GB allocat
2910: 69 6f 6e 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74  ion limit is not
2920: 20 61 20 62 75 72 64 65 6e 2e 29 20 20 53 6f 20   a burden.)  So 
2930: 74 68 65 20 36 34 2d 62 69 74 20 73 69 7a 65 20  the 64-bit size 
2940: 70 61 72 61 6d 65 74 65 72 0a 70 72 6f 76 69 64  parameter.provid
2950: 65 73 20 6c 6f 74 73 20 6f 66 20 68 65 61 64 72  es lots of headr
2960: 6f 6f 6d 20 66 6f 72 20 64 65 74 65 63 74 69 6e  oom for detectin
2970: 67 20 6f 76 65 72 66 6c 6f 77 73 2e 20 20 54 68  g overflows.  Th
2980: 65 20 73 61 6d 65 20 61 75 64 69 74 20 74 68 61  e same audit tha
2990: 74 0a 76 65 72 69 66 69 65 73 20 74 68 61 74 20  t.verifies that 
29a0: 61 6c 6c 20 73 69 7a 65 20 63 6f 6d 70 75 74 61  all size computa
29b0: 74 69 6f 6e 73 20 61 72 65 20 64 6f 6e 65 20 61  tions are done a
29c0: 73 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  s 64-bit signed 
29d0: 69 6e 74 65 67 65 72 73 0a 61 6c 73 6f 20 76 65  integers.also ve
29e0: 72 69 66 69 65 73 20 74 68 61 74 20 69 74 20 69  rifies that it i
29f0: 73 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20  s impossible to 
2a00: 6f 76 65 72 66 6c 6f 77 20 61 20 36 34 2d 62 69  overflow a 64-bi
2a10: 74 20 69 6e 74 65 67 65 72 0a 64 75 72 69 6e 67  t integer.during
2a20: 20 74 68 65 20 63 6f 6d 70 75 74 61 74 69 6f 6e   the computation
2a30: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 63 6f  .</p>..<p>The co
2a40: 64 65 20 61 75 64 69 74 73 20 75 73 65 64 20 74  de audits used t
2a50: 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 6d 65  o ensure that me
2a60: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2a70: 73 69 7a 65 20 63 6f 6d 70 75 74 61 74 69 6f 6e  size computation
2a80: 73 0a 64 6f 20 6e 6f 74 20 6f 76 65 72 66 6c 6f  s.do not overflo
2a90: 77 20 69 6e 20 53 51 4c 69 74 65 20 61 72 65 20  w in SQLite are 
2aa0: 72 65 70 65 61 74 65 64 20 70 72 69 6f 72 20 74  repeated prior t
2ab0: 6f 20 65 76 65 72 79 20 53 51 4c 69 74 65 20 72  o every SQLite r
2ac0: 65 6c 65 61 73 65 2e 3c 2f 70 3e 0a 0a 3c 61 20  elease.</p>..<a 
2ad0: 6e 61 6d 65 3d 22 63 6f 6e 66 69 67 22 3e 3c 2f  name="config"></
2ae0: 61 3e 0a 3c 68 31 3e 20 43 6f 6e 66 69 67 75 72  a>.<h1> Configur
2af0: 61 74 69 6f 6e 3c 2f 68 31 3e 0a 0a 3c 70 3e 54  ation</h1>..<p>T
2b00: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
2b10: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 65 74  y allocation set
2b20: 74 69 6e 67 73 20 69 6e 20 53 51 4c 69 74 65 20  tings in SQLite 
2b30: 61 72 65 20 61 70 70 72 6f 70 72 69 61 74 65 0a  are appropriate.
2b40: 66 6f 72 20 6d 6f 73 74 20 61 70 70 6c 69 63 61  for most applica
2b50: 74 69 6f 6e 73 2e 20 20 48 6f 77 65 76 65 72 2c  tions.  However,
2b60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69   applications wi
2b70: 74 68 20 75 6e 75 73 75 61 6c 20 6f 72 20 70 61  th unusual or pa
2b80: 72 74 69 63 75 6c 61 72 6c 79 0a 73 74 72 69 63  rticularly.stric
2b90: 74 20 72 65 71 75 69 72 65 6d 65 6e 74 73 20 6d  t requirements m
2ba0: 61 79 20 77 61 6e 74 20 74 6f 20 61 64 6a 75 73  ay want to adjus
2bb0: 74 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74  t the configurat
2bc0: 69 6f 6e 20 74 6f 20 6d 6f 72 65 20 63 6c 6f 73  ion to more clos
2bd0: 65 6c 79 0a 61 6c 69 67 6e 20 53 51 4c 69 74 65  ely.align SQLite
2be0: 20 74 6f 20 74 68 65 69 72 20 6e 65 65 64 73 2e   to their needs.
2bf0: 0a 42 6f 74 68 20 63 6f 6d 70 69 6c 65 2d 74 69  .Both compile-ti
2c00: 6d 65 20 61 6e 64 20 73 74 61 72 74 2d 74 69 6d  me and start-tim
2c10: 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  e configuration 
2c20: 6f 70 74 69 6f 6e 73 20 61 72 65 20 61 76 61 69  options are avai
2c30: 6c 61 62 6c 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c  lable.</p>..<tcl
2c40: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 61 6c 74  >hd_fragment alt
2c50: 61 6c 6c 6f 63 20 7b 62 75 69 6c 74 2d 69 6e 20  alloc {built-in 
2c60: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
2c70: 73 7d 3c 2f 74 63 6c 3e 0a 3c 68 32 3e 20 41 6c  s}</tcl>.<h2> Al
2c80: 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65  ternative low-le
2c90: 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  vel memory alloc
2ca0: 61 74 6f 72 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  ators</h2>..<p>T
2cb0: 68 65 20 53 51 4c 69 74 65 20 73 6f 75 72 63 65  he SQLite source
2cc0: 20 63 6f 64 65 20 69 6e 63 6c 75 64 65 73 20 73   code includes s
2cd0: 65 76 65 72 61 6c 20 64 69 66 66 65 72 65 6e 74  everal different
2ce0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2cf0: 6f 6e 0a 6d 6f 64 75 6c 65 73 20 74 68 61 74 20  on.modules that 
2d00: 63 61 6e 20 62 65 20 73 65 6c 65 63 74 65 64 20  can be selected 
2d10: 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 2c  at compile-time,
2d20: 20 6f 72 20 74 6f 20 61 20 6c 69 6d 69 74 65 64   or to a limited
2d30: 20 65 78 74 65 6e 74 0a 61 74 20 73 74 61 72 74   extent.at start
2d40: 2d 74 69 6d 65 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c  -time.</p>..<tcl
2d50: 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 64 65 66  >hd_fragment def
2d60: 61 75 6c 74 61 6c 6c 6f 63 20 7b 64 65 66 61 75  aultalloc {defau
2d70: 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
2d80: 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 33 3e 54  tor}</tcl>.<h3>T
2d90: 68 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  he default memor
2da0: 79 20 61 6c 6c 6f 63 61 74 6f 72 3c 2f 68 33 3e  y allocator</h3>
2db0: 0a 0a 3c 70 3e 42 79 20 64 65 66 61 75 6c 74 2c  ..<p>By default,
2dc0: 20 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65   SQLite uses the
2dd0: 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c   malloc(), reall
2de0: 6f 63 28 29 2c 20 61 6e 64 20 66 72 65 65 28 29  oc(), and free()
2df0: 20 72 6f 75 74 69 6e 65 73 0a 66 72 6f 6d 20 74   routines.from t
2e00: 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
2e10: 62 72 61 72 79 20 66 6f 72 20 69 74 73 20 6d 65  brary for its me
2e20: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
2e30: 6e 65 65 64 73 2e 20 20 54 68 65 73 65 20 72 6f  needs.  These ro
2e40: 75 74 69 6e 65 73 0a 61 72 65 20 73 75 72 72 6f  utines.are surro
2e50: 75 6e 64 65 64 20 62 79 20 61 20 74 68 69 6e 20  unded by a thin 
2e60: 77 72 61 70 70 65 72 20 74 68 61 74 20 61 6c 73  wrapper that als
2e70: 6f 20 70 72 6f 76 69 64 65 73 20 61 20 22 6d 65  o provides a "me
2e80: 6d 73 69 7a 65 28 29 22 20 66 75 6e 63 74 69 6f  msize()" functio
2e90: 6e 0a 74 68 61 74 20 77 69 6c 6c 20 72 65 74 75  n.that will retu
2ea0: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
2eb0: 6e 20 65 78 69 73 74 69 6e 67 20 61 6c 6c 6f 63  n existing alloc
2ec0: 61 74 69 6f 6e 2e 20 20 54 68 65 20 6d 65 6d 73  ation.  The mems
2ed0: 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 0a 69  ize() function.i
2ee0: 73 20 6e 65 65 64 65 64 20 74 6f 20 6b 65 65 70  s needed to keep
2ef0: 20 61 6e 20 61 63 63 75 72 61 74 65 20 63 6f 75   an accurate cou
2f00: 6e 74 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72  nt of the number
2f10: 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6f 75 74   of bytes of out
2f20: 73 74 61 6e 64 69 6e 67 0a 6d 65 6d 6f 72 79 3b  standing.memory;
2f30: 20 6d 65 6d 73 69 7a 65 28 29 20 64 65 74 65 72   memsize() deter
2f40: 6d 69 6e 65 73 20 68 6f 77 20 6d 61 6e 79 20 62  mines how many b
2f50: 79 74 65 73 20 74 6f 20 72 65 6d 6f 76 65 20 66  ytes to remove f
2f60: 72 6f 6d 20 74 68 65 20 6f 75 74 73 74 61 6e 64  rom the outstand
2f70: 69 6e 67 0a 63 6f 75 6e 74 20 77 68 65 6e 20 61  ing.count when a
2f80: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20  n allocation is 
2f90: 66 72 65 65 64 2e 20 20 54 68 65 20 64 65 66 61  freed.  The defa
2fa0: 75 6c 74 20 61 6c 6c 6f 63 61 74 6f 72 20 69 6d  ult allocator im
2fb0: 70 6c 65 6d 65 6e 74 73 0a 6d 65 6d 73 69 7a 65  plements.memsize
2fc0: 28 29 20 62 79 20 61 6c 77 61 79 73 20 61 6c 6c  () by always all
2fd0: 6f 63 61 74 69 6e 67 20 38 20 65 78 74 72 61 20  ocating 8 extra 
2fe0: 62 79 74 65 73 20 6f 6e 20 65 61 63 68 20 6d 61  bytes on each ma
2ff0: 6c 6c 6f 63 28 29 20 72 65 71 75 65 73 74 20 61  lloc() request a
3000: 6e 64 0a 73 74 6f 72 69 6e 67 20 74 68 65 20 73  nd.storing the s
3010: 69 7a 65 20 6f 66 20 74 68 65 20 61 6c 6c 6f 63  ize of the alloc
3020: 61 74 69 6f 6e 20 69 6e 20 74 68 61 74 20 38 2d  ation in that 8-
3030: 62 79 74 65 20 68 65 61 64 65 72 2e 3c 2f 70 3e  byte header.</p>
3040: 0a 0a 3c 70 3e 54 68 65 20 64 65 66 61 75 6c 74  ..<p>The default
3050: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
3060: 72 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  r is recommended
3070: 20 66 6f 72 20 6d 6f 73 74 20 61 70 70 6c 69 63   for most applic
3080: 61 74 69 6f 6e 73 2e 0a 49 66 20 79 6f 75 20 64  ations..If you d
3090: 6f 20 6e 6f 74 20 68 61 76 65 20 61 20 63 6f 6d  o not have a com
30a0: 70 65 6c 6c 69 6e 67 20 6e 65 65 64 20 74 6f 20  pelling need to 
30b0: 75 73 65 20 61 6e 20 61 6c 74 65 72 6e 61 74 69  use an alternati
30c0: 76 65 20 6d 65 6d 6f 72 79 0a 61 6c 6c 6f 63 61  ve memory.alloca
30d0: 74 6f 72 2c 20 74 68 65 6e 20 75 73 65 20 74 68  tor, then use th
30e0: 65 20 64 65 66 61 75 6c 74 2e 3c 2f 70 3e 0a 0a  e default.</p>..
30f0: 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74  <tcl>hd_fragment
3100: 20 6d 65 6d 64 65 62 75 67 20 7b 64 65 62 75 67   memdebug {debug
3110: 67 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ging memory allo
3120: 63 61 74 6f 72 7d 20 2a 6d 65 6d 73 79 73 32 3c  cator} *memsys2<
3130: 2f 74 63 6c 3e 0a 3c 68 33 3e 54 68 65 20 64 65  /tcl>.<h3>The de
3140: 62 75 67 67 69 6e 67 20 6d 65 6d 6f 72 79 20 61  bugging memory a
3150: 6c 6c 6f 63 61 74 6f 72 3c 2f 68 33 3e 0a 0a 3c  llocator</h3>..<
3160: 70 3e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63  p>If SQLite is c
3170: 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65  ompiled with the
3180: 20 5b 53 51 4c 49 54 45 5f 4d 45 4d 44 45 42 55   [SQLITE_MEMDEBU
3190: 47 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  G] compile-time 
31a0: 6f 70 74 69 6f 6e 2c 0a 74 68 65 6e 20 61 20 64  option,.then a d
31b0: 69 66 66 65 72 65 6e 74 2c 20 68 65 61 76 79 20  ifferent, heavy 
31c0: 77 72 61 70 70 65 72 20 69 73 20 75 73 65 64 20  wrapper is used 
31d0: 61 72 6f 75 6e 64 20 73 79 73 74 65 6d 20 6d 61  around system ma
31e0: 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28  lloc(), realloc(
31f0: 29 2c 20 0a 61 6e 64 20 66 72 65 65 28 29 2e 0a  ), .and free()..
3200: 54 68 65 20 68 65 61 76 79 20 77 72 61 70 70 65  The heavy wrappe
3210: 72 20 61 6c 6c 6f 63 61 74 65 73 20 61 72 6f 75  r allocates arou
3220: 6e 64 20 31 30 30 20 62 79 74 65 73 20 6f 66 20  nd 100 bytes of 
3230: 65 78 74 72 61 20 73 70 61 63 65 0a 77 69 74 68  extra space.with
3240: 20 65 61 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e   each allocation
3250: 2e 20 20 54 68 65 20 65 78 74 72 61 20 73 70 61  .  The extra spa
3260: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 70 6c  ce is used to pl
3270: 61 63 65 20 73 65 6e 74 69 6e 65 6c 20 76 61 6c  ace sentinel val
3280: 75 65 73 20 0a 61 74 20 62 6f 74 68 20 65 6e 64  ues .at both end
3290: 73 20 6f 66 20 74 68 65 20 61 6c 6c 6f 63 61 74  s of the allocat
32a0: 69 6f 6e 20 72 65 74 75 72 6e 65 64 20 74 6f 20  ion returned to 
32b0: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
32c0: 20 20 57 68 65 6e 20 61 6e 0a 61 6c 6c 6f 63 61    When an.alloca
32d0: 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2c 0a 74  tion is freed,.t
32e0: 68 65 73 65 20 73 65 6e 74 69 6e 65 6c 73 20 61  hese sentinels a
32f0: 72 65 20 63 68 65 63 6b 65 64 20 74 6f 20 6d 61  re checked to ma
3300: 6b 65 20 73 75 72 65 20 74 68 65 20 53 51 4c 69  ke sure the SQLi
3310: 74 65 20 63 6f 72 65 20 64 69 64 20 6e 6f 74 20  te core did not 
3320: 6f 76 65 72 72 75 6e 0a 74 68 65 20 62 75 66 66  overrun.the buff
3330: 65 72 20 69 6e 20 65 69 74 68 65 72 20 64 69 72  er in either dir
3340: 65 63 74 69 6f 6e 2e 20 20 57 68 65 6e 20 74 68  ection.  When th
3350: 65 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72 79  e system library
3360: 20 69 73 20 47 4c 49 42 43 2c 20 74 68 65 20 0a   is GLIBC, the .
3370: 68 65 61 76 79 20 77 72 61 70 70 65 72 20 61 6c  heavy wrapper al
3380: 73 6f 20 6d 61 6b 65 73 20 75 73 65 20 6f 66 20  so makes use of 
3390: 74 68 65 20 47 4e 55 20 62 61 63 6b 74 72 61 63  the GNU backtrac
33a0: 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  e() function to 
33b0: 65 78 61 6d 69 6e 65 0a 74 68 65 20 73 74 61 63  examine.the stac
33c0: 6b 20 61 6e 64 20 72 65 63 6f 72 64 20 74 68 65  k and record the
33d0: 20 61 6e 63 65 73 74 6f 72 20 66 75 6e 63 74 69   ancestor functi
33e0: 6f 6e 73 20 6f 66 20 74 68 65 20 6d 61 6c 6c 6f  ons of the mallo
33f0: 63 28 29 20 63 61 6c 6c 2e 20 20 57 68 65 6e 0a  c() call.  When.
3400: 72 75 6e 6e 69 6e 67 20 74 68 65 20 53 51 4c 69  running the SQLi
3410: 74 65 20 74 65 73 74 20 73 75 69 74 65 2c 20 74  te test suite, t
3420: 68 65 20 68 65 61 76 79 20 77 72 61 70 70 65 72  he heavy wrapper
3430: 20 61 6c 73 6f 20 72 65 63 6f 72 64 73 20 74 68   also records th
3440: 65 20 6e 61 6d 65 20 6f 66 0a 74 68 65 20 63 75  e name of.the cu
3450: 72 72 65 6e 74 20 74 65 73 74 20 63 61 73 65 2e  rrent test case.
3460: 20 20 54 68 65 73 65 20 6c 61 74 74 65 72 20 74    These latter t
3470: 77 6f 20 66 65 61 74 75 72 65 73 20 61 72 65 20  wo features are 
3480: 75 73 65 66 75 6c 20 66 6f 72 0a 74 72 61 63 6b  useful for.track
3490: 69 6e 67 20 64 6f 77 6e 20 74 68 65 20 73 6f 75  ing down the sou
34a0: 72 63 65 20 6f 66 20 6d 65 6d 6f 72 79 20 6c 65  rce of memory le
34b0: 61 6b 73 20 64 65 74 65 63 74 65 64 20 62 79 20  aks detected by 
34c0: 74 68 65 20 74 65 73 74 20 73 75 69 74 65 2e 3c  the test suite.<
34d0: 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 68 65 61 76  /p>..<p>The heav
34e0: 79 20 77 72 61 70 70 65 72 20 74 68 61 74 20 69  y wrapper that i
34f0: 73 20 75 73 65 64 20 77 68 65 6e 20 5b 53 51 4c  s used when [SQL
3500: 49 54 45 5f 4d 45 4d 44 45 42 55 47 5d 20 69 73  ITE_MEMDEBUG] is
3510: 20 73 65 74 20 61 6c 73 6f 0a 6d 61 6b 65 73 20   set also.makes 
3520: 73 75 72 65 20 65 61 63 68 20 6e 65 77 20 61 6c  sure each new al
3530: 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 69 6c 6c  location is fill
3540: 65 64 20 77 69 74 68 20 6e 6f 6e 73 65 6e 73 65  ed with nonsense
3550: 20 64 61 74 61 20 70 72 69 6f 72 20 74 6f 0a 72   data prior to.r
3560: 65 74 75 72 6e 69 6e 67 20 74 68 65 20 61 6c 6c  eturning the all
3570: 6f 63 61 74 69 6f 6e 20 74 6f 20 74 68 65 20 63  ocation to the c
3580: 61 6c 6c 65 72 2e 20 20 41 6e 64 20 61 73 20 73  aller.  And as s
3590: 6f 6f 6e 20 61 73 20 61 6e 20 61 6c 6c 6f 63 61  oon as an alloca
35a0: 74 69 6f 6e 0a 69 73 20 66 72 65 65 2c 20 69 74  tion.is free, it
35b0: 20 69 73 20 61 67 61 69 6e 20 66 69 6c 6c 65 64   is again filled
35c0: 20 77 69 74 68 20 6e 6f 6e 73 65 6e 73 65 20 64   with nonsense d
35d0: 61 74 61 2e 20 20 54 68 65 73 65 20 74 77 6f 20  ata.  These two 
35e0: 61 63 74 69 6f 6e 73 20 68 65 6c 70 0a 74 6f 20  actions help.to 
35f0: 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  ensure that the 
3600: 53 51 4c 69 74 65 20 63 6f 72 65 20 64 6f 65 73  SQLite core does
3610: 20 6e 6f 74 20 6d 61 6b 65 20 61 73 73 75 6d 70   not make assump
3620: 74 69 6f 6e 73 20 61 62 6f 75 74 20 74 68 65 20  tions about the 
3630: 73 74 61 74 65 0a 6f 66 20 6e 65 77 6c 79 20 61  state.of newly a
3640: 6c 6c 6f 63 61 74 65 64 20 6d 65 6d 6f 72 79 20  llocated memory 
3650: 61 6e 64 20 74 68 61 74 20 6d 65 6d 6f 72 79 20  and that memory 
3660: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65 20  allocations are 
3670: 6e 6f 74 20 75 73 65 64 20 61 66 74 65 72 0a 74  not used after.t
3680: 68 65 79 20 68 61 76 65 20 62 65 65 6e 20 66 72  hey have been fr
3690: 65 65 64 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65  eed.</p>..<p>The
36a0: 20 68 65 61 76 79 20 77 72 61 70 70 65 72 20 65   heavy wrapper e
36b0: 6d 70 6c 6f 79 65 64 20 62 79 20 5b 53 51 4c 49  mployed by [SQLI
36c0: 54 45 5f 4d 45 4d 44 45 42 55 47 5d 20 69 73 20  TE_MEMDEBUG] is 
36d0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
36e0: 0a 6f 6e 6c 79 20 64 75 72 69 6e 67 20 74 65 73  .only during tes
36f0: 74 69 6e 67 2c 20 61 6e 61 6c 79 73 69 73 2c 20  ting, analysis, 
3700: 61 6e 64 20 64 65 62 75 67 67 69 6e 67 20 6f 66  and debugging of
3710: 20 53 51 4c 69 74 65 2e 20 20 54 68 65 20 68 65   SQLite.  The he
3720: 61 76 79 20 77 72 61 70 70 65 72 0a 68 61 73 20  avy wrapper.has 
3730: 61 20 73 69 67 6e 69 66 69 63 61 6e 74 20 70 65  a significant pe
3740: 72 66 6f 72 6d 61 6e 63 65 20 61 6e 64 20 6d 65  rformance and me
3750: 6d 6f 72 79 20 6f 76 65 72 68 65 61 64 20 61 6e  mory overhead an
3760: 64 20 70 72 6f 62 61 62 6c 79 20 73 68 6f 75 6c  d probably shoul
3770: 64 20 6e 6f 74 0a 62 65 20 75 73 65 64 20 69 6e  d not.be used in
3780: 20 70 72 6f 64 75 63 74 69 6f 6e 2e 3c 2f 70 3e   production.</p>
3790: 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
37a0: 6e 74 20 77 69 6e 33 32 68 65 61 70 20 7b 57 69  nt win32heap {Wi
37b0: 6e 33 32 20 6e 61 74 69 76 65 20 6d 65 6d 6f 72  n32 native memor
37c0: 79 20 61 6c 6c 6f 63 61 74 6f 72 7d 3c 2f 74 63  y allocator}</tc
37d0: 6c 3e 0a 3c 68 33 3e 54 68 65 20 57 69 6e 33 32  l>.<h3>The Win32
37e0: 20 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20 61   native memory a
37f0: 6c 6c 6f 63 61 74 6f 72 3c 2f 68 33 3e 0a 0a 3c  llocator</h3>..<
3800: 70 3e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63  p>If SQLite is c
3810: 6f 6d 70 69 6c 65 64 20 66 6f 72 20 57 69 6e 64  ompiled for Wind
3820: 6f 77 73 20 77 69 74 68 20 74 68 65 20 5b 53 51  ows with the [SQ
3830: 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
3840: 43 5d 0a 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  C].compile-time 
3850: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 61 20 64  option, then a d
3860: 69 66 66 65 72 65 6e 74 2c 20 74 68 69 6e 20 77  ifferent, thin w
3870: 72 61 70 70 65 72 20 69 73 20 75 73 65 64 20 61  rapper is used a
3880: 72 6f 75 6e 64 0a 48 65 61 70 41 6c 6c 6f 63 28  round.HeapAlloc(
3890: 29 2c 20 48 65 61 70 52 65 41 6c 6c 6f 63 28 29  ), HeapReAlloc()
38a0: 2c 20 61 6e 64 20 48 65 61 70 46 72 65 65 28 29  , and HeapFree()
38b0: 2e 20 20 54 68 65 20 74 68 69 6e 20 77 72 61 70  .  The thin wrap
38c0: 70 65 72 20 75 73 65 73 20 74 68 65 0a 63 6f 6e  per uses the.con
38d0: 66 69 67 75 72 65 64 20 53 51 4c 69 74 65 20 68  figured SQLite h
38e0: 65 61 70 2c 20 77 68 69 63 68 20 77 69 6c 6c 20  eap, which will 
38f0: 62 65 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  be different fro
3900: 6d 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 72  m the default pr
3910: 6f 63 65 73 73 0a 68 65 61 70 20 69 66 20 74 68  ocess.heap if th
3920: 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f  e [SQLITE_WIN32_
3930: 48 45 41 50 5f 43 52 45 41 54 45 5d 20 63 6f 6d  HEAP_CREATE] com
3940: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
3950: 20 69 73 20 75 73 65 64 2e 20 20 49 6e 0a 61 64   is used.  In.ad
3960: 64 69 74 69 6f 6e 2c 20 77 68 65 6e 20 61 6e 20  dition, when an 
3970: 61 6c 6c 6f 63 61 74 69 6f 6e 20 69 73 20 6d 61  allocation is ma
3980: 64 65 20 6f 72 20 66 72 65 65 64 2c 20 48 65 61  de or freed, Hea
3990: 70 56 61 6c 69 64 61 74 65 28 29 20 77 69 6c 6c  pValidate() will
39a0: 20 62 65 0a 63 61 6c 6c 65 64 20 69 66 20 53 51   be.called if SQ
39b0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
39c0: 20 77 69 74 68 20 61 73 73 65 72 74 28 29 20 65   with assert() e
39d0: 6e 61 62 6c 65 64 20 61 6e 64 20 74 68 65 0a 5b  nabled and the.[
39e0: 53 51 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c  SQLITE_WIN32_MAL
39f0: 4c 4f 43 5f 56 41 4c 49 44 41 54 45 5d 20 63 6f  LOC_VALIDATE] co
3a00: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
3a10: 6e 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64 5f  n.</p>..<tcl>hd_
3a20: 66 72 61 67 6d 65 6e 74 20 6d 65 6d 73 79 73 35  fragment memsys5
3a30: 20 2a 6d 65 6d 73 79 73 35 20 7b 7a 65 72 6f 2d   *memsys5 {zero-
3a40: 6d 61 6c 6c 6f 63 20 6d 65 6d 6f 72 79 20 61 6c  malloc memory al
3a50: 6c 6f 63 61 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c  locator}</tcl>.<
3a60: 68 33 3e 5a 65 72 6f 2d 6d 61 6c 6c 6f 63 20 6d  h3>Zero-malloc m
3a70: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 3c  emory allocator<
3a80: 2f 68 33 3e 0a 0a 3c 70 3e 57 68 65 6e 20 53 51  /h3>..<p>When SQ
3a90: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
3aa0: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
3ab0: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35  E_ENABLE_MEMSYS5
3ac0: 5d 20 6f 70 74 69 6f 6e 2c 20 61 6e 0a 61 6c 74  ] option, an.alt
3ad0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20  ernative memory 
3ae0: 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 64  allocator that d
3af0: 6f 65 73 20 6e 6f 74 20 75 73 65 20 6d 61 6c 6c  oes not use mall
3b00: 6f 63 28 29 20 69 73 20 69 6e 63 6c 75 64 65 64  oc() is included
3b10: 20 69 6e 20 74 68 65 0a 62 75 69 6c 64 2e 20 20   in the.build.  
3b20: 54 68 65 20 53 51 4c 69 74 65 20 64 65 76 65 6c  The SQLite devel
3b30: 6f 70 65 72 73 20 72 65 66 65 72 20 74 6f 20 74  opers refer to t
3b40: 68 69 73 20 61 6c 74 65 72 6e 61 74 69 76 65 20  his alternative 
3b50: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
3b60: 0a 61 73 20 22 6d 65 6d 73 79 73 35 22 2e 20 20  .as "memsys5".  
3b70: 45 76 65 6e 20 77 68 65 6e 20 69 74 20 69 73 20  Even when it is 
3b80: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
3b90: 62 75 69 6c 64 2c 20 6d 65 6d 73 79 73 35 20 69  build, memsys5 i
3ba0: 73 20 0a 64 69 73 61 62 6c 65 64 20 62 79 20 64  s .disabled by d
3bb0: 65 66 61 75 6c 74 2e 0a 54 6f 20 65 6e 61 62 6c  efault..To enabl
3bc0: 65 20 6d 65 6d 73 79 73 35 2c 20 74 68 65 20 61  e memsys5, the a
3bd0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3be0: 69 6e 76 6f 6b 65 20 74 68 65 20 66 6f 6c 6c 6f  invoke the follo
3bf0: 77 69 6e 67 20 53 51 4c 69 74 65 20 0a 69 6e 74  wing SQLite .int
3c00: 65 72 66 61 63 65 20 61 74 20 73 74 61 72 74 2d  erface at start-
3c10: 74 69 6d 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  time:</p>..<bloc
3c20: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 5b 73 71  kquote><pre>.[sq
3c30: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53  lite3_config]([S
3c40: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
3c50: 50 5d 2c 20 70 42 75 66 2c 20 73 7a 42 75 66 2c  P], pBuf, szBuf,
3c60: 20 6d 6e 52 65 71 29 3b 0a 3c 2f 70 72 65 3e 3c   mnReq);.</pre><
3c70: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
3c80: 3e 49 6e 20 74 68 65 20 63 61 6c 6c 20 61 62 6f  >In the call abo
3c90: 76 65 2c 20 70 42 75 66 20 69 73 20 61 20 70 6f  ve, pBuf is a po
3ca0: 69 6e 74 65 72 20 74 6f 20 61 20 6c 61 72 67 65  inter to a large
3cb0: 2c 20 63 6f 6e 74 69 67 75 6f 75 73 20 63 68 75  , contiguous chu
3cc0: 6e 6b 0a 6f 66 20 6d 65 6d 6f 72 79 20 73 70 61  nk.of memory spa
3cd0: 63 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  ce that SQLite w
3ce0: 69 6c 6c 20 75 73 65 20 74 6f 20 73 61 74 69 73  ill use to satis
3cf0: 66 79 20 61 6c 6c 20 6f 66 20 69 74 73 20 6d 65  fy all of its me
3d00: 6d 6f 72 79 0a 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory.allocation 
3d10: 6e 65 65 64 73 2e 20 20 20 70 42 75 66 20 6d 69  needs.   pBuf mi
3d20: 67 68 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73  ght point to a s
3d30: 74 61 74 69 63 20 61 72 72 61 79 20 6f 72 20 69  tatic array or i
3d40: 74 20 6d 69 67 68 74 0a 62 65 20 6d 65 6d 6f 72  t might.be memor
3d50: 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
3d60: 73 6f 6d 65 20 6f 74 68 65 72 20 61 70 70 6c 69  some other appli
3d70: 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63 20  cation-specific 
3d80: 6d 65 63 68 61 6e 69 73 6d 2e 0a 73 7a 42 75 66  mechanism..szBuf
3d90: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 74   is an integer t
3da0: 68 61 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  hat is the numbe
3db0: 72 20 6f 66 20 62 79 74 65 73 20 6f 66 20 6d 65  r of bytes of me
3dc0: 6d 6f 72 79 20 73 70 61 63 65 0a 70 6f 69 6e 74  mory space.point
3dd0: 65 64 20 74 6f 20 62 79 20 70 42 75 66 2e 20 20  ed to by pBuf.  
3de0: 6d 6e 52 65 71 20 69 73 20 61 6e 6f 74 68 65 72  mnReq is another
3df0: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 69 73   integer that is
3e00: 20 74 68 65 0a 6d 69 6e 69 6d 75 6d 20 73 69 7a   the.minimum siz
3e10: 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
3e20: 6f 6e 2e 20 20 41 6e 79 20 63 61 6c 6c 20 74 6f  on.  Any call to
3e30: 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
3e40: 28 4e 29 5d 20 77 68 65 72 65 0a 4e 20 69 73 20  (N)] where.N is 
3e50: 6c 65 73 73 20 74 68 61 6e 20 6d 6e 52 65 71 20  less than mnReq 
3e60: 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64 20  will be rounded 
3e70: 75 70 20 74 6f 20 6d 6e 52 65 71 2e 20 20 6d 6e  up to mnReq.  mn
3e80: 52 65 71 20 6d 75 73 74 20 62 65 0a 61 20 70 6f  Req must be.a po
3e90: 77 65 72 20 6f 66 20 74 77 6f 2e 20 20 57 65 20  wer of two.  We 
3ea0: 73 68 61 6c 6c 20 73 65 65 20 6c 61 74 65 72 20  shall see later 
3eb0: 74 68 61 74 20 74 68 65 20 6d 6e 52 65 71 20 70  that the mnReq p
3ec0: 61 72 61 6d 65 74 65 72 20 69 73 0a 69 6d 70 6f  arameter is.impo
3ed0: 72 74 61 6e 74 20 69 6e 20 72 65 64 75 63 69 6e  rtant in reducin
3ee0: 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 3c  g the value of <
3ef0: 62 3e 6e 3c 2f 62 3e 20 61 6e 64 20 68 65 6e 63  b>n</b> and henc
3f00: 65 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20 6d 65  e the minimum me
3f10: 6d 6f 72 79 0a 73 69 7a 65 20 72 65 71 75 69 72  mory.size requir
3f20: 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 5b 52 6f  ement in the [Ro
3f30: 62 73 6f 6e 20 70 72 6f 6f 66 5d 2e 3c 2f 70 3e  bson proof].</p>
3f40: 0a 0a 3c 70 3e 54 68 65 20 6d 65 6d 73 79 73 35  ..<p>The memsys5
3f50: 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 64 65   allocator is de
3f60: 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 6f  signed for use o
3f70: 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73 74 65  n embedded syste
3f80: 6d 73 2c 20 0a 74 68 6f 75 67 68 20 74 68 65 72  ms, .though ther
3f90: 65 20 69 73 20 6e 6f 74 68 69 6e 67 20 74 6f 20  e is nothing to 
3fa0: 70 72 65 76 65 6e 74 20 69 74 73 20 75 73 65 20  prevent its use 
3fb0: 6f 6e 20 77 6f 72 6b 73 74 61 74 69 6f 6e 73 2e  on workstations.
3fc0: 0a 54 68 65 20 73 7a 42 75 66 20 69 73 20 74 79  .The szBuf is ty
3fd0: 70 69 63 61 6c 6c 79 20 62 65 74 77 65 65 6e 20  pically between 
3fe0: 61 20 66 65 77 20 68 75 6e 64 72 65 64 20 6b 69  a few hundred ki
3ff0: 6c 6f 62 79 74 65 73 20 75 70 20 74 6f 20 61 20  lobytes up to a 
4000: 66 65 77 0a 64 6f 7a 65 6e 20 6d 65 67 61 62 79  few.dozen megaby
4010: 74 65 73 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f  tes, depending o
4020: 6e 20 73 79 73 74 65 6d 20 72 65 71 75 69 72 65  n system require
4030: 6d 65 6e 74 73 20 61 6e 64 20 6d 65 6d 6f 72 79  ments and memory
4040: 20 62 75 64 67 65 74 2e 3c 2f 70 3e 0a 0a 3c 70   budget.</p>..<p
4050: 3e 54 68 65 20 61 6c 67 6f 72 69 74 68 6d 20 75  >The algorithm u
4060: 73 65 64 20 62 79 20 6d 65 6d 73 79 73 35 20 63  sed by memsys5 c
4070: 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 22 70 6f  an be called "po
4080: 77 65 72 2d 6f 66 2d 74 77 6f 2c 0a 66 69 72 73  wer-of-two,.firs
4090: 74 2d 66 69 74 22 2e 20 20 54 68 65 20 73 69 7a  t-fit".  The siz
40a0: 65 73 20 6f 66 20 61 6c 6c 20 6d 65 6d 6f 72 79  es of all memory
40b0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 72 65 71   allocation .req
40c0: 75 65 73 74 73 20 61 72 65 20 72 6f 75 6e 64 65  uests are rounde
40d0: 64 20 75 70 20 74 6f 20 61 20 70 6f 77 65 72 20  d up to a power 
40e0: 6f 66 20 74 77 6f 20 61 6e 64 20 74 68 65 20 72  of two and the r
40f0: 65 71 75 65 73 74 20 69 73 20 73 61 74 69 73 66  equest is satisf
4100: 69 65 64 0a 62 79 20 74 68 65 20 66 69 72 73 74  ied.by the first
4110: 20 66 72 65 65 20 73 6c 6f 74 20 69 6e 20 70 42   free slot in pB
4120: 75 66 20 74 68 61 74 20 69 73 20 6c 61 72 67 65  uf that is large
4130: 20 65 6e 6f 75 67 68 2e 20 20 41 64 6a 61 63 65   enough.  Adjace
4140: 6e 74 20 66 72 65 65 64 0a 61 6c 6c 6f 63 61 74  nt freed.allocat
4150: 69 6f 6e 73 20 61 72 65 20 63 6f 61 6c 65 73 63  ions are coalesc
4160: 65 64 20 75 73 69 6e 67 20 61 20 62 75 64 64 79  ed using a buddy
4170: 20 73 79 73 74 65 6d 2e 20 57 68 65 6e 20 75 73   system. When us
4180: 65 64 20 61 70 70 72 6f 70 72 69 61 74 65 6c 79  ed appropriately
4190: 2c 0a 74 68 69 73 20 61 6c 67 6f 72 69 74 68 6d  ,.this algorithm
41a0: 20 70 72 6f 76 69 64 65 73 20 6d 61 74 68 65 6d   provides mathem
41b0: 61 74 69 63 61 6c 20 67 75 61 72 61 6e 74 65 65  atical guarantee
41c0: 73 20 61 67 61 69 6e 73 74 20 66 72 61 67 6d 65  s against fragme
41d0: 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 62 72 65 61  ntation and.brea
41e0: 6b 64 6f 77 6e 2c 20 61 73 20 64 65 73 63 72 69  kdown, as descri
41f0: 62 65 64 20 66 75 72 74 68 65 72 20 3c 61 20 68  bed further <a h
4200: 72 65 66 3d 22 23 6e 6f 66 72 61 67 22 3e 62 65  ref="#nofrag">be
4210: 6c 6f 77 3c 2f 61 3e 2e 3c 2f 70 3e 0a 0a 3c 74  low</a>.</p>..<t
4220: 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d  cl>hd_fragment m
4230: 65 6d 73 79 73 78 20 7b 65 78 70 65 72 69 6d 65  emsysx {experime
4240: 6e 74 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ntal memory allo
4250: 63 61 74 6f 72 73 7d 3c 2f 74 63 6c 3e 0a 3c 68  cators}</tcl>.<h
4260: 33 3e 45 78 70 65 72 69 6d 65 6e 74 61 6c 20 6d  3>Experimental m
4270: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
4280: 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68 65 20 6e 61  </h3>..<p>The na
4290: 6d 65 20 22 6d 65 6d 73 79 73 35 22 20 75 73 65  me "memsys5" use
42a0: 64 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 2d 6d  d for the zero-m
42b0: 61 6c 6c 6f 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  alloc memory all
42c0: 6f 63 61 74 6f 72 20 69 6d 70 6c 69 65 73 0a 74  ocator implies.t
42d0: 68 61 74 20 74 68 65 72 65 20 61 72 65 20 73 65  hat there are se
42e0: 76 65 72 61 6c 20 61 64 64 69 74 69 6f 6e 61 6c  veral additional
42f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
4300: 72 73 20 61 76 61 69 6c 61 62 6c 65 2c 20 61 6e  rs available, an
4310: 64 20 69 6e 64 65 65 64 0a 74 68 65 72 65 20 61  d indeed.there a
4320: 72 65 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74  re.  The default
4330: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
4340: 72 20 69 73 20 22 6d 65 6d 73 79 73 31 22 2e 20  r is "memsys1". 
4350: 20 54 68 65 20 64 65 62 75 67 67 69 6e 67 0a 6d   The debugging.m
4360: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
4370: 69 73 20 22 6d 65 6d 73 79 73 32 22 2e 20 20 54  is "memsys2".  T
4380: 68 6f 73 65 20 68 61 76 65 20 61 6c 72 65 61 64  hose have alread
4390: 79 20 62 65 65 6e 20 63 6f 76 65 72 65 64 2e 3c  y been covered.<
43a0: 2f 70 3e 0a 0a 3c 70 3e 49 66 20 53 51 4c 69 74  /p>..<p>If SQLit
43b0: 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
43c0: 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  th [SQLITE_ENABL
43d0: 45 5f 4d 45 4d 53 59 53 33 5d 20 74 68 65 6e 20  E_MEMSYS3] then 
43e0: 61 6e 6f 74 68 65 72 0a 7a 65 72 6f 2d 6d 61 6c  another.zero-mal
43f0: 6c 6f 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  loc memory alloc
4400: 61 74 6f 72 2c 20 73 69 6d 69 6c 61 72 20 74 6f  ator, similar to
4410: 20 6d 65 6d 73 79 73 35 2c 20 69 73 20 69 6e 63   memsys5, is inc
4420: 6c 75 64 65 64 20 69 6e 20 74 68 65 0a 73 6f 75  luded in the.sou
4430: 72 63 65 20 74 72 65 65 2e 20 20 54 68 65 20 6d  rce tree.  The m
4440: 65 6d 73 79 73 33 20 61 6c 6c 6f 63 61 74 6f 72  emsys3 allocator
4450: 2c 20 6c 69 6b 65 20 6d 65 6d 73 79 73 35 2c 20  , like memsys5, 
4460: 6d 75 73 74 20 62 65 20 61 63 74 69 76 61 74 65  must be activate
4470: 64 0a 62 79 20 61 20 63 61 6c 6c 20 74 6f 20 5b  d.by a call to [
4480: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
4490: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48  [SQLITE_CONFIG_H
44a0: 45 41 50 5d 2c 2e 2e 2e 29 2e 20 20 4d 65 6d 73  EAP],...).  Mems
44b0: 79 73 33 0a 75 73 65 73 20 74 68 65 20 6d 65 6d  ys3.uses the mem
44c0: 6f 72 79 20 62 75 66 66 65 72 20 73 75 70 70 6c  ory buffer suppl
44d0: 69 65 64 20 61 73 20 69 74 73 20 73 6f 75 72 63  ied as its sourc
44e0: 65 20 66 6f 72 20 61 6c 6c 20 6d 65 6d 6f 72 79  e for all memory
44f0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 54 68   allocations..Th
4500: 65 20 64 69 66 66 65 72 65 6e 63 65 20 62 65 74  e difference bet
4510: 77 65 65 6e 20 6d 65 6d 73 79 73 33 20 61 6e 64  ween memsys3 and
4520: 20 6d 65 6d 73 79 73 35 20 69 73 20 74 68 61 74   memsys5 is that
4530: 20 6d 65 6d 73 79 73 33 20 75 73 65 73 20 61 0a   memsys3 uses a.
4540: 64 69 66 66 65 72 65 6e 74 20 6d 65 6d 6f 72 79  different memory
4550: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 6c 67 6f   allocation algo
4560: 72 69 74 68 6d 20 74 68 61 74 20 73 65 65 6d 73  rithm that seems
4570: 20 74 6f 20 77 6f 72 6b 20 77 65 6c 6c 20 69 6e   to work well in
4580: 0a 70 72 61 63 74 69 63 65 2c 20 62 75 74 20 77  .practice, but w
4590: 68 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 70 72  hich does not pr
45a0: 6f 76 69 64 65 20 6d 61 74 68 65 6d 61 74 69 63  ovide mathematic
45b0: 61 6c 0a 67 75 61 72 61 6e 74 65 65 73 20 61 67  al.guarantees ag
45c0: 61 69 6e 73 74 20 6d 65 6d 6f 72 79 20 66 72 61  ainst memory fra
45d0: 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 20 62  gmentation and b
45e0: 72 65 61 6b 64 6f 77 6e 2e 20 20 4d 65 6d 73 79  reakdown.  Memsy
45f0: 73 33 20 77 61 73 0a 61 20 70 72 65 64 65 63 65  s3 was.a predece
4600: 73 73 6f 72 20 74 6f 20 6d 65 6d 73 79 73 35 2e  ssor to memsys5.
4610: 20 20 54 68 65 20 53 51 4c 69 74 65 20 64 65 76    The SQLite dev
4620: 65 6c 6f 70 65 72 73 20 6e 6f 77 20 62 65 6c 69  elopers now beli
4630: 65 76 65 20 74 68 61 74 20 0a 6d 65 6d 73 79 73  eve that .memsys
4640: 35 20 69 73 20 73 75 70 65 72 69 6f 72 20 74 6f  5 is superior to
4650: 0a 6d 65 6d 73 79 73 33 20 61 6e 64 20 74 68 61  .memsys3 and tha
4660: 74 20 61 6c 6c 20 61 70 70 6c 69 63 61 74 69 6f  t all applicatio
4670: 6e 73 20 74 68 61 74 20 6e 65 65 64 20 61 20 7a  ns that need a z
4680: 65 72 6f 2d 6d 61 6c 6c 6f 63 20 6d 65 6d 6f 72  ero-malloc memor
4690: 79 0a 61 6c 6c 6f 63 61 74 6f 72 20 73 68 6f 75  y.allocator shou
46a0: 6c 64 20 75 73 65 20 6d 65 6d 73 79 73 35 20 69  ld use memsys5 i
46b0: 6e 20 70 72 65 66 65 72 65 6e 63 65 20 74 6f 20  n preference to 
46c0: 6d 65 6d 73 79 73 33 2e 20 20 4d 65 6d 73 79 73  memsys3.  Memsys
46d0: 33 20 69 73 0a 63 6f 6e 73 69 64 65 72 65 64 20  3 is.considered 
46e0: 62 6f 74 68 20 65 78 70 65 72 69 6d 65 6e 74 61  both experimenta
46f0: 6c 20 61 6e 64 20 64 65 70 72 65 63 61 74 65 64  l and deprecated
4700: 20 61 6e 64 20 77 69 6c 6c 20 6c 69 6b 65 6c 79   and will likely
4710: 20 62 65 20 72 65 6d 6f 76 65 64 20 0a 66 72 6f   be removed .fro
4720: 6d 20 74 68 65 20 73 6f 75 72 63 65 20 74 72 65  m the source tre
4730: 65 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  e in a future re
4740: 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e  lease of SQLite.
4750: 3c 2f 70 3e 0a 0a 3c 70 3e 4d 65 6d 73 79 73 34  </p>..<p>Memsys4
4760: 20 61 6e 64 20 6d 65 6d 73 79 73 36 20 77 65 72   and memsys6 wer
4770: 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 6d  e experimental m
4780: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73  emory allocators
4790: 0a 69 6e 74 72 6f 64 75 63 65 64 20 69 6e 20 61  .introduced in a
47a0: 72 6f 75 6e 64 20 32 30 30 37 20 61 6e 64 20 73  round 2007 and s
47b0: 75 62 73 65 71 75 65 6e 74 6c 79 20 72 65 6d 6f  ubsequently remo
47c0: 76 65 64 20 66 72 6f 6d 20 74 68 65 0a 73 6f 75  ved from the.sou
47d0: 72 63 65 20 74 72 65 65 20 69 6e 20 61 72 6f 75  rce tree in arou
47e0: 6e 64 20 32 30 30 38 2c 20 61 66 74 65 72 20 69  nd 2008, after i
47f0: 74 20 62 65 63 61 6d 65 20 63 6c 65 61 72 20 74  t became clear t
4800: 68 61 74 20 74 68 65 79 0a 61 64 64 65 64 20 6e  hat they.added n
4810: 6f 20 6e 65 77 20 76 61 6c 75 65 2e 3c 2f 70 3e  o new value.</p>
4820: 0a 0a 3c 70 3e 4f 74 68 65 72 20 65 78 70 65 72  ..<p>Other exper
4830: 69 6d 65 6e 74 61 6c 20 6d 65 6d 6f 72 79 20 61  imental memory a
4840: 6c 6c 6f 63 61 74 6f 72 73 20 6d 69 67 68 74 20  llocators might 
4850: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
4860: 72 65 20 72 65 6c 65 61 73 65 73 0a 6f 66 20 53  re releases.of S
4870: 51 4c 69 74 65 2e 20 20 4f 6e 65 20 6d 61 79 20  QLite.  One may 
4880: 61 6e 74 69 63 69 70 61 74 65 20 74 68 61 74 20  anticipate that 
4890: 74 68 65 73 65 20 77 69 6c 6c 20 62 65 20 63 61  these will be ca
48a0: 6c 6c 65 64 20 6d 65 6d 73 79 73 37 2c 20 6d 65  lled memsys7, me
48b0: 6d 73 79 73 38 2c 0a 61 6e 64 20 73 6f 20 66 6f  msys8,.and so fo
48c0: 72 74 68 2e 3c 2f 70 3e 0a 0a 3c 61 20 6e 61 6d  rth.</p>..<a nam
48d0: 65 3d 22 61 70 70 61 6c 6c 6f 63 22 3e 3c 2f 61  e="appalloc"></a
48e0: 3e 0a 3c 68 33 3e 41 70 70 6c 69 63 61 74 69 6f  >.<h3>Applicatio
48f0: 6e 2d 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79  n-defined memory
4900: 20 61 6c 6c 6f 63 61 74 6f 72 73 3c 2f 68 33 3e   allocators</h3>
4910: 0a 0a 3c 70 3e 4e 65 77 20 6d 65 6d 6f 72 79 20  ..<p>New memory 
4920: 61 6c 6c 6f 63 61 74 6f 72 73 20 64 6f 20 6e 6f  allocators do no
4930: 74 20 68 61 76 65 20 74 6f 20 62 65 20 70 61 72  t have to be par
4940: 74 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20  t of the SQLite 
4950: 73 6f 75 72 63 65 20 74 72 65 65 0a 6e 6f 72 20  source tree.nor 
4960: 69 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20  included in the 
4970: 73 71 6c 69 74 65 33 2e 63 20 5b 61 6d 61 6c 67  sqlite3.c [amalg
4980: 61 6d 61 74 69 6f 6e 5d 2e 20 20 49 6e 64 69 76  amation].  Indiv
4990: 69 64 75 61 6c 20 61 70 70 6c 69 63 61 74 69 6f  idual applicatio
49a0: 6e 73 20 63 61 6e 0a 73 75 70 70 6c 79 20 74 68  ns can.supply th
49b0: 65 69 72 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 61  eir own memory a
49c0: 6c 6c 6f 63 61 74 6f 72 73 20 74 6f 20 53 51 4c  llocators to SQL
49d0: 69 74 65 20 61 74 20 73 74 61 72 74 2d 74 69 6d  ite at start-tim
49e0: 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 6f 20 63 61  e.</p>..<p>To ca
49f0: 75 73 65 20 53 51 4c 69 74 65 20 74 6f 20 75 73  use SQLite to us
4a00: 65 20 61 20 6e 65 77 20 6d 65 6d 6f 72 79 20 61  e a new memory a
4a10: 6c 6c 6f 63 61 74 6f 72 2c 20 74 68 65 20 61 70  llocator, the ap
4a20: 70 6c 69 63 61 74 69 6f 6e 0a 73 69 6d 70 6c 79  plication.simply
4a30: 20 63 61 6c 6c 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c   calls:</p>..<bl
4a40: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 5b  ockquote><pre>.[
4a50: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
4a60: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
4a70: 41 4c 4c 4f 43 5d 2c 20 70 4d 65 6d 29 3b 0a 3c  ALLOC], pMem);.<
4a80: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
4a90: 65 3e 0a 0a 3c 70 3e 49 6e 20 74 68 65 20 63 61  e>..<p>In the ca
4aa0: 6c 6c 20 61 62 6f 76 65 2c 20 70 4d 65 6d 20 69  ll above, pMem i
4ab0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
4ac0: 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  n [sqlite3_mem_m
4ad0: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 0a 74  ethods] object.t
4ae0: 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  hat defines the 
4af0: 69 6e 74 65 72 66 61 63 65 20 74 6f 20 74 68 65  interface to the
4b00: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
4b10: 63 69 66 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c  cific memory all
4b20: 6f 63 61 74 6f 72 2e 0a 54 68 65 20 5b 73 71 6c  ocator..The [sql
4b30: 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
4b40: 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 61 6c  ] object is real
4b50: 6c 79 20 6a 75 73 74 20 61 20 73 74 72 75 63 74  ly just a struct
4b60: 75 72 65 20 63 6f 6e 74 61 69 6e 69 6e 67 0a 70  ure containing.p
4b70: 6f 69 6e 74 65 72 73 20 74 6f 20 66 75 6e 63 74  ointers to funct
4b80: 69 6f 6e 73 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  ions to implemen
4b90: 74 20 74 68 65 20 76 61 72 69 6f 75 73 20 6d 65  t the various me
4ba0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
4bb0: 70 72 69 6d 69 74 69 76 65 73 2e 0a 3c 2f 70 3e  primitives..</p>
4bc0: 0a 0a 3c 70 3e 49 6e 20 61 20 6d 75 6c 74 69 2d  ..<p>In a multi-
4bd0: 74 68 72 65 61 64 65 64 20 61 70 70 6c 69 63 61  threaded applica
4be0: 74 69 6f 6e 2c 20 61 63 63 65 73 73 20 74 6f 20  tion, access to 
4bf0: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
4c00: 5f 6d 65 74 68 6f 64 73 5d 0a 69 73 20 73 65 72  _methods].is ser
4c10: 69 61 6c 69 7a 65 64 20 69 66 20 61 6e 64 20 6f  ialized if and o
4c20: 6e 6c 79 20 69 66 20 5b 53 51 4c 49 54 45 5f 43  nly if [SQLITE_C
4c30: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
4c40: 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 49 66 20   is enabled..If 
4c50: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
4c60: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
4c70: 61 62 6c 65 64 20 74 68 65 6e 20 74 68 65 20 6d  abled then the m
4c80: 65 74 68 6f 64 73 20 69 6e 0a 5b 73 71 6c 69 74  ethods in.[sqlit
4c90: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
4ca0: 6d 75 73 74 20 74 61 6b 65 20 63 61 72 65 20 6f  must take care o
4cb0: 66 20 74 68 65 69 72 20 6f 77 6e 20 73 65 72 69  f their own seri
4cc0: 61 6c 69 7a 61 74 69 6f 6e 20 6e 65 65 64 73 2e  alization needs.
4cd0: 3c 2f 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22 6f  </p>..<a name="o
4ce0: 76 65 72 6c 61 79 61 6c 6c 6f 63 22 3e 3c 2f 61  verlayalloc"></a
4cf0: 3e 0a 3c 68 33 3e 4d 65 6d 6f 72 79 20 61 6c 6c  >.<h3>Memory all
4d00: 6f 63 61 74 6f 72 20 6f 76 65 72 6c 61 79 73 3c  ocator overlays<
4d10: 2f 68 33 3e 0a 0a 3c 70 3e 41 6e 20 61 70 70 6c  /h3>..<p>An appl
4d20: 69 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 73 65  ication can inse
4d30: 72 74 20 6c 61 79 65 72 73 20 6f 72 20 22 6f 76  rt layers or "ov
4d40: 65 72 6c 61 79 73 22 20 69 6e 20 62 65 74 77 65  erlays" in betwe
4d50: 65 6e 20 74 68 65 0a 53 51 4c 69 74 65 20 63 6f  en the.SQLite co
4d60: 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72  re and the under
4d70: 6c 79 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  lying memory all
4d80: 6f 63 61 74 6f 72 2e 0a 46 6f 72 20 65 78 61 6d  ocator..For exam
4d90: 70 6c 65 2c 20 74 68 65 20 3c 61 20 68 72 65 66  ple, the <a href
4da0: 3d 22 23 6f 6f 6d 74 65 73 74 69 6e 67 22 3e 6f  ="#oomtesting">o
4db0: 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 74 65 73  ut-of-memory tes
4dc0: 74 20 6c 6f 67 69 63 3c 2f 61 3e 0a 66 6f 72 20  t logic</a>.for 
4dd0: 53 51 4c 69 74 65 20 75 73 65 73 20 61 6e 20 6f  SQLite uses an o
4de0: 76 65 72 6c 61 79 20 74 68 61 74 20 63 61 6e 20  verlay that can 
4df0: 73 69 6d 75 6c 61 74 65 20 6d 65 6d 6f 72 79 20  simulate memory 
4e00: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 66 61 69 6c 75  allocation.failu
4e10: 72 65 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e 41 6e 20  res.</p>..<p>An 
4e20: 6f 76 65 72 6c 61 79 20 63 61 6e 20 62 65 20 63  overlay can be c
4e30: 72 65 61 74 65 64 20 62 79 20 75 73 69 6e 67 20  reated by using 
4e40: 74 68 65 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  the</p>..<blockq
4e50: 75 6f 74 65 3e 3c 70 72 65 3e 0a 5b 73 71 6c 69  uote><pre>.[sqli
4e60: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
4e70: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
4e80: 4c 4c 4f 43 5d 2c 20 70 4f 6c 64 4d 65 6d 29 3b  LLOC], pOldMem);
4e90: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
4ea0: 6f 74 65 3e 0a 0a 3c 70 3e 69 6e 74 65 72 66 61  ote>..<p>interfa
4eb0: 63 65 20 74 6f 20 6f 62 74 61 69 6e 20 70 6f 69  ce to obtain poi
4ec0: 6e 74 65 72 73 20 74 6f 20 74 68 65 20 65 78 69  nters to the exi
4ed0: 73 74 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  sting memory all
4ee0: 6f 63 61 74 6f 72 2e 0a 54 68 65 20 65 78 69 73  ocator..The exis
4ef0: 74 69 6e 67 20 61 6c 6c 6f 63 61 74 6f 72 20 69  ting allocator i
4f00: 73 20 73 61 76 65 64 20 62 79 20 74 68 65 20 6f  s saved by the o
4f10: 76 65 72 6c 61 79 20 61 6e 64 20 69 73 20 75 73  verlay and is us
4f20: 65 64 20 61 73 0a 61 20 66 61 6c 6c 62 61 63 6b  ed as.a fallback
4f30: 20 74 6f 20 64 6f 20 72 65 61 6c 20 6d 65 6d 6f   to do real memo
4f40: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20  ry allocation.  
4f50: 54 68 65 6e 20 74 68 65 20 6f 76 65 72 6c 61 79  Then the overlay
4f60: 20 69 73 0a 69 6e 73 65 72 74 65 64 20 69 6e 20   is.inserted in 
4f70: 70 6c 61 63 65 20 6f 66 20 74 68 65 20 65 78 69  place of the exi
4f80: 73 74 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c  sting memory all
4f90: 6f 63 61 74 6f 72 20 75 73 69 6e 67 0a 74 68 65  ocator using.the
4fa0: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
4fb0: 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ]([SQLITE_CONFIG
4fc0: 5f 4d 41 4c 4c 4f 43 5d 2c 2e 2e 2e 29 20 61 73  _MALLOC],...) as
4fd0: 20 64 65 73 63 72 69 62 65 64 0a 3c 61 20 68 72   described.<a hr
4fe0: 65 66 3d 22 23 61 70 70 61 6c 6c 6f 63 22 3e 61  ef="#appalloc">a
4ff0: 62 6f 76 65 3c 2f 61 3e 2e 0a 0a 3c 61 20 6e 61  bove</a>...<a na
5000: 6d 65 3d 22 73 74 75 62 61 6c 6c 6f 63 22 3e 3c  me="stuballoc"><
5010: 2f 61 3e 0a 3c 68 33 3e 4e 6f 2d 6f 70 20 6d 65  /a>.<h3>No-op me
5020: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 73  mory allocator s
5030: 74 75 62 3c 2f 68 33 3e 0a 0a 3c 70 3e 49 66 20  tub</h3>..<p>If 
5040: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
5050: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
5060: 49 54 45 5f 5a 45 52 4f 5f 4d 41 4c 4c 4f 43 5d  ITE_ZERO_MALLOC]
5070: 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 74 68   option, then.th
5080: 65 20 5b 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72  e [default memor
5090: 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 69 73 20  y allocator] is 
50a0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 72 65 70 6c  omitted and repl
50b0: 61 63 65 64 20 62 79 20 61 20 73 74 75 62 0a 6d  aced by a stub.m
50c0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
50d0: 74 68 61 74 20 6e 65 76 65 72 20 61 6c 6c 6f 63  that never alloc
50e0: 61 74 65 73 20 61 6e 79 20 6d 65 6d 6f 72 79 2e  ates any memory.
50f0: 20 20 41 6e 79 20 63 61 6c 6c 73 20 74 6f 20 74    Any calls to t
5100: 68 65 0a 73 74 75 62 20 6d 65 6d 6f 72 79 20 61  he.stub memory a
5110: 6c 6c 6f 63 61 74 6f 72 20 77 69 6c 6c 20 72 65  llocator will re
5120: 70 6f 72 74 20 62 61 63 6b 20 74 68 61 74 20 6e  port back that n
5130: 6f 20 6d 65 6d 6f 72 79 20 69 73 20 61 76 61 69  o memory is avai
5140: 6c 61 62 6c 65 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54  lable.</p>..<p>T
5150: 68 65 20 6e 6f 2d 6f 70 20 6d 65 6d 6f 72 79 20  he no-op memory 
5160: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 6e 6f 74  allocator is not
5170: 20 75 73 65 66 75 6c 20 62 79 20 69 74 73 65 6c   useful by itsel
5180: 66 2e 20 20 49 74 20 65 78 69 73 74 73 20 6f 6e  f.  It exists on
5190: 6c 79 0a 61 73 20 61 20 70 6c 61 63 65 68 6f 6c  ly.as a placehol
51a0: 64 65 72 20 73 6f 20 74 68 61 74 20 53 51 4c 69  der so that SQLi
51b0: 74 65 20 68 61 73 20 61 20 6d 65 6d 6f 72 79 20  te has a memory 
51c0: 61 6c 6c 6f 63 61 74 6f 72 20 74 6f 20 6c 69 6e  allocator to lin
51d0: 6b 20 61 67 61 69 6e 73 74 0a 6f 6e 20 73 79 73  k against.on sys
51e0: 74 65 6d 73 20 74 68 61 74 20 6d 61 79 20 6e 6f  tems that may no
51f0: 74 20 68 61 76 65 20 6d 61 6c 6c 6f 63 28 29 2c  t have malloc(),
5200: 20 66 72 65 65 28 29 2c 20 6f 72 20 72 65 61 6c   free(), or real
5210: 6c 6f 63 28 29 20 69 6e 20 74 68 65 69 72 0a 73  loc() in their.s
5220: 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79 2e  tandard library.
5230: 0a 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .An application 
5240: 74 68 61 74 20 69 73 20 63 6f 6d 70 69 6c 65 64  that is compiled
5250: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 5a 45   with [SQLITE_ZE
5260: 52 4f 5f 4d 41 4c 4c 4f 43 5d 20 77 69 6c 6c 20  RO_MALLOC] will 
5270: 6e 65 65 64 20 74 6f 0a 75 73 65 20 5b 73 71 6c  need to.use [sql
5280: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74  ite3_config()] t
5290: 6f 67 65 74 68 65 72 20 77 69 74 68 20 5b 53 51  ogether with [SQ
52a0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
52b0: 4f 43 5d 20 6f 72 0a 5b 53 51 4c 49 54 45 5f 43  OC] or.[SQLITE_C
52c0: 4f 4e 46 49 47 5f 48 45 41 50 5d 20 74 6f 20 73  ONFIG_HEAP] to s
52d0: 70 65 63 69 66 79 20 61 20 6e 65 77 20 61 6c 74  pecify a new alt
52e0: 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 20  ernative memory 
52f0: 61 6c 6c 6f 63 61 74 6f 72 0a 62 65 66 6f 72 65  allocator.before
5300: 20 62 65 67 69 6e 6e 69 6e 67 20 74 6f 20 75 73   beginning to us
5310: 65 20 53 51 4c 69 74 65 2e 3c 2f 70 3e 0a 0a 3c  e SQLite.</p>..<
5320: 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65 6e 74 20  tcl>hd_fragment 
5330: 70 61 67 65 63 61 63 68 65 20 7b 70 61 67 65 63  pagecache {pagec
5340: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
5350: 63 61 74 6f 72 7d 3c 2f 74 63 6c 3e 0a 3c 68 32  cator}</tcl>.<h2
5360: 3e 20 50 61 67 65 20 63 61 63 68 65 20 6d 65 6d  > Page cache mem
5370: 6f 72 79 3c 2f 68 32 3e 0a 0a 3c 70 3e 49 6e 20  ory</h2>..<p>In 
5380: 6d 6f 73 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  most application
5390: 73 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  s, the database 
53a0: 70 61 67 65 20 63 61 63 68 65 20 73 75 62 73 79  page cache subsy
53b0: 73 74 65 6d 20 77 69 74 68 69 6e 20 0a 53 51 4c  stem within .SQL
53c0: 69 74 65 20 75 73 65 73 20 6d 6f 72 65 20 64 79  ite uses more dy
53d0: 6e 61 6d 69 63 61 6c 6c 79 20 61 6c 6c 6f 63 61  namically alloca
53e0: 74 65 64 20 6d 65 6d 6f 72 79 20 74 68 61 6e 20  ted memory than 
53f0: 61 6c 6c 20 6f 74 68 65 72 20 70 61 72 74 73 0a  all other parts.
5400: 6f 66 20 53 51 4c 69 74 65 20 63 6f 6d 62 69 6e  of SQLite combin
5410: 65 64 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 75  ed.  It is not u
5420: 6e 75 73 75 61 6c 20 74 6f 20 73 65 65 20 74 68  nusual to see th
5430: 65 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20  e database page 
5440: 63 61 63 68 65 0a 63 6f 6e 73 75 6d 65 20 6f 76  cache.consume ov
5450: 65 72 20 31 30 20 74 69 6d 65 73 20 6d 6f 72 65  er 10 times more
5460: 20 6d 65 6d 6f 72 79 20 74 68 61 6e 20 74 68 65   memory than the
5470: 20 72 65 73 74 20 6f 66 20 53 51 4c 69 74 65 20   rest of SQLite 
5480: 63 6f 6d 62 69 6e 65 64 2e 3c 2f 70 3e 0a 0a 3c  combined.</p>..<
5490: 70 3e 53 51 4c 69 74 65 20 63 61 6e 20 62 65 20  p>SQLite can be 
54a0: 63 6f 6e 66 69 67 75 72 65 64 20 74 6f 20 6d 61  configured to ma
54b0: 6b 65 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  ke page cache me
54c0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
54d0: 20 66 72 6f 6d 0a 61 20 73 65 70 61 72 61 74 65   from.a separate
54e0: 20 61 6e 64 20 64 69 73 74 69 6e 63 74 20 6d 65   and distinct me
54f0: 6d 6f 72 79 20 70 6f 6f 6c 20 6f 66 20 66 69 78  mory pool of fix
5500: 65 64 2d 73 69 7a 65 0a 73 6c 6f 74 73 2e 20 20  ed-size.slots.  
5510: 54 68 69 73 20 63 61 6e 20 68 61 76 65 20 74 77  This can have tw
5520: 6f 20 61 64 76 61 6e 74 61 67 65 73 3a 3c 2f 70  o advantages:</p
5530: 3e 0a 0a 3c 75 6c 3e 0a 3c 6c 69 3e 3c 70 3e 0a  >..<ul>.<li><p>.
5540: 42 65 63 61 75 73 65 20 61 6c 6c 6f 63 61 74 69  Because allocati
5550: 6f 6e 73 20 61 72 65 20 61 6c 6c 20 74 68 65 20  ons are all the 
5560: 73 61 6d 65 20 73 69 7a 65 2c 20 74 68 65 20 6d  same size, the m
5570: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
5580: 63 61 6e 0a 6f 70 65 72 61 74 65 20 6d 75 63 68  can.operate much
5590: 20 66 61 73 74 65 72 2e 20 20 54 68 65 20 61 6c   faster.  The al
55a0: 6c 6f 63 61 74 6f 72 20 6e 65 65 64 20 6e 6f 74  locator need not
55b0: 20 62 6f 74 68 65 72 20 77 69 74 68 20 63 6f 61   bother with coa
55c0: 6c 65 73 63 69 6e 67 20 0a 61 64 6a 61 63 65 6e  lescing .adjacen
55d0: 74 20 66 72 65 65 20 73 6c 6f 74 73 20 6f 72 20  t free slots or 
55e0: 73 65 61 72 63 68 69 6e 67 20 66 6f 72 20 61 20  searching for a 
55f0: 73 6c 6f 74 0a 6f 66 20 61 6e 20 61 70 70 72 6f  slot.of an appro
5600: 70 72 69 61 74 65 20 73 69 7a 65 2e 20 20 41 6c  priate size.  Al
5610: 6c 20 75 6e 61 6c 6c 6f 63 61 74 65 64 20 6d 65  l unallocated me
5620: 6d 6f 72 79 20 73 6c 6f 74 73 20 63 61 6e 20 62  mory slots can b
5630: 65 20 73 74 6f 72 65 64 20 6f 6e 0a 61 20 6c 69  e stored on.a li
5640: 6e 6b 65 64 20 6c 69 73 74 2e 20 20 41 6c 6c 6f  nked list.  Allo
5650: 63 61 74 69 6e 67 20 63 6f 6e 73 69 73 74 73 20  cating consists 
5660: 6f 66 20 72 65 6d 6f 76 69 6e 67 20 74 68 65 20  of removing the 
5670: 66 69 72 73 74 20 65 6e 74 72 79 20 66 72 6f 6d  first entry from
5680: 20 74 68 65 0a 6c 69 73 74 2e 20 20 44 65 61 6c   the.list.  Deal
5690: 6c 6f 63 61 74 69 6e 67 20 69 73 20 73 69 6d 70  locating is simp
56a0: 6c 79 20 61 64 64 69 6e 67 20 61 6e 20 65 6e 74  ly adding an ent
56b0: 72 79 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e  ry to the beginn
56c0: 69 6e 67 20 6f 66 20 74 68 65 20 6c 69 73 74 2e  ing of the list.
56d0: 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 0a 3c 6c 69 3e  .</p></li>..<li>
56e0: 3c 70 3e 0a 57 69 74 68 20 61 20 73 69 6e 67 6c  <p>.With a singl
56f0: 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a  e allocation siz
5700: 65 2c 20 74 68 65 20 3c 62 3e 6e 3c 2f 62 3e 20  e, the <b>n</b> 
5710: 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
5720: 0a 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 5d 20  .[Robson proof] 
5730: 69 73 20 31 2c 20 61 6e 64 20 74 68 65 20 74 6f  is 1, and the to
5740: 74 61 6c 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  tal memory space
5750: 20 72 65 71 75 69 72 65 64 20 62 79 20 74 68 65   required by the
5760: 20 61 6c 6c 6f 63 61 74 6f 72 0a 28 3c 62 3e 4e   allocator.(<b>N
5770: 3c 2f 62 3e 29 20 69 73 20 65 78 61 63 74 6c 79  </b>) is exactly
5780: 20 65 71 75 61 6c 20 74 6f 20 6d 61 78 69 6d 75   equal to maximu
5790: 6d 20 6d 65 6d 6f 72 79 20 75 73 65 64 20 28 3c  m memory used (<
57a0: 62 3e 4d 3c 2f 62 3e 29 2e 20 20 0a 4e 6f 20 61  b>M</b>).  .No a
57b0: 64 64 69 74 69 6f 6e 61 6c 20 6d 65 6d 6f 72 79  dditional memory
57c0: 20 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20   is required to 
57d0: 63 6f 76 65 72 20 66 72 61 67 6d 65 6e 74 61 74  cover fragmentat
57e0: 69 6f 6e 20 6f 76 65 72 68 65 61 64 2c 20 74 68  ion overhead, th
57f0: 75 73 20 0a 72 65 64 75 63 69 6e 67 20 6d 65 6d  us .reducing mem
5800: 6f 72 79 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ory requirements
5810: 2e 20 20 54 68 69 73 20 69 73 20 70 61 72 74 69  .  This is parti
5820: 63 75 6c 61 72 6c 79 20 69 6d 70 6f 72 74 61 6e  cularly importan
5830: 74 20 66 6f 72 20 74 68 65 0a 70 61 67 65 20 63  t for the.page c
5840: 61 63 68 65 20 6d 65 6d 6f 72 79 20 73 69 6e 63  ache memory sinc
5850: 65 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  e the page cache
5860: 20 63 6f 6e 73 74 69 74 75 74 65 73 20 74 68 65   constitutes the
5870: 20 6c 61 72 67 65 73 74 20 63 6f 6d 70 6f 6e 65   largest compone
5880: 6e 74 0a 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79  nt.of the memory
5890: 20 6e 65 65 64 73 20 6f 66 20 53 51 4c 69 74 65   needs of SQLite
58a0: 2e 0a 3c 2f 70 3e 3c 2f 6c 69 3e 0a 3c 2f 75 6c  ..</p></li>.</ul
58b0: 3e 0a 0a 3c 70 3e 54 68 65 20 70 61 67 65 2d 63  >..<p>The page-c
58c0: 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
58d0: 63 61 74 6f 72 20 69 73 20 64 69 73 61 62 6c 65  cator is disable
58e0: 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 41 6e  d by default..An
58f0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e   application can
5900: 20 65 6e 61 62 6c 65 20 69 74 20 61 74 20 73 74   enable it at st
5910: 61 72 74 2d 74 69 6d 65 20 61 73 20 66 6f 6c 6c  art-time as foll
5920: 6f 77 73 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b  ows:</p>..<block
5930: 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 5b 73 71 6c  quote><pre>.[sql
5940: 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51  ite3_config]([SQ
5950: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
5960: 43 41 43 48 45 5d 2c 20 70 42 75 66 2c 20 73 7a  CACHE], pBuf, sz
5970: 2c 20 4e 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c  , N);.</pre></bl
5980: 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68  ockquote>..<p>Th
5990: 65 20 70 42 75 66 20 70 61 72 61 6d 65 74 65 72  e pBuf parameter
59a0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
59b0: 20 61 20 63 6f 6e 74 69 67 75 6f 75 73 20 72 61   a contiguous ra
59c0: 6e 67 65 20 6f 66 20 62 79 74 65 73 20 74 68 61  nge of bytes tha
59d0: 74 0a 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73  t.SQLite will us
59e0: 65 20 66 6f 72 20 70 61 67 65 2d 63 61 63 68 65  e for page-cache
59f0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
5a00: 6f 6e 73 2e 20 20 54 68 65 20 62 75 66 66 65 72  ons.  The buffer
5a10: 20 6d 75 73 74 20 62 65 0a 61 74 20 6c 65 61 73   must be.at leas
5a20: 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 69 6e 20  t sz*N bytes in 
5a30: 73 69 7a 65 2e 20 20 54 68 65 20 22 73 7a 22 20  size.  The "sz" 
5a40: 70 61 72 61 6d 65 74 65 72 0a 69 73 20 74 68 65  parameter.is the
5a50: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
5a60: 67 65 2d 63 61 63 68 65 20 61 6c 6c 6f 63 61 74  ge-cache allocat
5a70: 69 6f 6e 2e 20 20 4e 20 69 73 20 74 68 65 20 6d  ion.  N is the m
5a80: 61 78 69 6d 75 6d 20 0a 6e 75 6d 62 65 72 20 6f  aximum .number o
5a90: 66 20 61 76 61 69 6c 61 62 6c 65 20 61 6c 6c 6f  f available allo
5aa0: 63 61 74 69 6f 6e 73 2e 3c 2f 70 3e 0a 0a 3c 70  cations.</p>..<p
5ab0: 3e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64 73  >If SQLite needs
5ac0: 20 61 20 70 61 67 65 2d 63 61 63 68 65 20 65 6e   a page-cache en
5ad0: 74 72 79 20 74 68 61 74 20 69 73 20 6c 61 72 67  try that is larg
5ae0: 65 72 20 74 68 61 6e 20 22 73 7a 22 20 62 79 74  er than "sz" byt
5af0: 65 73 20 6f 72 0a 69 66 20 69 74 20 6e 65 65 64  es or.if it need
5b00: 73 20 6d 6f 72 65 20 74 68 61 6e 20 4e 20 65 6e  s more than N en
5b10: 74 72 69 65 73 2c 20 69 74 20 66 61 6c 6c 73 20  tries, it falls 
5b20: 62 61 63 6b 20 74 6f 20 75 73 69 6e 67 20 74 68  back to using th
5b30: 65 0a 67 65 6e 65 72 61 6c 2d 70 75 72 70 6f 73  e.general-purpos
5b40: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
5b50: 6f 72 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e 68 64  or.</p>..<tcl>hd
5b60: 5f 66 72 61 67 6d 65 6e 74 20 6c 6f 6f 6b 61 73  _fragment lookas
5b70: 69 64 65 20 7b 6c 6f 6f 6b 61 73 69 64 65 20 6d  ide {lookaside m
5b80: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 7d  emory allocator}
5b90: 20 5c 0a 20 20 20 7b 6c 6f 6f 6b 61 73 69 64 65   \.   {lookaside
5ba0: 20 62 75 66 66 65 72 7d 20 7b 6c 6f 6f 6b 61 73   buffer} {lookas
5bb0: 69 64 65 20 6d 65 6d 6f 72 79 7d 20 7b 6c 6f 6f  ide memory} {loo
5bc0: 6b 61 73 69 64 65 7d 3c 2f 74 63 6c 3e 0a 3c 68  kaside}</tcl>.<h
5bd0: 32 3e 20 4c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  2> Lookaside mem
5be0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 3c 2f 68  ory allocator</h
5bf0: 32 3e 0a 0a 3c 70 3e 53 51 4c 69 74 65 20 5b 64  2>..<p>SQLite [d
5c00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5c10: 6f 6e 73 5d 20 6d 61 6b 65 20 6d 61 6e 79 0a 73  ons] make many.s
5c20: 6d 61 6c 6c 20 61 6e 64 20 73 68 6f 72 74 2d 6c  mall and short-l
5c30: 69 76 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ived memory allo
5c40: 63 61 74 69 6f 6e 73 2e 0a 54 68 69 73 20 6f 63  cations..This oc
5c50: 63 75 72 73 20 6d 6f 73 74 20 63 6f 6d 6d 6f 6e  curs most common
5c60: 6c 79 20 77 68 65 6e 20 63 6f 6d 70 69 6c 69 6e  ly when compilin
5c70: 67 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  g SQL statements
5c80: 20 75 73 69 6e 67 0a 5b 73 71 6c 69 74 65 33 5f   using.[sqlite3_
5c90: 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 62 75  prepare_v2()] bu
5ca0: 74 20 61 6c 73 6f 20 74 6f 20 61 20 6c 65 73 73  t also to a less
5cb0: 65 72 20 65 78 74 65 6e 74 20 77 68 65 6e 20 72  er extent when r
5cc0: 75 6e 6e 69 6e 67 0a 5b 70 72 65 70 61 72 65 64  unning.[prepared
5cd0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 75 73 69   statements] usi
5ce0: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ng [sqlite3_step
5cf0: 28 29 5d 2e 20 20 54 68 65 73 65 20 73 6d 61 6c  ()].  These smal
5d00: 6c 20 6d 65 6d 6f 72 79 0a 61 6c 6c 6f 63 61 74  l memory.allocat
5d10: 69 6f 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f  ions are used to
5d20: 20 68 6f 6c 64 20 74 68 69 6e 67 73 20 73 75 63   hold things suc
5d30: 68 20 61 73 20 74 68 65 20 6e 61 6d 65 73 20 6f  h as the names o
5d40: 66 20 74 61 62 6c 65 73 0a 61 6e 64 20 63 6f 6c  f tables.and col
5d50: 75 6d 6e 73 2c 20 70 61 72 73 65 20 74 72 65 65  umns, parse tree
5d60: 20 6e 6f 64 65 73 2c 20 69 6e 64 69 76 69 64 75   nodes, individu
5d70: 61 6c 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  al query results
5d80: 20 76 61 6c 75 65 73 2c 0a 61 6e 64 20 42 2d 54   values,.and B-T
5d90: 72 65 65 20 63 75 72 73 6f 72 20 6f 62 6a 65 63  ree cursor objec
5da0: 74 73 2e 20 20 54 68 65 72 65 20 61 72 65 20 63  ts.  There are c
5db0: 6f 6e 73 65 71 75 65 6e 74 6c 79 0a 6d 61 6e 79  onsequently.many
5dc0: 20 63 61 6c 6c 73 20 74 6f 20 6d 61 6c 6c 6f 63   calls to malloc
5dd0: 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 2d 20  () and free() - 
5de0: 73 6f 20 6d 61 6e 79 20 63 61 6c 6c 73 20 74 68  so many calls th
5df0: 61 74 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 0a  at malloc() and.
5e00: 66 72 65 65 28 29 20 65 6e 64 20 75 70 20 75 73  free() end up us
5e10: 69 6e 67 20 61 20 73 69 67 6e 69 66 69 63 61 6e  ing a significan
5e20: 74 20 66 72 61 63 74 69 6f 6e 20 6f 66 20 74 68  t fraction of th
5e30: 65 20 43 50 55 20 74 69 6d 65 20 61 73 73 69 67  e CPU time assig
5e40: 6e 65 64 0a 74 6f 20 53 51 4c 69 74 65 2e 3c 2f  ned.to SQLite.</
5e50: 70 3e 0a 0a 3c 70 3e 53 51 4c 69 74 65 20 5b 76  p>..<p>SQLite [v
5e60: 65 72 73 69 6f 6e 20 33 2e 36 2e 31 5d 20 28 5b  ersion 3.6.1] ([
5e70: 64 61 74 65 6f 66 3a 33 2e 36 2e 31 5d 29 0a 69  dateof:3.6.1]).i
5e80: 6e 74 72 6f 64 75 63 65 64 20 74 68 65 20 6c 6f  ntroduced the lo
5e90: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61  okaside memory a
5ea0: 6c 6c 6f 63 61 74 6f 72 20 74 6f 0a 68 65 6c 70  llocator to.help
5eb0: 20 72 65 64 75 63 65 20 74 68 65 20 6d 65 6d 6f   reduce the memo
5ec0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6c 6f  ry allocation lo
5ed0: 61 64 2e 20 20 49 6e 20 74 68 65 20 6c 6f 6f 6b  ad.  In the look
5ee0: 61 73 69 64 65 20 61 6c 6c 6f 63 61 74 6f 72 2c  aside allocator,
5ef0: 0a 65 61 63 68 20 5b 64 61 74 61 62 61 73 65 20  .each [database 
5f00: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 72 65 61  connection] prea
5f10: 6c 6c 6f 63 61 74 65 73 20 61 20 73 69 6e 67 6c  llocates a singl
5f20: 65 20 6c 61 72 67 65 20 63 68 75 6e 6b 20 6f 66  e large chunk of
5f30: 20 6d 65 6d 6f 72 79 0a 28 74 79 70 69 63 61 6c   memory.(typical
5f40: 6c 79 20 69 6e 20 74 68 65 20 72 61 6e 67 65 20  ly in the range 
5f50: 6f 66 20 36 30 20 74 6f 20 31 32 30 20 6b 69 6c  of 60 to 120 kil
5f60: 6f 62 79 74 65 73 29 20 61 6e 64 20 64 69 76 69  obytes) and divi
5f70: 64 65 73 20 74 68 61 74 20 63 68 75 6e 6b 0a 75  des that chunk.u
5f80: 70 20 69 6e 74 6f 20 73 6d 61 6c 6c 20 66 69 78  p into small fix
5f90: 65 64 2d 73 69 7a 65 20 22 73 6c 6f 74 73 22 20  ed-size "slots" 
5fa0: 6f 66 20 61 72 6f 75 6e 64 20 31 30 30 20 74 6f  of around 100 to
5fb0: 20 31 30 30 30 20 62 79 74 65 20 65 61 63 68 2e   1000 byte each.
5fc0: 20 20 54 68 69 73 0a 62 65 63 6f 6d 65 73 20 74    This.becomes t
5fd0: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
5fe0: 6f 72 79 20 70 6f 6f 6c 2e 20 20 54 68 65 72 65  ory pool.  There
5ff0: 61 66 74 65 72 2c 20 6d 65 6d 6f 72 79 20 61 6c  after, memory al
6000: 6c 6f 63 61 74 69 6f 6e 73 0a 61 73 73 6f 63 69  locations.associ
6010: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b 64  ated with the [d
6020: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
6030: 6f 6e 5d 20 61 6e 64 20 74 68 61 74 20 61 72 65  on] and that are
6040: 20 6e 6f 74 20 74 6f 6f 20 6c 61 72 67 65 0a 61   not too large.a
6050: 72 65 20 73 61 74 69 73 66 69 65 64 20 75 73 69  re satisfied usi
6060: 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 20 6c 6f  ng one of the lo
6070: 6f 6b 61 73 69 64 65 20 70 6f 6f 6c 20 73 6c 6f  okaside pool slo
6080: 74 73 20 72 61 74 68 65 72 20 74 68 61 6e 20 62  ts rather than b
6090: 79 20 63 61 6c 6c 69 6e 67 0a 74 68 65 20 67 65  y calling.the ge
60a0: 6e 65 72 61 6c 2d 70 75 72 70 6f 73 65 20 6d 65  neral-purpose me
60b0: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20  mory allocator. 
60c0: 20 4c 61 72 67 65 72 20 61 6c 6c 6f 63 61 74 69   Larger allocati
60d0: 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 74 6f 0a  ons continue to.
60e0: 75 73 65 20 74 68 65 20 67 65 6e 65 72 61 6c 2d  use the general-
60f0: 70 75 72 70 6f 73 65 20 6d 65 6d 6f 72 79 20 61  purpose memory a
6100: 6c 6c 6f 63 61 74 6f 72 2c 20 61 73 20 64 6f 20  llocator, as do 
6110: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74  allocations that
6120: 20 6f 63 63 75 72 0a 77 68 65 6e 20 74 68 65 20   occur.when the 
6130: 6c 6f 6f 6b 61 73 69 64 65 20 70 6f 6f 6c 20 73  lookaside pool s
6140: 6c 6f 74 73 20 61 72 65 20 61 6c 6c 20 63 68 65  lots are all che
6150: 63 6b 65 64 20 6f 75 74 2e 20 20 0a 42 75 74 20  cked out.  .But 
6160: 69 6e 20 6d 61 6e 79 20 63 61 73 65 73 2c 20 74  in many cases, t
6170: 68 65 20 6d 65 6d 6f 72 79 0a 61 6c 6c 6f 63 61  he memory.alloca
6180: 74 69 6f 6e 73 20 61 72 65 20 73 6d 61 6c 6c 20  tions are small 
6190: 65 6e 6f 75 67 68 20 61 6e 64 20 74 68 65 72 65  enough and there
61a0: 20 61 72 65 20 66 65 77 20 65 6e 6f 75 67 68 20   are few enough 
61b0: 6f 75 74 73 74 61 6e 64 69 6e 67 20 74 68 61 74  outstanding that
61c0: 0a 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 20  .the new memory 
61d0: 72 65 71 75 65 73 74 73 20 63 61 6e 20 62 65 20  requests can be 
61e0: 73 61 74 69 73 66 69 65 64 20 66 72 6f 6d 20 74  satisfied from t
61f0: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 70 6f 6f  he lookaside.poo
6200: 6c 2e 3c 2f 70 3e 0a 0a 3c 70 3e 42 65 63 61 75  l.</p>..<p>Becau
6210: 73 65 20 6c 6f 6f 6b 61 73 69 64 65 20 61 6c 6c  se lookaside all
6220: 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 61 6c 77  ocations are alw
6230: 61 79 73 20 74 68 65 20 73 61 6d 65 20 73 69 7a  ays the same siz
6240: 65 2c 20 74 68 65 20 61 6c 6c 6f 63 61 74 69 6f  e, the allocatio
6250: 6e 0a 61 6e 64 20 64 65 61 6c 6c 6f 63 61 74 69  n.and deallocati
6260: 6f 6e 20 61 6c 67 6f 72 69 74 68 6d 73 20 61 72  on algorithms ar
6270: 65 20 76 65 72 79 20 71 75 69 63 6b 2e 20 20 54  e very quick.  T
6280: 68 65 72 65 20 69 73 20 6e 6f 0a 6e 65 65 64 20  here is no.need 
6290: 74 6f 20 63 6f 61 6c 65 73 63 65 20 61 64 6a 61  to coalesce adja
62a0: 63 65 6e 74 20 66 72 65 65 20 73 6c 6f 74 73 20  cent free slots 
62b0: 6f 72 20 73 65 61 72 63 68 20 66 6f 72 20 61 20  or search for a 
62c0: 73 6c 6f 74 0a 6f 66 20 61 20 70 61 72 74 69 63  slot.of a partic
62d0: 75 6c 61 72 20 73 69 7a 65 2e 20 20 45 61 63 68  ular size.  Each
62e0: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
62f0: 63 74 69 6f 6e 5d 20 6d 61 69 6e 74 61 69 6e 73  ction] maintains
6300: 20 61 20 73 69 6e 67 6c 79 2d 6c 69 6e 6b 65 64   a singly-linked
6310: 0a 6c 69 73 74 20 6f 66 20 75 6e 75 73 65 64 20  .list of unused 
6320: 73 6c 6f 74 73 2e 20 20 41 6c 6c 6f 63 61 74 69  slots.  Allocati
6330: 6f 6e 20 72 65 71 75 65 73 74 73 20 73 69 6d 70  on requests simp
6340: 6c 79 20 70 75 6c 6c 20 74 68 65 20 66 69 72 73  ly pull the firs
6350: 74 0a 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 69  t.element of thi
6360: 73 20 6c 69 73 74 2e 20 20 44 65 61 6c 6c 6f 63  s list.  Dealloc
6370: 61 74 69 6f 6e 73 20 73 69 6d 70 6c 79 20 70 75  ations simply pu
6380: 73 68 20 74 68 65 20 65 6c 65 6d 65 6e 74 20 62  sh the element b
6390: 61 63 6b 20 6f 6e 74 6f 0a 74 68 65 20 66 72 6f  ack onto.the fro
63a0: 6e 74 20 6f 66 20 74 68 65 20 6c 69 73 74 2e 0a  nt of the list..
63b0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 65 61 63  Furthermore, eac
63c0: 68 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  h [database conn
63d0: 65 63 74 69 6f 6e 5d 20 69 73 20 61 73 73 75 6d  ection] is assum
63e0: 65 64 20 74 6f 20 61 6c 72 65 61 64 79 20 62 65  ed to already be
63f0: 0a 72 75 6e 6e 69 6e 67 20 69 6e 20 61 20 73 69  .running in a si
6400: 6e 67 6c 65 20 74 68 72 65 61 64 20 28 74 68 65  ngle thread (the
6410: 72 65 20 61 72 65 20 6d 75 74 65 78 65 73 20 61  re are mutexes a
6420: 6c 72 65 61 64 79 20 69 6e 0a 70 6c 61 63 65 20  lready in.place 
6430: 74 6f 20 65 6e 66 6f 72 63 65 20 74 68 69 73 29  to enforce this)
6440: 20 73 6f 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61   so no additiona
6450: 6c 20 6d 75 74 65 78 69 6e 67 20 69 73 20 72 65  l mutexing is re
6460: 71 75 69 72 65 64 20 74 6f 20 0a 73 65 72 69 61  quired to .seria
6470: 6c 69 7a 65 20 61 63 63 65 73 73 20 74 6f 20 74  lize access to t
6480: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 73 6c 6f  he lookaside slo
6490: 74 20 66 72 65 65 6c 69 73 74 2e 0a 43 6f 6e 73  t freelist..Cons
64a0: 65 71 75 65 6e 74 6c 79 2c 20 6c 6f 6f 6b 61 73  equently, lookas
64b0: 69 64 65 20 6d 65 6d 6f 72 79 0a 61 6c 6c 6f 63  ide memory.alloc
64c0: 61 74 69 6f 6e 73 20 61 6e 64 20 64 65 61 6c 6c  ations and deall
64d0: 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 76 65 72  ocations are ver
64e0: 79 20 66 61 73 74 2e 20 20 49 6e 20 73 70 65 65  y fast.  In spee
64f0: 64 20 74 65 73 74 73 20 6f 6e 0a 4c 69 6e 75 78  d tests on.Linux
6500: 20 61 6e 64 20 4d 61 63 20 4f 53 20 58 20 77 6f   and Mac OS X wo
6510: 72 6b 73 74 61 74 69 6f 6e 73 2c 20 53 51 4c 69  rkstations, SQLi
6520: 74 65 20 68 61 73 20 73 68 6f 77 6e 20 6f 76 65  te has shown ove
6530: 72 61 6c 6c 20 70 65 72 66 6f 72 6d 61 6e 63 65  rall performance
6540: 0a 69 6d 70 72 6f 76 65 6d 65 6e 74 73 20 61 73  .improvements as
6550: 20 68 69 67 68 20 61 73 20 31 30 25 20 61 6e 64   high as 10% and
6560: 20 31 35 25 2c 20 64 65 70 65 6e 64 69 6e 67 20   15%, depending 
6570: 6f 6e 20 74 68 65 20 77 6f 72 6b 6c 6f 61 64 20  on the workload 
6580: 68 6f 77 0a 61 6e 64 20 6c 6f 6f 6b 61 73 69 64  how.and lookasid
6590: 65 20 69 73 20 63 6f 6e 66 69 67 75 72 65 64 2e  e is configured.
65a0: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 73 69 7a  </p>..<p>The siz
65b0: 65 20 6f 66 20 74 68 65 20 6c 6f 6f 6b 61 73 69  e of the lookasi
65c0: 64 65 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 68  de memory pool h
65d0: 61 73 20 61 20 67 6c 6f 62 61 6c 20 64 65 66 61  as a global defa
65e0: 75 6c 74 20 76 61 6c 75 65 0a 62 75 74 20 63 61  ult value.but ca
65f0: 6e 20 61 6c 73 6f 20 62 65 20 63 6f 6e 66 69 67  n also be config
6600: 75 72 65 64 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  ured on a connec
6610: 74 69 6f 6e 2d 62 79 2d 63 6f 6e 6e 65 63 74 69  tion-by-connecti
6620: 6f 6e 20 62 61 73 69 73 2e 0a 54 6f 20 63 68 61  on basis..To cha
6630: 6e 67 65 20 74 68 65 20 64 65 66 61 75 6c 74 20  nge the default 
6640: 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 6f 6f 6b  size of the look
6650: 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 70 6f 6f  aside memory poo
6660: 6c 20 61 74 0a 63 6f 6d 70 69 6c 65 2d 74 69 6d  l at.compile-tim
6670: 65 2c 20 75 73 65 20 74 68 65 20 0a 5b 53 51 4c  e, use the .[SQL
6680: 49 54 45 5f 44 45 46 41 55 4c 54 5f 4c 4f 4f 4b  ITE_DEFAULT_LOOK
6690: 41 53 49 44 45 7c 2d 44 53 51 4c 49 54 45 5f 44  ASIDE|-DSQLITE_D
66a0: 45 46 41 55 4c 54 5f 4c 4f 4f 4b 41 53 49 44 45  EFAULT_LOOKASIDE
66b0: 3d 3c 69 3e 53 5a 2c 4e 3c 2f 69 3e 5d 0a 6f 70  =<i>SZ,N</i>].op
66c0: 74 69 6f 6e 2e 0a 54 6f 20 63 68 61 6e 67 65 20  tion..To change 
66d0: 74 68 65 20 64 65 66 61 75 6c 74 20 73 69 7a 65  the default size
66e0: 20 6f 66 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64   of the lookasid
66f0: 65 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 61 74  e memory pool at
6700: 0a 73 74 61 72 74 2d 74 69 6d 65 2c 20 75 73 65  .start-time, use
6710: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
6720: 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63  nfig()] interfac
6730: 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75  e:</p>..<blockqu
6740: 6f 74 65 3e 3c 70 72 65 3e 0a 5b 73 71 6c 69 74  ote><pre>.[sqlit
6750: 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
6760: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
6770: 49 44 45 5d 2c 20 73 7a 2c 20 63 6e 74 29 3b 0a  IDE], sz, cnt);.
6780: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
6790: 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 22 73 7a 22  te>..<p>The "sz"
67a0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
67b0: 65 20 73 69 7a 65 20 69 6e 20 62 79 74 65 73 20  e size in bytes 
67c0: 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
67d0: 65 20 73 6c 6f 74 2e 0a 54 68 65 20 22 63 6e 74  e slot..The "cnt
67e0: 22 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 74  " parameter is.t
67f0: 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20  he total number 
6800: 6f 66 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  of lookaside mem
6810: 6f 72 79 20 73 6c 6f 74 73 20 70 65 72 20 64 61  ory slots per da
6820: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6830: 6e 2e 0a 54 68 65 20 74 6f 74 61 6c 20 61 6d 6f  n..The total amo
6840: 75 6e 74 0a 6f 66 20 6c 6f 6f 6b 61 73 69 64 65  unt.of lookaside
6850: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
6860: 64 20 74 6f 20 65 61 63 68 20 5b 64 61 74 61 62  d to each [datab
6870: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
6880: 69 73 0a 73 7a 2a 63 6e 74 20 62 79 74 65 73 2e  is.sz*cnt bytes.
6890: 20 0a 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 6c   .</p>..<p>The l
68a0: 6f 6f 6b 61 73 69 64 65 20 70 6f 6f 6c 20 63 61  ookaside pool ca
68b0: 6e 20 62 65 20 63 68 61 6e 67 65 64 20 66 6f 72  n be changed for
68c0: 20 61 6e 20 69 6e 64 69 76 69 64 75 61 6c 0a 5b   an individual.[
68d0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
68e0: 69 6f 6e 5d 20 22 64 62 22 20 75 73 69 6e 67 20  ion] "db" using 
68f0: 74 68 69 73 20 63 61 6c 6c 3a 3c 2f 70 3e 0a 0a  this call:</p>..
6900: 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
6910: 3e 0a 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  >.[sqlite3_db_co
6920: 6e 66 69 67 5d 28 64 62 2c 20 5b 53 51 4c 49 54  nfig](db, [SQLIT
6930: 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
6940: 53 49 44 45 5d 2c 20 70 42 75 66 2c 20 73 7a 2c  SIDE], pBuf, sz,
6950: 20 63 6e 74 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62   cnt);.</pre></b
6960: 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54  lockquote>..<p>T
6970: 68 65 20 22 70 42 75 66 22 20 70 61 72 61 6d 65  he "pBuf" parame
6980: 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ter is a pointer
6990: 20 74 6f 20 6d 65 6d 6f 72 79 20 73 70 61 63 65   to memory space
69a0: 20 74 68 61 74 20 77 69 6c 6c 20 62 65 0a 75 73   that will be.us
69b0: 65 64 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  ed for the looka
69c0: 73 69 64 65 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c  side memory pool
69d0: 2e 20 20 49 66 20 70 42 75 66 20 69 73 20 4e 55  .  If pBuf is NU
69e0: 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a  LL, then SQLite.
69f0: 77 69 6c 6c 20 6f 62 74 61 69 6e 20 69 74 73 20  will obtain its 
6a00: 6f 77 6e 20 73 70 61 63 65 20 66 6f 72 20 74 68  own space for th
6a10: 65 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 75 73  e memory pool us
6a20: 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  ing [sqlite3_mal
6a30: 6c 6f 63 28 29 5d 2e 0a 54 68 65 20 22 73 7a 22  loc()]..The "sz"
6a40: 20 61 6e 64 20 22 63 6e 74 22 20 70 61 72 61 6d   and "cnt" param
6a50: 65 74 65 72 73 20 61 72 65 20 74 68 65 20 73 69  eters are the si
6a60: 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61  ze of each looka
6a70: 73 69 64 65 20 73 6c 6f 74 0a 61 6e 64 20 74 68  side slot.and th
6a80: 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 6c 6f 74  e number of slot
6a90: 73 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  s, respectively.
6aa0: 20 20 49 66 20 70 42 75 66 20 69 73 20 6e 6f 74    If pBuf is not
6ab0: 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 0a 6d   NULL, then it.m
6ac0: 75 73 74 20 70 6f 69 6e 74 20 74 6f 20 61 74 20  ust point to at 
6ad0: 6c 65 61 73 74 20 73 7a 2a 63 6e 74 20 62 79 74  least sz*cnt byt
6ae0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 3c 2f 70  es of memory.</p
6af0: 3e 0a 0a 3c 70 3e 54 68 65 20 6c 6f 6f 6b 61 73  >..<p>The lookas
6b00: 69 64 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ide configuratio
6b10: 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68  n can only be ch
6b20: 61 6e 67 65 64 20 77 68 69 6c 65 20 74 68 65 72  anged while ther
6b30: 65 20 61 72 65 0a 6e 6f 20 6f 75 74 73 74 61 6e  e are.no outstan
6b40: 64 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65 20 61  ding lookaside a
6b50: 6c 6c 6f 63 61 74 69 6f 6e 73 20 66 6f 72 20 74  llocations for t
6b60: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
6b70: 65 63 74 69 6f 6e 2e 0a 48 65 6e 63 65 2c 20 74  ection..Hence, t
6b80: 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
6b90: 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 69   should be set i
6ba0: 6d 6d 65 64 69 61 74 65 6c 79 20 61 66 74 65 72  mmediately after
6bb0: 20 63 72 65 61 74 69 6e 67 20 74 68 65 20 0a 64   creating the .d
6bc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
6bd0: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
6be0: 33 5f 6f 70 65 6e 28 29 5d 20 28 6f 72 20 65 71  3_open()] (or eq
6bf0: 75 69 76 61 6c 65 6e 74 29 20 61 6e 64 20 62 65  uivalent) and be
6c00: 66 6f 72 65 0a 65 76 61 6c 75 61 74 69 6e 67 20  fore.evaluating 
6c10: 61 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  any SQL statemen
6c20: 74 73 20 6f 6e 20 74 68 65 20 63 6f 6e 6e 65 63  ts on the connec
6c30: 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 74 63 6c 3e  tion.</p>..<tcl>
6c40: 68 64 5f 66 72 61 67 6d 65 6e 74 20 6d 65 6d 73  hd_fragment mems
6c50: 74 61 74 75 73 20 7b 6d 65 6d 6f 72 79 20 73 74  tatus {memory st
6c60: 61 74 69 73 74 69 63 73 7d 3c 2f 74 63 6c 3e 0a  atistics}</tcl>.
6c70: 3c 68 32 3e 20 4d 65 6d 6f 72 79 20 73 74 61 74  <h2> Memory stat
6c80: 75 73 3c 2f 68 32 3e 0a 0a 3c 70 3e 42 79 20 64  us</h2>..<p>By d
6c90: 65 66 61 75 6c 74 2c 20 53 51 4c 69 74 65 20 6b  efault, SQLite k
6ca0: 65 65 70 73 20 73 74 61 74 69 73 74 69 63 73 20  eeps statistics 
6cb0: 6f 6e 20 69 74 73 20 6d 65 6d 6f 72 79 20 75 73  on its memory us
6cc0: 61 67 65 2e 20 20 54 68 65 73 65 0a 73 74 61 74  age.  These.stat
6cd0: 69 73 74 69 63 73 20 61 72 65 20 75 73 65 66 75  istics are usefu
6ce0: 6c 20 69 6e 20 68 65 6c 70 69 6e 67 20 74 6f 20  l in helping to 
6cf0: 64 65 74 65 72 6d 69 6e 65 20 68 6f 77 20 6d 75  determine how mu
6d00: 63 68 20 6d 65 6d 6f 72 79 20 61 6e 0a 61 70 70  ch memory an.app
6d10: 6c 69 63 61 74 69 6f 6e 20 72 65 61 6c 6c 79 20  lication really 
6d20: 6e 65 65 64 73 2e 20 20 54 68 65 20 73 74 61 74  needs.  The stat
6d30: 69 73 74 69 63 73 20 63 61 6e 20 61 6c 73 6f 20  istics can also 
6d40: 62 65 20 75 73 65 64 20 69 6e 0a 68 69 67 68 2d  be used in.high-
6d50: 72 65 6c 69 61 62 69 6c 69 74 79 20 73 79 73 74  reliability syst
6d60: 65 6d 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 0a  em to determine.
6d70: 69 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 75 73  if the memory us
6d80: 61 67 65 20 69 73 20 63 6f 6d 69 6e 67 20 63 6c  age is coming cl
6d90: 6f 73 65 20 74 6f 20 6f 72 20 65 78 63 65 65 64  ose to or exceed
6da0: 69 6e 67 20 74 68 65 20 6c 69 6d 69 74 73 20 0a  ing the limits .
6db0: 6f 66 20 74 68 65 20 5b 52 6f 62 73 6f 6e 20 70  of the [Robson p
6dc0: 72 6f 6f 66 5d 20 61 6e 64 20 68 65 6e 63 65 20  roof] and hence 
6dd0: 74 68 61 74 20 74 68 65 20 6d 65 6d 6f 72 79 20  that the memory 
6de0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79  allocation subsy
6df0: 73 74 65 6d 20 69 73 20 0a 6c 69 61 62 6c 65 20  stem is .liable 
6e00: 74 6f 20 62 72 65 61 6b 64 6f 77 6e 2e 3c 2f 70  to breakdown.</p
6e10: 3e 0a 0a 3c 70 3e 4d 6f 73 74 20 6d 65 6d 6f 72  >..<p>Most memor
6e20: 79 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  y statistics are
6e30: 20 67 6c 6f 62 61 6c 2c 20 61 6e 64 20 74 68 65   global, and the
6e40: 72 65 66 6f 72 65 20 74 68 65 20 74 72 61 63 6b  refore the track
6e50: 69 6e 67 20 6f 66 0a 73 74 61 74 69 73 74 69 63  ing of.statistic
6e60: 73 20 6d 75 73 74 20 62 65 20 73 65 72 69 61 6c  s must be serial
6e70: 69 7a 65 64 20 77 69 74 68 20 61 20 6d 75 74 65  ized with a mute
6e80: 78 2e 20 20 53 74 61 74 69 73 74 69 63 73 20 61  x.  Statistics a
6e90: 72 65 20 74 75 72 6e 65 64 20 0a 6f 6e 20 62 79  re turned .on by
6ea0: 20 64 65 66 61 75 6c 74 2c 20 62 75 74 20 61 6e   default, but an
6eb0: 20 6f 70 74 69 6f 6e 20 65 78 69 73 74 73 20 74   option exists t
6ec0: 6f 20 64 69 73 61 62 6c 65 20 74 68 65 6d 2e 20  o disable them. 
6ed0: 20 42 79 20 64 69 73 61 62 6c 69 6e 67 20 0a 6d   By disabling .m
6ee0: 65 6d 6f 72 79 20 73 74 61 74 69 73 74 69 63 73  emory statistics
6ef0: 2c 0a 53 51 4c 69 74 65 20 61 76 6f 69 64 73 20  ,.SQLite avoids 
6f00: 65 6e 74 65 72 69 6e 67 20 61 6e 64 20 6c 65 61  entering and lea
6f10: 76 69 6e 67 20 61 20 6d 75 74 65 78 20 6f 6e 20  ving a mutex on 
6f20: 65 61 63 68 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  each memory allo
6f30: 63 61 74 69 6f 6e 0a 61 6e 64 20 64 65 61 6c 6c  cation.and deall
6f40: 6f 63 61 74 69 6f 6e 2e 20 20 54 68 61 74 20 73  ocation.  That s
6f50: 61 76 69 6e 67 73 20 63 61 6e 20 62 65 20 6e 6f  avings can be no
6f60: 74 69 63 65 61 62 6c 65 20 6f 6e 20 73 79 73 74  ticeable on syst
6f70: 65 6d 73 20 77 68 65 72 65 0a 6d 75 74 65 78 20  ems where.mutex 
6f80: 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20 65  operations are e
6f90: 78 70 65 6e 73 69 76 65 2e 20 20 54 6f 20 64 69  xpensive.  To di
6fa0: 73 61 62 6c 65 20 6d 65 6d 6f 72 79 20 73 74 61  sable memory sta
6fb0: 74 69 73 74 69 63 73 2c 20 74 68 65 0a 66 6f 6c  tistics, the.fol
6fc0: 6c 6f 77 69 6e 67 20 69 6e 74 65 72 66 61 63 65  lowing interface
6fd0: 20 69 73 20 75 73 65 64 20 61 74 20 73 74 61 72   is used at star
6fe0: 74 2d 74 69 6d 65 3a 3c 2f 70 3e 0a 0a 3c 62 6c  t-time:</p>..<bl
6ff0: 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 5b  ockquote><pre>.[
7000: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
7010: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
7020: 45 4d 53 54 41 54 55 53 5d 2c 20 6f 6e 6f 66 66  EMSTATUS], onoff
7030: 29 3b 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  );.</pre></block
7040: 71 75 6f 74 65 3e 0a 0a 3c 70 3e 54 68 65 20 22  quote>..<p>The "
7050: 6f 6e 6f 66 66 22 20 70 61 72 61 6d 65 74 65 72  onoff" parameter
7060: 20 69 73 20 74 72 75 65 20 74 6f 20 65 6e 61 62   is true to enab
7070: 6c 65 20 74 68 65 20 74 72 61 63 6b 69 6e 67 20  le the tracking 
7080: 6f 66 20 6d 65 6d 6f 72 79 0a 73 74 61 74 69 73  of memory.statis
7090: 74 69 63 73 20 61 6e 64 20 66 61 6c 73 65 20 74  tics and false t
70a0: 6f 20 64 69 73 61 62 6c 65 20 73 74 61 74 69 73  o disable statis
70b0: 74 69 63 73 20 74 72 61 63 6b 69 6e 67 2e 3c 2f  tics tracking.</
70c0: 70 3e 0a 0a 3c 70 3e 41 73 73 75 6d 69 6e 67 20  p>..<p>Assuming 
70d0: 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
70e0: 6e 61 62 6c 65 64 2c 20 74 68 65 20 66 6f 6c 6c  nabled, the foll
70f0: 6f 77 69 6e 67 20 72 6f 75 74 69 6e 65 20 63 61  owing routine ca
7100: 6e 20 62 65 20 75 73 65 64 0a 74 6f 20 61 63 63  n be used.to acc
7110: 65 73 73 20 74 68 65 6d 3a 3c 2f 70 3e 0a 0a 3c  ess them:</p>..<
7120: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
7130: 0a 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73  .[sqlite3_status
7140: 5d 28 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53  ]([SQLITE_STATUS
7150: 5f 4d 45 4d 4f 52 59 5f 55 53 45 44 7c 76 65 72  _MEMORY_USED|ver
7160: 62 5d 2c 20 26 61 6d 70 3b 63 75 72 72 65 6e 74  b], &amp;current
7170: 2c 20 26 61 6d 70 3b 68 69 67 68 77 61 74 65 72  , &amp;highwater
7180: 2c 20 72 65 73 65 74 66 6c 61 67 29 3b 0a 3c 2f  , resetflag);.</
7190: 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
71a0: 3e 0a 0a 3c 70 3e 54 68 65 20 22 76 65 72 62 22  >..<p>The "verb"
71b0: 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72 6d   argument determ
71c0: 69 6e 65 73 20 77 68 61 74 20 73 74 61 74 69 73  ines what statis
71d0: 74 69 63 20 69 73 20 61 63 63 65 73 73 65 64 2e  tic is accessed.
71e0: 0a 54 68 65 72 65 20 61 72 65 20 5b 53 51 4c 49  .There are [SQLI
71f0: 54 45 5f 53 54 41 54 55 53 5f 4d 45 4d 4f 52 59  TE_STATUS_MEMORY
7200: 5f 55 53 45 44 20 7c 20 76 61 72 69 6f 75 73 20  _USED | various 
7210: 76 65 72 62 73 5d 20 64 65 66 69 6e 65 64 2e 20  verbs] defined. 
7220: 20 54 68 65 0a 6c 69 73 74 20 69 73 20 65 78 70   The.list is exp
7230: 65 63 74 65 64 20 74 6f 20 67 72 6f 77 20 61 73  ected to grow as
7240: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
7250: 61 74 75 73 28 29 5d 20 69 6e 74 65 72 66 61 63  atus()] interfac
7260: 65 20 6d 61 74 75 72 65 73 2e 0a 54 68 65 20 63  e matures..The c
7270: 75 72 72 65 6e 74 20 76 61 6c 75 65 20 74 68 65  urrent value the
7280: 20 73 65 6c 65 63 74 65 64 20 70 61 72 61 6d 65   selected parame
7290: 74 65 72 20 69 73 20 77 72 69 74 74 65 6e 20 69  ter is written i
72a0: 6e 74 6f 20 69 6e 74 65 67 65 72 20 0a 22 63 75  nto integer ."cu
72b0: 72 72 65 6e 74 22 20 61 6e 64 20 74 68 65 20 68  rrent" and the h
72c0: 69 67 68 65 73 74 20 68 69 73 74 6f 72 69 63 61  ighest historica
72d0: 6c 20 76 61 6c 75 65 0a 69 73 20 77 72 69 74 74  l value.is writt
72e0: 65 6e 20 69 6e 74 6f 20 69 6e 74 65 67 65 72 20  en into integer 
72f0: 22 68 69 67 68 77 61 74 65 72 22 2e 20 20 49 66  "highwater".  If
7300: 20 72 65 73 65 74 66 6c 61 67 20 69 73 20 74 72   resetflag is tr
7310: 75 65 2c 20 74 68 65 6e 0a 74 68 65 20 68 69 67  ue, then.the hig
7320: 68 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20  h-water mark is 
7330: 72 65 73 65 74 20 64 6f 77 6e 20 74 6f 20 74 68  reset down to th
7340: 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
7350: 61 66 74 65 72 20 74 68 65 20 63 61 6c 6c 0a 72  after the call.r
7360: 65 74 75 72 6e 73 2e 3c 2f 70 3e 0a 0a 3c 70 3e  eturns.</p>..<p>
7370: 41 20 64 69 66 66 65 72 65 6e 74 20 69 6e 74 65  A different inte
7380: 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74 6f  rface is used to
7390: 20 66 69 6e 64 20 73 74 61 74 69 73 74 69 63 73   find statistics
73a0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
73b0: 20 61 0a 73 69 6e 67 6c 65 20 5b 64 61 74 61 62   a.single [datab
73c0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3a  ase connection]:
73d0: 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74  </p>..<blockquot
73e0: 65 3e 3c 70 72 65 3e 0a 5b 73 71 6c 69 74 65 33  e><pre>.[sqlite3
73f0: 5f 64 62 5f 73 74 61 74 75 73 5d 28 64 62 2c 20  _db_status](db, 
7400: 5b 53 51 4c 49 54 45 5f 44 42 53 54 41 54 55 53  [SQLITE_DBSTATUS
7410: 5f 4c 4f 4f 4b 41 53 49 44 45 5f 55 53 45 44 7c  _LOOKASIDE_USED|
7420: 76 65 72 62 5d 2c 20 26 61 6d 70 3b 63 75 72 72  verb], &amp;curr
7430: 65 6e 74 2c 20 26 61 6d 70 3b 68 69 67 68 77 61  ent, &amp;highwa
7440: 74 65 72 2c 20 72 65 73 65 74 66 6c 61 67 29 3b  ter, resetflag);
7450: 0a 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75  .</pre></blockqu
7460: 6f 74 65 3e 0a 0a 3c 70 3e 54 68 69 73 20 69 6e  ote>..<p>This in
7470: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
7480: 61 72 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ar except that i
7490: 74 20 74 61 6b 65 73 20 61 20 70 6f 69 6e 74 65  t takes a pointe
74a0: 72 20 74 6f 0a 61 20 5b 64 61 74 61 62 61 73 65  r to.a [database
74b0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 73 20   connection] as 
74c0: 69 74 73 20 66 69 72 73 74 20 61 72 67 75 6d 65  its first argume
74d0: 6e 74 20 61 6e 64 20 72 65 74 75 72 6e 73 20 73  nt and returns s
74e0: 74 61 74 69 73 74 69 63 73 20 61 62 6f 75 74 0a  tatistics about.
74f0: 74 68 61 74 20 6f 6e 65 20 6f 62 6a 65 63 74 20  that one object 
7500: 72 61 74 68 65 72 20 74 68 61 6e 20 61 62 6f 75  rather than abou
7510: 74 20 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c  t the entire SQL
7520: 69 74 65 20 6c 69 62 72 61 72 79 2e 0a 54 68 65  ite library..The
7530: 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
7540: 74 75 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  tus()] interface
7550: 20 63 75 72 72 65 6e 74 6c 79 20 6f 6e 6c 79 20   currently only 
7560: 72 65 63 6f 67 6e 69 7a 65 73 20 61 0a 73 69 6e  recognizes a.sin
7570: 67 6c 65 20 76 65 72 62 20 5b 53 51 4c 49 54 45  gle verb [SQLITE
7580: 5f 44 42 53 54 41 54 55 53 5f 4c 4f 4f 4b 41 53  _DBSTATUS_LOOKAS
7590: 49 44 45 5f 55 53 45 44 5d 2c 20 74 68 6f 75 67  IDE_USED], thoug
75a0: 68 20 61 64 64 69 74 69 6f 6e 61 6c 20 76 65 72  h additional ver
75b0: 62 73 0a 6d 61 79 20 62 65 20 61 64 64 65 64 20  bs.may be added 
75c0: 69 6e 20 74 68 65 20 66 75 74 75 72 65 2e 3c 2f  in the future.</
75d0: 70 3e 0a 0a 3c 70 3e 54 68 65 20 70 65 72 2d 63  p>..<p>The per-c
75e0: 6f 6e 6e 65 63 74 69 6f 6e 20 73 74 61 74 69 73  onnection statis
75f0: 74 69 63 73 20 64 6f 20 6e 6f 74 20 75 73 65 20  tics do not use 
7600: 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73  global variables
7610: 20 61 6e 64 20 68 65 6e 63 65 0a 64 6f 20 6e 6f   and hence.do no
7620: 74 20 72 65 71 75 69 72 65 20 6d 75 74 65 78 65  t require mutexe
7630: 73 20 74 6f 20 75 70 64 61 74 65 20 6f 72 20 61  s to update or a
7640: 63 63 65 73 73 2e 20 20 43 6f 6e 73 65 71 75 65  ccess.  Conseque
7650: 6e 74 6c 79 20 74 68 65 0a 70 65 72 2d 63 6f 6e  ntly the.per-con
7660: 6e 65 63 74 69 6f 6e 20 73 74 61 74 69 73 74 69  nection statisti
7670: 63 73 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 66  cs continue to f
7680: 75 6e 63 74 69 6f 6e 20 65 76 65 6e 20 69 66 0a  unction even if.
7690: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
76a0: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 74 75 72  EMSTATUS] is tur
76b0: 6e 65 64 20 6f 66 66 2e 3c 2f 70 3e 0a 0a 3c 61  ned off.</p>..<a
76c0: 20 6e 61 6d 65 3d 22 68 65 61 70 6c 69 6d 69 74   name="heaplimit
76d0: 22 3e 3c 2f 61 3e 0a 3c 68 32 3e 20 53 65 74 74  "></a>.<h2> Sett
76e0: 69 6e 67 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  ing memory usage
76f0: 20 6c 69 6d 69 74 73 3c 2f 68 32 3e 0a 0a 3c 70   limits</h2>..<p
7700: 3e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f  >The [sqlite3_so
7710: 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
7720: 29 5d 20 69 6e 74 65 72 66 61 63 65 20 63 61 6e  )] interface can
7730: 20 62 65 20 75 73 65 64 20 74 6f 20 73 65 74 20   be used to set 
7740: 61 6e 0a 75 70 70 65 72 20 62 6f 75 6e 64 20 6f  an.upper bound o
7750: 6e 20 74 68 65 20 74 6f 74 61 6c 20 61 6d 6f 75  n the total amou
7760: 6e 74 20 6f 66 20 6f 75 74 73 74 61 6e 64 69 6e  nt of outstandin
7770: 67 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 74 68  g memory that th
7780: 65 0a 67 65 6e 65 72 61 6c 2d 70 75 72 70 6f 73  e.general-purpos
7790: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
77a0: 6f 72 20 66 6f 72 20 53 51 4c 69 74 65 20 77 69  or for SQLite wi
77b0: 6c 6c 20 61 6c 6c 6f 77 20 74 6f 20 62 65 20 6f  ll allow to be o
77c0: 75 74 73 74 61 6e 64 69 6e 67 0a 61 74 20 6f 6e  utstanding.at on
77d0: 65 20 74 69 6d 65 2e 20 20 49 66 20 61 74 74 65  e time.  If atte
77e0: 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
77f0: 20 61 6c 6c 6f 63 61 74 65 20 6d 6f 72 65 20 6d   allocate more m
7800: 65 6d 6f 72 79 20 74 68 61 6e 20 73 70 65 63 69  emory than speci
7810: 66 69 65 64 0a 62 79 20 74 68 65 20 73 6f 66 74  fied.by the soft
7820: 20 68 65 61 70 20 6c 69 6d 69 74 2c 20 74 68 65   heap limit, the
7830: 6e 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 66 69  n SQLite will fi
7840: 72 73 74 20 61 74 74 65 6d 70 74 20 74 6f 20 66  rst attempt to f
7850: 72 65 65 20 63 61 63 68 65 0a 6d 65 6d 6f 72 79  ree cache.memory
7860: 20 62 65 66 6f 72 65 20 63 6f 6e 74 69 6e 75 69   before continui
7870: 6e 67 20 77 69 74 68 20 74 68 65 20 61 6c 6c 6f  ng with the allo
7880: 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 2e 20  cation request. 
7890: 20 54 68 65 20 73 6f 66 74 20 68 65 61 70 0a 6c   The soft heap.l
78a0: 69 6d 69 74 20 6d 65 63 68 61 6e 69 73 6d 20 6f  imit mechanism o
78b0: 6e 6c 79 20 77 6f 72 6b 73 20 69 66 20 5b 6d 65  nly works if [me
78c0: 6d 6f 72 79 20 73 74 61 74 69 73 74 69 63 73 5d  mory statistics]
78d0: 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61 6e 64   are enabled and
78e0: 0a 69 74 20 77 6f 72 6b 73 20 62 65 73 74 0a 69  .it works best.i
78f0: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
7900: 72 61 72 79 20 69 73 20 63 6f 6d 70 69 6c 65 64  rary is compiled
7910: 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54   with the [SQLIT
7920: 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
7930: 4d 41 4e 41 47 45 4d 45 4e 54 5d 0a 63 6f 6d 70  MANAGEMENT].comp
7940: 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e  ile-time option.
7950: 3c 2f 70 3e 0a 0a 3c 70 3e 54 68 65 20 73 6f 66  </p>..<p>The sof
7960: 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73 20  t heap limit is 
7970: 22 73 6f 66 74 22 20 69 6e 20 74 68 69 73 20 73  "soft" in this s
7980: 65 6e 73 65 3a 20 20 49 66 20 53 51 4c 69 74 65  ense:  If SQLite
7990: 20 69 73 20 6e 6f 74 20 61 62 6c 65 0a 74 6f 20   is not able.to 
79a0: 66 72 65 65 20 75 70 20 65 6e 6f 75 67 68 20 61  free up enough a
79b0: 75 78 69 6c 69 61 72 79 20 6d 65 6d 6f 72 79 20  uxiliary memory 
79c0: 74 6f 20 73 74 61 79 20 62 65 6c 6f 77 20 74 68  to stay below th
79d0: 65 20 6c 69 6d 69 74 2c 20 69 74 20 67 6f 65 73  e limit, it goes
79e0: 0a 61 68 65 61 64 20 61 6e 64 20 61 6c 6c 6f 63  .ahead and alloc
79f0: 61 74 65 73 20 74 68 65 20 65 78 74 72 61 20 6d  ates the extra m
7a00: 65 6d 6f 72 79 20 61 6e 64 20 65 78 63 65 65 64  emory and exceed
7a10: 73 20 69 74 73 20 6c 69 6d 69 74 2e 20 20 54 68  s its limit.  Th
7a20: 69 73 20 6f 63 63 75 72 73 0a 75 6e 64 65 72 20  is occurs.under 
7a30: 74 68 65 20 74 68 65 6f 72 79 20 74 68 61 74 20  the theory that 
7a40: 69 74 20 69 73 20 62 65 74 74 65 72 20 74 6f 20  it is better to 
7a50: 75 73 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 6d  use additional m
7a60: 65 6d 6f 72 79 20 74 68 61 6e 20 74 6f 20 66 61  emory than to fa
7a70: 69 6c 0a 6f 75 74 72 69 67 68 74 2e 3c 2f 70 3e  il.outright.</p>
7a80: 0a 0a 3c 70 3e 41 73 20 6f 66 20 53 51 4c 69 74  ..<p>As of SQLit
7a90: 65 20 5b 76 65 72 73 69 6f 6e 20 33 2e 36 2e 31  e [version 3.6.1
7aa0: 5d 20 28 5b 64 61 74 65 6f 66 3a 33 2e 36 2e 31  ] ([dateof:3.6.1
7ab0: 5d 29 2c 20 0a 74 68 65 20 73 6f 66 74 20 68 65  ]), .the soft he
7ac0: 61 70 20 6c 69 6d 69 74 20 6f 6e 6c 79 20 61 70  ap limit only ap
7ad0: 70 6c 69 65 73 20 74 6f 20 74 68 65 0a 67 65 6e  plies to the.gen
7ae0: 65 72 61 6c 2d 70 75 72 70 6f 73 65 20 6d 65 6d  eral-purpose mem
7af0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20  ory allocator.  
7b00: 54 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69  The soft heap li
7b10: 6d 69 74 20 64 6f 65 73 20 6e 6f 74 20 6b 6e 6f  mit does not kno
7b20: 77 0a 61 62 6f 75 74 20 6f 72 20 69 6e 74 65 72  w.about or inter
7b30: 61 63 74 20 77 69 74 68 0a 74 68 65 20 5b 70 61  act with.the [pa
7b40: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
7b50: 6c 6c 6f 63 61 74 6f 72 5d 20 6f 72 20 74 68 65  llocator] or the
7b60: 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f   [lookaside memo
7b70: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 0a 54  ry allocator]..T
7b80: 68 69 73 20 64 65 66 69 63 69 65 6e 63 79 20 77  his deficiency w
7b90: 69 6c 6c 20 6c 69 6b 65 6c 79 20 62 65 20 61 64  ill likely be ad
7ba0: 64 72 65 73 73 65 64 20 69 6e 20 61 20 66 75 74  dressed in a fut
7bb0: 75 72 65 20 72 65 6c 65 61 73 65 2e 3c 2f 70 3e  ure release.</p>
7bc0: 0a 0a 3c 74 63 6c 3e 68 64 5f 66 72 61 67 6d 65  ..<tcl>hd_fragme
7bd0: 6e 74 20 6e 6f 66 72 61 67 20 7b 52 6f 62 73 6f  nt nofrag {Robso
7be0: 6e 20 70 72 6f 6f 66 7d 3c 2f 74 63 6c 3e 0a 3c  n proof}</tcl>.<
7bf0: 68 31 3e 20 4d 61 74 68 65 6d 61 74 69 63 61 6c  h1> Mathematical
7c00: 20 47 75 61 72 61 6e 74 65 65 73 20 41 67 61 69   Guarantees Agai
7c10: 6e 73 74 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63  nst Memory Alloc
7c20: 61 74 69 6f 6e 20 46 61 69 6c 75 72 65 73 3c 2f  ation Failures</
7c30: 68 31 3e 0a 0a 3c 70 3e 54 68 65 20 70 72 6f 62  h1>..<p>The prob
7c40: 6c 65 6d 20 6f 66 20 64 79 6e 61 6d 69 63 20 6d  lem of dynamic m
7c50: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
7c60: 2c 20 61 6e 64 20 73 70 65 63 69 66 69 63 61 6c  , and specifical
7c70: 6c 79 20 74 68 65 0a 70 72 6f 62 6c 65 6d 20 6f  ly the.problem o
7c80: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
7c90: 61 74 6f 72 20 62 72 65 61 6b 64 6f 77 6e 2c 20  ator breakdown, 
7ca0: 68 61 73 20 62 65 65 6e 20 73 74 75 64 69 65 64  has been studied
7cb0: 20 62 79 0a 4a 2e 20 4d 2e 20 52 6f 62 73 6f 6e   by.J. M. Robson
7cc0: 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c 74 73   and the results
7cd0: 20 70 75 62 6c 69 73 68 65 64 20 61 73 3a 3c 2f   published as:</
7ce0: 70 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  p>..<blockquote>
7cf0: 0a 4a 2e 20 4d 2e 20 52 6f 62 73 6f 6e 2e 20 20  .J. M. Robson.  
7d00: 22 42 6f 75 6e 64 73 20 66 6f 72 20 53 6f 6d 65  "Bounds for Some
7d10: 20 46 75 6e 63 74 69 6f 6e 73 20 43 6f 6e 63 65   Functions Conce
7d20: 72 6e 69 6e 67 20 44 79 6e 61 6d 69 63 0a 53 74  rning Dynamic.St
7d30: 6f 72 61 67 65 20 41 6c 6c 6f 63 61 74 69 6f 6e  orage Allocation
7d40: 22 2e 20 20 3c 69 3e 4a 6f 75 72 6e 61 6c 20 6f  ".  <i>Journal o
7d50: 66 20 74 68 65 20 41 73 73 6f 63 69 61 74 69 6f  f the Associatio
7d60: 6e 20 66 6f 72 0a 43 6f 6d 70 75 74 69 6e 67 20  n for.Computing 
7d70: 4d 61 63 68 69 6e 65 72 79 3c 2f 69 3e 2c 20 56  Machinery</i>, V
7d80: 6f 6c 75 6d 65 20 32 31 2c 20 4e 75 6d 62 65 72  olume 21, Number
7d90: 20 38 2c 20 4a 75 6c 79 20 31 39 37 34 2c 0a 70   8, July 1974,.p
7da0: 61 67 65 73 20 34 39 31 2d 34 39 39 2e 0a 3c 2f  ages 491-499..</
7db0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70 3e  blockquote>..<p>
7dc0: 4c 65 74 20 75 73 20 75 73 65 20 74 68 65 20 66  Let us use the f
7dd0: 6f 6c 6c 6f 77 69 6e 67 20 6e 6f 74 61 74 69 6f  ollowing notatio
7de0: 6e 20 28 73 69 6d 69 6c 61 72 20 62 75 74 20 6e  n (similar but n
7df0: 6f 74 20 69 64 65 6e 74 69 63 61 6c 20 74 6f 0a  ot identical to.
7e00: 52 6f 62 73 6f 6e 27 73 20 6e 6f 74 61 74 69 6f  Robson's notatio
7e10: 6e 29 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63 6b 71  n):</p>..<blockq
7e20: 75 6f 74 65 3e 0a 3c 74 61 62 6c 65 20 63 65 6c  uote>.<table cel
7e30: 6c 70 61 64 64 69 6e 67 3d 22 31 30 22 20 62 6f  lpadding="10" bo
7e40: 72 64 65 72 3d 22 30 22 3e 0a 3c 74 72 3e 3c 74  rder="0">.<tr><t
7e50: 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 3c  d valign="top"><
7e60: 62 3e 4e 3c 2f 62 3e 3c 2f 74 64 3e 0a 3c 74 64  b>N</b></td>.<td
7e70: 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a 54   valign="top">.T
7e80: 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 72 61 77  he amount of raw
7e90: 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 20 62   memory needed b
7ea0: 79 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  y the memory all
7eb0: 6f 63 61 74 69 6f 6e 20 73 79 73 74 65 6d 0a 69  ocation system.i
7ec0: 6e 20 6f 72 64 65 72 20 74 6f 20 67 75 61 72 61  n order to guara
7ed0: 6e 74 65 65 20 74 68 61 74 20 6e 6f 20 6d 65 6d  ntee that no mem
7ee0: 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 77  ory allocation w
7ef0: 69 6c 6c 20 65 76 65 72 20 66 61 69 6c 2e 0a 3c  ill ever fail..<
7f00: 2f 74 64 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74  /td></tr>.<tr><t
7f10: 64 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 3c  d valign="top"><
7f20: 62 3e 4d 3c 2f 62 3e 3c 2f 74 64 3e 0a 3c 74 64  b>M</b></td>.<td
7f30: 20 76 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a 54   valign="top">.T
7f40: 68 65 20 6d 61 78 69 6d 75 6d 20 61 6d 6f 75 6e  he maximum amoun
7f50: 74 20 6f 66 20 6d 65 6d 6f 72 79 20 74 68 61 74  t of memory that
7f60: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
7f70: 20 65 76 65 72 20 68 61 73 20 63 68 65 63 6b 65   ever has checke
7f80: 64 20 6f 75 74 0a 61 74 20 61 6e 79 20 70 6f 69  d out.at any poi
7f90: 6e 74 20 69 6e 20 74 69 6d 65 2e 0a 3c 2f 74 64  nt in time..</td
7fa0: 3e 3c 2f 74 72 3e 0a 3c 74 72 3e 3c 74 64 20 76  ></tr>.<tr><td v
7fb0: 61 6c 69 67 6e 3d 22 74 6f 70 22 3e 3c 62 3e 6e  align="top"><b>n
7fc0: 3c 2f 62 3e 3c 2f 74 64 3e 0a 3c 74 64 20 76 61  </b></td>.<td va
7fd0: 6c 69 67 6e 3d 22 74 6f 70 22 3e 0a 54 68 65 20  lign="top">.The 
7fe0: 72 61 74 69 6f 20 6f 66 20 74 68 65 20 6c 61 72  ratio of the lar
7ff0: 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  gest memory allo
8000: 63 61 74 69 6f 6e 20 74 6f 20 74 68 65 20 73 6d  cation to the sm
8010: 61 6c 6c 65 73 74 2e 20 20 57 65 20 61 73 73 75  allest.  We assu
8020: 6d 65 0a 74 68 61 74 20 65 76 65 72 79 20 6d 65  me.that every me
8030: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
8040: 73 69 7a 65 20 69 73 20 61 6e 20 69 6e 74 65 67  size is an integ
8050: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 74  er multiple of t
8060: 68 65 20 73 6d 61 6c 6c 65 73 74 20 6d 65 6d 6f  he smallest memo
8070: 72 79 0a 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  ry.allocation si
8080: 7a 65 2e 0a 3c 2f 74 64 3e 3c 2f 74 72 3e 0a 3c  ze..</td></tr>.<
8090: 2f 74 61 62 6c 65 3e 0a 3c 2f 62 6c 6f 63 6b 71  /table>.</blockq
80a0: 75 6f 74 65 3e 0a 0a 3c 70 3e 52 6f 62 73 6f 6e  uote>..<p>Robson
80b0: 20 70 72 6f 76 65 73 20 74 68 65 20 66 6f 6c 6c   proves the foll
80c0: 6f 77 69 6e 67 20 72 65 73 75 6c 74 3a 3c 2f 70  owing result:</p
80d0: 3e 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  >..<blockquote>.
80e0: 3c 62 3e 4e 3c 2f 62 3e 20 3d 20 3c 62 3e 4d 3c  <b>N</b> = <b>M<
80f0: 2f 62 3e 2a 28 31 20 2b 20 28 6c 6f 67 3c 73 75  /b>*(1 + (log<su
8100: 62 3e 32 3c 2f 73 75 62 3e 20 3c 62 3e 6e 3c 2f  b>2</sub> <b>n</
8110: 62 3e 29 2f 32 29 20 2d 20 3c 62 3e 6e 3c 2f 62  b>)/2) - <b>n</b
8120: 3e 20 2b 20 31 0a 3c 2f 62 6c 6f 63 6b 71 75 6f  > + 1.</blockquo
8130: 74 65 3e 0a 0a 3c 70 3e 43 6f 6c 6c 6f 71 75 69  te>..<p>Colloqui
8140: 61 6c 6c 79 2c 20 74 68 65 20 52 6f 62 73 6f 6e  ally, the Robson
8150: 20 70 72 6f 6f 66 20 73 68 6f 77 73 20 74 68 61   proof shows tha
8160: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 67 75  t in order to gu
8170: 61 72 61 6e 74 65 65 0a 62 72 65 61 6b 64 6f 77  arantee.breakdow
8180: 6e 2d 66 72 65 65 20 6f 70 65 72 61 74 69 6f 6e  n-free operation
8190: 2c 20 61 6e 79 20 6d 65 6d 6f 72 79 20 61 6c 6c  , any memory all
81a0: 6f 63 61 74 6f 72 20 6d 75 73 74 20 75 73 65 20  ocator must use 
81b0: 61 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 6f 66  a memory pool.of
81c0: 20 73 69 7a 65 20 3c 62 3e 4e 3c 2f 62 3e 20 77   size <b>N</b> w
81d0: 68 69 63 68 20 65 78 63 65 65 64 73 20 74 68 65  hich exceeds the
81e0: 20 6d 61 78 69 6d 75 6d 20 61 6d 6f 75 6e 74 20   maximum amount 
81f0: 6f 66 20 6d 65 6d 6f 72 79 20 65 76 65 72 0a 75  of memory ever.u
8200: 73 65 64 20 3c 62 3e 4d 3c 2f 62 3e 20 62 79 20  sed <b>M</b> by 
8210: 61 20 6d 75 6c 74 69 70 6c 69 65 72 20 74 68 61  a multiplier tha
8220: 74 20 64 65 70 65 6e 64 73 20 6f 6e 20 3c 62 3e  t depends on <b>
8230: 6e 3c 2f 62 3e 2c 20 0a 74 68 65 20 72 61 74 69  n</b>, .the rati
8240: 6f 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  o of the largest
8250: 20 74 6f 20 74 68 65 20 73 6d 61 6c 6c 65 73 74   to the smallest
8260: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
8270: 2e 20 20 49 6e 20 6f 74 68 65 72 0a 77 6f 72 64  .  In other.word
8280: 73 2c 20 75 6e 6c 65 73 73 20 61 6c 6c 20 6d 65  s, unless all me
8290: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
82a0: 20 61 72 65 20 6f 66 20 65 78 61 63 74 6c 79 20   are of exactly 
82b0: 74 68 65 20 73 61 6d 65 20 73 69 7a 65 0a 28 3c  the same size.(<
82c0: 62 3e 6e 3c 2f 62 3e 3d 31 29 20 74 68 65 6e 20  b>n</b>=1) then 
82d0: 74 68 65 20 73 79 73 74 65 6d 20 6e 65 65 64 73  the system needs
82e0: 20 61 63 63 65 73 73 20 74 6f 20 6d 6f 72 65 20   access to more 
82f0: 6d 65 6d 6f 72 79 20 74 68 61 6e 20 69 74 20 77  memory than it w
8300: 69 6c 6c 0a 65 76 65 72 20 75 73 65 20 61 74 20  ill.ever use at 
8310: 6f 6e 65 20 74 69 6d 65 2e 20 20 46 75 72 74 68  one time.  Furth
8320: 65 72 6d 6f 72 65 2c 20 77 65 20 73 65 65 20 74  ermore, we see t
8330: 68 61 74 20 74 68 65 20 61 6d 6f 75 6e 74 20 6f  hat the amount o
8340: 66 20 73 75 72 70 6c 75 73 0a 6d 65 6d 6f 72 79  f surplus.memory
8350: 20 72 65 71 75 69 72 65 64 20 67 72 6f 77 73 20   required grows 
8360: 72 61 70 69 64 6c 79 20 61 73 20 74 68 65 20 72  rapidly as the r
8370: 61 74 69 6f 20 6f 66 20 6c 61 72 67 65 73 74 20  atio of largest 
8380: 74 6f 20 73 6d 61 6c 6c 65 73 74 0a 61 6c 6c 6f  to smallest.allo
8390: 63 61 74 69 6f 6e 73 20 69 6e 63 72 65 61 73 65  cations increase
83a0: 73 2c 20 61 6e 64 20 73 6f 20 74 68 65 72 65 20  s, and so there 
83b0: 69 73 20 73 74 72 6f 6e 67 20 69 6e 63 65 6e 74  is strong incent
83c0: 69 76 65 20 74 6f 20 6b 65 65 70 20 61 6c 6c 0a  ive to keep all.
83d0: 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 73 20 6e  allocations as n
83e0: 65 61 72 20 74 6f 20 74 68 65 20 73 61 6d 65 20  ear to the same 
83f0: 73 69 7a 65 20 61 73 20 70 6f 73 73 69 62 6c 65  size as possible
8400: 2e 3c 2f 70 3e 0a 0a 3c 70 3e 52 6f 62 73 6f 6e  .</p>..<p>Robson
8410: 27 73 20 70 72 6f 6f 66 20 69 73 20 63 6f 6e 73  's proof is cons
8420: 74 72 75 63 74 69 76 65 2e 20 0a 48 65 20 70 72  tructive. .He pr
8430: 6f 76 69 64 65 73 20 61 6e 20 61 6c 67 6f 72 69  ovides an algori
8440: 74 68 6d 20 66 6f 72 20 63 6f 6d 70 75 74 69 6e  thm for computin
8450: 67 20 61 20 73 65 71 75 65 6e 63 65 20 6f 66 20  g a sequence of 
8460: 61 6c 6c 6f 63 61 74 69 6f 6e 0a 61 6e 64 20 64  allocation.and d
8470: 65 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 70 65 72  eallocation oper
8480: 61 74 69 6f 6e 73 20 74 68 61 74 20 77 69 6c 6c  ations that will
8490: 20 6c 65 61 64 20 74 6f 20 61 6e 20 61 6c 6c 6f   lead to an allo
84a0: 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 64  cation failure d
84b0: 75 65 20 74 6f 0a 6d 65 6d 6f 72 79 20 66 72 61  ue to.memory fra
84c0: 67 6d 65 6e 74 61 74 69 6f 6e 20 69 66 20 61 76  gmentation if av
84d0: 61 69 6c 61 62 6c 65 20 6d 65 6d 6f 72 79 20 69  ailable memory i
84e0: 73 20 61 73 20 6d 75 63 68 20 61 73 20 6f 6e 65  s as much as one
84f0: 20 62 79 74 65 0a 6c 65 73 73 20 74 68 61 6e 20   byte.less than 
8500: 3c 62 3e 4e 3c 2f 62 3e 2e 0a 41 6e 64 2c 20 52  <b>N</b>..And, R
8510: 6f 62 73 6f 6e 20 73 68 6f 77 73 20 74 68 61 74  obson shows that
8520: 20 61 20 70 6f 77 65 72 2d 6f 66 2d 74 77 6f 20   a power-of-two 
8530: 66 69 72 73 74 2d 66 69 74 20 6d 65 6d 6f 72 79  first-fit memory
8540: 20 61 6c 6c 6f 63 61 74 6f 72 0a 28 73 75 63 68   allocator.(such
8550: 20 61 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20   as implemented 
8560: 62 79 20 5b 6d 65 6d 73 79 73 35 5d 29 20 77 69  by [memsys5]) wi
8570: 6c 6c 20 6e 65 76 65 72 20 66 61 69 6c 20 61 20  ll never fail a 
8580: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
8590: 6e 0a 70 72 6f 76 69 64 65 64 20 74 68 61 74 20  n.provided that 
85a0: 61 76 61 69 6c 61 62 6c 65 20 6d 65 6d 6f 72 79  available memory
85b0: 20 69 73 20 3c 62 3e 4e 3c 2f 62 3e 20 6f 72 20   is <b>N</b> or 
85c0: 6d 6f 72 65 20 62 79 74 65 73 2e 3c 2f 70 3e 0a  more bytes.</p>.
85d0: 0a 3c 70 3e 54 68 65 20 76 61 6c 75 65 73 20 3c  .<p>The values <
85e0: 62 3e 4d 3c 2f 62 3e 20 61 6e 64 20 3c 62 3e 6e  b>M</b> and <b>n
85f0: 3c 2f 62 3e 20 61 72 65 20 70 72 6f 70 65 72 74  </b> are propert
8600: 69 65 73 20 6f 66 20 74 68 65 20 61 70 70 6c 69  ies of the appli
8610: 63 61 74 69 6f 6e 2e 0a 49 66 20 61 6e 20 61 70  cation..If an ap
8620: 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 63 6f 6e  plication is con
8630: 73 74 72 75 63 74 65 64 20 69 6e 20 73 75 63 68  structed in such
8640: 20 61 20 77 61 79 20 74 68 61 74 20 62 6f 74 68   a way that both
8650: 20 3c 62 3e 4d 3c 2f 62 3e 20 61 6e 64 0a 3c 62   <b>M</b> and.<b
8660: 3e 6e 3c 2f 62 3e 20 61 72 65 20 6b 6e 6f 77 6e  >n</b> are known
8670: 2c 20 6f 72 20 61 74 20 6c 65 61 73 74 20 68 61  , or at least ha
8680: 76 65 20 6b 6e 6f 77 6e 20 75 70 70 65 72 20 62  ve known upper b
8690: 6f 75 6e 64 73 2c 20 61 6e 64 20 69 66 20 74 68  ounds, and if th
86a0: 65 0a 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  e.application us
86b0: 65 73 0a 74 68 65 20 5b 6d 65 6d 73 79 73 35 5d  es.the [memsys5]
86c0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
86d0: 72 20 61 6e 64 20 69 73 20 70 72 6f 76 69 64 65  r and is provide
86e0: 64 20 77 69 74 68 20 3c 62 3e 4e 3c 2f 62 3e 20  d with <b>N</b> 
86f0: 62 79 74 65 73 20 6f 66 0a 61 76 61 69 6c 61 62  bytes of.availab
8700: 6c 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65 20  le memory space 
8710: 75 73 69 6e 67 20 5b 53 51 4c 49 54 45 5f 43 4f  using [SQLITE_CO
8720: 4e 46 49 47 5f 48 45 41 50 5d 0a 74 68 65 6e 20  NFIG_HEAP].then 
8730: 52 6f 62 73 6f 6e 20 70 72 6f 76 65 73 20 74 68  Robson proves th
8740: 61 74 20 6e 6f 20 6d 65 6d 6f 72 79 20 61 6c 6c  at no memory all
8750: 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20  ocation request 
8760: 77 69 6c 6c 20 65 76 65 72 20 66 61 69 6c 0a 77  will ever fail.w
8770: 69 74 68 69 6e 20 74 68 65 20 61 70 70 6c 69 63  ithin the applic
8780: 61 74 69 6f 6e 2e 0a 54 6f 20 70 75 74 20 74 68  ation..To put th
8790: 69 73 20 61 6e 6f 74 68 65 72 20 77 61 79 2c 20  is another way, 
87a0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
87b0: 64 65 76 65 6c 6f 70 65 72 20 63 61 6e 20 73 65  developer can se
87c0: 6c 65 63 74 20 61 20 76 61 6c 75 65 0a 66 6f 72  lect a value.for
87d0: 20 3c 62 3e 4e 3c 2f 62 3e 20 74 68 61 74 20 77   <b>N</b> that w
87e0: 69 6c 6c 20 67 75 61 72 61 6e 74 65 65 20 74 68  ill guarantee th
87f0: 61 74 20 6e 6f 20 63 61 6c 6c 20 74 6f 20 61 6e  at no call to an
8800: 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
8810: 63 65 0a 77 69 6c 6c 20 65 76 65 72 20 72 65 74  ce.will ever ret
8820: 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  urn [SQLITE_NOME
8830: 4d 5d 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  M].  The memory 
8840: 70 6f 6f 6c 20 77 69 6c 6c 20 6e 65 76 65 72 20  pool will never 
8850: 62 65 63 6f 6d 65 0a 73 6f 20 66 72 61 67 6d 65  become.so fragme
8860: 6e 74 65 64 20 74 68 61 74 20 61 20 6e 65 77 20  nted that a new 
8870: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
8880: 6e 20 72 65 71 75 65 73 74 20 63 61 6e 6e 6f 74  n request cannot
8890: 20 62 65 20 73 61 74 69 73 66 69 65 64 2e 0a 54   be satisfied..T
88a0: 68 69 73 20 69 73 20 61 6e 20 69 6d 70 6f 72 74  his is an import
88b0: 61 6e 74 20 70 72 6f 70 65 72 74 79 20 66 6f 72  ant property for
88c0: 0a 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 68  .applications wh
88d0: 65 72 65 20 61 20 73 6f 66 74 77 61 72 65 20 66  ere a software f
88e0: 61 75 6c 74 20 63 6f 75 6c 64 20 63 61 75 73 65  ault could cause
88f0: 20 69 6e 6a 75 72 79 2c 20 70 68 79 73 69 63 61   injury, physica
8900: 6c 20 68 61 72 6d 2c 20 6f 72 0a 6c 6f 73 73 20  l harm, or.loss 
8910: 6f 66 20 69 72 72 65 70 6c 61 63 65 61 62 6c 65  of irreplaceable
8920: 20 64 61 74 61 2e 3c 2f 70 3e 0a 0a 3c 68 32 3e   data.</p>..<h2>
8930: 20 43 6f 6d 70 75 74 69 6e 67 20 61 6e 64 20 63   Computing and c
8940: 6f 6e 74 72 6f 6c 6c 69 6e 67 20 70 61 72 61 6d  ontrolling param
8950: 65 74 65 72 73 20 3c 62 3e 4d 3c 2f 62 3e 20 61  eters <b>M</b> a
8960: 6e 64 20 3c 62 3e 6e 3c 2f 62 3e 3c 2f 68 32 3e  nd <b>n</b></h2>
8970: 0a 0a 3c 70 3e 54 68 65 20 52 6f 62 73 6f 6e 20  ..<p>The Robson 
8980: 70 72 6f 6f 66 20 61 70 70 6c 69 65 73 20 73 65  proof applies se
8990: 70 61 72 61 74 65 6c 79 20 74 6f 20 65 61 63 68  parately to each
89a0: 20 6f 66 20 74 68 65 20 6d 65 6d 6f 72 79 20 61   of the memory a
89b0: 6c 6c 6f 63 61 74 6f 72 73 0a 75 73 65 64 20 62  llocators.used b
89c0: 79 20 53 51 4c 69 74 65 3a 3c 2f 70 3e 0a 0a 3c  y SQLite:</p>..<
89d0: 75 6c 3e 0a 3c 6c 69 3e 54 68 65 20 67 65 6e 65  ul>.<li>The gene
89e0: 72 61 6c 2d 70 75 72 70 6f 73 65 20 6d 65 6d 6f  ral-purpose memo
89f0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 5b 6d  ry allocator ([m
8a00: 65 6d 73 79 73 35 5d 29 2e 3c 2f 6c 69 3e 0a 3c  emsys5]).</li>.<
8a10: 6c 69 3e 54 68 65 20 5b 70 61 67 65 63 61 63 68  li>The [pagecach
8a20: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
8a30: 6f 72 5d 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 54 68  or].</li>.<li>Th
8a40: 65 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  e [lookaside mem
8a50: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 2e 3c  ory allocator].<
8a60: 2f 6c 69 3e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 46  /li>.</ul>..<p>F
8a70: 6f 72 20 61 6c 6c 6f 63 61 74 6f 72 73 20 6f 74  or allocators ot
8a80: 68 65 72 20 74 68 61 6e 20 5b 6d 65 6d 73 79 73  her than [memsys
8a90: 35 5d 2c 0a 61 6c 6c 20 6d 65 6d 6f 72 79 20 61  5],.all memory a
8aa0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 72 65 20 6f  llocations are o
8ab0: 66 20 74 68 65 20 73 61 6d 65 20 73 69 7a 65 2e  f the same size.
8ac0: 20 20 48 65 6e 63 65 2c 20 3c 62 3e 6e 3c 2f 62    Hence, <b>n</b
8ad0: 3e 3d 31 0a 61 6e 64 20 74 68 65 72 65 66 6f 72  >=1.and therefor
8ae0: 65 20 3c 62 3e 4e 3c 2f 62 3e 3d 3c 62 3e 4d 3c  e <b>N</b>=<b>M<
8af0: 2f 62 3e 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  /b>.  In other w
8b00: 6f 72 64 73 2c 20 74 68 65 20 6d 65 6d 6f 72 79  ords, the memory
8b10: 20 70 6f 6f 6c 20 6e 65 65 64 0a 62 65 20 6e 6f   pool need.be no
8b20: 20 6c 61 72 67 65 72 20 74 68 61 6e 20 74 68 65   larger than the
8b30: 20 6c 61 72 67 65 73 74 20 61 6d 6f 75 6e 74 20   largest amount 
8b40: 6f 66 20 6d 65 6d 6f 72 79 20 69 6e 20 75 73 65  of memory in use
8b50: 20 61 74 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f   at any given mo
8b60: 6d 65 6e 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 54 68  ment.</p>..<p>Th
8b70: 65 20 75 73 61 67 65 20 6f 66 20 70 61 67 65 63  e usage of pagec
8b80: 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 73  ache memory is s
8b90: 6f 6d 65 77 68 61 74 20 68 61 72 64 65 72 20 74  omewhat harder t
8ba0: 6f 20 63 6f 6e 74 72 6f 6c 20 69 6e 0a 53 51 4c  o control in.SQL
8bb0: 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 36 2e  ite version 3.6.
8bc0: 31 2c 20 74 68 6f 75 67 68 20 6d 65 63 68 61 6e  1, though mechan
8bd0: 69 73 6d 73 20 61 72 65 20 70 6c 61 6e 6e 65 64  isms are planned
8be0: 20 66 6f 72 20 73 75 62 73 65 71 75 65 6e 74 0a   for subsequent.
8bf0: 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 77 69  releases that wi
8c00: 6c 6c 20 6d 61 6b 65 20 63 6f 6e 74 72 6f 6c 6c  ll make controll
8c10: 69 6e 67 20 70 61 67 65 63 61 63 68 65 20 6d 65  ing pagecache me
8c20: 6d 6f 72 79 20 6d 75 63 68 20 65 61 73 69 65 72  mory much easier
8c30: 2e 0a 50 72 69 6f 72 20 74 6f 20 74 68 65 20 69  ..Prior to the i
8c40: 6e 74 72 6f 64 75 63 74 69 6f 6e 20 6f 66 20 74  ntroduction of t
8c50: 68 65 73 65 20 6e 65 77 20 6d 65 63 68 61 6e 69  hese new mechani
8c60: 73 6d 73 2c 20 74 68 65 20 6f 6e 6c 79 20 77 61  sms, the only wa
8c70: 79 0a 74 6f 20 63 6f 6e 74 72 6f 6c 20 70 61 67  y.to control pag
8c80: 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69 73  ecache memory is
8c90: 20 75 73 69 6e 67 20 74 68 65 20 5b 63 61 63 68   using the [cach
8ca0: 65 5f 73 69 7a 65 20 70 72 61 67 6d 61 5d 2e 3c  e_size pragma].<
8cb0: 2f 70 3e 0a 0a 3c 70 3e 53 61 66 65 74 79 2d 63  /p>..<p>Safety-c
8cc0: 72 69 74 69 63 61 6c 20 61 70 70 6c 69 63 61 74  ritical applicat
8cd0: 69 6f 6e 73 20 77 69 6c 6c 20 75 73 75 61 6c 6c  ions will usuall
8ce0: 79 20 77 61 6e 74 20 74 6f 20 6d 6f 64 69 66 79  y want to modify
8cf0: 20 74 68 65 0a 64 65 66 61 75 6c 74 20 6c 6f 6f   the.default loo
8d00: 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f  kaside memory co
8d10: 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 6f 20 74  nfiguration so t
8d20: 68 61 74 20 77 68 65 6e 20 74 68 65 20 69 6e 69  hat when the ini
8d30: 74 69 61 6c 0a 6c 6f 6f 6b 61 73 69 64 65 20 6d  tial.lookaside m
8d40: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 69 73 20  emory buffer is 
8d50: 61 6c 6c 6f 63 61 74 65 64 20 64 75 72 69 6e 67  allocated during
8d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29   [sqlite3_open()
8d70: 5d 20 74 68 65 0a 72 65 73 75 6c 74 69 6e 67 20  ] the.resulting 
8d80: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
8d90: 6e 20 69 73 20 6e 6f 74 20 73 6f 20 6c 61 72 67  n is not so larg
8da0: 65 20 61 73 20 74 6f 20 66 6f 72 63 65 20 74 68  e as to force th
8db0: 65 20 3c 62 3e 6e 3c 2f 62 3e 0a 70 61 72 61 6d  e <b>n</b>.param
8dc0: 65 74 65 72 20 74 6f 20 62 65 20 74 6f 6f 20 6c  eter to be too l
8dd0: 61 72 67 65 2e 20 20 49 6e 20 6f 72 64 65 72 20  arge.  In order 
8de0: 74 6f 20 6b 65 65 70 20 3c 62 3e 6e 3c 2f 62 3e  to keep <b>n</b>
8df0: 20 75 6e 64 65 72 20 63 6f 6e 74 72 6f 6c 2c 0a   under control,.
8e00: 69 74 20 69 73 20 62 65 73 74 20 74 6f 20 74 72  it is best to tr
8e10: 79 20 74 6f 20 6b 65 65 70 20 74 68 65 20 6c 61  y to keep the la
8e20: 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61 6c 6c  rgest memory all
8e30: 6f 63 61 74 69 6f 6e 20 62 65 6c 6f 77 20 32 20  ocation below 2 
8e40: 6f 72 20 34 0a 6b 69 6c 6f 62 79 74 65 73 2e 20  or 4.kilobytes. 
8e50: 20 48 65 6e 63 65 2c 20 61 20 72 65 61 73 6f 6e   Hence, a reason
8e60: 61 62 6c 65 20 64 65 66 61 75 6c 74 20 73 65 74  able default set
8e70: 75 70 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61  up for the looka
8e80: 73 69 64 65 0a 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side.memory allo
8e90: 63 61 74 6f 72 20 6d 69 67 68 74 20 61 6e 79 20  cator might any 
8ea0: 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f  one of the follo
8eb0: 77 69 6e 67 3a 3c 2f 70 3e 0a 0a 3c 62 6c 6f 63  wing:</p>..<bloc
8ec0: 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 73 71 6c  kquote><pre>.sql
8ed0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 53 51 4c 49  ite3_config(SQLI
8ee0: 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
8ef0: 49 44 45 2c 20 33 32 2c 20 33 32 29 3b 20 20 2f  IDE, 32, 32);  /
8f00: 2a 20 31 4b 20 2a 2f 0a 73 71 6c 69 74 65 33 5f  * 1K */.sqlite3_
8f10: 63 6f 6e 66 69 67 28 53 51 4c 49 54 45 5f 43 4f  config(SQLITE_CO
8f20: 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 2c 20  NFIG_LOOKASIDE, 
8f30: 36 34 2c 20 33 32 29 3b 20 20 2f 2a 20 32 4b 20  64, 32);  /* 2K 
8f40: 2a 2f 0a 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  */.sqlite3_confi
8f50: 67 28 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  g(SQLITE_CONFIG_
8f60: 4c 4f 4f 4b 41 53 49 44 45 2c 20 33 32 2c 20 36  LOOKASIDE, 32, 6
8f70: 34 29 3b 20 20 2f 2a 20 32 4b 20 2a 2f 0a 73 71  4);  /* 2K */.sq
8f80: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 53 51 4c  lite3_config(SQL
8f90: 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
8fa0: 53 49 44 45 2c 20 36 34 2c 20 36 34 29 3b 20 20  SIDE, 64, 64);  
8fb0: 2f 2a 20 34 4b 20 2a 2f 0a 3c 2f 70 72 65 3e 3c  /* 4K */.</pre><
8fc0: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
8fd0: 3e 41 6e 6f 74 68 65 72 20 61 70 70 72 6f 61 63  >Another approac
8fe0: 68 20 69 73 20 74 6f 20 69 6e 69 74 69 61 6c 6c  h is to initiall
8ff0: 79 20 64 69 73 61 62 6c 65 20 74 68 65 20 6c 6f  y disable the lo
9000: 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a 61  okaside memory.a
9010: 6c 6c 6f 63 61 74 6f 72 3a 3c 2f 70 3e 0a 0a 3c  llocator:</p>..<
9020: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
9030: 0a 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  .sqlite3_config(
9040: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
9050: 4f 4b 41 53 49 44 45 2c 20 30 2c 20 30 29 3b 0a  OKASIDE, 0, 0);.
9060: 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
9070: 74 65 3e 0a 0a 3c 70 3e 54 68 65 6e 20 6c 65 74  te>..<p>Then let
9080: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
9090: 20 6d 61 69 6e 74 61 69 6e 20 61 20 73 65 70 61   maintain a sepa
90a0: 72 61 74 65 20 70 6f 6f 6c 20 6f 66 20 6c 61 72  rate pool of lar
90b0: 67 65 72 0a 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ger.lookaside me
90c0: 6d 6f 72 79 20 62 75 66 66 65 72 73 20 74 68 61  mory buffers tha
90d0: 74 20 69 74 20 63 61 6e 20 64 69 73 74 72 69 62  t it can distrib
90e0: 75 74 65 20 74 6f 20 5b 64 61 74 61 62 61 73 65  ute to [database
90f0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 61 73   connections].as
9100: 20 74 68 65 79 20 61 72 65 20 63 72 65 61 74 65   they are create
9110: 64 2e 20 20 49 6e 20 74 68 65 20 63 6f 6d 6d 6f  d.  In the commo
9120: 6e 20 63 61 73 65 2c 20 74 68 65 20 61 70 70 6c  n case, the appl
9130: 69 63 61 74 69 6f 6e 20 77 69 6c 6c 20 6f 6e 6c  ication will onl
9140: 79 0a 68 61 76 65 20 61 20 73 69 6e 67 6c 65 20  y.have a single 
9150: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
9160: 74 69 6f 6e 5d 20 61 6e 64 20 73 6f 20 74 68 65  tion] and so the
9170: 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
9180: 79 20 70 6f 6f 6c 0a 63 61 6e 20 63 6f 6e 73 69  y pool.can consi
9190: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 6c  st of a single l
91a0: 61 72 67 65 20 62 75 66 66 65 72 2e 3c 2f 70 3e  arge buffer.</p>
91b0: 0a 0a 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  ..<blockquote><p
91c0: 72 65 3e 0a 73 71 6c 69 74 65 33 5f 64 62 5f 63  re>.sqlite3_db_c
91d0: 6f 6e 66 69 67 28 64 62 2c 20 53 51 4c 49 54 45  onfig(db, SQLITE
91e0: 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
91f0: 49 44 45 2c 20 61 53 74 61 74 69 63 2c 20 32 35  IDE, aStatic, 25
9200: 36 2c 20 35 30 30 29 3b 0a 3c 2f 70 72 65 3e 3c  6, 500);.</pre><
9210: 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 0a 3c 70  /blockquote>..<p
9220: 3e 54 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d  >The lookaside m
9230: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
9240: 69 73 20 72 65 61 6c 6c 79 20 69 6e 74 65 6e 64  is really intend
9250: 65 64 20 61 73 20 70 65 72 66 6f 72 6d 61 6e 63  ed as performanc
9260: 65 0a 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 2c 20  e.optimization, 
9270: 6e 6f 74 20 61 73 20 61 20 6d 65 74 68 6f 64 20  not as a method 
9280: 66 6f 72 20 61 73 73 75 72 69 6e 67 20 62 72 65  for assuring bre
9290: 61 6b 64 6f 77 6e 2d 66 72 65 65 20 6d 65 6d 6f  akdown-free memo
92a0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 0a 73  ry allocation,.s
92b0: 6f 20 69 74 20 69 73 20 6e 6f 74 20 75 6e 72 65  o it is not unre
92c0: 61 73 6f 6e 61 62 6c 65 20 74 6f 20 63 6f 6d 70  asonable to comp
92d0: 6c 65 74 65 6c 79 20 64 69 73 61 62 6c 65 20 74  letely disable t
92e0: 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
92f0: 6f 72 79 0a 61 6c 6c 6f 63 61 74 6f 72 20 66 6f  ory.allocator fo
9300: 72 20 73 61 66 65 74 79 2d 63 72 69 74 69 63 61  r safety-critica
9310: 6c 20 6f 70 65 72 61 74 69 6f 6e 73 2e 3c 2f 70  l operations.</p
9320: 3e 0a 0a 3c 70 3e 54 68 65 20 67 65 6e 65 72 61  >..<p>The genera
9330: 6c 20 70 75 72 70 6f 73 65 20 6d 65 6d 6f 72 79  l purpose memory
9340: 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 74 68   allocator is th
9350: 65 20 6d 6f 73 74 20 64 69 66 66 69 63 75 6c 74  e most difficult
9360: 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 0a 74 6f 20   memory pool.to 
9370: 6d 61 6e 61 67 65 20 62 65 63 61 75 73 65 20 69  manage because i
9380: 74 20 73 75 70 70 6f 72 74 73 20 61 6c 6c 6f 63  t supports alloc
9390: 61 74 69 6f 6e 73 20 6f 66 20 76 61 72 79 69 6e  ations of varyin
93a0: 67 20 73 69 7a 65 73 2e 20 20 53 69 6e 63 65 20  g sizes.  Since 
93b0: 0a 3c 62 3e 6e 3c 2f 62 3e 20 69 73 20 61 20 6d  .<b>n</b> is a m
93c0: 75 6c 74 69 70 6c 69 65 72 20 6f 6e 20 3c 62 3e  ultiplier on <b>
93d0: 4d 3c 2f 62 3e 20 77 65 20 77 61 6e 74 20 74 6f  M</b> we want to
93e0: 20 6b 65 65 70 20 3c 62 3e 6e 3c 2f 62 3e 20 61   keep <b>n</b> a
93f0: 73 20 73 6d 61 6c 6c 0a 61 73 20 70 6f 73 73 69  s small.as possi
9400: 62 6c 65 2e 20 20 54 68 69 73 20 61 72 67 75 65  ble.  This argue
9410: 73 20 66 6f 72 20 6b 65 65 70 69 6e 67 20 74 68  s for keeping th
9420: 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
9430: 74 69 6f 6e 20 73 69 7a 65 20 66 6f 72 0a 5b 6d  tion size for.[m
9440: 65 6d 73 79 73 35 5d 20 61 73 20 6c 61 72 67 65  emsys5] as large
9450: 20 61 73 20 70 6f 73 73 69 62 6c 65 2e 20 20 49   as possible.  I
9460: 6e 20 6d 6f 73 74 20 61 70 70 6c 69 63 61 74 69  n most applicati
9470: 6f 6e 73 2c 20 74 68 65 0a 5b 6c 6f 6f 6b 61 73  ons, the.[lookas
9480: 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ide memory alloc
9490: 61 74 6f 72 5d 20 69 73 20 61 62 6c 65 20 74 6f  ator] is able to
94a0: 20 68 61 6e 64 6c 65 20 73 6d 61 6c 6c 20 61 6c   handle small al
94b0: 6c 6f 63 61 74 69 6f 6e 73 2e 20 20 53 6f 0a 69  locations.  So.i
94c0: 74 20 69 73 20 72 65 61 73 6f 6e 61 62 6c 65 20  t is reasonable 
94d0: 74 6f 20 73 65 74 20 74 68 65 20 6d 69 6e 69 6d  to set the minim
94e0: 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
94f0: 7a 65 20 66 6f 72 20 5b 6d 65 6d 73 79 73 35 5d  ze for [memsys5]
9500: 20 74 6f 0a 32 2c 20 34 20 6f 72 20 65 76 65 6e   to.2, 4 or even
9510: 20 38 20 74 69 6d 65 73 20 74 68 65 20 6d 61 78   8 times the max
9520: 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 20 6c  imum size of a l
9530: 6f 6f 6b 61 73 69 64 65 20 61 6c 6c 6f 63 61 74  ookaside allocat
9540: 69 6f 6e 2e 20 20 0a 41 20 6d 69 6e 69 6d 75 6d  ion.  .A minimum
9550: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
9560: 20 6f 66 20 35 31 32 20 69 73 20 61 20 72 65 61   of 512 is a rea
9570: 73 6f 6e 61 62 6c 65 20 73 65 74 74 69 6e 67 2e  sonable setting.
9580: 3c 2f 70 3e 0a 0a 3c 70 3e 46 75 72 74 68 65 72  </p>..<p>Further
9590: 20 74 6f 20 6b 65 65 70 69 6e 67 20 3c 62 3e 6e   to keeping <b>n
95a0: 3c 2f 62 3e 20 73 6d 61 6c 6c 2c 20 6f 6e 65 20  </b> small, one 
95b0: 64 65 73 69 72 65 73 20 74 6f 20 6b 65 65 70 20  desires to keep 
95c0: 74 68 65 20 73 69 7a 65 20 6f 66 0a 74 68 65 20  the size of.the 
95d0: 6c 61 72 67 65 73 74 20 6d 65 6d 6f 72 79 20 61  largest memory a
95e0: 6c 6c 6f 63 61 74 69 6f 6e 73 20 75 6e 64 65 72  llocations under
95f0: 20 63 6f 6e 74 72 6f 6c 2e 0a 4c 61 72 67 65 20   control..Large 
9600: 72 65 71 75 65 73 74 73 20 74 6f 20 74 68 65 20  requests to the 
9610: 67 65 6e 65 72 61 6c 2d 70 75 72 70 6f 73 65 20  general-purpose 
9620: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
9630: 0a 6d 69 67 68 74 20 63 6f 6d 65 20 66 72 6f 6d  .might come from
9640: 20 73 65 76 65 72 61 6c 20 73 6f 75 72 63 65 73   several sources
9650: 3a 3c 2f 70 3e 0a 0a 3c 6f 6c 3e 0a 3c 6c 69 3e  :</p>..<ol>.<li>
9660: 53 51 4c 20 74 61 62 6c 65 20 72 6f 77 73 20 74  SQL table rows t
9670: 68 61 74 20 63 6f 6e 74 61 69 6e 20 6c 61 72 67  hat contain larg
9680: 65 20 73 74 72 69 6e 67 73 20 6f 72 20 42 4c 4f  e strings or BLO
9690: 42 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 43 6f 6d  Bs.</li>.<li>Com
96a0: 70 6c 65 78 20 53 51 4c 20 71 75 65 72 69 65 73  plex SQL queries
96b0: 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 20 64 6f   that compile do
96c0: 77 6e 20 74 6f 20 6c 61 72 67 65 20 5b 70 72 65  wn to large [pre
96d0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
96e0: 5d 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 53 51 4c 20  ].</li>.<li>SQL 
96f0: 70 61 72 73 65 72 20 6f 62 6a 65 63 74 73 20 75  parser objects u
9700: 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62  sed internally b
9710: 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
9720: 72 65 5f 76 32 28 29 5d 2e 3c 2f 6c 69 3e 0a 3c  re_v2()].</li>.<
9730: 6c 69 3e 53 74 6f 72 61 67 65 20 73 70 61 63 65  li>Storage space
9740: 20 66 6f 72 20 5b 64 61 74 61 62 61 73 65 20 63   for [database c
9750: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 6a 65 63  onnection] objec
9760: 74 73 2e 3c 2f 6c 69 3e 0a 3c 6c 69 3e 50 61 67  ts.</li>.<li>Pag
9770: 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  e cache memory a
9780: 6c 6c 6f 63 61 74 69 6f 6e 73 20 74 68 61 74 20  llocations that 
9790: 6f 76 65 72 66 6c 6f 77 20 69 6e 74 6f 20 74 68  overflow into th
97a0: 65 20 67 65 6e 65 72 61 6c 2d 70 75 72 70 6f 73  e general-purpos
97b0: 65 0a 20 20 20 20 6d 65 6d 6f 72 79 20 61 6c 6c  e.    memory all
97c0: 6f 63 61 74 6f 72 2e 3c 2f 6c 69 3e 0a 3c 6c 69  ocator.</li>.<li
97d0: 3e 4c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65  >Lookaside buffe
97e0: 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 66 6f  r allocations fo
97f0: 72 20 6e 65 77 20 5b 64 61 74 61 62 61 73 65 20  r new [database 
9800: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 2e 3c 2f 6c  connections].</l
9810: 69 3e 0a 3c 2f 6f 6c 3e 0a 0a 3c 70 3e 54 68 65  i>.</ol>..<p>The
9820: 20 6c 61 73 74 20 74 77 6f 20 61 6c 6c 6f 63 61   last two alloca
9830: 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 63 6f 6e  tions can be con
9840: 74 72 6f 6c 6c 65 64 20 61 6e 64 2f 6f 72 20 65  trolled and/or e
9850: 6c 69 6d 69 6e 61 74 65 64 20 62 79 0a 63 6f 6e  liminated by.con
9860: 66 69 67 75 72 69 6e 67 20 74 68 65 20 5b 70 61  figuring the [pa
9870: 67 65 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 61  gecache memory a
9880: 6c 6c 6f 63 61 74 6f 72 5d 2c 0a 61 6e 64 20 5b  llocator],.and [
9890: 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
98a0: 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 61 70 70 72   allocator] appr
98b0: 6f 70 72 69 61 74 65 6c 79 2c 20 61 73 20 64 65  opriately, as de
98c0: 73 63 72 69 62 65 64 20 61 62 6f 76 65 2e 0a 54  scribed above..T
98d0: 68 65 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  he storage space
98e0: 20 72 65 71 75 69 72 65 64 20 66 6f 72 20 5b 64   required for [d
98f0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
9900: 6f 6e 5d 20 6f 62 6a 65 63 74 73 20 64 65 70 65  on] objects depe
9910: 6e 64 73 0a 74 6f 20 73 6f 6d 65 20 65 78 74 65  nds.to some exte
9920: 6e 74 20 6f 6e 20 74 68 65 20 6c 65 6e 67 74 68  nt on the length
9930: 20 6f 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65   of the filename
9940: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
9950: 20 66 69 6c 65 2c 20 62 75 74 0a 72 61 72 65 6c   file, but.rarel
9960: 79 20 65 78 63 65 65 64 73 20 32 4b 42 20 6f 6e  y exceeds 2KB on
9970: 20 33 32 2d 62 69 74 20 73 79 73 74 65 6d 73 2e   32-bit systems.
9980: 20 20 28 4d 6f 72 65 20 73 70 61 63 65 20 69 73    (More space is
9990: 20 72 65 71 75 69 72 65 64 20 6f 6e 0a 36 34 2d   required on.64-
99a0: 62 69 74 20 73 79 73 74 65 6d 73 20 64 75 65 20  bit systems due 
99b0: 74 6f 20 74 68 65 20 69 6e 63 72 65 61 73 65 64  to the increased
99c0: 20 73 69 7a 65 20 6f 66 20 70 6f 69 6e 74 65 72   size of pointer
99d0: 73 2e 29 0a 45 61 63 68 20 70 61 72 73 65 72 20  s.).Each parser 
99e0: 6f 62 6a 65 63 74 20 75 73 65 73 20 61 62 6f 75  object uses abou
99f0: 74 20 31 2e 36 4b 42 20 6f 66 20 6d 65 6d 6f 72  t 1.6KB of memor
9a00: 79 2e 20 20 54 68 75 73 2c 20 65 6c 65 6d 65 6e  y.  Thus, elemen
9a10: 74 73 20 33 20 74 68 72 6f 75 67 68 20 37 0a 61  ts 3 through 7.a
9a20: 62 6f 76 65 20 63 61 6e 20 65 61 73 69 6c 79 20  bove can easily 
9a30: 62 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 74 6f  be controlled to
9a40: 20 6b 65 65 70 20 74 68 65 20 6d 61 78 69 6d 75   keep the maximu
9a50: 6d 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  m memory allocat
9a60: 69 6f 6e 0a 73 69 7a 65 20 62 65 6c 6f 77 20 32  ion.size below 2
9a70: 4b 42 2e 3c 2f 70 3e 0a 0a 3c 70 3e 49 66 20 74  KB.</p>..<p>If t
9a80: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
9a90: 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 6d 61  s designed to ma
9aa0: 6e 61 67 65 20 64 61 74 61 20 69 6e 20 73 6d 61  nage data in sma
9ab0: 6c 6c 20 70 69 65 63 65 73 2c 0a 74 68 65 6e 20  ll pieces,.then 
9ac0: 74 68 65 20 64 61 74 61 62 61 73 65 20 73 68 6f  the database sho
9ad0: 75 6c 64 20 6e 65 76 65 72 20 63 6f 6e 74 61 69  uld never contai
9ae0: 6e 20 61 6e 79 20 6c 61 72 67 65 20 73 74 72 69  n any large stri
9af0: 6e 67 73 20 6f 72 20 42 4c 4f 42 73 0a 61 6e 64  ngs or BLOBs.and
9b00: 20 68 65 6e 63 65 20 65 6c 65 6d 65 6e 74 20 31   hence element 1
9b10: 20 61 62 6f 76 65 20 73 68 6f 75 6c 64 20 6e 6f   above should no
9b20: 74 20 62 65 20 61 20 66 61 63 74 6f 72 2e 20 20  t be a factor.  
9b30: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  If the database.
9b40: 64 6f 65 73 20 63 6f 6e 74 61 69 6e 20 6c 61 72  does contain lar
9b50: 67 65 20 73 74 72 69 6e 67 73 20 6f 72 20 42 4c  ge strings or BL
9b60: 4f 42 73 2c 20 74 68 65 79 20 73 68 6f 75 6c 64  OBs, they should
9b70: 20 62 65 20 72 65 61 64 20 75 73 69 6e 67 0a 5b   be read using.[
9b80: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 20 7c 20 69  sqlite3_blob | i
9b90: 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20  ncremental BLOB 
9ba0: 49 2f 4f 5d 20 61 6e 64 20 72 6f 77 73 20 74 68  I/O] and rows th
9bb0: 61 74 20 63 6f 6e 74 61 69 6e 20 74 68 65 0a 6c  at contain the.l
9bc0: 61 72 67 65 20 73 74 72 69 6e 67 73 20 6f 72 20  arge strings or 
9bd0: 42 4c 4f 42 73 20 73 68 6f 75 6c 64 20 6e 65 76  BLOBs should nev
9be0: 65 72 20 62 65 20 75 70 64 61 74 65 20 62 79 20  er be update by 
9bf0: 61 6e 79 20 6d 65 61 6e 73 20 6f 74 68 65 72 0a  any means other.
9c00: 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 62 6c  than [sqlite3_bl
9c10: 6f 62 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  ob | incremental
9c20: 20 42 4c 4f 42 20 49 2f 4f 5d 2e 20 20 4f 74 68   BLOB I/O].  Oth
9c30: 65 72 77 69 73 65 2c 20 74 68 65 20 0a 5b 73 71  erwise, the .[sq
9c40: 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 6f  lite3_step()] ro
9c50: 75 74 69 6e 65 20 77 69 6c 6c 20 6e 65 65 64 20  utine will need 
9c60: 74 6f 20 72 65 61 64 20 74 68 65 20 65 6e 74 69  to read the enti
9c70: 72 65 20 72 6f 77 20 69 6e 74 6f 0a 63 6f 6e 74  re row into.cont
9c80: 69 67 75 6f 75 73 20 6d 65 6d 6f 72 79 20 61 74  iguous memory at
9c90: 20 73 6f 6d 65 20 70 6f 69 6e 74 2c 20 61 6e 64   some point, and
9ca0: 20 74 68 61 74 20 77 69 6c 6c 20 69 6e 76 6f 6c   that will invol
9cb0: 76 65 20 61 74 20 6c 65 61 73 74 0a 6f 6e 65 20  ve at least.one 
9cc0: 6c 61 72 67 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  large memory all
9cd0: 6f 63 61 74 69 6f 6e 2e 3c 2f 70 3e 0a 0a 3c 70  ocation.</p>..<p
9ce0: 3e 54 68 65 20 66 69 6e 61 6c 20 73 6f 75 72 63  >The final sourc
9cf0: 65 20 6f 66 20 6c 61 72 67 65 20 6d 65 6d 6f 72  e of large memor
9d00: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 69 73  y allocations is
9d10: 20 74 68 65 20 73 70 61 63 65 20 74 6f 20 68 6f   the space to ho
9d20: 6c 64 0a 74 68 65 20 5b 70 72 65 70 61 72 65 64  ld.the [prepared
9d30: 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 74 68 61   statements] tha
9d40: 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 63 6f  t result from co
9d50: 6d 70 69 6c 69 6e 67 20 63 6f 6d 70 6c 65 78 20  mpiling complex 
9d60: 53 51 4c 0a 6f 70 65 72 61 74 69 6f 6e 73 2e 20  SQL.operations. 
9d70: 20 4f 6e 67 6f 69 6e 67 20 77 6f 72 6b 20 62 79   Ongoing work by
9d80: 20 74 68 65 20 53 51 4c 69 74 65 20 64 65 76 65   the SQLite deve
9d90: 6c 6f 70 65 72 73 20 69 73 20 72 65 64 75 63 69  lopers is reduci
9da0: 6e 67 20 74 68 65 0a 61 6d 6f 75 6e 74 20 6f 66  ng the.amount of
9db0: 20 73 70 61 63 65 20 72 65 71 75 69 72 65 64 20   space required 
9dc0: 68 65 72 65 2e 20 20 42 75 74 20 6c 61 72 67 65  here.  But large
9dd0: 20 61 6e 64 20 63 6f 6d 70 6c 65 78 20 71 75 65   and complex que
9de0: 72 69 65 73 20 6d 69 67 68 74 0a 73 74 69 6c 6c  ries might.still
9df0: 20 72 65 71 75 69 72 65 20 5b 70 72 65 70 61 72   require [prepar
9e00: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 74  ed statements] t
9e10: 68 61 74 20 61 72 65 20 73 65 76 65 72 61 6c 20  hat are several 
9e20: 6b 69 6c 6f 62 79 74 65 73 20 69 6e 0a 73 69 7a  kilobytes in.siz
9e30: 65 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 6f 72  e.  The only wor
9e40: 6b 61 72 6f 75 6e 64 20 61 74 20 74 68 65 20 6d  karound at the m
9e50: 6f 6d 65 6e 74 20 69 73 20 66 6f 72 20 74 68 65  oment is for the
9e60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 0a   application to.
9e70: 62 72 65 61 6b 20 63 6f 6d 70 6c 65 78 20 53 51  break complex SQ
9e80: 4c 20 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20  L operations up 
9e90: 69 6e 74 6f 20 74 77 6f 20 6f 72 20 6d 6f 72 65  into two or more
9ea0: 20 73 6d 61 6c 6c 65 72 20 61 6e 64 20 73 69 6d   smaller and sim
9eb0: 70 6c 65 72 20 0a 6f 70 65 72 61 74 69 6f 6e 73  pler .operations
9ec0: 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 73 65   contained in se
9ed0: 70 61 72 61 74 65 20 5b 70 72 65 70 61 72 65 64  parate [prepared
9ee0: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 3c 2f 70   statements].</p
9ef0: 3e 0a 0a 3c 70 3e 41 6c 6c 20 74 68 69 6e 67 73  >..<p>All things
9f00: 20 63 6f 6e 73 69 64 65 72 65 64 2c 20 61 70 70   considered, app
9f10: 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
9f20: 20 6e 6f 72 6d 61 6c 6c 79 20 62 65 20 61 62 6c   normally be abl
9f30: 65 20 74 6f 0a 68 6f 6c 64 20 74 68 65 69 72 20  e to.hold their 
9f40: 6d 61 78 69 6d 75 6d 20 6d 65 6d 6f 72 79 20 61  maximum memory a
9f50: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 62  llocation size b
9f60: 65 6c 6f 77 20 32 4b 20 6f 72 20 34 4b 2e 20 20  elow 2K or 4K.  
9f70: 54 68 69 73 0a 67 69 76 65 73 20 61 20 76 61 6c  This.gives a val
9f80: 75 65 20 66 6f 72 20 6c 6f 67 3c 73 75 62 3e 32  ue for log<sub>2
9f90: 3c 2f 73 75 62 3e 28 3c 62 3e 6e 3c 2f 62 3e 29  </sub>(<b>n</b>)
9fa0: 20 6f 66 20 32 20 6f 72 20 33 2e 20 20 54 68 69   of 2 or 3.  Thi
9fb0: 73 20 77 69 6c 6c 0a 6c 69 6d 69 74 20 3c 62 3e  s will.limit <b>
9fc0: 4e 3c 2f 62 3e 20 74 6f 20 62 65 74 77 65 65 6e  N</b> to between
9fd0: 20 32 20 61 6e 64 20 32 2e 35 20 74 69 6d 65 73   2 and 2.5 times
9fe0: 20 3c 62 3e 4d 3c 2f 62 3e 2e 3c 2f 70 3e 0a 0a   <b>M</b>.</p>..
9ff0: 3c 70 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 61  <p>The maximum a
a000: 6d 6f 75 6e 74 20 6f 66 20 67 65 6e 65 72 61 6c  mount of general
a010: 2d 70 75 72 70 6f 73 65 20 6d 65 6d 6f 72 79 20  -purpose memory 
a020: 6e 65 65 64 65 64 20 62 79 20 74 68 65 20 61 70  needed by the ap
a030: 70 6c 69 63 61 74 69 6f 6e 0a 69 73 20 64 65 74  plication.is det
a040: 65 72 6d 69 6e 65 64 20 62 79 20 73 75 63 68 20  ermined by such 
a050: 66 61 63 74 6f 72 73 20 61 73 20 68 6f 77 20 6d  factors as how m
a060: 61 6e 79 20 73 69 6d 75 6c 74 61 6e 65 6f 75 73  any simultaneous
a070: 20 6f 70 65 6e 20 0a 5b 64 61 74 61 62 61 73 65   open .[database
a080: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
a090: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
a0a0: 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 20 74 68  ment] objects th
a0b0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 75 73  e application.us
a0c0: 65 73 2c 20 61 6e 64 20 6f 6e 20 74 68 65 20 63  es, and on the c
a0d0: 6f 6d 70 6c 65 78 69 74 79 20 6f 66 20 74 68 65  omplexity of the
a0e0: 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
a0f0: 6d 65 6e 74 73 5d 2e 20 20 46 6f 72 20 61 6e 79  ments].  For any
a100: 0a 67 69 76 65 6e 20 61 70 70 6c 69 63 61 74 69  .given applicati
a110: 6f 6e 2c 20 74 68 65 73 65 20 66 61 63 74 6f 72  on, these factor
a120: 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c 79 20 66  s are normally f
a130: 69 78 65 64 20 61 6e 64 20 63 61 6e 20 62 65 0a  ixed and can be.
a140: 64 65 74 65 72 6d 69 6e 65 64 20 65 78 70 65 72  determined exper
a150: 69 6d 65 6e 74 61 6c 6c 79 20 75 73 69 6e 67 20  imentally using 
a160: 5b 53 51 4c 49 54 45 5f 53 54 41 54 55 53 5f 4d  [SQLITE_STATUS_M
a170: 45 4d 4f 52 59 5f 55 53 45 44 5d 2e 0a 41 20 74  EMORY_USED]..A t
a180: 79 70 69 63 61 6c 20 61 70 70 6c 69 63 61 74 69  ypical applicati
a190: 6f 6e 20 6d 69 67 68 74 20 6f 6e 6c 79 20 75 73  on might only us
a1a0: 65 20 61 62 6f 75 74 20 34 30 4b 42 20 6f 66 20  e about 40KB of 
a1b0: 67 65 6e 65 72 61 6c 2d 70 75 72 70 6f 73 65 0a  general-purpose.
a1c0: 6d 65 6d 6f 72 79 2e 20 20 54 68 69 73 20 67 69  memory.  This gi
a1d0: 76 65 73 20 61 20 76 61 6c 75 65 20 6f 66 20 3c  ves a value of <
a1e0: 62 3e 4e 3c 2f 62 3e 20 6f 66 20 61 72 6f 75 6e  b>N</b> of aroun
a1f0: 64 20 31 30 30 4b 42 2e 3c 2f 70 3e 0a 0a 3c 68  d 100KB.</p>..<h
a200: 32 3e 20 44 75 63 74 69 6c 65 20 66 61 69 6c 75  2> Ductile failu
a210: 72 65 3c 2f 68 32 3e 0a 0a 3c 70 3e 49 66 20 74  re</h2>..<p>If t
a220: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
a230: 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 73 20  tion subsystems 
a240: 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 61 72  within SQLite ar
a250: 65 20 63 6f 6e 66 69 67 75 72 65 64 0a 66 6f 72  e configured.for
a260: 20 62 72 65 61 6b 64 6f 77 6e 2d 66 72 65 65 20   breakdown-free 
a270: 6f 70 65 72 61 74 69 6f 6e 20 62 75 74 20 74 68  operation but th
a280: 65 20 61 63 74 75 61 6c 20 6d 65 6d 6f 72 79 20  e actual memory 
a290: 75 73 61 67 65 20 65 78 63 65 65 64 73 0a 64 65  usage exceeds.de
a2a0: 73 69 67 6e 20 6c 69 6d 69 74 73 20 73 65 74 20  sign limits set 
a2b0: 62 79 20 74 68 65 20 5b 52 6f 62 73 6f 6e 20 70  by the [Robson p
a2c0: 72 6f 6f 66 5d 2c 20 53 51 4c 69 74 65 20 77 69  roof], SQLite wi
a2d0: 6c 6c 20 75 73 75 61 6c 6c 79 20 63 6f 6e 74 69  ll usually conti
a2e0: 6e 75 65 20 0a 74 6f 20 6f 70 65 72 61 74 65 20  nue .to operate 
a2f0: 6e 6f 72 6d 61 6c 6c 79 2e 0a 54 68 65 20 74 68  normally..The th
a300: 65 20 5b 70 61 67 65 63 61 63 68 65 20 6d 65 6d  e [pagecache mem
a310: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 0a 61  ory allocator].a
a320: 6e 64 20 74 68 65 20 5b 6c 6f 6f 6b 61 73 69 64  nd the [lookasid
a330: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
a340: 6f 72 5d 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  or] automaticall
a350: 79 20 66 61 69 6c 6f 76 65 72 0a 74 6f 20 74 68  y failover.to th
a360: 65 20 5b 6d 65 6d 73 79 73 35 5d 20 67 65 6e 65  e [memsys5] gene
a370: 72 61 6c 2d 70 75 72 70 6f 73 65 20 6d 65 6d 6f  ral-purpose memo
a380: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 41  ry allocator.  A
a390: 6e 64 20 69 74 20 69 73 20 75 73 75 61 6c 6c 79  nd it is usually
a3a0: 20 74 68 65 0a 63 61 73 65 20 74 68 61 74 20 74   the.case that t
a3b0: 68 65 20 5b 6d 65 6d 73 79 73 35 5d 20 6d 65 6d  he [memsys5] mem
a3c0: 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 77 69  ory allocator wi
a3d0: 6c 6c 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 66  ll continue to f
a3e0: 75 6e 63 74 69 6f 6e 0a 77 69 74 68 6f 75 74 20  unction.without 
a3f0: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 65 76  fragmentation ev
a400: 65 6e 20 69 66 20 3c 62 3e 4d 3c 2f 62 3e 20 61  en if <b>M</b> a
a410: 6e 64 2f 6f 72 20 3c 62 3e 6e 3c 2f 62 3e 20 65  nd/or <b>n</b> e
a420: 78 63 65 65 64 73 20 74 68 65 20 6c 69 6d 69 74  xceeds the limit
a430: 73 0a 69 6d 70 6f 73 65 64 20 62 79 20 74 68 65  s.imposed by the
a440: 20 5b 52 6f 62 73 6f 6e 20 70 72 6f 6f 66 5d 2e   [Robson proof].
a450: 20 20 54 68 65 20 5b 52 6f 62 73 6f 6e 20 70 72    The [Robson pr
a460: 6f 6f 66 5d 20 73 68 6f 77 73 20 74 68 61 74 20  oof] shows that 
a470: 69 74 20 69 73 20 0a 70 6f 73 73 69 62 6c 65 20  it is .possible 
a480: 66 6f 72 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c  for a memory all
a490: 6f 63 61 74 69 6f 6e 20 74 6f 20 62 72 65 61 6b  ocation to break
a4a0: 20 64 6f 77 6e 20 61 6e 64 20 66 61 69 6c 20 69   down and fail i
a4b0: 6e 20 74 68 69 73 20 0a 63 69 72 63 75 6d 73 74  n this .circumst
a4c0: 61 6e 63 65 2c 20 62 75 74 20 73 75 63 68 20 61  ance, but such a
a4d0: 20 66 61 69 6c 75 72 65 20 72 65 71 75 69 72 65   failure require
a4e0: 73 20 61 6e 20 65 73 70 65 63 69 61 6c 6c 79 0a  s an especially.
a4f0: 64 65 73 70 69 63 61 62 6c 65 20 73 65 71 75 65  despicable seque
a500: 6e 63 65 20 6f 66 20 61 6c 6c 6f 63 61 74 69 6f  nce of allocatio
a510: 6e 73 20 61 6e 64 20 64 65 61 6c 6c 6f 63 61 74  ns and deallocat
a520: 69 6f 6e 73 20 2d 20 61 20 73 65 71 75 65 6e 63  ions - a sequenc
a530: 65 20 74 68 61 74 0a 53 51 4c 69 74 65 20 68 61  e that.SQLite ha
a540: 73 20 6e 65 76 65 72 20 62 65 65 6e 20 6f 62 73  s never been obs
a550: 65 72 76 65 64 20 74 6f 20 66 6f 6c 6c 6f 77 2e  erved to follow.
a560: 20 20 53 6f 20 69 6e 20 70 72 61 63 74 69 63 65    So in practice
a570: 20 69 74 20 69 73 20 75 73 75 61 6c 6c 79 0a 74   it is usually.t
a580: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
a590: 20 6c 69 6d 69 74 73 20 69 6d 70 6f 73 65 64 20   limits imposed 
a5a0: 62 79 20 52 6f 62 73 6f 6e 20 63 61 6e 20 62 65  by Robson can be
a5b0: 20 65 78 63 65 65 64 65 64 20 62 79 20 61 0a 63   exceeded by a.c
a5c0: 6f 6e 73 69 64 65 72 61 62 6c 65 20 6d 61 72 67  onsiderable marg
a5d0: 69 6e 20 77 69 74 68 20 6e 6f 20 69 6c 6c 20 65  in with no ill e
a5e0: 66 66 65 63 74 2e 3c 2f 70 3e 0a 0a 3c 70 3e 4e  ffect.</p>..<p>N
a5f0: 65 76 65 72 74 68 65 6c 65 73 73 2c 20 61 70 70  evertheless, app
a600: 6c 69 63 61 74 69 6f 6e 20 64 65 76 65 6c 6f 70  lication develop
a610: 65 72 73 20 61 72 65 20 61 64 6d 6f 6e 69 73 68  ers are admonish
a620: 65 64 20 74 6f 20 6d 6f 6e 69 74 6f 72 0a 74 68  ed to monitor.th
a630: 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20 6d  e state of the m
a640: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
a650: 20 73 75 62 73 79 73 74 65 6d 73 20 61 6e 64 20   subsystems and 
a660: 72 61 69 73 65 20 61 6c 61 72 6d 73 20 77 68 65  raise alarms whe
a670: 6e 0a 6d 65 6d 6f 72 79 20 75 73 61 67 65 20 61  n.memory usage a
a680: 70 70 72 6f 61 63 68 65 73 20 6f 72 20 65 78 63  pproaches or exc
a690: 65 65 64 73 20 52 6f 62 73 6f 6e 20 6c 69 6d 69  eeds Robson limi
a6a0: 74 73 2e 20 20 49 6e 20 74 68 69 73 20 77 61 79  ts.  In this way
a6b0: 2c 0a 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  ,.the applicatio
a6c0: 6e 20 77 69 6c 6c 20 70 72 6f 76 69 64 65 20 6f  n will provide o
a6d0: 70 65 72 61 74 6f 72 73 20 77 69 74 68 20 61 62  perators with ab
a6e0: 75 6e 64 61 6e 74 20 77 61 72 6e 69 6e 67 20 77  undant warning w
a6f0: 65 6c 6c 0a 69 6e 20 61 64 76 61 6e 63 65 20 6f  ell.in advance o
a700: 66 20 66 61 69 6c 75 72 65 2e 0a 54 68 65 20 5b  f failure..The [
a710: 6d 65 6d 6f 72 79 20 73 74 61 74 69 73 74 69 63  memory statistic
a720: 73 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6f 66  s] interfaces of
a730: 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 20   SQLite provide 
a740: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
a750: 77 69 74 68 0a 61 6c 6c 20 74 68 65 20 6d 65 63  with.all the mec
a760: 68 61 6e 69 73 6d 20 6e 65 63 65 73 73 61 72 79  hanism necessary
a770: 20 74 6f 20 63 6f 6d 70 6c 65 74 65 20 74 68 65   to complete the
a780: 20 6d 6f 6e 69 74 6f 72 69 6e 67 20 70 6f 72 74   monitoring port
a790: 69 6f 6e 20 6f 66 0a 74 68 69 73 20 74 61 73 6b  ion of.this task
a7a0: 2e 3c 2f 70 3e 0a 0a 3c 61 20 6e 61 6d 65 3d 22  .</p>..<a name="
a7b0: 73 74 61 62 69 6c 69 74 79 22 3e 3c 2f 61 3e 0a  stability"></a>.
a7c0: 3c 68 31 3e 20 53 74 61 62 69 6c 69 74 79 20 4f  <h1> Stability O
a7d0: 66 20 4d 65 6d 6f 72 79 20 49 6e 74 65 72 66 61  f Memory Interfa
a7e0: 63 65 73 3c 2f 68 31 3e 0a 0a 3c 70 3e 3c 62 3e  ces</h1>..<p><b>
a7f0: 55 70 64 61 74 65 3a 3c 2f 62 3e 20 41 73 20 6f  Update:</b> As o
a800: 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
a810: 20 33 2e 37 2e 30 20 28 5b 64 61 74 65 6f 66 3a   3.7.0 ([dateof:
a820: 33 2e 37 2e 30 5d 29 2c 20 0a 61 6c 6c 20 6f 66  3.7.0]), .all of
a830: 20 53 51 4c 69 74 65 20 6d 65 6d 6f 72 79 20 61   SQLite memory a
a840: 6c 6c 6f 63 61 74 69 6f 6e 20 69 6e 74 65 72 66  llocation interf
a850: 61 63 65 73 0a 61 72 65 20 63 6f 6e 73 69 64 65  aces.are conside
a860: 72 65 64 20 73 74 61 62 6c 65 20 61 6e 64 20 77  red stable and w
a870: 69 6c 6c 20 62 65 20 73 75 70 70 6f 72 74 65 64  ill be supported
a880: 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
a890: 73 65 73 2e 3c 2f 70 3e 0a                       ses.</p>.