SQLite4
Hex Artifact Content
Not logged in

Artifact 41b08c1d31c156d3916558aad89b7e7ae8a381c5:


0000: 0a 3c 74 69 74 6c 65 3e 4c 53 4d 20 55 73 65 72  .<title>LSM User
0010: 73 20 47 75 69 64 65 3c 2f 74 69 74 6c 65 3e 0a  s Guide</title>.
0020: 3c 6e 6f 77 69 6b 69 3e 0a 0a 3c 68 32 3e 54 61  <nowiki>..<h2>Ta
0030: 62 6c 65 20 6f 66 20 43 6f 6e 74 65 6e 74 73 3c  ble of Contents<
0040: 2f 68 32 3e 0a 0a 0a 0a 0a 0a 3c 64 69 76 20 69  /h2>......<div i
0050: 64 3d 73 74 61 72 74 5f 6f 66 5f 74 6f 63 3e 3c  d=start_of_toc><
0060: 2f 64 69 76 3e 0a 26 6e 62 73 70 3b 26 6e 62 73  /div>.&nbsp;&nbs
0070: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
0080: 62 73 70 3b 26 6e 62 73 70 3b 3c 61 20 68 72 65  bsp;&nbsp;<a hre
0090: 66 3d 23 69 6e 74 72 6f 64 75 63 74 69 6f 6e 5f  f=#introduction_
00a0: 74 6f 5f 6c 73 6d 20 73 74 79 6c 65 3d 74 65 78  to_lsm style=tex
00b0: 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f 6e  t-decoration:non
00c0: 65 3e 31 2e 20 49 6e 74 72 6f 64 75 63 74 69 6f  e>1. Introductio
00d0: 6e 20 74 6f 20 4c 53 4d 3c 2f 61 3e 3c 62 72 3e  n to LSM</a><br>
00e0: 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  .&nbsp;&nbsp;&nb
00f0: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0100: 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d 23 75 73  nbsp;<a href=#us
0110: 69 6e 67 5f 6c 73 6d 5f 69 6e 5f 61 70 70 6c 69  ing_lsm_in_appli
0120: 63 61 74 69 6f 6e 73 20 73 74 79 6c 65 3d 74 65  cations style=te
0130: 78 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f  xt-decoration:no
0140: 6e 65 3e 32 2e 20 55 73 69 6e 67 20 4c 53 4d 20  ne>2. Using LSM 
0150: 69 6e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  in Applications 
0160: 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73 70 3b 26  </a><br>.&nbsp;&
0170: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0180: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 61 20  ;&nbsp;&nbsp;<a 
0190: 68 72 65 66 3d 23 62 61 73 69 63 5f 75 73 61 67  href=#basic_usag
01a0: 65 20 73 74 79 6c 65 3d 74 65 78 74 2d 64 65 63  e style=text-dec
01b0: 6f 72 61 74 69 6f 6e 3a 6e 6f 6e 65 3e 33 2e 20  oration:none>3. 
01c0: 42 61 73 69 63 20 55 73 61 67 65 3c 2f 61 3e 3c  Basic Usage</a><
01d0: 62 72 3e 0a 26 6e 62 73 70 3b 26 6e 62 73 70 3b  br>.&nbsp;&nbsp;
01e0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
01f0: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
0200: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
0210: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 61 20 68  &nbsp;&nbsp;<a h
0220: 72 65 66 3d 23 6f 70 65 6e 69 6e 67 5f 61 6e 64  ref=#opening_and
0230: 5f 63 6c 6f 73 69 6e 67 5f 64 61 74 61 62 61 73  _closing_databas
0240: 65 5f 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 74  e_connections st
0250: 79 6c 65 3d 74 65 78 74 2d 64 65 63 6f 72 61 74  yle=text-decorat
0260: 69 6f 6e 3a 6e 6f 6e 65 3e 33 2e 31 2e 20 4f 70  ion:none>3.1. Op
0270: 65 6e 69 6e 67 20 61 6e 64 20 43 6c 6f 73 69 6e  ening and Closin
0280: 67 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  g Database Conne
0290: 63 74 69 6f 6e 73 20 3c 2f 61 3e 3c 62 72 3e 0a  ctions </a><br>.
02a0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
02b0: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
02c0: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
02d0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
02e0: 70 3b 26 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d  p;&nbsp;<a href=
02f0: 23 77 72 69 74 69 6e 67 5f 74 6f 5f 61 5f 64 61  #writing_to_a_da
0300: 74 61 62 61 73 65 20 73 74 79 6c 65 3d 74 65 78  tabase style=tex
0310: 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f 6e  t-decoration:non
0320: 65 3e 33 2e 32 2e 20 57 72 69 74 69 6e 67 20 74  e>3.2. Writing t
0330: 6f 20 61 20 44 61 74 61 62 61 73 65 20 3c 2f 61  o a Database </a
0340: 3e 3c 62 72 3e 0a 26 6e 62 73 70 3b 26 6e 62 73  ><br>.&nbsp;&nbs
0350: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
0360: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
0370: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
0380: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 61  p;&nbsp;&nbsp;<a
0390: 20 68 72 65 66 3d 23 72 65 61 64 69 6e 67 5f 66   href=#reading_f
03a0: 72 6f 6d 5f 61 5f 64 61 74 61 62 61 73 65 20 73  rom_a_database s
03b0: 74 79 6c 65 3d 74 65 78 74 2d 64 65 63 6f 72 61  tyle=text-decora
03c0: 74 69 6f 6e 3a 6e 6f 6e 65 3e 33 2e 33 2e 20 52  tion:none>3.3. R
03d0: 65 61 64 69 6e 67 20 66 72 6f 6d 20 61 20 44 61  eading from a Da
03e0: 74 61 62 61 73 65 20 3c 2f 61 3e 3c 62 72 3e 0a  tabase </a><br>.
03f0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
0400: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
0410: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
0420: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
0430: 70 3b 26 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d  p;&nbsp;<a href=
0440: 23 64 61 74 61 62 61 73 65 5f 74 72 61 6e 73 61  #database_transa
0450: 63 74 69 6f 6e 73 5f 61 6e 64 5f 6d 76 63 63 20  ctions_and_mvcc 
0460: 73 74 79 6c 65 3d 74 65 78 74 2d 64 65 63 6f 72  style=text-decor
0470: 61 74 69 6f 6e 3a 6e 6f 6e 65 3e 33 2e 34 2e 20  ation:none>3.4. 
0480: 44 61 74 61 62 61 73 65 20 54 72 61 6e 73 61 63  Database Transac
0490: 74 69 6f 6e 73 20 61 6e 64 20 4d 56 43 43 20 3c  tions and MVCC <
04a0: 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73 70 3b 26 6e  /a><br>.&nbsp;&n
04b0: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
04c0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 3c 61 20 68  &nbsp;&nbsp;<a h
04d0: 72 65 66 3d 23 64 61 74 61 5f 64 75 72 61 62 69  ref=#data_durabi
04e0: 6c 69 74 79 20 73 74 79 6c 65 3d 74 65 78 74 2d  lity style=text-
04f0: 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f 6e 65 3e  decoration:none>
0500: 34 2e 20 44 61 74 61 20 44 75 72 61 62 69 6c 69  4. Data Durabili
0510: 74 79 20 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73  ty </a><br>.&nbs
0520: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
0530: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
0540: 3c 61 20 68 72 65 66 3d 23 63 6f 6d 70 72 65 73  <a href=#compres
0550: 73 65 64 5f 61 6e 64 5f 65 6e 63 72 79 70 74 65  sed_and_encrypte
0560: 64 5f 64 61 74 61 62 61 73 65 73 20 73 74 79 6c  d_databases styl
0570: 65 3d 74 65 78 74 2d 64 65 63 6f 72 61 74 69 6f  e=text-decoratio
0580: 6e 3a 6e 6f 6e 65 3e 35 2e 20 43 6f 6d 70 72 65  n:none>5. Compre
0590: 73 73 65 64 20 61 6e 64 20 45 6e 63 72 79 70 74  ssed and Encrypt
05a0: 65 64 20 44 61 74 61 62 61 73 65 73 20 3c 2f 61  ed Databases </a
05b0: 3e 3c 62 72 3e 0a 26 6e 62 73 70 3b 26 6e 62 73  ><br>.&nbsp;&nbs
05c0: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
05d0: 62 73 70 3b 26 6e 62 73 70 3b 3c 61 20 68 72 65  bsp;&nbsp;<a hre
05e0: 66 3d 23 70 65 72 66 6f 72 6d 61 6e 63 65 5f 74  f=#performance_t
05f0: 75 6e 69 6e 67 20 73 74 79 6c 65 3d 74 65 78 74  uning style=text
0600: 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f 6e 65  -decoration:none
0610: 3e 36 2e 20 50 65 72 66 6f 72 6d 61 6e 63 65 20  >6. Performance 
0620: 54 75 6e 69 6e 67 3c 2f 61 3e 3c 62 72 3e 0a 26  Tuning</a><br>.&
0630: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0640: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
0650: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0660: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0670: 3b 26 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d 23  ;&nbsp;<a href=#
0680: 70 65 72 66 6f 72 6d 61 6e 63 65 5f 72 65 6c 61  performance_rela
0690: 74 65 64 5f 63 6f 6e 66 69 67 75 72 61 74 69 6f  ted_configuratio
06a0: 6e 5f 6f 70 74 69 6f 6e 73 20 73 74 79 6c 65 3d  n_options style=
06b0: 74 65 78 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a  text-decoration:
06c0: 6e 6f 6e 65 3e 36 2e 31 2e 20 50 65 72 66 6f 72  none>6.1. Perfor
06d0: 6d 61 6e 63 65 20 52 65 6c 61 74 65 64 20 43 6f  mance Related Co
06e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
06f0: 6f 6e 73 20 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62  ons </a><br>.&nb
0700: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0710: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0720: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
0730: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0740: 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d 23 75 73  nbsp;<a href=#us
0750: 69 6e 67 5f 77 6f 72 6b 65 72 5f 74 68 72 65 61  ing_worker_threa
0760: 64 73 5f 6f 72 5f 70 72 6f 63 65 73 73 65 73 20  ds_or_processes 
0770: 73 74 79 6c 65 3d 74 65 78 74 2d 64 65 63 6f 72  style=text-decor
0780: 61 74 69 6f 6e 3a 6e 6f 6e 65 3e 36 2e 32 2e 20  ation:none>6.2. 
0790: 55 73 69 6e 67 20 57 6f 72 6b 65 72 20 54 68 72  Using Worker Thr
07a0: 65 61 64 73 20 6f 72 20 50 72 6f 63 65 73 73 65  eads or Processe
07b0: 73 20 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73 70  s </a><br>.&nbsp
07c0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
07d0: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
07e0: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
07f0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
0800: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0810: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0820: 3b 26 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d 23  ;&nbsp;<a href=#
0830: 61 72 63 68 69 74 65 63 74 75 72 61 6c 5f 6f 76  architectural_ov
0840: 65 72 76 69 65 77 20 73 74 79 6c 65 3d 74 65 78  erview style=tex
0850: 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f 6e  t-decoration:non
0860: 65 3e 36 2e 32 2e 31 2e 20 41 72 63 68 69 74 65  e>6.2.1. Archite
0870: 63 74 75 72 61 6c 20 4f 76 65 72 76 69 65 77 20  ctural Overview 
0880: 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73 70 3b 26  </a><br>.&nbsp;&
0890: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
08a0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
08b0: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
08c0: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
08d0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
08e0: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
08f0: 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d 23 61 75  nbsp;<a href=#au
0900: 74 6f 6d 61 74 69 63 5f 77 6f 72 6b 5f 61 6e 64  tomatic_work_and
0910: 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 73 63 68 65  _checkpoint_sche
0920: 64 75 6c 69 6e 67 20 73 74 79 6c 65 3d 74 65 78  duling style=tex
0930: 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f 6e  t-decoration:non
0940: 65 3e 36 2e 32 2e 32 2e 20 41 75 74 6f 6d 61 74  e>6.2.2. Automat
0950: 69 63 20 57 6f 72 6b 20 61 6e 64 20 43 68 65 63  ic Work and Chec
0960: 6b 70 6f 69 6e 74 20 53 63 68 65 64 75 6c 69 6e  kpoint Schedulin
0970: 67 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73 70 3b  g</a><br>.&nbsp;
0980: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
0990: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
09a0: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
09b0: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
09c0: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
09d0: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
09e0: 26 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d 23 65  &nbsp;<a href=#e
09f0: 78 70 6c 69 63 69 74 5f 77 6f 72 6b 5f 61 6e 64  xplicit_work_and
0a00: 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 73 63 68 65  _checkpoint_sche
0a10: 64 75 6c 69 6e 67 20 73 74 79 6c 65 3d 74 65 78  duling style=tex
0a20: 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f 6e  t-decoration:non
0a30: 65 3e 36 2e 32 2e 33 2e 20 45 78 70 6c 69 63 69  e>6.2.3. Explici
0a40: 74 20 57 6f 72 6b 20 61 6e 64 20 43 68 65 63 6b  t Work and Check
0a50: 70 6f 69 6e 74 20 53 63 68 65 64 75 6c 69 6e 67  point Scheduling
0a60: 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73 70 3b 26  </a><br>.&nbsp;&
0a70: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0a80: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
0a90: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0aa0: 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70  nbsp;&nbsp;&nbsp
0ab0: 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62  ;&nbsp;&nbsp;&nb
0ac0: 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26  sp;&nbsp;&nbsp;&
0ad0: 6e 62 73 70 3b 3c 61 20 68 72 65 66 3d 23 63 6f  nbsp;<a href=#co
0ae0: 6d 70 75 6c 73 61 72 79 5f 77 6f 72 6b 5f 61 6e  mpulsary_work_an
0af0: 64 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 73 63 68  d_checkpoint_sch
0b00: 65 64 75 6c 69 6e 67 20 73 74 79 6c 65 3d 74 65  eduling style=te
0b10: 78 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f  xt-decoration:no
0b20: 6e 65 3e 36 2e 32 2e 34 2e 20 43 6f 6d 70 75 6c  ne>6.2.4. Compul
0b30: 73 61 72 79 20 57 6f 72 6b 20 61 6e 64 20 43 68  sary Work and Ch
0b40: 65 63 6b 70 6f 69 6e 74 20 53 63 68 65 64 75 6c  eckpoint Schedul
0b50: 69 6e 67 3c 2f 61 3e 3c 62 72 3e 0a 26 6e 62 73  ing</a><br>.&nbs
0b60: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
0b70: 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b  bsp;&nbsp;&nbsp;
0b80: 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e 62 73  &nbsp;&nbsp;&nbs
0b90: 70 3b 26 6e 62 73 70 3b 26 6e 62 73 70 3b 26 6e  p;&nbsp;&nbsp;&n
0ba0: 62 73 70 3b 3c 61 20 68 72 65 66 3d 23 64 61 74  bsp;<a href=#dat
0bb0: 61 62 61 73 65 5f 66 69 6c 65 5f 6f 70 74 69 6d  abase_file_optim
0bc0: 69 7a 61 74 69 6f 6e 20 73 74 79 6c 65 3d 74 65  ization style=te
0bd0: 78 74 2d 64 65 63 6f 72 61 74 69 6f 6e 3a 6e 6f  xt-decoration:no
0be0: 6e 65 3e 36 2e 33 2e 20 44 61 74 61 62 61 73 65  ne>6.3. Database
0bf0: 20 46 69 6c 65 20 4f 70 74 69 6d 69 7a 61 74 69   File Optimizati
0c00: 6f 6e 3c 2f 61 3e 3c 62 72 3e 0a 0a 3c 64 69 76  on</a><br>..<div
0c10: 20 69 64 3d 65 6e 64 5f 6f 66 5f 74 6f 63 3e 3c   id=end_of_toc><
0c20: 2f 64 69 76 3e 0a 0a 3c 68 32 3e 4f 76 65 72 76  /div>..<h2>Overv
0c30: 69 65 77 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 69  iew</h2>..<p>Thi
0c40: 73 20 64 6f 63 75 6d 65 6e 74 20 64 65 73 63 72  s document descr
0c50: 69 62 65 73 20 74 68 65 20 4c 53 4d 20 65 6d 62  ibes the LSM emb
0c60: 65 64 64 65 64 20 64 61 74 61 62 61 73 65 20 6c  edded database l
0c70: 69 62 72 61 72 79 20 61 6e 64 20 75 73 65 20 74  ibrary and use t
0c80: 68 65 72 65 6f 66 2e 20 0a 49 74 20 69 73 20 69  hereof. .It is i
0c90: 6e 74 65 6e 64 65 64 20 74 6f 20 62 65 20 70 61  ntended to be pa
0ca0: 72 74 20 75 73 65 72 2d 6d 61 6e 75 61 6c 20 61  rt user-manual a
0cb0: 6e 64 20 70 61 72 74 20 74 75 74 6f 72 69 61 6c  nd part tutorial
0cc0: 2e 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64  . It is intended
0cd0: 20 74 6f 0a 63 6f 6d 70 6c 65 6d 65 6e 74 20 74   to.complement t
0ce0: 68 65 20 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70  he <a href=lsmap
0cf0: 69 2e 77 69 6b 69 3e 4c 53 4d 20 41 50 49 20 72  i.wiki>LSM API r
0d00: 65 66 65 72 65 6e 63 65 20 6d 61 6e 75 61 6c 3c  eference manual<
0d10: 2f 61 3e 2e 0a 0a 3c 70 3e 54 68 65 20 3c 61 20  /a>...<p>The <a 
0d20: 68 72 65 66 3d 23 69 6e 74 72 6f 64 75 63 74 69  href=#introducti
0d30: 6f 6e 5f 74 6f 5f 6c 73 6d 3e 66 69 72 73 74 20  on_to_lsm>first 
0d40: 73 65 63 74 69 6f 6e 3c 2f 61 3e 20 6f 66 20 74  section</a> of t
0d50: 68 69 73 20 64 6f 63 75 6d 65 6e 74 20 63 6f 6e  his document con
0d60: 74 61 69 6e 73 0a 61 20 64 65 73 63 72 69 70 74  tains.a descript
0d70: 69 6f 6e 20 6f 66 20 74 68 65 20 4c 53 4d 20 6c  ion of the LSM l
0d80: 69 62 72 61 72 79 20 61 6e 64 20 69 74 73 20 66  ibrary and its f
0d90: 65 61 74 75 72 65 73 2e 20 0a 3c 61 20 68 72 65  eatures. .<a hre
0da0: 66 3d 23 75 73 69 6e 67 5f 6c 73 6d 5f 69 6e 5f  f=#using_lsm_in_
0db0: 61 70 70 6c 69 63 61 74 69 6f 6e 73 3e 53 65 63  applications>Sec
0dc0: 74 69 6f 6e 20 32 3c 2f 61 3e 20 64 65 73 63 72  tion 2</a> descr
0dd0: 69 62 65 73 20 68 6f 77 20 74 6f 20 75 73 65 20  ibes how to use 
0de0: 4c 53 4d 20 66 72 6f 6d 0a 77 69 74 68 69 6e 20  LSM from.within 
0df0: 61 20 43 20 6f 72 20 43 2b 2b 20 61 70 70 6c 69  a C or C++ appli
0e00: 63 61 74 69 6f 6e 20 28 68 6f 77 20 74 6f 20 63  cation (how to c
0e10: 6f 6d 70 69 6c 65 20 61 6e 64 20 6c 69 6e 6b 20  ompile and link 
0e20: 4c 53 4d 2c 20 77 68 61 74 20 74 6f 20 23 69 6e  LSM, what to #in
0e30: 63 6c 75 64 65 0a 65 74 63 2e 29 2e 20 54 68 65  clude.etc.). The
0e40: 20 3c 61 20 68 72 65 66 3d 23 62 61 73 69 63 5f   <a href=#basic_
0e50: 75 73 61 67 65 3e 74 68 69 72 64 20 73 65 63 74  usage>third sect
0e60: 69 6f 6e 3c 2f 61 3e 20 64 65 73 63 72 69 62 65  ion</a> describe
0e70: 73 20 74 68 65 20 65 73 73 65 6e 74 69 61 6c 20  s the essential 
0e80: 41 50 49 73 0a 74 68 61 74 20 61 70 70 6c 69 63  APIs.that applic
0e90: 61 74 69 6f 6e 73 20 75 73 65 20 74 6f 20 6f 70  ations use to op
0ea0: 65 6e 20 61 6e 64 20 63 6c 6f 73 65 20 64 61 74  en and close dat
0eb0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
0ec0: 73 2c 20 61 6e 64 20 74 6f 20 72 65 61 64 20 66  s, and to read f
0ed0: 72 6f 6d 0a 61 6e 64 20 77 72 69 74 65 20 74 6f  rom.and write to
0ee0: 20 64 61 74 61 62 61 73 65 73 2e 20 0a 0a 3c 70   databases. ..<p
0ef0: 3e 54 68 65 20 74 68 72 65 65 20 73 65 63 74 69  >The three secti
0f00: 6f 6e 73 20 64 65 73 63 72 69 62 65 64 20 61 62  ons described ab
0f10: 6f 76 65 20 63 6f 6e 74 61 69 6e 20 61 6c 6c 20  ove contain all 
0f20: 74 68 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  the information 
0f30: 72 65 71 75 69 72 65 64 20 74 6f 0a 63 72 65 61  required to.crea
0f40: 74 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  te applications 
0f50: 74 68 61 74 20 75 73 65 20 4c 53 4d 2e 20 54 68  that use LSM. Th
0f60: 65 20 72 65 6d 61 69 6e 69 6e 67 20 73 65 63 74  e remaining sect
0f70: 69 6f 6e 73 20 64 69 73 63 75 73 73 20 6d 6f 72  ions discuss mor
0f80: 65 0a 73 70 65 63 69 61 6c 69 7a 65 64 20 74 6f  e.specialized to
0f90: 70 69 63 73 2e 20 3c 61 20 68 72 65 66 3d 23 64  pics. <a href=#d
0fa0: 61 74 61 5f 64 75 72 61 62 69 6c 69 74 79 3e 53  ata_durability>S
0fb0: 65 63 74 69 6f 6e 20 34 3c 2f 61 3e 20 64 69 73  ection 4</a> dis
0fc0: 63 75 73 73 65 73 20 74 68 65 0a 63 6f 6e 66 69  cusses the.confi
0fd0: 67 75 72 61 74 69 6f 6e 20 70 61 72 61 6d 65 74  guration paramet
0fe0: 65 72 20 74 68 61 74 20 69 6e 66 6c 75 65 6e 63  er that influenc
0ff0: 65 73 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 64  es transaction d
1000: 75 72 61 62 69 6c 69 74 79 20 28 74 68 65 20 67  urability (the g
1010: 75 61 72 61 6e 74 65 65 73 0a 6f 66 66 65 72 65  uarantees.offere
1020: 64 20 77 69 74 68 20 72 65 73 70 65 63 74 20 74  d with respect t
1030: 6f 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 6d 69  o recently commi
1040: 74 74 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e  tted transaction
1050: 73 20 69 66 20 61 20 70 6f 77 65 72 20 66 61 69  s if a power fai
1060: 6c 75 72 65 20 0a 6f 63 63 75 72 73 29 2e 20 3c  lure .occurs). <
1070: 61 20 68 72 65 66 3d 23 63 6f 6d 70 72 65 73 73  a href=#compress
1080: 65 64 5f 61 6e 64 5f 65 6e 63 72 79 70 74 65 64  ed_and_encrypted
1090: 5f 64 61 74 61 62 61 73 65 73 3e 53 65 63 74 69  _databases>Secti
10a0: 6f 6e 20 35 3c 2f 61 3e 20 65 78 70 6c 61 69 6e  on 5</a> explain
10b0: 73 0a 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s.the interface 
10c0: 70 72 6f 76 69 64 65 64 20 62 79 20 4c 53 4d 20  provided by LSM 
10d0: 74 68 61 74 20 61 6c 6c 6f 77 20 65 78 74 65 72  that allow exter
10e0: 6e 61 6c 20 64 61 74 61 20 63 6f 6d 70 72 65 73  nal data compres
10f0: 73 69 6f 6e 20 61 6e 64 2f 6f 72 0a 65 6e 63 72  sion and/or.encr
1100: 79 70 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  yption functions
1110: 20 74 6f 20 62 65 20 75 73 65 64 20 74 6f 20 63   to be used to c
1120: 72 65 61 74 65 20 63 6f 6d 70 72 65 73 73 65 64  reate compressed
1130: 20 61 6e 64 2f 6f 72 20 65 6e 63 72 79 70 74 65   and/or encrypte
1140: 64 0a 64 61 74 61 62 61 73 65 73 2e 20 3c 61 20  d.databases. <a 
1150: 68 72 65 66 3d 23 70 65 72 66 6f 72 6d 61 6e 63  href=#performanc
1160: 65 5f 74 75 6e 69 6e 67 3e 53 65 63 74 69 6f 6e  e_tuning>Section
1170: 20 36 3c 2f 61 3e 20 64 65 61 6c 73 20 77 69 74   6</a> deals wit
1180: 68 20 74 68 65 20 74 6f 70 69 63 0a 6f 66 20 70  h the topic.of p
1190: 65 72 66 6f 72 6d 61 6e 63 65 20 74 75 6e 69 6e  erformance tunin
11a0: 67 2e 0a 0a 3c 68 31 20 69 64 3d 69 6e 74 72 6f  g...<h1 id=intro
11b0: 64 75 63 74 69 6f 6e 5f 74 6f 5f 6c 73 6d 3e 31  duction_to_lsm>1
11c0: 2e 20 49 6e 74 72 6f 64 75 63 74 69 6f 6e 20 74  . Introduction t
11d0: 6f 20 4c 53 4d 3c 2f 68 31 3e 0a 0a 3c 70 3e 4c  o LSM</h1>..<p>L
11e0: 53 4d 20 69 73 20 61 6e 20 65 6d 62 65 64 64 65  SM is an embedde
11f0: 64 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61  d database libra
1200: 72 79 20 66 6f 72 20 6b 65 79 2d 76 61 6c 75 65  ry for key-value
1210: 20 64 61 74 61 2c 20 72 6f 75 67 68 6c 79 20 73   data, roughly s
1220: 69 6d 69 6c 61 72 0a 69 6e 20 73 63 6f 70 65 20  imilar.in scope 
1230: 74 6f 0a 3c 61 20 68 72 65 66 3d 22 68 74 74 70  to.<a href="http
1240: 3a 2f 2f 77 77 77 2e 6f 72 61 63 6c 65 2e 63 6f  ://www.oracle.co
1250: 6d 2f 74 65 63 68 6e 65 74 77 6f 72 6b 2f 70 72  m/technetwork/pr
1260: 6f 64 75 63 74 73 2f 62 65 72 6b 65 6c 65 79 64  oducts/berkeleyd
1270: 62 2f 6f 76 65 72 76 69 65 77 2f 69 6e 64 65 78  b/overview/index
1280: 2e 68 74 6d 6c 22 3e 42 65 72 6b 65 6c 65 79 20  .html">Berkeley 
1290: 44 42 3c 2f 61 3e 2c 20 0a 3c 61 20 68 72 65 66  DB</a>, .<a href
12a0: 3d 22 68 74 74 70 3a 2f 2f 63 6f 64 65 2e 67 6f  ="http://code.go
12b0: 6f 67 6c 65 2e 63 6f 6d 2f 70 2f 6c 65 76 65 6c  ogle.com/p/level
12c0: 64 62 2f 22 3e 4c 65 76 65 6c 44 42 3c 2f 61 3e  db/">LevelDB</a>
12d0: 20 6f 72 0a 3c 61 20 68 72 65 66 3d 22 68 74 74   or.<a href="htt
12e0: 70 3a 2f 2f 66 61 6c 6c 61 62 73 2e 63 6f 6d 2f  p://fallabs.com/
12f0: 6b 79 6f 74 6f 63 61 62 69 6e 65 74 2f 22 3e 4b  kyotocabinet/">K
1300: 79 6f 74 6f 43 61 62 69 6e 65 74 3c 2f 61 3e 2e  yotoCabinet</a>.
1310: 0a 42 6f 74 68 20 6b 65 79 73 20 61 6e 64 0a 76  .Both keys and.v
1320: 61 6c 75 65 73 20 61 72 65 20 73 70 65 63 69 66  alues are specif
1330: 69 65 64 20 61 6e 64 20 73 74 6f 72 65 64 20 61  ied and stored a
1340: 73 20 62 79 74 65 20 61 72 72 61 79 73 2e 20 44  s byte arrays. D
1350: 75 70 6c 69 63 61 74 65 20 6b 65 79 73 20 61 72  uplicate keys ar
1360: 65 20 6e 6f 74 20 0a 73 75 70 70 6f 72 74 65 64  e not .supported
1370: 2e 20 4b 65 79 73 20 61 72 65 20 61 6c 77 61 79  . Keys are alway
1380: 73 20 73 6f 72 74 65 64 20 69 6e 20 6d 65 6d 63  s sorted in memc
1390: 6d 70 28 29 20 6f 72 64 65 72 2e 20 4c 53 4d 20  mp() order. LSM 
13a0: 73 75 70 70 6f 72 74 73 20 74 68 65 20 66 6f 6c  supports the fol
13b0: 6c 6f 77 69 6e 67 0a 6f 70 65 72 61 74 69 6f 6e  lowing.operation
13c0: 73 20 66 6f 72 20 74 68 65 20 6d 61 6e 69 70 75  s for the manipu
13d0: 6c 61 74 69 6f 6e 20 61 6e 64 20 71 75 65 72 79  lation and query
13e0: 20 6f 66 20 64 61 74 61 62 61 73 65 20 64 61 74   of database dat
13f0: 61 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20  a:..<ul>.  <li> 
1400: 57 72 69 74 69 6e 67 20 61 20 6e 65 77 20 6b 65  Writing a new ke
1410: 79 20 61 6e 64 20 76 61 6c 75 65 20 69 6e 74 6f  y and value into
1420: 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 20   the database.. 
1430: 20 3c 6c 69 3e 20 44 65 6c 65 74 69 6e 67 20 61   <li> Deleting a
1440: 6e 20 65 78 69 73 74 69 6e 67 20 6b 65 79 20 66  n existing key f
1450: 72 6f 6d 20 74 68 65 20 64 61 74 61 62 61 73 65  rom the database
1460: 2e 0a 20 20 3c 6c 69 3e 20 44 65 6c 65 74 69 6e  ..  <li> Deletin
1470: 67 20 61 20 72 61 6e 67 65 20 6f 66 20 6b 65 79  g a range of key
1480: 73 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  s from the datab
1490: 61 73 65 2e 0a 20 20 3c 6c 69 3e 20 51 75 65 72  ase..  <li> Quer
14a0: 79 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73  ying the databas
14b0: 65 20 66 6f 72 20 61 20 73 70 65 63 69 66 69 63  e for a specific
14c0: 20 6b 65 79 2e 0a 20 20 3c 6c 69 3e 20 49 74 65   key..  <li> Ite
14d0: 72 61 74 69 6e 67 20 74 68 72 6f 75 67 68 20 61  rating through a
14e0: 20 72 61 6e 67 65 20 6f 66 20 64 61 74 61 62 61   range of databa
14f0: 73 65 20 6b 65 79 73 20 28 65 69 74 68 65 72 20  se keys (either 
1500: 66 6f 72 77 61 72 64 73 20 6f 72 0a 20 20 20 20  forwards or.    
1510: 20 20 20 62 61 63 6b 77 61 72 64 73 29 2e 0a 3c     backwards)..<
1520: 2f 75 6c 3e 0a 0a 3c 70 3e 4f 74 68 65 72 20 73  /ul>..<p>Other s
1530: 61 6c 69 65 6e 74 20 66 65 61 74 75 72 65 73 20  alient features 
1540: 61 72 65 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69  are:..<ul>.  <li
1550: 3e 3c 70 3e 4c 53 4d 20 73 75 70 70 6f 72 74 73  ><p>LSM supports
1560: 20 61 20 3c 62 3e 73 69 6e 67 6c 65 2d 77 72 69   a <b>single-wri
1570: 74 65 72 2f 6d 75 6c 74 69 70 6c 65 2d 72 65 61  ter/multiple-rea
1580: 64 65 72 20 4d 56 43 43 3c 2f 62 3e 20 62 61 73  der MVCC</b> bas
1590: 65 64 0a 20 20 20 20 20 20 74 72 61 6e 73 61 63  ed.      transac
15a0: 74 69 6f 6e 61 6c 20 63 6f 6e 63 75 72 72 65 6e  tional concurren
15b0: 63 79 20 6d 6f 64 65 6c 2e 20 53 51 4c 20 73 74  cy model. SQL st
15c0: 79 6c 65 20 6e 65 73 74 65 64 20 73 75 62 2d 74  yle nested sub-t
15d0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 61 72 65 0a  ransactions are.
15e0: 20 20 20 20 20 20 73 75 70 70 6f 72 74 65 64 2e        supported.
15f0: 20 43 6c 69 65 6e 74 73 20 6d 61 79 20 63 6f 6e   Clients may con
1600: 63 75 72 72 65 6e 74 6c 79 20 61 63 63 65 73 73  currently access
1610: 20 61 20 73 69 6e 67 6c 65 20 4c 53 4d 20 64 61   a single LSM da
1620: 74 61 62 61 73 65 20 66 72 6f 6d 0a 20 20 20 20  tabase from.    
1630: 20 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c    within a singl
1640: 65 20 6f 72 20 6d 75 6c 74 69 70 6c 65 20 61 70  e or multiple ap
1650: 70 6c 69 63 61 74 69 6f 6e 20 70 72 6f 63 65 73  plication proces
1660: 73 65 73 2e 20 0a 0a 20 20 3c 6c 69 3e 3c 70 3e  ses. ..  <li><p>
1670: 41 6e 20 65 6e 74 69 72 65 20 4c 53 4d 20 64 61  An entire LSM da
1680: 74 61 62 61 73 65 20 69 73 20 73 74 6f 72 65 64  tabase is stored
1690: 20 69 6e 20 61 20 3c 62 3e 73 69 6e 67 6c 65 20   in a <b>single 
16a0: 66 69 6c 65 20 6f 6e 20 64 69 73 6b 3c 2f 62 3e  file on disk</b>
16b0: 2e 20 0a 0a 20 20 3c 6c 69 3e 3c 70 3e 44 61 74  . ..  <li><p>Dat
16c0: 61 20 3c 62 3e 64 75 72 61 62 69 6c 69 74 79 20  a <b>durability 
16d0: 69 6e 20 74 68 65 20 66 61 63 65 20 6f 66 20 61  in the face of a
16e0: 70 70 6c 69 63 61 74 69 6f 6e 20 6f 72 20 70 6f  pplication or po
16f0: 77 65 72 20 66 61 69 6c 75 72 65 3c 2f 62 3e 2e  wer failure</b>.
1700: 0a 20 20 20 20 20 20 4c 53 4d 20 6d 61 79 20 6f  .      LSM may o
1710: 70 74 69 6f 6e 61 6c 6c 79 20 75 73 65 20 61 20  ptionally use a 
1720: 77 72 69 74 65 2d 61 68 65 61 64 20 6c 6f 67 20  write-ahead log 
1730: 66 69 6c 65 20 77 68 65 6e 20 77 72 69 74 69 6e  file when writin
1740: 67 20 74 6f 20 74 68 65 0a 20 20 20 20 20 20 64  g to the.      d
1750: 61 74 61 62 61 73 65 20 74 6f 20 65 6e 73 75 72  atabase to ensur
1760: 65 20 63 6f 6d 6d 69 74 74 65 64 20 74 72 61 6e  e committed tran
1770: 73 61 63 74 69 6f 6e 73 20 61 72 65 20 6e 6f 74  sactions are not
1780: 20 6c 6f 73 74 20 69 66 20 61 6e 20 61 70 70 6c   lost if an appl
1790: 69 63 61 74 69 6f 6e 0a 20 20 20 20 20 20 6f 72  ication.      or
17a0: 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 20 6f   power failure o
17b0: 63 63 75 72 73 2e 0a 0a 20 20 3c 6c 69 3e 4c 53  ccurs...  <li>LS
17c0: 4d 20 3c 62 3e 6d 61 79 20 62 65 20 63 6f 6e 66  M <b>may be conf
17d0: 69 67 75 72 65 64 20 74 6f 20 75 73 65 20 65 78  igured to use ex
17e0: 74 65 72 6e 61 6c 20 64 61 74 61 20 63 6f 6d 70  ternal data comp
17f0: 72 65 73 73 69 6f 6e 20 61 6e 64 2f 6f 72 0a 20  ression and/or. 
1800: 20 20 20 20 20 65 6e 63 72 79 70 74 69 6f 6e 20       encryption 
1810: 72 6f 75 74 69 6e 65 73 3c 2f 62 3e 20 74 6f 20  routines</b> to 
1820: 63 72 65 61 74 65 20 61 6e 64 20 61 63 63 65 73  create and acces
1830: 73 20 63 6f 6d 70 72 65 73 73 65 64 20 61 6e 64  s compressed and
1840: 2f 6f 72 20 65 6e 63 72 79 70 74 65 64 0a 20 20  /or encrypted.  
1850: 20 20 20 20 64 61 74 61 62 61 73 65 73 2e 0a 3c      databases..<
1860: 2f 75 6c 3e 0a 20 20 20 20 0a 0a 3c 70 3e 4d 61  /ul>.    ..<p>Ma
1870: 6e 79 20 64 61 74 61 62 61 73 65 20 73 79 73 74  ny database syst
1880: 65 6d 73 20 74 68 61 74 20 73 75 70 70 6f 72 74  ems that support
1890: 20 72 61 6e 67 65 20 71 75 65 72 69 65 73 2c 20   range queries, 
18a0: 69 6e 63 6c 75 64 69 6e 67 20 3c 61 0a 68 72 65  including <a.hre
18b0: 66 3d 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71 6c  f=http://www.sql
18c0: 69 74 65 2e 6f 72 67 3e 53 51 4c 69 74 65 20 33  ite.org>SQLite 3
18d0: 3c 2f 61 3e 2c 20 42 65 72 6b 65 6c 65 79 20 44  </a>, Berkeley D
18e0: 42 20 61 6e 64 20 4b 79 6f 74 6f 20 43 61 62 69  B and Kyoto Cabi
18f0: 6e 65 74 2c 20 61 72 65 0a 62 61 73 65 64 20 6f  net, are.based o
1900: 6e 20 6f 6e 65 20 6f 66 20 6d 61 6e 79 20 76 61  n one of many va
1910: 72 69 61 6e 74 73 20 6f 66 20 74 68 65 20 0a 3c  riants of the .<
1920: 61 20 68 72 65 66 3d 22 68 74 74 70 3a 2f 2f 65  a href="http://e
1930: 6e 2e 77 69 6b 69 70 65 64 69 61 2e 6f 72 67 2f  n.wikipedia.org/
1940: 77 69 6b 69 2f 42 2d 74 72 65 65 22 3e 62 2d 74  wiki/B-tree">b-t
1950: 72 65 65 20 64 61 74 61 20 73 74 72 75 63 74 75  ree data structu
1960: 72 65 3c 2f 61 3e 2e 0a 42 2d 74 72 65 65 73 20  re</a>..B-trees 
1970: 61 72 65 20 61 74 74 72 61 63 74 69 76 65 20 62  are attractive b
1980: 65 63 61 75 73 65 20 61 20 62 2d 74 72 65 65 20  ecause a b-tree 
1990: 73 74 72 75 63 74 75 72 65 20 6d 69 6e 69 6d 69  structure minimi
19a0: 7a 65 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  zes the number o
19b0: 66 20 64 69 73 6b 0a 73 65 63 74 6f 72 73 20 74  f disk.sectors t
19c0: 68 61 74 20 6d 75 73 74 20 62 65 20 72 65 61 64  hat must be read
19d0: 20 66 72 6f 6d 20 64 69 73 6b 20 77 68 65 6e 20   from disk when 
19e0: 73 65 61 72 63 68 69 6e 67 20 74 68 65 20 64 61  searching the da
19f0: 74 61 62 61 73 65 20 66 6f 72 20 61 20 73 70 65  tabase for a spe
1a00: 63 69 66 69 63 0a 6b 65 79 2e 20 48 6f 77 65 76  cific.key. Howev
1a10: 65 72 2c 20 62 2d 74 72 65 65 20 69 6d 70 6c 65  er, b-tree imple
1a20: 6d 65 6e 74 61 74 69 6f 6e 73 20 75 73 75 61 6c  mentations usual
1a30: 6c 79 20 73 75 66 66 65 72 20 66 72 6f 6d 20 70  ly suffer from p
1a40: 6f 6f 72 20 77 72 69 74 65 0a 6c 6f 63 61 6c 69  oor write.locali
1a50: 7a 61 74 69 6f 6e 20 2d 20 75 70 64 61 74 69 6e  zation - updatin
1a60: 67 20 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f  g the contents o
1a70: 66 20 61 20 62 2d 74 72 65 65 20 6f 66 74 65 6e  f a b-tree often
1a80: 20 69 6e 76 6f 6c 76 65 73 20 6d 6f 64 69 66 79   involves modify
1a90: 69 6e 67 20 74 68 65 0a 63 6f 6e 74 65 6e 74 73  ing the.contents
1aa0: 20 6f 66 20 6e 6f 64 65 73 20 73 63 61 74 74 65   of nodes scatte
1ab0: 72 65 64 20 74 68 72 6f 75 67 68 6f 75 74 20 74  red throughout t
1ac0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
1ad0: 2e 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73  . If the databas
1ae0: 65 20 69 73 0a 73 74 6f 72 65 64 20 6f 6e 20 61  e is.stored on a
1af0: 20 73 70 69 6e 6e 69 6e 67 20 64 69 73 6b 20 28   spinning disk (
1b00: 48 44 44 29 2c 20 74 68 65 6e 20 74 68 65 20 64  HDD), then the d
1b10: 69 73 6b 20 68 65 61 64 73 20 6d 75 73 74 20 62  isk heads must b
1b20: 65 20 6d 6f 76 65 64 20 62 65 66 6f 72 65 0a 77  e moved before.w
1b30: 72 69 74 69 6e 67 20 6e 6f 6e 2d 63 6f 6e 74 69  riting non-conti
1b40: 67 75 6f 75 73 20 73 65 63 74 6f 72 2c 20 77 68  guous sector, wh
1b50: 69 63 68 20 69 73 20 65 78 74 72 65 6d 65 6c 79  ich is extremely
1b60: 20 73 6c 6f 77 2e 20 49 66 20 74 68 65 20 64 61   slow. If the da
1b70: 74 61 62 61 73 65 20 69 73 0a 73 74 6f 72 65 64  tabase is.stored
1b80: 20 6f 6e 20 73 6f 6c 69 64 20 73 74 61 74 65 20   on solid state 
1b90: 73 74 6f 72 61 67 65 20 28 53 44 44 29 20 61 20  storage (SDD) a 
1ba0: 73 69 6d 69 6c 61 72 20 70 68 65 6e 6f 6d 65 6e  similar phenomen
1bb0: 61 20 69 73 20 65 6e 63 6f 75 6e 74 65 72 65 64  a is encountered
1bc0: 20 64 75 65 20 74 6f 0a 74 68 65 20 6c 61 72 67   due to.the larg
1bd0: 65 20 65 72 61 73 65 2d 62 6c 6f 63 6b 20 73 69  e erase-block si
1be0: 7a 65 73 2e 20 49 6e 20 67 65 6e 65 72 61 6c 2c  zes. In general,
1bf0: 20 77 72 69 74 69 6e 67 20 74 6f 20 61 20 73 65   writing to a se
1c00: 72 69 65 73 20 6f 66 20 63 6f 6e 74 69 67 75 6f  ries of contiguo
1c10: 75 73 20 64 69 73 6b 0a 73 65 63 74 6f 72 73 20  us disk.sectors 
1c20: 69 73 20 6f 72 64 65 72 73 20 6f 66 20 6d 61 67  is orders of mag
1c30: 6e 69 74 75 64 65 20 66 61 73 74 65 72 20 74 68  nitude faster th
1c40: 61 6e 20 75 70 64 61 74 69 6e 67 20 74 6f 20 74  an updating to t
1c50: 68 65 20 73 61 6d 65 20 6e 75 6d 62 65 72 20 6f  he same number o
1c60: 66 20 64 69 73 6b 0a 73 65 63 74 6f 72 73 20 73  f disk.sectors s
1c70: 63 61 74 74 65 72 65 64 20 72 61 6e 64 6f 6d 6c  cattered randoml
1c80: 79 20 74 68 72 6f 75 67 68 6f 75 74 20 61 20 6c  y throughout a l
1c90: 61 72 67 65 20 66 69 6c 65 2e 20 41 64 64 69 74  arge file. Addit
1ca0: 69 6f 6e 61 6c 6c 79 2c 20 62 2d 74 72 65 65 0a  ionally, b-tree.
1cb0: 73 74 72 75 63 74 75 72 65 73 20 61 72 65 20 70  structures are p
1cc0: 72 6f 6e 65 20 74 6f 20 66 72 61 67 6d 65 6e 74  rone to fragment
1cd0: 61 74 69 6f 6e 2c 20 72 65 64 75 63 69 6e 67 20  ation, reducing 
1ce0: 74 68 65 20 73 70 65 65 64 20 6f 66 20 72 61 6e  the speed of ran
1cf0: 67 65 20 71 75 65 72 69 65 73 2e 0a 0a 3c 70 3e  ge queries...<p>
1d00: 3c 69 3e 54 6f 64 6f 3a 20 53 68 6f 75 6c 64 20  <i>Todo: Should 
1d10: 68 61 76 65 20 72 65 66 65 72 65 6e 63 65 73 20  have references 
1d20: 66 6f 72 20 74 68 65 20 63 6c 61 69 6d 73 20 61  for the claims a
1d30: 62 6f 76 65 2e 3c 2f 69 3e 0a 0a 3c 70 3e 3c 69  bove.</i>..<p><i
1d40: 3e 41 6c 73 6f 2c 20 66 69 78 20 74 68 65 20 6c  >Also, fix the l
1d50: 69 6e 6b 20 69 6e 20 74 68 65 20 6e 65 78 74 20  ink in the next 
1d60: 70 61 72 61 67 72 61 70 68 20 74 6f 20 70 6f 69  paragraph to poi
1d70: 6e 74 20 74 6f 20 61 20 64 65 73 63 72 69 70 74  nt to a descript
1d80: 69 6f 6e 0a 6f 66 20 74 68 65 20 6c 6f 67 2d 73  ion.of the log-s
1d90: 74 72 75 63 74 75 72 65 64 2d 6d 65 72 67 65 20  tructured-merge 
1da0: 74 72 65 65 20 77 69 74 68 69 6e 20 6c 73 6d 2e  tree within lsm.
1db0: 77 69 6b 69 20 28 6f 72 20 69 74 73 20 73 75 63  wiki (or its suc
1dc0: 63 65 73 73 6f 72 29 2e 3c 2f 69 3e 0a 0a 3c 70  cessor).</i>..<p
1dd0: 3e 4c 53 4d 20 75 73 65 73 20 61 20 3c 61 20 68  >LSM uses a <a h
1de0: 72 65 66 3d 6c 73 6d 2e 77 69 6b 69 3e 64 69 66  ref=lsm.wiki>dif
1df0: 66 65 72 65 6e 74 20 64 61 74 61 20 73 74 72 75  ferent data stru
1e00: 63 74 75 72 65 3c 2f 61 3e 20 74 68 61 74 20 6d  cture</a> that m
1e10: 61 6b 65 73 20 74 68 65 0a 66 6f 6c 6c 6f 77 69  akes the.followi
1e20: 6e 67 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 74  ng performance t
1e30: 72 61 64 65 6f 66 66 73 20 72 65 6c 61 74 69 76  radeoffs relativ
1e40: 65 20 74 6f 20 61 20 62 2d 74 72 65 65 3a 0a 0a  e to a b-tree:..
1e50: 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 41 20 76 65  <ul>.  <li> A ve
1e60: 72 79 20 6c 61 72 67 65 20 70 65 72 63 65 6e 74  ry large percent
1e70: 61 67 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20  age of the disk 
1e80: 73 65 63 74 6f 72 73 20 6d 6f 64 69 66 69 65 64  sectors modified
1e90: 20 77 68 65 6e 20 77 72 69 74 69 6e 67 20 74 6f   when writing to
1ea0: 0a 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61  .       the data
1eb0: 62 61 73 65 20 61 72 65 20 63 6f 6e 74 69 67 75  base are contigu
1ec0: 6f 75 73 2e 0a 20 20 20 20 20 20 20 41 64 64 69  ous..       Addi
1ed0: 74 69 6f 6e 61 6c 6c 79 2c 20 69 6e 20 6d 61 6e  tionally, in man
1ee0: 79 20 63 61 73 65 73 20 74 68 65 20 74 6f 74 61  y cases the tota
1ef0: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 73 65 63 74  l number of sect
1f00: 6f 72 73 20 77 72 69 74 74 65 6e 0a 20 20 20 20  ors written.    
1f10: 20 20 20 74 6f 20 64 69 73 6b 20 69 73 20 72 65     to disk is re
1f20: 64 75 63 65 64 2e 20 54 68 69 73 20 6d 61 6b 65  duced. This make
1f30: 73 20 77 72 69 74 69 6e 67 20 74 6f 20 61 6e 20  s writing to an 
1f40: 4c 53 4d 20 64 61 74 61 62 61 73 65 20 6d 75 63  LSM database muc
1f50: 68 0a 20 20 20 20 20 20 20 66 61 73 74 65 72 20  h.       faster 
1f60: 74 68 61 6e 20 74 68 65 20 65 71 75 69 76 61 6c  than the equival
1f70: 65 6e 74 20 62 2d 74 72 65 65 2e 0a 0a 20 20 3c  ent b-tree...  <
1f80: 6c 69 3e 20 4c 53 4d 20 64 61 74 61 62 61 73 65  li> LSM database
1f90: 73 20 64 6f 20 6e 6f 74 20 73 75 66 66 65 72 20  s do not suffer 
1fa0: 66 72 6f 6d 20 66 72 61 67 6d 65 6e 74 61 74 69  from fragmentati
1fb0: 6f 6e 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64  on to the same d
1fc0: 65 67 72 65 65 0a 20 20 20 20 20 20 20 61 73 20  egree.       as 
1fd0: 62 2d 74 72 65 65 73 2e 20 54 68 69 73 20 6d 65  b-trees. This me
1fe0: 61 6e 73 20 74 68 61 74 20 74 68 65 20 70 65 72  ans that the per
1ff0: 66 6f 72 6d 61 6e 63 65 20 6f 66 20 6c 61 72 67  formance of larg
2000: 65 20 72 61 6e 67 65 20 71 75 65 72 69 65 73 20  e range queries 
2010: 0a 20 20 20 20 20 20 20 64 6f 65 73 20 6e 6f 74  .       does not
2020: 20 64 65 67 72 61 64 65 20 61 73 20 74 68 65 20   degrade as the 
2030: 64 61 74 61 62 61 73 65 20 69 73 20 75 70 64 61  database is upda
2040: 74 65 64 20 61 73 20 69 74 20 6d 61 79 20 77 69  ted as it may wi
2050: 74 68 20 61 20 62 2d 74 72 65 65 2e 0a 0a 20 20  th a b-tree...  
2060: 3c 6c 69 3e 20 49 74 20 69 73 20 61 63 63 65 70  <li> It is accep
2070: 74 65 64 20 74 68 61 74 20 75 6e 64 65 72 20 73  ted that under s
2080: 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ome circumstance
2090: 73 20 73 65 61 72 63 68 69 6e 67 20 61 6e 20 4c  s searching an L
20a0: 53 4d 20 0a 20 20 20 20 20 20 20 64 61 74 61 62  SM .       datab
20b0: 61 73 65 20 66 6f 72 20 61 20 67 69 76 65 6e 20  ase for a given 
20c0: 6b 65 79 20 77 69 6c 6c 20 69 6e 76 6f 6c 76 65  key will involve
20d0: 20 65 78 61 6d 69 6e 69 6e 67 20 6d 6f 72 65 20   examining more 
20e0: 64 69 73 6b 20 73 65 63 74 6f 72 73 0a 20 20 20  disk sectors.   
20f0: 20 20 20 20 74 68 61 6e 20 69 74 20 77 6f 75 6c      than it woul
2100: 64 20 77 69 74 68 20 61 20 62 2d 74 72 65 65 2e  d with a b-tree.
2110: 20 49 6e 20 74 65 72 6d 73 20 6f 66 20 64 69 73   In terms of dis
2120: 6b 20 73 65 63 74 6f 72 73 20 61 63 63 65 73 73  k sectors access
2130: 65 64 20 77 68 65 6e 0a 20 20 20 20 20 20 20 73  ed when.       s
2140: 65 61 72 63 68 69 6e 67 20 61 20 64 61 74 61 62  earching a datab
2150: 61 73 65 20 6f 66 20 73 69 7a 65 20 4e 2c 20 62  ase of size N, b
2160: 6f 74 68 20 62 2d 74 72 65 65 73 20 61 6e 64 20  oth b-trees and 
2170: 4c 53 4d 20 70 72 6f 76 69 64 65 20 4f 28 6c 6f  LSM provide O(lo
2180: 67 28 4e 29 29 0a 20 20 20 20 20 20 20 65 66 66  g(N)).       eff
2190: 69 63 69 65 6e 63 79 2c 20 62 75 74 20 74 68 65  iciency, but the
21a0: 20 62 61 73 65 20 6f 66 20 74 68 65 20 6c 6f 67   base of the log
21b0: 61 72 69 74 68 6d 20 69 73 20 67 65 6e 65 72 61  arithm is genera
21c0: 6c 6c 79 20 6c 61 72 67 65 72 20 66 6f 72 20 61  lly larger for a
21d0: 0a 20 20 20 20 20 20 20 62 2d 74 72 65 65 20 74  .       b-tree t
21e0: 68 61 6e 20 66 6f 72 20 4c 53 4d 2e 0a 3c 2f 75  han for LSM..</u
21f0: 6c 3e 0a 0a 3c 70 3e 49 6e 20 6f 74 68 65 72 20  l>..<p>In other 
2200: 77 6f 72 64 73 2c 20 77 72 69 74 69 6e 67 20 74  words, writing t
2210: 6f 20 61 6e 20 4c 53 4d 20 64 61 74 61 62 61 73  o an LSM databas
2220: 65 20 73 68 6f 75 6c 64 20 62 65 20 76 65 72 79  e should be very
2230: 20 66 61 73 74 20 61 6e 64 20 73 63 61 6e 6e 69   fast and scanni
2240: 6e 67 0a 74 68 72 6f 75 67 68 20 6c 61 72 67 65  ng.through large
2250: 20 72 61 6e 67 65 73 20 6f 66 20 6b 65 79 73 20   ranges of keys 
2260: 73 68 6f 75 6c 64 20 61 6c 73 6f 20 70 65 72 66  should also perf
2270: 6f 72 6d 20 77 65 6c 6c 2c 20 62 75 74 20 73 65  orm well, but se
2280: 61 72 63 68 69 6e 67 20 74 68 65 0a 64 61 74 61  arching the.data
2290: 62 61 73 65 20 66 6f 72 20 73 70 65 63 69 66 69  base for specifi
22a0: 63 20 6b 65 79 73 20 6d 61 79 20 62 65 20 73 6c  c keys may be sl
22b0: 69 67 68 74 6c 79 20 73 6c 6f 77 65 72 20 74 68  ightly slower th
22c0: 61 6e 20 77 68 65 6e 20 75 73 69 6e 67 20 61 20  an when using a 
22d0: 62 2d 74 72 65 65 0a 62 61 73 65 64 20 73 79 73  b-tree.based sys
22e0: 74 65 6d 2e 20 41 64 64 69 74 69 6f 6e 61 6c 6c  tem. Additionall
22f0: 79 2c 20 61 76 6f 69 64 69 6e 67 20 72 61 6e 64  y, avoiding rand
2300: 6f 6d 20 77 72 69 74 65 73 20 69 6e 20 66 61 76  om writes in fav
2310: 6f 75 72 20 6f 66 20 6c 61 72 67 65 6c 79 0a 63  our of largely.c
2320: 6f 6e 74 69 67 75 6f 75 73 20 75 70 64 61 74 65  ontiguous update
2330: 73 20 28 61 73 20 4c 53 4d 20 64 6f 65 73 29 20  s (as LSM does) 
2340: 63 61 6e 20 73 69 67 6e 69 66 69 63 61 6e 74 6c  can significantl
2350: 79 20 72 65 64 75 63 65 20 74 68 65 20 77 65 61  y reduce the wea
2360: 72 20 6f 6e 20 53 53 44 20 6f 72 0a 66 6c 61 73  r on SSD or.flas
2370: 68 20 6d 65 6d 6f 72 79 20 64 65 76 69 63 65 73  h memory devices
2380: 2e 0a 0a 3c 70 3e 41 6c 74 68 6f 75 67 68 20 69  ...<p>Although i
2390: 74 20 68 61 73 20 71 75 69 74 65 20 64 69 66 66  t has quite diff
23a0: 65 72 65 6e 74 20 66 65 61 74 75 72 65 73 20 74  erent features t
23b0: 6f 20 4c 53 4d 20 69 6e 20 6f 74 68 65 72 20 72  o LSM in other r
23c0: 65 73 70 65 63 74 73 2c 20 0a 4c 65 76 65 6c 44  espects, .LevelD
23d0: 42 20 6d 61 6b 65 73 20 73 69 6d 69 6c 61 72 20  B makes similar 
23e0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 74 72 61 64  performance trad
23f0: 65 6f 66 66 73 2e 0a 0a 3c 70 3e 42 65 6e 63 68  eoffs...<p>Bench
2400: 6d 61 72 6b 20 74 65 73 74 20 72 65 73 75 6c 74  mark test result
2410: 73 20 66 6f 72 20 4c 53 4d 20 61 72 65 20 3c 61  s for LSM are <a
2420: 20 68 72 65 66 3d 23 3e 61 76 61 69 6c 61 62 6c   href=#>availabl
2430: 65 20 68 65 72 65 3c 2f 61 3e 2e 20 3c 69 3e 54  e here</a>. <i>T
2440: 6f 64 6f 3a 0a 46 69 78 20 74 68 69 73 20 6c 69  odo:.Fix this li
2450: 6e 6b 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61  nk to point to a
2460: 20 70 61 67 65 20 77 69 74 68 20 70 65 72 66 6f   page with perfo
2470: 72 6d 61 6e 63 65 20 67 72 61 70 68 73 2e 3c 2f  rmance graphs.</
2480: 69 3e 0a 0a 0a 3c 68 31 20 69 64 3d 75 73 69 6e  i>...<h1 id=usin
2490: 67 5f 6c 73 6d 5f 69 6e 5f 61 70 70 6c 69 63 61  g_lsm_in_applica
24a0: 74 69 6f 6e 73 3e 32 2e 20 55 73 69 6e 67 20 4c  tions>2. Using L
24b0: 53 4d 20 69 6e 20 41 70 70 6c 69 63 61 74 69 6f  SM in Applicatio
24c0: 6e 73 20 3c 2f 68 31 3e 0a 0a 3c 70 3e 4c 53 4d  ns </h1>..<p>LSM
24d0: 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c   is not currentl
24e0: 79 20 62 75 69 6c 74 20 6f 72 20 64 69 73 74 72  y built or distr
24f0: 69 62 75 74 65 64 20 69 6e 64 65 70 65 6e 64 65  ibuted independe
2500: 6e 74 6c 79 2e 20 49 6e 73 74 65 61 64 2c 20 69  ntly. Instead, i
2510: 74 0a 69 73 20 70 61 72 74 20 6f 66 20 74 68 65  t.is part of the
2520: 20 53 51 4c 69 74 65 34 20 6c 69 62 72 61 72 79   SQLite4 library
2530: 2e 20 54 6f 20 75 73 65 20 4c 53 4d 20 69 6e 20  . To use LSM in 
2540: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  an application, 
2550: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  the application.
2560: 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 6c 69  links against li
2570: 62 73 71 6c 69 74 65 34 20 61 6e 64 20 69 6e 63  bsqlite4 and inc
2580: 6c 75 64 65 73 20 74 68 65 20 68 65 61 64 65 72  ludes the header
2590: 20 66 69 6c 65 20 22 6c 73 6d 2e 68 22 20 69 6e   file "lsm.h" in
25a0: 20 61 6e 79 20 66 69 6c 65 73 0a 74 68 61 74 20   any files.that 
25b0: 61 63 63 65 73 73 20 74 68 65 20 4c 53 4d 20 41  access the LSM A
25c0: 50 49 2e 0a 0a 3c 70 3e 3c 69 3e 50 6f 69 6e 74  PI...<p><i>Point
25d0: 65 72 20 74 6f 20 62 75 69 6c 64 20 69 6e 73 74  er to build inst
25e0: 72 75 63 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c  ructions for sql
25f0: 69 74 65 34 3c 2f 69 3e 0a 0a 3c 68 31 20 69 64  ite4</i>..<h1 id
2600: 3d 62 61 73 69 63 5f 75 73 61 67 65 3e 33 2e 20  =basic_usage>3. 
2610: 42 61 73 69 63 20 55 73 61 67 65 3c 2f 68 31 3e  Basic Usage</h1>
2620: 0a 0a 3c 68 32 20 69 64 3d 6f 70 65 6e 69 6e 67  ..<h2 id=opening
2630: 5f 61 6e 64 5f 63 6c 6f 73 69 6e 67 5f 64 61 74  _and_closing_dat
2640: 61 62 61 73 65 5f 63 6f 6e 6e 65 63 74 69 6f 6e  abase_connection
2650: 73 3e 33 2e 31 2e 20 4f 70 65 6e 69 6e 67 20 61  s>3.1. Opening a
2660: 6e 64 20 43 6c 6f 73 69 6e 67 20 44 61 74 61 62  nd Closing Datab
2670: 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase Connections 
2680: 3c 2f 68 32 3e 0a 0a 3c 70 3e 4f 70 65 6e 69 6e  </h2>..<p>Openin
2690: 67 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  g a connection t
26a0: 6f 20 61 20 64 61 74 61 62 61 73 65 20 69 73 20  o a database is 
26b0: 61 20 74 77 6f 2d 73 74 65 70 20 70 72 6f 63 65  a two-step proce
26c0: 73 73 2e 20 54 68 65 20 0a 3c 61 20 68 72 65 66  ss. The .<a href
26d0: 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23 6c 73 6d  =lsmapi.wiki#lsm
26e0: 5f 6e 65 77 3e 6c 73 6d 5f 6e 65 77 28 29 3c 2f  _new>lsm_new()</
26f0: 61 3e 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  a> function is u
2700: 73 65 64 20 74 6f 20 63 72 65 61 74 65 20 61 20  sed to create a 
2710: 6e 65 77 0a 64 61 74 61 62 61 73 65 20 68 61 6e  new.database han
2720: 64 6c 65 2c 20 61 6e 64 20 74 68 65 20 3c 61 20  dle, and the <a 
2730: 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69  href=lsmapi.wiki
2740: 23 6c 73 6d 5f 6f 70 65 6e 3e 6c 73 6d 5f 6f 70  #lsm_open>lsm_op
2750: 65 6e 28 29 3c 2f 61 3e 20 66 75 6e 63 74 69 6f  en()</a> functio
2760: 6e 20 0a 69 73 20 75 73 65 64 20 74 6f 20 63 6f  n .is used to co
2770: 6e 6e 65 63 74 20 61 6e 20 65 78 69 73 74 69 6e  nnect an existin
2780: 67 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c  g database handl
2790: 65 20 74 6f 20 61 20 64 61 74 61 62 61 73 65 20  e to a database 
27a0: 6f 6e 20 64 69 73 6b 2e 20 54 68 69 73 0a 69 73  on disk. This.is
27b0: 20 62 65 63 61 75 73 65 20 73 6f 6d 65 20 64 61   because some da
27c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
27d0: 6e 20 70 72 6f 70 65 72 74 69 65 73 20 6d 61 79  n properties may
27e0: 20 6f 6e 6c 79 20 62 65 20 63 6f 6e 66 69 67 75   only be configu
27f0: 72 65 64 0a 62 65 66 6f 72 65 20 74 68 65 20 64  red.before the d
2800: 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
2810: 64 2e 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  d. In that case,
2820: 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c   one or more cal
2830: 6c 73 20 74 6f 20 74 68 65 20 0a 3c 61 20 68 72  ls to the .<a hr
2840: 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23 6c  ef=lsmapi.wiki#l
2850: 73 6d 5f 63 6f 6e 66 69 67 3e 6c 73 6d 5f 63 6f  sm_config>lsm_co
2860: 6e 66 69 67 28 29 3c 2f 61 3e 20 6d 65 74 68 6f  nfig()</a> metho
2870: 64 20 61 72 65 20 6d 61 64 65 20 62 65 74 77 65  d are made betwe
2880: 65 6e 20 74 68 65 0a 63 61 6c 6c 73 20 74 6f 20  en the.calls to 
2890: 6c 73 6d 5f 6e 65 77 28 29 20 61 6e 64 20 6c 73  lsm_new() and ls
28a0: 6d 5f 6f 70 65 6e 28 29 2e 0a 0a 3c 70 3e 54 68  m_open()...<p>Th
28b0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
28c0: 64 65 66 69 6e 65 64 20 61 73 20 66 6f 6c 6c 6f  defined as follo
28d0: 77 73 3a 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a  ws:..<verbatim>.
28e0: 20 20 69 6e 74 20 6c 73 6d 5f 6e 65 77 28 6c 73    int lsm_new(ls
28f0: 6d 5f 65 6e 76 20 2a 65 6e 76 2c 20 6c 73 6d 5f  m_env *env, lsm_
2900: 64 62 20 2a 2a 70 44 62 29 3b 0a 20 20 69 6e 74  db **pDb);.  int
2910: 20 6c 73 6d 5f 6f 70 65 6e 28 6c 73 6d 5f 64 62   lsm_open(lsm_db
2920: 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68 61 72   *db, const char
2930: 20 2a 7a 46 69 6c 65 29 3b 0a 3c 2f 76 65 72 62   *zFile);.</verb
2940: 61 74 69 6d 3e 0a 0a 3c 70 3e 4c 69 6b 65 20 6d  atim>..<p>Like m
2950: 6f 73 74 20 6c 73 6d 5f 78 78 78 28 29 20 66 75  ost lsm_xxx() fu
2960: 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 72 65 74  nctions that ret
2970: 75 72 6e 20 74 79 70 65 20 69 6e 74 20 28 74 68  urn type int (th
2980: 65 20 65 78 63 65 70 74 69 6f 6e 20 69 73 0a 3c  e exception is.<
2990: 61 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69  a href=lsmapi.wi
29a0: 6b 69 23 6c 73 6d 5f 63 73 72 5f 76 61 6c 69 64  ki#lsm_csr_valid
29b0: 3e 6c 73 6d 5f 63 73 72 5f 76 61 6c 69 64 28 29  >lsm_csr_valid()
29c0: 3c 2f 61 3e 29 2c 20 62 6f 74 68 20 6f 66 20 74  </a>), both of t
29d0: 68 65 20 61 62 6f 76 65 20 0a 72 65 74 75 72 6e  he above .return
29e0: 20 4c 53 4d 5f 4f 4b 20 28 30 29 20 69 66 20 73   LSM_OK (0) if s
29f0: 75 63 63 65 73 73 66 75 6c 2c 20 6f 72 20 61 6e  uccessful, or an
2a00: 20 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e   <a href=lsmapi.
2a10: 77 69 6b 69 23 4c 53 4d 5f 45 52 52 4f 52 3e 4c  wiki#LSM_ERROR>L
2a20: 53 4d 20 0a 65 72 72 6f 72 20 63 6f 64 65 3c 2f  SM .error code</
2a30: 61 3e 20 6f 74 68 65 72 77 69 73 65 2e 20 54 68  a> otherwise. Th
2a40: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
2a50: 20 74 6f 20 6c 73 6d 5f 6e 65 77 28 29 20 6d 61   to lsm_new() ma
2a60: 79 20 62 65 20 70 61 73 73 65 64 20 65 69 74 68  y be passed eith
2a70: 65 72 0a 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  er.a pointer to 
2a80: 61 20 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70 69  a <a href=lsmapi
2a90: 2e 77 69 6b 69 23 6c 73 6d 5f 65 6e 76 3e 64 61  .wiki#lsm_env>da
2aa0: 74 61 62 61 73 65 20 65 6e 76 69 72 6f 6e 6d 65  tabase environme
2ab0: 6e 74 20 6f 62 6a 65 63 74 3c 2f 61 3e 0a 6f 72  nt object</a>.or
2ac0: 20 4e 55 4c 4c 2e 20 41 6c 6d 6f 73 74 20 61 6c   NULL. Almost al
2ad0: 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73  l applications s
2ae0: 68 6f 75 6c 64 20 70 61 73 73 20 4e 55 4c 4c 2e  hould pass NULL.
2af0: 20 41 20 64 61 74 61 62 61 73 65 20 65 6e 76 69   A database envi
2b00: 72 6f 6e 6d 65 6e 74 0a 6f 62 6a 65 63 74 20 61  ronment.object a
2b10: 6c 6c 6f 77 73 20 74 68 65 20 61 70 70 6c 69 63  llows the applic
2b20: 61 74 69 6f 6e 20 74 6f 20 73 75 70 70 6c 79 20  ation to supply 
2b30: 63 75 73 74 6f 6d 20 69 6d 70 6c 65 6d 65 6e 74  custom implement
2b40: 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 76 61  ations of the va
2b50: 72 69 6f 75 73 0a 6f 70 65 72 61 74 69 6e 67 20  rious.operating 
2b60: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
2b70: 74 20 4c 53 4d 20 75 73 65 73 20 74 6f 20 72 65  t LSM uses to re
2b80: 61 64 20 61 6e 64 20 77 72 69 74 65 20 66 69 6c  ad and write fil
2b90: 65 73 2c 20 61 6c 6c 6f 63 61 74 65 20 68 65 61  es, allocate hea
2ba0: 70 20 0a 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 63  p .memory, and c
2bb0: 6f 6f 72 64 69 6e 61 74 65 20 62 65 74 77 65 65  oordinate betwee
2bc0: 6e 20 6d 75 6c 74 69 70 6c 65 20 61 70 70 6c 69  n multiple appli
2bd0: 63 61 74 69 6f 6e 20 74 68 72 65 61 64 73 20 61  cation threads a
2be0: 6e 64 20 70 72 6f 63 65 73 73 65 73 2e 0a 54 68  nd processes..Th
2bf0: 69 73 20 69 73 20 6e 6f 72 6d 61 6c 6c 79 20 6f  is is normally o
2c00: 6e 6c 79 20 72 65 71 75 69 72 65 64 20 69 66 20  nly required if 
2c10: 4c 53 4d 20 69 73 20 62 65 69 6e 67 20 75 73 65  LSM is being use
2c20: 64 20 6f 6e 20 61 20 70 6c 61 74 66 6f 72 6d 20  d on a platform 
2c30: 74 68 61 74 20 69 73 20 6e 6f 74 0a 73 75 70 70  that is not.supp
2c40: 6f 72 74 65 64 20 62 79 20 64 65 66 61 75 6c 74  orted by default
2c50: 2e 20 50 61 73 73 69 6e 67 20 4e 55 4c 4c 20 69  . Passing NULL i
2c60: 6e 73 74 72 75 63 74 73 20 74 68 65 20 6c 69 62  nstructs the lib
2c70: 72 61 72 79 20 74 6f 20 75 73 65 20 74 68 65 20  rary to use the 
2c80: 64 65 66 61 75 6c 74 0a 69 6d 70 6c 65 6d 65 6e  default.implemen
2c90: 74 61 74 69 6f 6e 73 20 6f 66 20 61 6c 6c 20 74  tations of all t
2ca0: 68 65 73 65 20 74 68 69 6e 67 73 2c 20 77 68 69  hese things, whi
2cb0: 63 68 20 69 73 20 75 73 75 61 6c 6c 79 20 74 68  ch is usually th
2cc0: 65 20 72 69 67 68 74 20 74 68 69 6e 67 20 74 6f  e right thing to
2cd0: 20 64 6f 2e 0a 54 68 65 20 73 65 63 6f 6e 64 20   do..The second 
2ce0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 6c 73 6d 5f  argument to lsm_
2cf0: 6e 65 77 28 29 20 69 73 20 61 6e 20 6f 75 74 70  new() is an outp
2d00: 75 74 20 76 61 72 69 61 62 6c 65 2e 20 41 73 73  ut variable. Ass
2d10: 75 6d 69 6e 67 20 74 68 65 20 63 61 6c 6c 0a 69  uming the call.i
2d20: 73 20 73 75 63 63 65 73 73 66 75 6c 2c 20 2a 70  s successful, *p
2d30: 44 62 20 69 73 20 73 65 74 20 74 6f 20 70 6f 69  Db is set to poi
2d40: 6e 74 20 74 6f 20 74 68 65 20 6e 65 77 20 64 61  nt to the new da
2d50: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 62 65  tabase handle be
2d60: 66 6f 72 65 20 0a 72 65 74 75 72 6e 69 6e 67 2e  fore .returning.
2d70: 0a 0a 3c 70 3e 54 68 65 20 66 69 72 73 74 20 61  ..<p>The first a
2d80: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
2d90: 6f 20 6c 73 6d 5f 6f 70 65 6e 28 29 20 6d 75 73  o lsm_open() mus
2da0: 74 20 62 65 20 61 6e 20 65 78 69 73 74 69 6e 67  t be an existing
2db0: 20 64 61 74 61 62 61 73 65 20 0a 68 61 6e 64 6c   database .handl
2dc0: 65 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 69 73  e. The second is
2dd0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
2de0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74   database file t
2df0: 6f 20 63 6f 6e 6e 65 63 74 20 74 6f 2e 20 4f 6e  o connect to. On
2e00: 63 65 0a 6c 73 6d 5f 6f 70 65 6e 28 29 20 68 61  ce.lsm_open() ha
2e10: 73 20 62 65 65 6e 20 73 75 63 63 65 73 73 66 75  s been successfu
2e20: 6c 6c 79 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20  lly called on a 
2e30: 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 2c  database handle,
2e40: 20 69 74 20 63 61 6e 20 6e 6f 74 20 62 65 0a 63   it can not be.c
2e50: 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
2e60: 68 65 20 73 61 6d 65 20 68 61 6e 64 6c 65 2e 20  he same handle. 
2e70: 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 64 6f  Attempting to do
2e80: 20 73 6f 20 69 73 20 61 6e 20 4c 53 4d 5f 4d 49   so is an LSM_MI
2e90: 53 55 53 45 20 65 72 72 6f 72 2e 0a 0a 3c 70 3e  SUSE error...<p>
2ea0: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f 20  For example, to 
2eb0: 63 72 65 61 74 65 20 61 20 6e 65 77 20 68 61 6e  create a new han
2ec0: 64 6c 65 20 61 6e 64 20 63 6f 6e 6e 65 63 74 20  dle and connect 
2ed0: 69 74 20 74 6f 20 64 61 74 61 62 61 73 65 20 22  it to database "
2ee0: 74 65 73 74 2e 64 62 22 0a 6f 6e 20 64 69 73 6b  test.db".on disk
2ef0: 3a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20 20 69  :.<verbatim>.  i
2f00: 6e 74 20 72 63 3b 0a 20 20 6c 73 6d 5f 64 62 20  nt rc;.  lsm_db 
2f10: 2a 64 62 3b 0a 0a 20 20 2f 2a 20 41 6c 6c 6f 63  *db;..  /* Alloc
2f20: 61 74 65 20 61 20 6e 65 77 20 64 61 74 61 62 61  ate a new databa
2f30: 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 72  se handle */.  r
2f40: 63 20 3d 20 6c 73 6d 5f 6e 65 77 28 30 2c 20 26  c = lsm_new(0, &
2f50: 64 62 29 3b 0a 20 20 69 66 28 20 72 63 21 3d 4c  db);.  if( rc!=L
2f60: 53 4d 5f 4f 4b 20 29 20 65 78 69 74 28 31 29 3b  SM_OK ) exit(1);
2f70: 0a 0a 20 20 2f 2a 20 43 6f 6e 6e 65 63 74 20 74  ..  /* Connect t
2f80: 68 65 20 64 61 74 61 62 61 73 65 20 68 61 6e 64  he database hand
2f90: 6c 65 20 74 6f 20 64 61 74 61 62 61 73 65 20 22  le to database "
2fa0: 74 65 73 74 2e 64 62 22 20 2a 2f 0a 20 20 72 63  test.db" */.  rc
2fb0: 20 3d 20 6c 73 6d 5f 6f 70 65 6e 28 64 62 2c 20   = lsm_open(db, 
2fc0: 22 74 65 73 74 2e 64 62 22 29 3b 0a 20 20 69 66  "test.db");.  if
2fd0: 28 20 72 63 21 3d 4c 53 4d 5f 4f 4b 20 29 20 65  ( rc!=LSM_OK ) e
2fe0: 78 69 74 28 31 29 3b 0a 3c 2f 76 65 72 62 61 74  xit(1);.</verbat
2ff0: 69 6d 3e 0a 0a 3c 70 3e 41 20 64 61 74 61 62 61  im>..<p>A databa
3000: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
3010: 6e 20 62 65 20 63 6c 6f 73 65 64 20 75 73 69 6e  n be closed usin
3020: 67 20 74 68 65 20 6c 73 6d 5f 63 6c 6f 73 65 28  g the lsm_close(
3030: 29 20 66 75 6e 63 74 69 6f 6e 2e 20 43 61 6c 6c  ) function. Call
3040: 69 6e 67 0a 6c 73 6d 5f 63 6c 6f 73 65 28 29 20  ing.lsm_close() 
3050: 64 69 73 63 6f 6e 6e 65 63 74 73 20 66 72 6f 6d  disconnects from
3060: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28 61   the database (a
3070: 73 73 75 6d 69 6e 67 20 6c 73 6d 5f 6f 70 65 6e  ssuming lsm_open
3080: 28 29 20 68 61 73 20 62 65 65 6e 0a 73 75 63 63  () has been.succ
3090: 65 73 73 66 75 6c 6c 79 20 63 61 6c 6c 65 64 29  essfully called)
30a0: 20 61 6e 64 20 64 65 6c 65 74 65 73 20 74 68 65   and deletes the
30b0: 20 68 61 6e 64 6c 65 20 69 74 73 65 6c 66 2e 20   handle itself. 
30c0: 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 75 73  Attempting to us
30d0: 65 20 61 0a 64 61 74 61 62 61 73 65 20 68 61 6e  e a.database han
30e0: 64 6c 65 20 61 66 74 65 72 20 69 74 20 68 61 73  dle after it has
30f0: 20 62 65 65 6e 20 70 61 73 73 65 64 20 74 6f 20   been passed to 
3100: 6c 73 6d 5f 63 6c 6f 73 65 28 29 20 72 65 73 75  lsm_close() resu
3110: 6c 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64  lts in undefined
3120: 0a 62 65 68 61 76 69 6f 75 72 20 28 6c 69 6b 65  .behaviour (like
3130: 6c 79 20 61 20 73 65 67 66 61 75 6c 74 29 2e 0a  ly a segfault)..
3140: 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20 20 72 63  .<verbatim>.  rc
3150: 20 3d 20 6c 73 6d 5f 63 6c 6f 73 65 28 64 62 29   = lsm_close(db)
3160: 3b 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c  ;.</verbatim>..<
3170: 70 3e 49 74 20 69 73 20 69 6d 70 6f 72 74 61 6e  p>It is importan
3180: 74 20 74 68 61 74 20 6c 73 6d 5f 63 6c 6f 73 65  t that lsm_close
3190: 28 29 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  () is called to 
31a0: 63 6c 6f 73 65 20 61 6c 6c 20 64 61 74 61 62 61  close all databa
31b0: 73 65 20 68 61 6e 64 6c 65 73 0a 63 72 65 61 74  se handles.creat
31c0: 65 64 20 77 69 74 68 20 6c 73 6d 5f 6e 65 77 28  ed with lsm_new(
31d0: 29 2c 20 70 61 72 74 69 63 75 6c 61 72 6c 79 20  ), particularly 
31e0: 69 66 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  if the connectio
31f0: 6e 20 68 61 73 20 77 72 69 74 74 65 6e 20 74 6f  n has written to
3200: 20 74 68 65 0a 64 61 74 61 62 61 73 65 2e 20 49   the.database. I
3210: 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
3220: 20 74 68 61 74 20 68 61 73 20 77 72 69 74 74 65   that has writte
3230: 6e 20 74 6f 20 61 20 64 61 74 61 62 61 73 65 20  n to a database 
3240: 65 78 69 74 73 20 77 69 74 68 6f 75 74 0a 63 6c  exits without.cl
3250: 6f 73 69 6e 67 20 69 74 73 20 64 61 74 61 62 61  osing its databa
3260: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
3270: 68 65 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63  hen subsequent c
3280: 6c 69 65 6e 74 73 20 6d 61 79 20 68 61 76 65 20  lients may have 
3290: 74 6f 20 72 75 6e 0a 22 64 61 74 61 62 61 73 65  to run."database
32a0: 20 72 65 63 6f 76 65 72 79 22 20 77 68 65 6e 20   recovery" when 
32b0: 74 68 65 79 20 6f 70 65 6e 20 74 68 65 20 64 61  they open the da
32c0: 74 61 62 61 73 65 2c 20 6d 61 6b 69 6e 67 20 74  tabase, making t
32d0: 68 65 20 6c 73 6d 5f 6f 70 65 6e 28 29 20 63 61  he lsm_open() ca
32e0: 6c 6c 0a 6c 65 73 73 20 72 65 73 70 6f 6e 73 69  ll.less responsi
32f0: 76 65 2e 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79  ve. Additionally
3300: 2c 20 6e 6f 74 20 6d 61 74 63 68 69 6e 67 20 65  , not matching e
3310: 61 63 68 20 73 75 63 63 65 73 73 66 75 6c 20 6c  ach successful l
3320: 73 6d 5f 6e 65 77 28 29 20 63 61 6c 6c 20 0a 77  sm_new() call .w
3330: 69 74 68 20 61 20 63 61 6c 6c 20 74 6f 20 6c 73  ith a call to ls
3340: 6d 5f 63 6c 6f 73 65 28 29 20 69 73 20 61 20 72  m_close() is a r
3350: 65 73 6f 75 72 63 65 20 6c 65 61 6b 2e 0a 0a 3c  esource leak...<
3360: 70 3e 43 6f 75 6e 74 65 72 2d 69 6e 74 75 69 74  p>Counter-intuit
3370: 69 76 65 6c 79 2c 20 61 6e 20 6c 73 6d 5f 63 6c  ively, an lsm_cl
3380: 6f 73 65 28 29 20 63 61 6c 6c 20 6d 61 79 20 66  ose() call may f
3390: 61 69 6c 2e 20 49 6e 20 74 68 69 73 20 63 61 73  ail. In this cas
33a0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 68  e the database.h
33b0: 61 6e 64 6c 65 20 69 73 20 6e 6f 74 20 63 6c 6f  andle is not clo
33c0: 73 65 64 2c 20 73 6f 20 69 66 20 74 68 65 20 61  sed, so if the a
33d0: 70 70 6c 69 63 61 74 69 6f 6e 20 65 78 69 74 73  pplication exits
33e0: 20 69 74 20 69 6e 76 69 74 65 73 20 74 68 65 20   it invites the 
33f0: 22 64 61 74 61 62 61 73 65 0a 72 65 63 6f 76 65  "database.recove
3400: 72 79 22 20 70 65 72 66 6f 72 6d 61 6e 63 65 20  ry" performance 
3410: 70 72 6f 62 6c 65 6d 20 6d 65 6e 74 69 6f 6e 65  problem mentione
3420: 64 20 61 62 6f 76 65 2e 20 54 68 65 20 75 73 75  d above. The usu
3430: 61 6c 20 72 65 61 73 6f 6e 20 66 6f 72 20 61 6e  al reason for an
3440: 0a 6c 73 6d 5f 63 6c 6f 73 65 28 29 20 63 61 6c  .lsm_close() cal
3450: 6c 20 66 61 69 6c 69 6e 67 20 69 73 20 74 68 61  l failing is tha
3460: 74 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  t the database h
3470: 61 6e 64 6c 65 20 68 61 73 20 62 65 65 6e 20 75  andle has been u
3480: 73 65 64 20 74 6f 20 63 72 65 61 74 65 0a 3c 61  sed to create.<a
3490: 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b   href=lsmapi.wik
34a0: 69 23 6c 73 6d 5f 63 73 72 5f 6f 70 65 6e 3e 64  i#lsm_csr_open>d
34b0: 61 74 61 62 61 73 65 20 63 75 72 73 6f 72 73 3c  atabase cursors<
34c0: 2f 61 3e 20 74 68 61 74 20 68 61 76 65 20 6e 6f  /a> that have no
34d0: 74 20 62 65 65 6e 20 0a 63 6c 6f 73 65 64 2e 20  t been .closed. 
34e0: 55 6e 6c 65 73 73 20 61 6c 6c 20 64 61 74 61 62  Unless all datab
34f0: 61 73 65 20 63 75 72 73 6f 72 73 20 61 72 65 20  ase cursors are 
3500: 63 6c 6f 73 65 64 20 62 65 66 6f 72 65 20 6c 73  closed before ls
3510: 6d 5f 63 6c 6f 73 65 28 29 20 69 73 20 63 61 6c  m_close() is cal
3520: 6c 65 64 2c 0a 69 74 20 66 61 69 6c 73 20 77 69  led,.it fails wi
3530: 74 68 20 61 6e 20 4c 53 4d 5f 42 55 53 59 20 65  th an LSM_BUSY e
3540: 72 72 6f 72 20 61 6e 64 20 74 68 65 20 64 61 74  rror and the dat
3550: 61 62 61 73 65 20 68 61 6e 64 6c 65 20 69 73 20  abase handle is 
3560: 6e 6f 74 20 63 6c 6f 73 65 64 2e 0a 0a 3c 68 32  not closed...<h2
3570: 20 69 64 3d 77 72 69 74 69 6e 67 5f 74 6f 5f 61   id=writing_to_a
3580: 5f 64 61 74 61 62 61 73 65 3e 33 2e 32 2e 20 57  _database>3.2. W
3590: 72 69 74 69 6e 67 20 74 6f 20 61 20 44 61 74 61  riting to a Data
35a0: 62 61 73 65 20 3c 2f 68 32 3e 0a 0a 3c 70 3e 54  base </h2>..<p>T
35b0: 68 72 65 65 20 41 50 49 20 66 75 6e 63 74 69 6f  hree API functio
35c0: 6e 73 20 61 72 65 20 75 73 65 64 20 74 6f 20 77  ns are used to w
35d0: 72 69 74 65 20 74 6f 20 74 68 65 20 64 61 74 61  rite to the data
35e0: 62 61 73 65 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  base:..<ul>.  <l
35f0: 69 3e 20 3c 62 3e 6c 73 6d 5f 69 6e 73 65 72 74  i> <b>lsm_insert
3600: 28 29 3c 2f 62 3e 3a 20 69 6e 73 65 72 74 20 61  ()</b>: insert a
3610: 20 6e 65 77 20 6b 65 79 2f 76 61 6c 75 65 20 70   new key/value p
3620: 61 69 72 20 69 6e 74 6f 20 74 68 65 20 64 61 74  air into the dat
3630: 61 62 61 73 65 2c 0a 20 20 20 20 20 20 20 6f 76  abase,.       ov
3640: 65 72 77 72 69 74 69 6e 67 20 61 6e 79 20 65 78  erwriting any ex
3650: 69 73 74 69 6e 67 20 65 6e 74 72 79 20 77 69 74  isting entry wit
3660: 68 20 74 68 65 20 73 61 6d 65 20 6b 65 79 2e 0a  h the same key..
3670: 20 20 3c 6c 69 3e 20 3c 62 3e 6c 73 6d 5f 64 65    <li> <b>lsm_de
3680: 6c 65 74 65 28 29 3c 2f 62 3e 3a 20 72 65 6d 6f  lete()</b>: remo
3690: 76 65 20 61 20 73 70 65 63 69 66 69 63 20 6b 65  ve a specific ke
36a0: 79 20 66 72 6f 6d 20 74 68 65 20 64 61 74 61 62  y from the datab
36b0: 61 73 65 2e 0a 20 20 3c 6c 69 3e 20 3c 62 3e 6c  ase..  <li> <b>l
36c0: 73 6d 5f 64 65 6c 65 74 65 5f 72 61 6e 67 65 28  sm_delete_range(
36d0: 29 3c 2f 62 3e 3a 20 72 65 6d 6f 76 65 20 61 6e  )</b>: remove an
36e0: 20 6f 70 65 6e 2d 65 6e 64 65 64 20 72 61 6e 67   open-ended rang
36f0: 65 20 28 6f 6e 65 20 74 68 61 74 20 64 6f 65 73  e (one that does
3700: 20 6e 6f 74 0a 20 20 20 20 20 20 20 69 6e 63 6c   not.       incl
3710: 75 64 65 20 69 74 73 20 65 6e 64 70 6f 69 6e 74  ude its endpoint
3720: 73 29 20 6f 66 20 6b 65 79 73 20 66 72 6f 6d 20  s) of keys from 
3730: 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 0a 3c  the database. .<
3740: 2f 75 6c 3e 0a 0a 3c 70 3e 45 61 63 68 20 6f 66  /ul>..<p>Each of
3750: 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
3760: 20 72 65 74 75 72 6e 73 20 4c 53 4d 5f 4f 4b 20   returns LSM_OK 
3770: 28 30 29 20 69 66 20 73 75 63 63 65 73 73 66 75  (0) if successfu
3780: 6c 2c 20 6f 72 20 61 6e 20 4c 53 4d 20 65 72 72  l, or an LSM err
3790: 6f 72 0a 63 6f 64 65 20 6f 74 68 65 72 77 69 73  or.code otherwis
37a0: 65 20 28 73 6f 6d 65 20 6e 6f 6e 2d 7a 65 72 6f  e (some non-zero
37b0: 20 76 61 6c 75 65 29 2e 0a 0a 3c 70 3e 54 68 65   value)...<p>The
37c0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d 70   following examp
37d0: 6c 65 20 63 6f 64 65 20 69 6e 73 65 72 74 73 20  le code inserts 
37e0: 61 20 6b 65 79 2f 76 61 6c 75 65 20 70 61 69 72  a key/value pair
37f0: 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61   into the databa
3800: 73 65 2e 20 54 68 65 0a 6b 65 79 20 69 73 20 61  se. The.key is a
3810: 20 31 2d 62 79 74 65 20 62 6c 6f 62 20 63 6f 6e   1-byte blob con
3820: 73 69 73 74 69 6e 67 20 6f 66 20 74 68 65 20 76  sisting of the v
3830: 61 6c 75 65 20 30 78 36 31 2c 20 61 6e 64 20 74  alue 0x61, and t
3840: 68 65 20 76 61 6c 75 65 20 69 73 20 61 20 33 20  he value is a 3 
3850: 62 79 74 65 0a 62 6c 6f 62 20 63 6f 6e 73 69 73  byte.blob consis
3860: 74 69 6e 67 20 6f 66 20 30 78 36 46 2c 20 30 78  ting of 0x6F, 0x
3870: 36 45 20 61 6e 64 20 30 78 36 35 2c 20 69 6e 20  6E and 0x65, in 
3880: 74 68 61 74 20 6f 72 64 65 72 2e 20 41 6e 20 61  that order. An a
3890: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
38a0: 0a 69 6e 74 65 72 70 72 65 74 20 74 68 65 73 65  .interpret these
38b0: 20 61 73 20 75 74 66 2d 38 20 6f 72 20 41 53 43   as utf-8 or ASC
38c0: 49 49 20 63 6f 64 65 70 6f 69 6e 74 73 2c 20 62  II codepoints, b
38d0: 75 74 20 4c 53 4d 20 74 72 65 61 74 73 20 74 68  ut LSM treats th
38e0: 65 6d 20 61 73 20 6f 70 61 71 75 65 0a 62 6c 6f  em as opaque.blo
38f0: 62 73 20 6f 66 20 64 61 74 61 2e 0a 3c 76 65 72  bs of data..<ver
3900: 62 61 74 69 6d 3e 0a 20 20 72 63 20 3d 20 6c 73  batim>.  rc = ls
3910: 6d 5f 69 6e 73 65 72 74 28 64 62 2c 20 22 61 22  m_insert(db, "a"
3920: 2c 20 31 2c 20 22 6f 6e 65 22 2c 20 33 29 3b 0a  , 1, "one", 3);.
3930: 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70 3e  </verbatim>..<p>
3940: 52 65 6d 6f 76 65 20 74 68 65 20 65 6e 74 72 79  Remove the entry
3950: 20 77 69 74 68 20 74 68 65 20 6b 65 79 20 22 61   with the key "a
3960: 22 20 28 73 69 6e 67 6c 65 20 30 78 36 31 20 6f  " (single 0x61 o
3970: 63 74 65 74 29 20 66 72 6f 6d 20 74 68 65 20 64  ctet) from the d
3980: 61 74 61 62 61 73 65 3a 0a 0a 3c 76 65 72 62 61  atabase:..<verba
3990: 74 69 6d 3e 0a 20 20 72 63 20 3d 20 6c 73 6d 5f  tim>.  rc = lsm_
39a0: 64 65 6c 65 74 65 28 64 62 2c 20 22 61 22 2c 20  delete(db, "a", 
39b0: 31 29 3b 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a  1);.</verbatim>.
39c0: 0a 3c 70 3e 52 65 6d 6f 76 65 20 61 6c 6c 20 65  .<p>Remove all e
39d0: 6e 74 72 69 65 73 20 77 69 74 68 20 6b 65 79 73  ntries with keys
39e0: 20 74 68 61 74 20 61 72 65 20 67 72 65 61 74 65   that are greate
39f0: 72 20 74 68 61 6e 20 22 63 22 20 62 75 74 20 6c  r than "c" but l
3a00: 65 73 73 20 74 68 61 6e 20 22 66 22 2e 0a 49 6e  ess than "f"..In
3a10: 20 74 68 69 73 20 63 6f 6e 74 65 78 74 20 6b 65   this context ke
3a20: 79 20 62 6c 6f 62 73 20 61 72 65 20 63 6f 6d 70  y blobs are comp
3a30: 61 72 65 64 20 69 6e 20 74 68 65 20 6e 6f 72 6d  ared in the norm
3a40: 61 6c 20 77 61 79 20 2d 20 75 73 69 6e 67 20 6d  al way - using m
3a50: 65 6d 63 6d 70 28 29 2c 20 0a 77 69 74 68 20 6c  emcmp(), .with l
3a60: 6f 6e 67 65 72 20 6b 65 79 73 20 62 65 69 6e 67  onger keys being
3a70: 20 63 6f 6e 73 69 64 65 72 65 64 20 6c 61 72 67   considered larg
3a80: 65 72 20 74 68 61 6e 20 74 68 65 69 72 20 70 72  er than their pr
3a90: 65 66 69 78 65 73 2e 0a 0a 3c 76 65 72 62 61 74  efixes...<verbat
3aa0: 69 6d 3e 0a 20 20 72 63 20 3d 20 6c 73 6d 5f 64  im>.  rc = lsm_d
3ab0: 65 6c 65 74 65 5f 72 61 6e 67 65 28 64 62 2c 20  elete_range(db, 
3ac0: 22 63 22 2c 20 31 2c 20 22 66 22 2c 20 31 29 3b  "c", 1, "f", 1);
3ad0: 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70  .</verbatim>..<p
3ae0: 3e 54 68 65 20 65 78 61 6d 70 6c 65 20 61 62 6f  >The example abo
3af0: 76 65 20 72 65 6d 6f 76 65 73 20 61 6c 6c 20 6b  ve removes all k
3b00: 65 79 73 20 62 65 74 77 65 65 6e 20 22 63 22 20  eys between "c" 
3b10: 61 6e 64 20 22 66 22 2c 20 62 75 74 20 64 6f 65  and "f", but doe
3b20: 73 20 6e 6f 74 0a 72 65 6d 6f 76 65 20 74 68 65  s not.remove the
3b30: 20 65 6e 64 70 6f 69 6e 74 73 20 22 63 22 20 61   endpoints "c" a
3b40: 6e 64 20 22 66 22 20 74 68 65 6d 73 65 6c 76 65  nd "f" themselve
3b50: 73 2e 20 54 6f 20 64 6f 20 74 68 69 73 2c 20 72  s. To do this, r
3b60: 65 71 75 69 72 65 73 20 74 68 72 65 65 0a 73 65  equires three.se
3b70: 70 61 72 61 74 65 20 63 61 6c 6c 73 20 2d 20 6f  parate calls - o
3b80: 6e 65 20 74 6f 20 72 65 6d 6f 76 65 20 74 68 65  ne to remove the
3b90: 20 6f 70 65 6e 2d 65 6e 64 65 64 20 72 61 6e 67   open-ended rang
3ba0: 65 20 6f 66 20 6b 65 79 73 20 61 6e 64 20 74 77  e of keys and tw
3bb0: 6f 20 74 6f 20 0a 72 65 6d 6f 76 65 20 74 68 65  o to .remove the
3bc0: 20 74 77 6f 20 65 6e 64 70 6f 69 6e 74 73 2e 20   two endpoints. 
3bd0: 41 73 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 76 65  As follows:..<ve
3be0: 72 62 61 74 69 6d 3e 0a 20 20 2f 2a 20 53 68 6f  rbatim>.  /* Sho
3bf0: 75 6c 64 20 62 65 20 63 68 65 63 6b 69 6e 67 20  uld be checking 
3c00: 72 65 74 75 72 6e 20 63 6f 64 65 73 21 20 2a 2f  return codes! */
3c10: 0a 20 20 6c 73 6d 5f 64 65 6c 65 74 65 28 64 62  .  lsm_delete(db
3c20: 2c 20 22 63 22 2c 20 31 29 3b 0a 20 20 6c 73 6d  , "c", 1);.  lsm
3c30: 5f 64 65 6c 65 74 65 5f 72 61 6e 67 65 28 64 62  _delete_range(db
3c40: 2c 20 22 63 22 2c 20 31 2c 20 22 66 22 2c 20 31  , "c", 1, "f", 1
3c50: 29 3b 0a 20 20 6c 73 6d 5f 64 65 6c 65 74 65 28  );.  lsm_delete(
3c60: 64 62 2c 20 22 66 22 2c 20 31 29 3b 0a 3c 2f 76  db, "f", 1);.</v
3c70: 65 72 62 61 74 69 6d 3e 0a 0a 3c 68 32 20 69 64  erbatim>..<h2 id
3c80: 3d 72 65 61 64 69 6e 67 5f 66 72 6f 6d 5f 61 5f  =reading_from_a_
3c90: 64 61 74 61 62 61 73 65 3e 33 2e 33 2e 20 52 65  database>3.3. Re
3ca0: 61 64 69 6e 67 20 66 72 6f 6d 20 61 20 44 61 74  ading from a Dat
3cb0: 61 62 61 73 65 20 3c 2f 68 32 3e 0a 0a 3c 70 3e  abase </h2>..<p>
3cc0: 41 6c 6c 20 64 61 74 61 20 72 65 61 64 20 66 72  All data read fr
3cd0: 6f 6d 20 61 6e 20 4c 53 4d 20 64 61 74 61 62 61  om an LSM databa
3ce0: 73 65 20 69 73 20 72 65 61 64 20 76 69 61 20 61  se is read via a
3cf0: 20 63 75 72 73 6f 72 20 68 61 6e 64 6c 65 2e 20   cursor handle. 
3d00: 43 75 72 73 6f 72 0a 68 61 6e 64 6c 65 73 20 61  Cursor.handles a
3d10: 72 65 20 6f 70 65 6e 65 64 20 75 73 69 6e 67 20  re opened using 
3d20: 74 68 65 20 0a 3c 61 20 68 72 65 66 3d 6c 73 6d  the .<a href=lsm
3d30: 61 70 69 2e 77 69 6b 69 23 6c 73 6d 5f 63 73 72  api.wiki#lsm_csr
3d40: 5f 6f 70 65 6e 3e 6c 73 6d 5f 63 73 72 5f 6f 70  _open>lsm_csr_op
3d50: 65 6e 28 29 3c 2f 61 3e 20 41 50 49 2c 20 61 73  en()</a> API, as
3d60: 20 66 6f 6c 6c 6f 77 73 3a 0a 0a 3c 76 65 72 62   follows:..<verb
3d70: 61 74 69 6d 3e 0a 20 20 6c 73 6d 5f 63 73 72 20  atim>.  lsm_csr 
3d80: 2a 63 73 72 3b 0a 20 20 72 63 20 3d 20 6c 73 6d  *csr;.  rc = lsm
3d90: 5f 63 73 72 5f 6f 70 65 6e 28 64 62 2c 20 26 63  _csr_open(db, &c
3da0: 73 72 29 3b 0a 3c 2f 76 65 72 62 61 74 69 6d 3e  sr);.</verbatim>
3db0: 0a 0a 3c 70 3e 4f 6e 63 65 20 61 6e 20 61 70 70  ..<p>Once an app
3dc0: 6c 69 63 61 74 69 6f 6e 20 68 61 73 20 66 69 6e  lication has fin
3dd0: 69 73 68 65 64 20 75 73 69 6e 67 20 61 20 64 61  ished using a da
3de0: 74 61 62 61 73 65 20 63 75 72 73 6f 72 2c 20 69  tabase cursor, i
3df0: 74 20 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64  t must be closed
3e00: 0a 75 73 69 6e 67 20 74 68 65 20 3c 61 20 68 72  .using the <a hr
3e10: 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23 6c  ef=lsmapi.wiki#l
3e20: 73 6d 5f 63 73 72 5f 63 6c 6f 73 65 3e 6c 73 6d  sm_csr_close>lsm
3e30: 5f 63 73 72 5f 63 6c 6f 73 65 28 29 3c 2f 61 3e  _csr_close()</a>
3e40: 20 41 50 49 2e 20 54 68 65 0a 6c 73 6d 5f 63 73   API. The.lsm_cs
3e50: 72 5f 63 6c 6f 73 65 28 29 20 66 75 6e 63 74 69  r_close() functi
3e60: 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  on does not retu
3e70: 72 6e 20 61 6e 79 20 76 61 6c 75 65 2e 20 49 74  rn any value. It
3e80: 20 63 61 6e 6e 6f 74 20 66 61 69 6c 2e 0a 0a 3c   cannot fail...<
3e90: 76 65 72 62 61 74 69 6d 3e 0a 20 20 6c 73 6d 5f  verbatim>.  lsm_
3ea0: 63 73 72 5f 63 6c 6f 73 65 28 63 73 72 29 3b 0a  csr_close(csr);.
3eb0: 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70 3e  </verbatim>..<p>
3ec0: 44 61 74 61 62 61 73 65 20 63 75 72 73 6f 72 73  Database cursors
3ed0: 20 73 75 70 70 6f 72 74 20 74 68 65 20 66 6f 6c   support the fol
3ee0: 6c 6f 77 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lowing functions
3ef0: 20 66 6f 72 20 70 6f 73 69 74 69 6f 6e 69 6e 67   for positioning
3f00: 20 74 68 65 20 63 75 72 73 6f 72 3a 0a 0a 3c 75   the cursor:..<u
3f10: 6c 3e 0a 20 20 3c 6c 69 3e 20 3c 62 3e 6c 73 6d  l>.  <li> <b>lsm
3f20: 5f 63 73 72 5f 73 65 65 6b 28 29 3c 2f 62 3e 20  _csr_seek()</b> 
3f30: 2d 20 6d 6f 76 65 20 74 68 65 20 63 75 72 73 6f  - move the curso
3f40: 72 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  r to point to a 
3f50: 6e 6f 6d 69 6e 61 74 65 64 20 0a 20 20 20 20 20  nominated .     
3f60: 20 20 64 61 74 61 62 61 73 65 20 6b 65 79 2e 0a    database key..
3f70: 20 20 3c 6c 69 3e 20 3c 62 3e 6c 73 6d 5f 63 73    <li> <b>lsm_cs
3f80: 72 5f 66 69 72 73 74 28 29 3c 2f 62 3e 20 2d 20  r_first()</b> - 
3f90: 6d 6f 76 65 20 74 68 65 20 63 75 72 73 6f 72 20  move the cursor 
3fa0: 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
3fb0: 66 69 72 73 74 20 65 6e 74 72 79 20 69 6e 0a 20  first entry in. 
3fc0: 20 20 20 20 20 20 74 68 65 20 64 61 74 61 62 61        the databa
3fd0: 73 65 20 28 74 68 65 20 6f 6e 65 20 77 69 74 68  se (the one with
3fe0: 20 74 68 65 20 73 6d 61 6c 6c 65 73 74 20 6b 65   the smallest ke
3ff0: 79 29 2e 0a 20 20 3c 6c 69 3e 20 3c 62 3e 6c 73  y)..  <li> <b>ls
4000: 6d 5f 63 73 72 5f 6c 61 73 74 28 29 3c 2f 62 3e  m_csr_last()</b>
4010: 20 2d 20 6d 6f 76 65 20 74 68 65 20 63 75 72 73   - move the curs
4020: 6f 72 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  or to point to t
4030: 68 65 20 6c 61 73 74 20 65 6e 74 72 79 20 69 6e  he last entry in
4040: 0a 20 20 20 20 20 20 20 74 68 65 20 64 61 74 61  .       the data
4050: 62 61 73 65 20 28 74 68 65 20 6f 6e 65 20 77 69  base (the one wi
4060: 74 68 20 74 68 65 20 6c 61 72 67 65 73 74 20 6b  th the largest k
4070: 65 79 29 2e 0a 20 20 3c 6c 69 3e 20 3c 62 3e 6c  ey)..  <li> <b>l
4080: 73 6d 5f 63 73 72 5f 6e 65 78 74 28 29 3c 2f 62  sm_csr_next()</b
4090: 3e 20 2d 20 6d 6f 76 65 20 74 68 65 20 63 75 72  > - move the cur
40a0: 73 6f 72 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  sor to point to 
40b0: 74 68 65 20 6e 65 78 74 20 65 6e 74 72 79 20 69  the next entry i
40c0: 6e 20 0a 20 20 20 20 20 20 20 74 68 65 20 74 68  n .       the th
40d0: 65 20 64 61 74 61 62 61 73 65 2e 0a 20 20 3c 6c  e database..  <l
40e0: 69 3e 20 3c 62 3e 6c 73 6d 5f 63 73 72 5f 70 72  i> <b>lsm_csr_pr
40f0: 65 76 28 29 3c 2f 62 3e 20 2d 20 6d 6f 76 65 20  ev()</b> - move 
4100: 74 68 65 20 63 75 72 73 6f 72 20 74 6f 20 70 6f  the cursor to po
4110: 69 6e 74 20 74 6f 20 74 68 65 20 70 72 65 76 69  int to the previ
4120: 6f 75 73 20 65 6e 74 72 79 0a 20 20 20 20 20 20  ous entry.      
4130: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
4140: 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 4f 6e 63 65  ..</ul>..<p>Once
4150: 20 61 20 63 75 72 73 6f 72 20 68 61 73 20 62 65   a cursor has be
4160: 65 6e 20 70 6f 73 69 74 69 6f 6e 65 64 2c 20 69  en positioned, i
4170: 74 20 73 75 70 70 6f 72 74 73 20 74 68 65 20 66  t supports the f
4180: 6f 6c 6c 6f 77 69 6e 67 20 66 75 6e 63 74 69 6f  ollowing functio
4190: 6e 73 0a 66 6f 72 20 72 65 74 72 69 65 76 69 6e  ns.for retrievin
41a0: 67 20 74 68 65 20 64 65 74 61 69 6c 73 20 6f 66  g the details of
41b0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 65 6e 74   the current ent
41c0: 72 79 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e  ry:..<ul>.  <li>
41d0: 20 3c 62 3e 6c 73 6d 5f 63 73 72 5f 76 61 6c 69   <b>lsm_csr_vali
41e0: 64 28 29 3c 2f 62 3e 20 2d 20 64 65 74 65 72 6d  d()</b> - determ
41f0: 69 6e 65 20 77 68 65 74 68 65 72 20 6f 72 20 6e  ine whether or n
4200: 6f 74 20 74 68 65 20 63 75 72 73 6f 72 20 63 75  ot the cursor cu
4210: 72 72 65 6e 74 6c 79 0a 20 20 20 20 20 20 20 70  rrently.       p
4220: 6f 69 6e 74 73 20 74 6f 20 61 20 76 61 6c 69 64  oints to a valid
4230: 20 65 6e 74 72 79 2e 0a 20 20 3c 6c 69 3e 20 3c   entry..  <li> <
4240: 62 3e 6c 73 6d 5f 63 73 72 5f 6b 65 79 28 29 3c  b>lsm_csr_key()<
4250: 2f 62 3e 20 2d 20 72 65 74 72 69 65 76 65 20 74  /b> - retrieve t
4260: 68 65 20 6b 65 79 20 61 73 73 6f 63 69 61 74 65  he key associate
4270: 64 20 77 69 74 68 20 74 68 65 0a 20 20 20 20 20  d with the.     
4280: 20 20 64 61 74 61 62 61 73 65 20 65 6e 74 72 79    database entry
4290: 20 74 68 65 20 63 75 72 73 6f 72 20 70 6f 69 6e   the cursor poin
42a0: 74 73 20 74 6f 2e 0a 20 20 3c 6c 69 3e 20 3c 62  ts to..  <li> <b
42b0: 3e 6c 73 6d 5f 63 73 72 5f 76 61 6c 75 65 28 29  >lsm_csr_value()
42c0: 3c 2f 62 3e 20 2d 20 72 65 74 72 69 65 76 65 20  </b> - retrieve 
42d0: 74 68 65 20 76 61 6c 75 65 20 61 73 73 6f 63 69  the value associ
42e0: 61 74 65 64 20 77 69 74 68 20 74 68 65 0a 20 20  ated with the.  
42f0: 20 20 20 20 20 64 61 74 61 62 61 73 65 20 65 6e       database en
4300: 74 72 79 20 74 68 65 20 63 75 72 73 6f 72 20 70  try the cursor p
4310: 6f 69 6e 74 73 20 74 6f 2e 0a 20 20 3c 6c 69 3e  oints to..  <li>
4320: 20 3c 62 3e 6c 73 6d 5f 63 73 72 5f 63 6d 70 28   <b>lsm_csr_cmp(
4330: 29 3c 2f 62 3e 20 2d 20 63 6f 6d 70 61 72 65 20  )</b> - compare 
4340: 61 20 6b 65 79 20 73 75 70 70 6c 69 65 64 20 62  a key supplied b
4350: 79 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  y the applicatio
4360: 6e 20 77 69 74 68 0a 20 20 20 20 20 20 20 74 68  n with.       th
4370: 65 20 6b 65 79 20 61 73 73 6f 63 69 61 74 65 64  e key associated
4380: 20 77 69 74 68 20 74 68 65 20 65 6e 74 72 79 20   with the entry 
4390: 74 68 65 20 63 75 72 73 6f 72 20 70 6f 69 6e 74  the cursor point
43a0: 73 20 74 6f 2e 20 0a 3c 2f 75 6c 3e 0a 0a 3c 70  s to. .</ul>..<p
43b0: 3e 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 65  >The following e
43c0: 78 61 6d 70 6c 65 20 64 65 6d 6f 6e 73 74 72 61  xample demonstra
43d0: 74 65 73 20 75 73 69 6e 67 20 74 68 65 20 0a 3c  tes using the .<
43e0: 61 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69  a href=lsmapi.wi
43f0: 6b 69 23 6c 73 6d 5f 63 73 72 5f 73 65 65 6b 3e  ki#lsm_csr_seek>
4400: 6c 73 6d 5f 63 73 72 5f 73 65 65 6b 28 29 3c 2f  lsm_csr_seek()</
4410: 61 3e 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 73  a> function to s
4420: 65 61 72 63 68 20 74 68 65 0a 64 61 74 61 62 61  earch the.databa
4430: 73 65 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  se for a specifi
4440: 65 64 20 6b 65 79 2c 20 0a 3c 61 20 68 72 65 66  ed key, .<a href
4450: 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23 6c 73 6d  =lsmapi.wiki#lsm
4460: 5f 63 73 72 5f 76 61 6c 69 64 3e 6c 73 6d 5f 63  _csr_valid>lsm_c
4470: 73 72 5f 76 61 6c 69 64 28 29 3c 2f 61 3e 20 74  sr_valid()</a> t
4480: 6f 20 63 68 65 63 6b 20 69 66 20 74 68 65 20 73  o check if the s
4490: 65 61 72 63 68 0a 77 61 73 20 73 75 63 63 65 73  earch.was succes
44a0: 73 66 75 6c 2c 20 61 6e 64 20 3c 61 20 68 72 65  sful, and <a hre
44b0: 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23 6c 73  f=lsmapi.wiki#ls
44c0: 6d 5f 63 73 72 5f 76 61 6c 75 65 3e 6c 73 6d 5f  m_csr_value>lsm_
44d0: 63 73 72 5f 76 61 6c 75 65 28 29 3c 2f 61 3e 20  csr_value()</a> 
44e0: 0a 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65  .to retrieve the
44f0: 20 76 61 6c 75 65 20 61 73 73 6f 63 69 61 74 65   value associate
4500: 64 20 77 69 74 68 20 74 68 65 20 6b 65 79 20 77  d with the key w
4510: 69 74 68 69 6e 20 74 68 65 20 64 61 74 61 62 61  ithin the databa
4520: 73 65 2e 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a  se...<verbatim>.
4530: 20 20 72 63 20 3d 20 6c 73 6d 5f 63 73 72 5f 73    rc = lsm_csr_s
4540: 65 65 6b 28 63 73 72 2c 20 22 62 22 2c 20 31 2c  eek(csr, "b", 1,
4550: 20 4c 53 4d 5f 53 45 45 4b 5f 45 51 29 3b 0a 20   LSM_SEEK_EQ);. 
4560: 20 69 66 28 20 6c 73 6d 5f 63 73 72 5f 76 61 6c   if( lsm_csr_val
4570: 69 64 28 63 73 72 29 20 29 7b 0a 20 20 20 20 63  id(csr) ){.    c
4580: 6f 6e 73 74 20 76 6f 69 64 20 2a 70 56 61 6c 3b  onst void *pVal;
4590: 20 69 6e 74 20 6e 56 61 6c 3b 0a 0a 20 20 20 20   int nVal;..    
45a0: 72 63 20 3d 20 6c 73 6d 5f 63 73 72 5f 76 61 6c  rc = lsm_csr_val
45b0: 75 65 28 63 73 72 2c 20 26 70 56 61 6c 2c 20 26  ue(csr, &pVal, &
45c0: 6e 56 61 6c 29 3b 0a 20 20 20 20 69 66 28 20 72  nVal);.    if( r
45d0: 63 3d 3d 4c 53 4d 5f 4f 4b 20 29 7b 0a 20 20 20  c==LSM_OK ){.   
45e0: 20 20 20 2f 2a 20 70 56 61 6c 20 6e 6f 77 20 70     /* pVal now p
45f0: 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
4600: 72 20 6e 56 61 6c 20 62 79 74 65 73 20 69 6e 20  r nVal bytes in 
4610: 73 69 7a 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20  size containing 
4620: 74 68 65 0a 20 20 20 20 20 20 2a 2a 20 76 61 6c  the.      ** val
4630: 75 65 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ue associated wi
4640: 74 68 20 64 61 74 61 62 61 73 65 20 6b 65 79 20  th database key 
4650: 22 62 22 2e 20 20 2a 2f 0a 20 20 20 20 7d 0a 20  "b".  */.    }. 
4660: 20 7d 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a   }.</verbatim>..
4670: 3c 70 3e 20 54 68 65 20 65 78 61 6d 70 6c 65 20  <p> The example 
4680: 63 6f 64 65 20 62 65 6c 6f 77 20 69 74 65 72 61  code below itera
4690: 74 65 73 20 66 6f 72 77 61 72 64 73 20 74 68 72  tes forwards thr
46a0: 6f 75 67 68 20 61 6c 6c 20 65 6e 74 72 69 65 73  ough all entries
46b0: 20 28 69 6e 20 6b 65 79 20 0a 6f 72 64 65 72 2c   (in key .order,
46c0: 20 66 72 6f 6d 20 73 6d 61 6c 6c 65 73 74 20 74   from smallest t
46d0: 6f 20 6c 61 72 67 65 73 74 29 20 69 6e 20 74 68  o largest) in th
46e0: 65 20 64 61 74 61 62 61 73 65 2e 20 46 75 6e 63  e database. Func
46f0: 74 69 6f 6e 20 0a 3c 61 20 68 72 65 66 3d 6c 73  tion .<a href=ls
4700: 6d 61 70 69 2e 77 69 6b 69 23 6c 73 6d 5f 63 73  mapi.wiki#lsm_cs
4710: 72 5f 66 69 72 73 74 3e 6c 73 6d 5f 63 73 72 5f  r_first>lsm_csr_
4720: 66 69 72 73 74 28 29 3c 2f 61 3e 20 69 73 20 75  first()</a> is u
4730: 73 65 64 20 74 6f 20 70 6f 73 69 74 69 6f 6e 0a  sed to position.
4740: 74 68 65 20 63 75 72 73 6f 72 20 74 6f 20 70 6f  the cursor to po
4750: 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73 74  int to the first
4760: 20 65 6e 74 72 79 20 69 6e 20 74 68 65 20 64 61   entry in the da
4770: 74 61 62 61 73 65 2c 20 61 6e 64 20 0a 3c 61 20  tabase, and .<a 
4780: 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69  href=lsmapi.wiki
4790: 23 6c 73 6d 5f 63 73 72 5f 6e 65 78 74 3e 6c 73  #lsm_csr_next>ls
47a0: 6d 5f 63 73 72 5f 6e 65 78 74 28 29 3c 2f 61 3e  m_csr_next()</a>
47b0: 20 69 73 20 75 73 65 64 20 74 6f 20 61 64 76 61   is used to adva
47c0: 6e 63 65 20 74 6f 0a 74 68 65 20 6e 65 78 74 20  nce to.the next 
47d0: 65 6e 74 72 79 2e 20 41 66 74 65 72 20 6c 73 6d  entry. After lsm
47e0: 5f 63 73 72 5f 6e 65 78 74 28 29 20 69 73 20 63  _csr_next() is c
47f0: 61 6c 6c 65 64 20 74 6f 20 61 64 76 61 6e 63 65  alled to advance
4800: 20 70 61 73 74 20 74 68 65 20 66 69 6e 61 6c 0a   past the final.
4810: 65 6e 74 72 79 20 69 6e 20 74 68 65 20 64 61 74  entry in the dat
4820: 61 62 61 73 65 2c 20 74 68 65 20 63 75 72 73 6f  abase, the curso
4830: 72 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  r is left pointi
4840: 6e 67 20 74 6f 20 6e 6f 20 65 6e 74 72 79 20 61  ng to no entry a
4850: 74 20 61 6c 6c 2c 0a 6c 73 6d 5f 63 73 72 5f 76  t all,.lsm_csr_v
4860: 61 6c 69 64 28 29 20 72 65 74 75 72 6e 73 20 30  alid() returns 0
4870: 2c 20 61 6e 64 20 74 68 65 20 6c 6f 6f 70 20 69  , and the loop i
4880: 73 20 66 69 6e 69 73 68 65 64 2e 20 41 50 49 20  s finished. API 
4890: 66 75 6e 63 74 69 6f 6e 20 0a 3c 61 20 68 72 65  function .<a hre
48a0: 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23 6c 73  f=lsmapi.wiki#ls
48b0: 6d 5f 63 73 72 5f 6b 65 79 3e 6c 73 6d 5f 63 73  m_csr_key>lsm_cs
48c0: 72 5f 6b 65 79 28 29 3c 2f 61 3e 20 69 73 20 75  r_key()</a> is u
48d0: 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
48e0: 74 68 65 0a 6b 65 79 20 61 73 73 6f 63 69 61 74  the.key associat
48f0: 65 64 20 77 69 74 68 20 65 61 63 68 20 64 61 74  ed with each dat
4900: 61 62 61 73 65 20 65 6e 74 72 79 20 76 69 73 69  abase entry visi
4910: 74 65 64 2e 0a 0a 3c 76 65 72 62 61 74 69 6d 3e  ted...<verbatim>
4920: 0a 20 20 66 6f 72 28 72 63 20 3d 20 6c 73 6d 5f  .  for(rc = lsm_
4930: 63 73 72 5f 66 69 72 73 74 28 63 73 72 29 3b 20  csr_first(csr); 
4940: 6c 73 6d 5f 63 73 72 5f 76 61 6c 69 64 28 63 73  lsm_csr_valid(cs
4950: 72 29 3b 20 72 63 20 3d 20 6c 73 6d 5f 63 73 72  r); rc = lsm_csr
4960: 5f 6e 65 78 74 28 63 73 72 29 29 7b 0a 20 20 20  _next(csr)){.   
4970: 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
4980: 79 3b 20 69 6e 74 20 6e 4b 65 79 3b 0a 20 20 20  y; int nKey;.   
4990: 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 56 61   const void *pVa
49a0: 6c 3b 20 69 6e 74 20 6e 56 61 6c 3b 0a 0a 20 20  l; int nVal;..  
49b0: 20 20 72 63 20 3d 20 6c 73 6d 5f 63 73 72 5f 6b    rc = lsm_csr_k
49c0: 65 79 28 63 73 72 2c 20 26 70 4b 65 79 2c 20 26  ey(csr, &pKey, &
49d0: 6e 4b 65 79 29 3b 0a 20 20 20 20 69 66 28 20 72  nKey);.    if( r
49e0: 63 3d 3d 4c 53 4d 5f 4f 4b 20 29 20 72 63 20 3d  c==LSM_OK ) rc =
49f0: 20 6c 73 6d 5f 63 73 72 5f 76 61 6c 75 65 28 63   lsm_csr_value(c
4a00: 73 72 2c 20 26 70 56 61 6c 2c 20 26 6e 56 61 6c  sr, &pVal, &nVal
4a10: 29 3b 0a 20 20 20 20 69 66 28 20 72 63 21 3d 4c  );.    if( rc!=L
4a20: 53 4d 5f 4f 4b 20 29 20 62 72 65 61 6b 3b 0a 0a  SM_OK ) break;..
4a30: 20 20 20 20 2f 2a 20 41 74 20 74 68 69 73 20 70      /* At this p
4a40: 6f 69 6e 74 20 70 4b 65 79 20 70 6f 69 6e 74 73  oint pKey points
4a50: 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20   to the current 
4a60: 6b 65 79 20 28 73 69 7a 65 20 6e 4b 65 79 20 62  key (size nKey b
4a70: 79 74 65 73 29 20 61 6e 64 0a 20 20 20 20 2a 2a  ytes) and.    **
4a80: 20 70 56 61 6c 20 70 6f 69 6e 74 73 20 74 6f 20   pVal points to 
4a90: 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
4aa0: 67 20 76 61 6c 75 65 20 28 73 69 7a 65 20 6e 56  g value (size nV
4ab0: 61 6c 20 62 79 74 65 73 29 2e 20 20 2a 2f 0a 20  al bytes).  */. 
4ac0: 20 7d 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a   }.</verbatim>..
4ad0: 3c 70 3e 20 54 68 65 20 65 78 61 6d 70 6c 65 20  <p> The example 
4ae0: 63 6f 64 65 20 61 62 6f 76 65 20 63 6f 75 6c 64  code above could
4af0: 20 62 65 20 6d 6f 64 69 66 69 65 64 20 74 6f 20   be modified to 
4b00: 69 74 65 72 61 74 65 20 62 61 63 6b 77 61 72 64  iterate backward
4b10: 73 20 74 68 72 6f 75 67 68 0a 74 68 65 20 65 6e  s through.the en
4b20: 74 72 69 65 73 20 69 6e 20 74 68 65 20 64 61 74  tries in the dat
4b30: 61 62 61 73 65 20 28 61 67 61 69 6e 20 69 6e 20  abase (again in 
4b40: 6b 65 79 20 6f 72 64 65 72 2c 20 62 75 74 20 74  key order, but t
4b50: 68 69 73 20 74 69 6d 65 20 66 72 6f 6d 20 6c 61  his time from la
4b60: 72 67 65 73 74 0a 74 6f 20 73 6d 61 6c 6c 65 73  rgest.to smalles
4b70: 74 29 20 62 79 20 72 65 70 6c 61 63 69 6e 67 20  t) by replacing 
4b80: 74 68 65 20 63 61 6c 6c 20 74 6f 20 6c 73 6d 5f  the call to lsm_
4b90: 63 73 72 5f 66 69 72 73 74 28 29 20 77 69 74 68  csr_first() with
4ba0: 20 0a 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70 69   .<a href=lsmapi
4bb0: 2e 77 69 6b 69 23 6c 73 6d 5f 63 73 72 5f 6c 61  .wiki#lsm_csr_la
4bc0: 73 74 3e 6c 73 6d 5f 63 73 72 5f 6c 61 73 74 28  st>lsm_csr_last(
4bd0: 29 3c 2f 61 3e 20 61 6e 64 20 74 68 65 20 63 61  )</a> and the ca
4be0: 6c 6c 20 74 6f 20 6c 73 6d 5f 63 73 72 5f 6e 65  ll to lsm_csr_ne
4bf0: 78 74 28 29 20 77 69 74 68 20 3c 61 20 68 72 65  xt() with <a hre
4c00: 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23 6c 73  f=lsmapi.wiki#ls
4c10: 6d 5f 63 73 72 5f 70 72 65 76 3e 6c 73 6d 5f 63  m_csr_prev>lsm_c
4c20: 73 72 5f 70 72 65 76 28 29 3c 2f 61 3e 2e 0a 0a  sr_prev()</a>...
4c30: 3c 70 3e 54 68 65 20 73 69 67 6e 61 74 75 72 65  <p>The signature
4c40: 20 6f 66 20 6c 73 6d 5f 63 73 72 5f 73 65 65 6b   of lsm_csr_seek
4c50: 28 29 20 69 73 3a 0a 0a 3c 76 65 72 62 61 74 69  () is:..<verbati
4c60: 6d 3e 0a 20 20 69 6e 74 20 6c 73 6d 5f 63 73 72  m>.  int lsm_csr
4c70: 5f 73 65 65 6b 28 6c 73 6d 5f 63 75 72 73 6f 72  _seek(lsm_cursor
4c80: 20 2a 63 73 72 2c 20 63 6f 6e 73 74 20 76 6f 69   *csr, const voi
4c90: 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
4ca0: 79 2c 20 69 6e 74 20 65 53 65 65 6b 29 3b 0a 3c  y, int eSeek);.<
4cb0: 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70 3e 54  /verbatim>..<p>T
4cc0: 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68  he second and th
4cd0: 69 72 64 20 61 72 67 75 6d 65 6e 74 73 20 70 61  ird arguments pa
4ce0: 73 73 65 64 20 74 6f 20 6c 73 6d 5f 63 73 72 5f  ssed to lsm_csr_
4cf0: 73 65 65 6b 28 29 20 64 65 66 69 6e 65 20 74 68  seek() define th
4d00: 65 20 6b 65 79 0a 74 6f 20 73 65 61 72 63 68 20  e key.to search 
4d10: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72  the database for
4d20: 20 28 70 4b 65 79 20 6d 75 73 74 20 70 6f 69 6e   (pKey must poin
4d30: 74 20 74 6f 20 74 68 65 20 62 75 66 66 65 72 20  t to the buffer 
4d40: 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 6e  containing the.n
4d50: 4b 65 79 20 62 79 74 65 20 6b 65 79 20 77 68 65  Key byte key whe
4d60: 6e 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  n this function 
4d70: 69 73 20 63 61 6c 6c 65 64 29 2e 20 41 73 73 75  is called). Assu
4d80: 6d 69 6e 67 20 6e 6f 20 65 72 72 6f 72 20 6f 63  ming no error oc
4d90: 63 75 72 73 2c 20 69 66 20 0a 74 68 65 72 65 20  curs, if .there 
4da0: 61 6e 20 65 6e 74 72 79 20 77 69 74 68 20 74 68  an entry with th
4db0: 65 20 72 65 71 75 65 73 74 65 64 20 6b 65 79 20  e requested key 
4dc0: 69 73 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68  is present in th
4dd0: 65 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 20  e database, the 
4de0: 63 75 72 73 6f 72 20 0a 69 73 20 6c 65 66 74 20  cursor .is left 
4df0: 70 6f 69 6e 74 69 6e 67 20 74 6f 20 69 74 2e 20  pointing to it. 
4e00: 4f 74 68 65 72 77 69 73 65 2c 20 69 66 20 6e 6f  Otherwise, if no
4e10: 20 73 75 63 68 20 65 6e 74 72 79 20 69 73 20 70   such entry is p
4e20: 72 65 73 65 6e 74 2c 20 74 68 65 20 66 69 6e 61  resent, the fina
4e30: 6c 0a 70 6f 73 69 74 69 6f 6e 20 6f 66 20 74 68  l.position of th
4e40: 65 20 63 75 72 73 6f 72 20 64 65 70 65 6e 64 73  e cursor depends
4e50: 20 6f 6e 20 74 68 65 20 76 61 6c 75 65 20 70 61   on the value pa
4e60: 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75 72  ssed as the four
4e70: 74 68 20 70 61 72 61 6d 65 74 65 72 0a 74 6f 20  th parameter.to 
4e80: 6c 73 6d 5f 63 73 72 5f 73 65 65 6b 28 29 2e 20  lsm_csr_seek(). 
4e90: 56 61 6c 69 64 20 76 61 6c 75 65 73 20 66 6f 72  Valid values for
4ea0: 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
4eb0: 6d 65 74 65 72 20 74 6f 20 6c 73 6d 5f 63 73 72  meter to lsm_csr
4ec0: 5f 73 65 65 6b 28 29 0a 61 72 65 3a 0a 0a 3c 64  _seek().are:..<d
4ed0: 6c 3e 0a 20 20 3c 64 74 3e 20 4c 53 4d 5f 53 45  l>.  <dt> LSM_SE
4ee0: 45 4b 5f 45 51 0a 20 20 3c 64 64 3e 20 3c 70 20  EK_EQ.  <dd> <p 
4ef0: 73 74 79 6c 65 3d 6d 61 72 67 69 6e 2d 74 6f 70  style=margin-top
4f00: 3a 30 3e 0a 20 20 20 20 20 20 20 49 6e 20 74 68  :0>.       In th
4f10: 69 73 20 63 61 73 65 2c 20 69 66 20 74 68 65 20  is case, if the 
4f20: 73 70 65 63 69 66 69 65 64 20 6b 65 79 20 69 73  specified key is
4f30: 20 6e 6f 74 20 70 72 65 73 65 6e 74 20 69 6e 20   not present in 
4f40: 74 68 65 20 64 61 74 61 62 61 73 65 2c 20 74 68  the database, th
4f50: 65 0a 20 20 20 20 20 20 20 63 75 72 73 6f 72 20  e.       cursor 
4f60: 69 73 20 6e 6f 74 20 6c 65 66 74 20 70 6f 69 6e  is not left poin
4f70: 74 69 6e 67 20 74 6f 20 61 6e 79 20 64 61 74 61  ting to any data
4f80: 62 61 73 65 20 65 6e 74 72 79 20 28 69 2e 65 2e  base entry (i.e.
4f90: 20 63 61 6c 6c 69 6e 67 0a 20 20 20 20 20 20 20   calling.       
4fa0: 6c 73 6d 5f 63 73 72 5f 76 61 6c 69 64 28 29 20  lsm_csr_valid() 
4fb0: 72 65 74 75 72 6e 73 20 30 29 2e 0a 0a 20 20 3c  returns 0)...  <
4fc0: 64 74 3e 20 4c 53 4d 5f 53 45 45 4b 5f 4c 45 0a  dt> LSM_SEEK_LE.
4fd0: 20 20 3c 64 64 3e 20 3c 70 20 73 74 79 6c 65 3d    <dd> <p style=
4fe0: 6d 61 72 67 69 6e 2d 74 6f 70 3a 30 3e 0a 20 20  margin-top:0>.  
4ff0: 20 20 20 20 20 49 66 20 74 68 65 20 73 70 65 63       If the spec
5000: 69 66 69 65 64 20 6b 65 79 20 69 73 20 6e 6f 74  ified key is not
5010: 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65 20   present in the 
5020: 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
5030: 20 66 6f 75 72 74 68 0a 20 20 20 20 20 20 20 61   fourth.       a
5040: 72 67 75 6d 65 6e 74 20 74 6f 20 6c 73 6d 5f 63  rgument to lsm_c
5050: 73 72 5f 73 65 65 6b 28 29 20 69 73 20 4c 53 4d  sr_seek() is LSM
5060: 5f 53 45 45 4b 5f 4c 45 20 28 4c 65 73 73 20 74  _SEEK_LE (Less t
5070: 68 61 6e 20 6f 72 20 45 71 75 61 6c 29 2c 20 74  han or Equal), t
5080: 68 65 0a 20 20 20 20 20 20 20 63 75 72 73 6f 72  he.       cursor
5090: 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e   is left pointin
50a0: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  g to the databas
50b0: 65 20 65 6e 74 72 79 20 77 69 74 68 20 74 68 65  e entry with the
50c0: 20 6c 61 72 67 65 73 74 20 6b 65 79 0a 20 20 20   largest key.   
50d0: 20 20 20 20 74 68 61 74 20 69 73 20 6c 65 73 73      that is less
50e0: 20 74 68 61 6e 20 74 68 65 20 73 70 65 63 69 66   than the specif
50f0: 69 65 64 20 6b 65 79 2e 20 4f 72 2c 20 69 66 20  ied key. Or, if 
5100: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 65 6e 74  there are no ent
5110: 72 69 65 73 20 69 6e 0a 20 20 20 20 20 20 20 74  ries in.       t
5120: 68 65 20 64 61 74 61 62 61 73 65 20 77 69 74 68  he database with
5130: 20 6b 65 79 73 20 73 6d 61 6c 6c 65 72 20 74 68   keys smaller th
5140: 61 6e 20 74 68 65 20 73 70 65 63 69 66 69 65 64  an the specified
5150: 20 6b 65 79 2c 20 74 68 65 20 63 75 72 73 6f 72   key, the cursor
5160: 20 69 73 0a 20 20 20 20 20 20 20 6c 65 66 74 20   is.       left 
5170: 70 6f 69 6e 74 69 6e 67 20 74 6f 20 6e 6f 20 65  pointing to no e
5180: 6e 74 72 79 20 61 74 20 61 6c 6c 2e 0a 0a 20 20  ntry at all...  
5190: 3c 64 74 3e 20 4c 53 4d 5f 53 45 45 4b 5f 47 45  <dt> LSM_SEEK_GE
51a0: 0a 20 20 3c 64 64 3e 20 3c 70 20 73 74 79 6c 65  .  <dd> <p style
51b0: 3d 6d 61 72 67 69 6e 2d 74 6f 70 3a 30 3e 0a 20  =margin-top:0>. 
51c0: 20 20 20 20 20 20 49 66 20 74 68 65 20 73 70 65        If the spe
51d0: 63 69 66 69 65 64 20 6b 65 79 20 69 73 20 6e 6f  cified key is no
51e0: 74 20 70 72 65 73 65 6e 74 20 69 6e 20 74 68 65  t present in the
51f0: 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68   database and th
5200: 65 20 66 6f 75 72 74 68 0a 20 20 20 20 20 20 20  e fourth.       
5210: 61 72 67 75 6d 65 6e 74 20 74 6f 20 6c 73 6d 5f  argument to lsm_
5220: 63 73 72 5f 73 65 65 6b 28 29 20 69 73 20 4c 53  csr_seek() is LS
5230: 4d 5f 53 45 45 4b 5f 47 45 20 28 47 72 65 61 74  M_SEEK_GE (Great
5240: 65 72 20 74 68 61 6e 20 6f 72 20 45 71 75 61 6c  er than or Equal
5250: 29 2c 20 74 68 65 0a 20 20 20 20 20 20 20 63 75  ), the.       cu
5260: 72 73 6f 72 20 69 73 20 6c 65 66 74 20 70 6f 69  rsor is left poi
5270: 6e 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74  nting to the dat
5280: 61 62 61 73 65 20 65 6e 74 72 79 20 77 69 74 68  abase entry with
5290: 20 74 68 65 20 73 6d 61 6c 6c 65 73 74 20 6b 65   the smallest ke
52a0: 79 0a 20 20 20 20 20 20 20 74 68 61 74 20 69 73  y.       that is
52b0: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
52c0: 65 20 73 70 65 63 69 66 69 65 64 20 6b 65 79 2e  e specified key.
52d0: 20 4f 72 2c 20 69 66 20 74 68 65 72 65 20 61 72   Or, if there ar
52e0: 65 20 6e 6f 20 65 6e 74 72 69 65 73 20 0a 20 20  e no entries .  
52f0: 20 20 20 20 20 69 6e 20 74 68 65 20 64 61 74 61       in the data
5300: 62 61 73 65 20 77 69 74 68 20 6b 65 79 73 20 6c  base with keys l
5310: 61 72 67 65 72 20 74 68 61 6e 20 74 68 65 20 73  arger than the s
5320: 70 65 63 69 66 69 65 64 20 6b 65 79 2c 20 74 68  pecified key, th
5330: 65 20 63 75 72 73 6f 72 20 69 73 0a 20 20 20 20  e cursor is.    
5340: 20 20 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67     left pointing
5350: 20 74 6f 20 6e 6f 20 65 6e 74 72 79 20 61 74 20   to no entry at 
5360: 61 6c 6c 2e 0a 20 20 3c 64 64 3e 20 3c 70 20 73  all..  <dd> <p s
5370: 74 79 6c 65 3d 6d 61 72 67 69 6e 2d 74 6f 70 3a  tyle=margin-top:
5380: 30 3e 0a 3c 2f 64 6c 3e 0a 0a 3c 70 3e 20 43 61  0>.</dl>..<p> Ca
5390: 6c 6c 73 20 6d 61 64 65 20 74 6f 20 6c 73 6d 5f  lls made to lsm_
53a0: 63 73 72 5f 73 65 65 6b 28 29 20 77 69 74 68 20  csr_seek() with 
53b0: 4c 53 4d 5f 53 45 45 4b 5f 45 51 20 61 73 20 74  LSM_SEEK_EQ as t
53c0: 68 65 20 66 69 6e 61 6c 20 61 72 67 75 6d 65 6e  he final argumen
53d0: 74 20 61 72 65 0a 73 6c 69 67 68 74 6c 79 20 6d  t are.slightly m
53e0: 6f 72 65 20 65 66 66 69 63 69 65 6e 74 20 74 68  ore efficient th
53f0: 61 6e 20 74 68 6f 73 65 20 6d 61 64 65 20 73 70  an those made sp
5400: 65 63 69 66 79 69 6e 67 20 4c 53 4d 5f 53 45 45  ecifying LSM_SEE
5410: 4b 5f 4c 45 20 6f 72 20 4c 53 4d 5f 53 45 45 4b  K_LE or LSM_SEEK
5420: 5f 47 45 2e 0a 53 6f 20 74 6f 20 72 65 74 72 69  _GE..So to retri
5430: 65 76 65 20 61 20 73 70 65 63 69 66 69 63 20 65  eve a specific e
5440: 6e 74 72 79 20 66 72 6f 6d 20 61 20 64 61 74 61  ntry from a data
5450: 62 61 73 65 2c 20 4c 53 4d 5f 53 45 45 4b 5f 45  base, LSM_SEEK_E
5460: 51 20 73 68 6f 75 6c 64 20 62 65 0a 70 72 65 66  Q should be.pref
5470: 65 72 72 65 64 2e 20 54 68 65 20 6f 74 68 65 72  erred. The other
5480: 20 74 77 6f 20 76 61 6c 75 65 73 20 61 72 65 20   two values are 
5490: 70 72 69 6d 61 72 69 6c 79 20 75 73 65 66 75 6c  primarily useful
54a0: 20 66 6f 72 20 69 6d 70 6c 65 6d 65 6e 74 69 6e   for implementin
54b0: 67 0a 72 61 6e 67 65 20 71 75 65 72 69 65 73 2e  g.range queries.
54c0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 74 6f   For example, to
54d0: 20 69 74 65 72 61 74 65 20 62 61 63 6b 77 61 72   iterate backwar
54e0: 64 73 20 74 68 72 6f 75 67 68 20 61 6c 6c 20 6b  ds through all k
54f0: 65 79 73 20 66 72 6f 6d 20 22 67 67 67 22 20 0a  eys from "ggg" .
5500: 74 6f 20 22 63 63 22 2c 20 69 6e 63 6c 75 73 69  to "cc", inclusi
5510: 76 65 3a 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a  ve:..<verbatim>.
5520: 20 20 66 6f 72 28 72 63 20 3d 20 6c 73 6d 5f 63    for(rc = lsm_c
5530: 73 72 5f 73 65 65 6b 28 63 73 72 2c 20 22 67 67  sr_seek(csr, "gg
5540: 67 22 2c 20 33 2c 20 4c 53 4d 5f 53 45 45 4b 5f  g", 3, LSM_SEEK_
5550: 4c 45 29 3b 20 6c 73 6d 5f 63 73 72 5f 76 61 6c  LE); lsm_csr_val
5560: 69 64 28 63 73 72 29 3b 20 72 63 20 3d 20 6c 73  id(csr); rc = ls
5570: 6d 5f 63 73 72 5f 70 72 65 76 28 63 73 72 29 29  m_csr_prev(csr))
5580: 7b 0a 20 20 20 20 63 6f 6e 73 74 20 76 6f 69 64  {.    const void
5590: 20 2a 70 4b 65 79 3b 20 69 6e 74 20 6e 4b 65 79   *pKey; int nKey
55a0: 3b 0a 20 20 20 20 63 6f 6e 73 74 20 76 6f 69 64  ;.    const void
55b0: 20 2a 70 56 61 6c 3b 20 69 6e 74 20 6e 56 61 6c   *pVal; int nVal
55c0: 3b 0a 20 20 20 20 69 6e 74 20 72 65 73 3b 0a 0a  ;.    int res;..
55d0: 20 20 20 20 2f 2a 20 43 6f 6d 70 61 72 65 20 74      /* Compare t
55e0: 68 65 20 6b 65 79 20 74 68 61 74 20 74 68 65 20  he key that the 
55f0: 63 75 72 73 6f 72 20 63 75 72 72 65 6e 74 6c 79  cursor currently
5600: 20 70 6f 69 6e 74 73 20 74 6f 20 77 69 74 68 20   points to with 
5610: 22 63 63 22 2e 20 49 66 0a 20 20 20 20 2a 2a 20  "cc". If.    ** 
5620: 74 68 65 20 63 75 72 73 6f 72 20 6b 65 79 20 69  the cursor key i
5630: 73 20 6c 65 73 73 20 74 68 61 6e 20 22 63 63 22  s less than "cc"
5640: 2c 20 62 72 65 61 6b 20 6f 75 74 20 6f 66 20 74  , break out of t
5650: 68 65 20 6c 6f 6f 70 2e 20 2a 2f 0a 20 20 20 20  he loop. */.    
5660: 72 63 20 3d 20 6c 73 6d 5f 63 73 72 5f 63 6d 70  rc = lsm_csr_cmp
5670: 28 63 73 72 2c 20 22 63 63 22 2c 20 32 2c 20 26  (csr, "cc", 2, &
5680: 72 65 73 29 3b 0a 20 20 20 20 69 66 28 20 72 63  res);.    if( rc
5690: 21 3d 4c 53 4d 5f 4f 4b 20 7c 7c 20 72 65 73 3c  !=LSM_OK || res<
56a0: 30 20 29 20 62 72 65 61 6b 3b 0a 0a 20 20 20 20  0 ) break;..    
56b0: 72 63 20 3d 20 6c 73 6d 5f 63 73 72 5f 6b 65 79  rc = lsm_csr_key
56c0: 28 63 73 72 2c 20 26 70 4b 65 79 2c 20 26 6e 4b  (csr, &pKey, &nK
56d0: 65 79 29 3b 0a 20 20 20 20 69 66 28 20 72 63 3d  ey);.    if( rc=
56e0: 3d 4c 53 4d 5f 4f 4b 20 29 20 72 63 20 3d 20 6c  =LSM_OK ) rc = l
56f0: 73 6d 5f 63 73 72 5f 76 61 6c 75 65 28 63 73 72  sm_csr_value(csr
5700: 2c 20 26 70 56 61 6c 2c 20 26 6e 56 61 6c 29 3b  , &pVal, &nVal);
5710: 0a 20 20 20 20 69 66 28 20 72 63 21 3d 4c 53 4d  .    if( rc!=LSM
5720: 5f 4f 4b 20 29 20 62 72 65 61 6b 3b 0a 0a 20 20  _OK ) break;..  
5730: 20 20 2f 2a 20 41 74 20 74 68 69 73 20 70 6f 69    /* At this poi
5740: 6e 74 20 70 4b 65 79 20 70 6f 69 6e 74 73 20 74  nt pKey points t
5750: 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 6b 65  o the current ke
5760: 79 20 28 73 69 7a 65 20 6e 4b 65 79 20 62 79 74  y (size nKey byt
5770: 65 73 29 20 61 6e 64 0a 20 20 20 20 2a 2a 20 70  es) and.    ** p
5780: 56 61 6c 20 70 6f 69 6e 74 73 20 74 6f 20 74 68  Val points to th
5790: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
57a0: 76 61 6c 75 65 20 28 73 69 7a 65 20 6e 56 61 6c  value (size nVal
57b0: 20 62 79 74 65 73 29 2e 20 20 2a 2f 0a 20 20 7d   bytes).  */.  }
57c0: 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70  .</verbatim>..<p
57d0: 3e 49 6e 20 74 68 65 20 65 78 61 6d 70 6c 65 20  >In the example 
57e0: 63 6f 64 65 20 61 62 6f 76 65 2c 20 74 68 65 20  code above, the 
57f0: 63 61 6c 6c 20 74 6f 20 6c 73 6d 5f 63 73 72 5f  call to lsm_csr_
5800: 73 65 65 6b 28 29 20 70 6f 73 69 74 69 6f 6e 73  seek() positions
5810: 20 74 68 65 20 63 75 72 73 6f 72 0a 74 6f 20 70   the cursor.to p
5820: 6f 69 6e 74 20 74 6f 20 74 68 65 20 65 6e 74 72  oint to the entr
5830: 79 20 77 69 74 68 20 6b 65 79 20 22 67 67 67 22  y with key "ggg"
5840: 2c 20 69 66 20 69 74 20 65 78 69 73 74 73 2c 20  , if it exists, 
5850: 6f 72 20 74 6f 20 74 68 65 20 6c 61 72 67 65 73  or to the larges
5860: 74 20 65 6e 74 72 79 0a 69 6e 20 74 68 65 20 64  t entry.in the d
5870: 61 74 61 62 61 73 65 20 77 69 74 68 20 61 20 6b  atabase with a k
5880: 65 79 20 73 6d 61 6c 6c 65 72 20 74 68 61 6e 20  ey smaller than 
5890: 22 67 67 67 22 20 69 66 20 73 75 63 68 20 61 20  "ggg" if such a 
58a0: 6b 65 79 20 63 61 6e 20 62 65 20 66 6f 75 6e 64  key can be found
58b0: 2c 0a 6f 72 20 74 6f 20 45 4f 46 20 6f 74 68 65  ,.or to EOF othe
58c0: 72 77 69 73 65 2e 20 54 68 65 20 6c 73 6d 5f 63  rwise. The lsm_c
58d0: 73 72 5f 70 72 65 76 28 29 20 63 61 6c 6c 20 61  sr_prev() call a
58e0: 64 76 61 6e 63 65 73 20 74 68 65 20 63 75 72 73  dvances the curs
58f0: 6f 72 20 74 6f 20 74 68 65 20 0a 6e 65 78 74 20  or to the .next 
5900: 65 6e 74 72 79 20 69 6e 20 74 68 65 20 64 61 74  entry in the dat
5910: 61 62 61 73 65 20 66 69 6c 65 20 28 69 6e 20 6b  abase file (in k
5920: 65 79 20 6f 72 64 65 72 20 66 72 6f 6d 20 6c 61  ey order from la
5930: 72 67 65 73 74 20 74 6f 20 73 6d 61 6c 6c 65 73  rgest to smalles
5940: 74 29 2c 20 61 6e 64 0a 74 68 65 20 6c 73 6d 5f  t), and.the lsm_
5950: 63 73 72 5f 76 61 6c 69 64 28 29 20 63 61 6c 6c  csr_valid() call
5960: 20 72 65 74 75 72 6e 73 20 30 20 74 6f 20 62 72   returns 0 to br
5970: 65 61 6b 20 6f 75 74 20 6f 66 20 74 68 65 20 6c  eak out of the l
5980: 6f 6f 70 20 6f 6e 63 65 20 74 68 65 0a 63 75 72  oop once the.cur
5990: 73 6f 72 20 69 73 20 61 64 76 61 6e 63 65 20 70  sor is advance p
59a0: 61 73 74 20 74 68 65 20 65 6e 74 72 79 20 77 69  ast the entry wi
59b0: 74 68 20 74 68 65 20 73 6d 61 6c 6c 65 73 74 20  th the smallest 
59c0: 6b 65 79 20 69 6e 20 74 68 65 20 64 61 74 61 62  key in the datab
59d0: 61 73 65 2e 20 53 6f 0a 6f 6e 20 69 74 73 20 6f  ase. So.on its o
59e0: 77 6e 2c 20 74 68 65 20 22 66 6f 72 22 20 73 74  wn, the "for" st
59f0: 61 74 65 6d 65 6e 74 20 73 65 72 76 65 73 20 74  atement serves t
5a00: 6f 20 69 74 65 72 61 74 65 20 74 68 65 20 63 75  o iterate the cu
5a10: 72 73 6f 72 20 69 6e 20 72 65 76 65 72 73 65 20  rsor in reverse 
5a20: 6f 72 64 65 72 20 0a 74 68 72 6f 75 67 68 20 61  order .through a
5a30: 6c 6c 20 6b 65 79 73 20 69 6e 20 74 68 65 20 64  ll keys in the d
5a40: 61 74 61 62 61 73 65 20 6c 65 73 73 20 74 68 61  atabase less tha
5a50: 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 22 67  n or equal to "g
5a60: 67 67 22 2e 0a 0a 3c 70 3e 54 68 65 20 63 61 6c  gg"...<p>The cal
5a70: 6c 20 74 6f 20 3c 61 20 68 72 65 66 3d 6c 73 6d  l to <a href=lsm
5a80: 61 70 69 2e 77 69 6b 69 23 6c 73 6d 5f 63 73 72  api.wiki#lsm_csr
5a90: 5f 63 6d 70 3e 6c 73 6d 5f 63 73 72 5f 63 6d 70  _cmp>lsm_csr_cmp
5aa0: 28 29 3c 2f 61 3e 20 63 61 6c 6c 20 69 6e 20 74  ()</a> call in t
5ab0: 68 65 0a 62 6f 64 79 20 6f 66 20 74 68 65 20 6c  he.body of the l
5ac0: 6f 6f 70 20 69 73 20 75 73 65 64 20 74 6f 20 65  oop is used to e
5ad0: 6e 66 6f 72 63 65 20 74 68 65 20 6c 6f 77 65 72  nforce the lower
5ae0: 20 62 6f 75 6e 64 20 28 6b 65 79 73 20 3e 3d 20   bound (keys >= 
5af0: 22 63 63 22 29 20 6f 6e 20 74 68 65 20 0a 72 61  "cc") on the .ra
5b00: 6e 67 65 20 71 75 65 72 79 20 62 79 20 62 72 65  nge query by bre
5b10: 61 6b 69 6e 67 20 6f 75 74 20 6f 66 20 74 68 65  aking out of the
5b20: 20 6c 6f 6f 70 20 69 66 20 61 6e 20 65 6e 74 72   loop if an entr
5b30: 79 20 77 69 74 68 20 61 20 6b 65 79 20 73 6d 61  y with a key sma
5b40: 6c 6c 65 72 20 74 68 61 6e 20 0a 22 63 63 22 20  ller than ."cc" 
5b50: 69 73 20 65 76 65 72 20 76 69 73 69 74 65 64 2e  is ever visited.
5b60: 20 6c 73 6d 5f 63 73 72 5f 63 6d 70 28 29 20 68   lsm_csr_cmp() h
5b70: 61 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  as the following
5b80: 20 73 69 67 6e 61 74 75 72 65 3a 0a 0a 3c 76 65   signature:..<ve
5b90: 72 62 61 74 69 6d 3e 0a 20 20 69 6e 74 20 6c 73  rbatim>.  int ls
5ba0: 6d 5f 63 73 72 5f 63 6d 70 28 6c 73 6d 5f 63 75  m_csr_cmp(lsm_cu
5bb0: 72 73 6f 72 20 2a 63 73 72 2c 20 63 6f 6e 73 74  rsor *csr, const
5bc0: 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74   void *pKey, int
5bd0: 20 6e 4b 65 79 2c 20 69 6e 74 20 2a 70 69 52 65   nKey, int *piRe
5be0: 73 29 3b 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a  s);.</verbatim>.
5bf0: 0a 3c 70 3e 20 57 68 65 6e 20 6c 73 6d 5f 63 73  .<p> When lsm_cs
5c00: 72 5f 63 6d 70 28 29 20 69 73 20 63 61 6c 6c 65  r_cmp() is calle
5c10: 64 2c 20 74 68 65 20 6b 65 79 20 73 70 65 63 69  d, the key speci
5c20: 66 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  fied by the seco
5c30: 6e 64 20 61 6e 64 20 74 68 69 72 64 0a 61 72 67  nd and third.arg
5c40: 75 6d 65 6e 74 73 20 28 70 4b 65 79 20 61 6e 64  uments (pKey and
5c50: 20 6e 4b 65 79 29 20 69 73 20 63 6f 6d 70 61 72   nKey) is compar
5c60: 65 64 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  ed to the databa
5c70: 73 65 20 6b 65 79 20 74 68 61 74 20 74 68 65 20  se key that the 
5c80: 63 75 72 73 6f 72 0a 63 75 72 72 65 6e 74 6c 79  cursor.currently
5c90: 20 70 6f 69 6e 74 73 20 74 6f 2e 20 41 73 73 75   points to. Assu
5ca0: 6d 69 6e 67 20 6e 6f 20 65 72 72 6f 72 20 6f 63  ming no error oc
5cb0: 63 75 72 73 2c 20 64 65 70 65 6e 64 69 6e 67 20  curs, depending 
5cc0: 6f 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  on whether or no
5cd0: 74 20 74 68 65 0a 63 75 72 73 6f 72 73 20 6b 65  t the.cursors ke
5ce0: 79 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20  y is less than, 
5cf0: 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65  equal to, or gre
5d00: 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 70  ater than the sp
5d10: 65 63 69 66 69 65 64 20 6b 65 79 2c 20 2a 70 69  ecified key, *pi
5d20: 52 65 73 0a 69 73 20 73 65 74 20 74 6f 20 61 20  Res.is set to a 
5d30: 76 61 6c 75 65 20 6c 65 73 73 20 74 68 61 6e 2c  value less than,
5d40: 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72   equal to, or gr
5d50: 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f 20  eater than zero 
5d60: 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
5d70: 2e 0a 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  ..In other words
5d80: 3a 0a 0a 3c 70 72 65 3e 3c 69 3e 20 20 2a 70 69  :..<pre><i>  *pi
5d90: 52 65 73 20 3d 20 28 63 75 72 73 6f 72 73 20 6b  Res = (cursors k
5da0: 65 79 29 20 2d 20 28 73 70 65 63 69 66 69 65 64  ey) - (specified
5db0: 20 6b 65 79 29 20 3c 2f 69 3e 3c 2f 70 72 65 3e   key) </i></pre>
5dc0: 0a 0a 0a 3c 68 32 20 69 64 3d 64 61 74 61 62 61  ...<h2 id=databa
5dd0: 73 65 5f 74 72 61 6e 73 61 63 74 69 6f 6e 73 5f  se_transactions_
5de0: 61 6e 64 5f 6d 76 63 63 3e 33 2e 34 2e 20 44 61  and_mvcc>3.4. Da
5df0: 74 61 62 61 73 65 20 54 72 61 6e 73 61 63 74 69  tabase Transacti
5e00: 6f 6e 73 20 61 6e 64 20 4d 56 43 43 20 3c 2f 68  ons and MVCC </h
5e10: 32 3e 0a 0a 3c 70 3e 4c 53 4d 20 73 75 70 70 6f  2>..<p>LSM suppo
5e20: 72 74 73 20 61 20 73 69 6e 67 6c 65 2d 77 72 69  rts a single-wri
5e30: 74 65 72 2f 6d 75 6c 74 69 70 6c 65 2d 72 65 61  ter/multiple-rea
5e40: 64 65 72 20 0a 3c 61 20 68 72 65 66 3d 68 74 74  der .<a href=htt
5e50: 70 3a 2f 2f 65 6e 2e 77 69 6b 69 70 65 64 69 61  p://en.wikipedia
5e60: 2e 6f 72 67 2f 77 69 6b 69 2f 4d 75 6c 74 69 76  .org/wiki/Multiv
5e70: 65 72 73 69 6f 6e 5f 63 6f 6e 63 75 72 72 65 6e  ersion_concurren
5e80: 63 79 5f 63 6f 6e 74 72 6f 6c 3e 4d 56 43 43 3c  cy_control>MVCC<
5e90: 2f 61 3e 0a 62 61 73 65 64 20 74 72 61 6e 73 61  /a>.based transa
5ea0: 63 74 69 6f 6e 61 6c 20 63 6f 6e 63 75 72 72 65  ctional concurre
5eb0: 6e 63 79 20 6d 6f 64 65 6c 2e 20 54 68 69 73 20  ncy model. This 
5ec0: 69 73 20 74 68 65 20 73 61 6d 65 20 6d 6f 64 65  is the same mode
5ed0: 6c 20 74 68 61 74 20 53 51 4c 69 74 65 0a 73 75  l that SQLite.su
5ee0: 70 70 6f 72 74 73 20 69 6e 20 3c 61 20 68 72 65  pports in <a hre
5ef0: 66 3d 22 68 74 74 70 3a 2f 2f 77 77 77 2e 73 71  f="http://www.sq
5f00: 6c 69 74 65 2e 6f 72 67 2f 77 61 6c 2e 68 74 6d  lite.org/wal.htm
5f10: 6c 22 3e 57 41 4c 20 6d 6f 64 65 3c 2f 61 3e 2e  l">WAL mode</a>.
5f20: 0a 0a 3c 70 3e 41 20 72 65 61 64 2d 74 72 61 6e  ..<p>A read-tran
5f30: 73 61 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20  saction must be 
5f40: 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65 72 20  opened in order 
5f50: 74 6f 20 72 65 61 64 20 66 72 6f 6d 20 74 68 65  to read from the
5f60: 20 64 61 74 61 62 61 73 65 2e 20 0a 41 66 74 65   database. .Afte
5f70: 72 20 61 20 72 65 61 64 2d 74 72 61 6e 73 61 63  r a read-transac
5f80: 74 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 6f 70  tion has been op
5f90: 65 6e 65 64 2c 20 6e 6f 20 77 72 69 74 65 73 20  ened, no writes 
5fa0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
5fb0: 6d 61 64 65 20 0a 62 79 20 6f 74 68 65 72 20 64  made .by other d
5fc0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
5fd0: 6f 6e 73 20 61 72 65 20 76 69 73 69 62 6c 65 20  ons are visible 
5fe0: 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
5ff0: 72 65 61 64 65 72 2e 20 49 6e 73 74 65 61 64 2c  reader. Instead,
6000: 0a 74 68 65 20 72 65 61 64 65 72 20 6f 70 65 72  .the reader oper
6010: 61 74 65 73 20 6f 6e 20 61 20 73 6e 61 70 73 68  ates on a snapsh
6020: 6f 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  ot of the databa
6030: 73 65 20 61 73 20 69 74 20 65 78 69 73 74 65 64  se as it existed
6040: 20 77 68 65 6e 20 74 68 65 0a 72 65 61 64 20 74   when the.read t
6050: 72 61 6e 73 61 63 74 69 6f 6e 20 77 61 73 20 66  ransaction was f
6060: 69 72 73 74 20 6f 70 65 6e 65 64 2e 20 41 6e 79  irst opened. Any
6070: 20 6e 75 6d 62 65 72 20 6f 66 20 63 6c 69 65 6e   number of clien
6080: 74 73 20 6d 61 79 20 73 69 6d 75 6c 74 61 6e 65  ts may simultane
6090: 6f 75 73 6c 79 0a 6d 61 69 6e 74 61 69 6e 20 6f  ously.maintain o
60a0: 70 65 6e 20 72 65 61 64 2d 74 72 61 6e 73 61 63  pen read-transac
60b0: 74 69 6f 6e 73 2e 0a 0a 3c 70 3e 49 66 20 6f 6e  tions...<p>If on
60c0: 65 20 69 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  e is not already
60d0: 20 6f 70 65 6e 2c 20 61 20 72 65 61 64 2d 74 72   open, a read-tr
60e0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65  ansaction is ope
60f0: 6e 65 64 20 77 68 65 6e 20 61 20 64 61 74 61 62  ned when a datab
6100: 61 73 65 20 0a 63 75 72 73 6f 72 20 69 73 20 63  ase .cursor is c
6110: 72 65 61 74 65 64 20 28 74 68 65 20 6c 73 6d 5f  reated (the lsm_
6120: 63 73 72 5f 6f 70 65 6e 28 29 20 66 75 6e 63 74  csr_open() funct
6130: 69 6f 6e 29 2e 20 49 74 20 69 73 20 63 6c 6f 73  ion). It is clos
6140: 65 64 20 77 68 65 6e 20 74 68 65 20 6e 75 6d 62  ed when the numb
6150: 65 72 0a 6f 66 20 6f 70 65 6e 20 63 75 72 73 6f  er.of open curso
6160: 72 73 20 64 72 6f 70 73 20 74 6f 20 7a 65 72 6f  rs drops to zero
6170: 2e 0a 0a 3c 70 3e 41 20 77 72 69 74 65 2d 74 72  ...<p>A write-tr
6180: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 72 65 71  ansaction is req
6190: 75 69 72 65 64 20 74 6f 20 77 72 69 74 65 20 74  uired to write t
61a0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20  o the database. 
61b0: 41 74 20 61 6e 79 20 70 6f 69 6e 74 2c 0a 61 74  At any point,.at
61c0: 20 6d 6f 73 74 20 6f 6e 65 20 64 61 74 61 62 61   most one databa
61d0: 73 65 20 63 6c 69 65 6e 74 20 6d 61 79 20 68 6f  se client may ho
61e0: 6c 64 20 61 6e 20 6f 70 65 6e 20 77 72 69 74 65  ld an open write
61f0: 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 49 66   transaction. If
6200: 20 61 6e 6f 74 68 65 72 0a 63 6c 69 65 6e 74 20   another.client 
6210: 61 6c 72 65 61 64 79 20 68 61 73 20 61 6e 20 6f  already has an o
6220: 70 65 6e 20 77 72 69 74 65 20 74 72 61 6e 73 61  pen write transa
6230: 63 74 69 6f 6e 2c 20 74 68 65 6e 20 61 74 74 65  ction, then atte
6240: 6d 70 74 69 6e 67 20 74 6f 20 6f 70 65 6e 20 6f  mpting to open o
6250: 6e 65 0a 69 73 20 61 6e 20 65 72 72 6f 72 20 28  ne.is an error (
6260: 4c 53 4d 5f 42 55 53 59 29 2e 20 49 66 20 61 20  LSM_BUSY). If a 
6270: 72 65 61 64 2d 74 72 61 6e 73 61 63 74 69 6f 6e  read-transaction
6280: 20 69 73 20 61 6c 72 65 61 64 79 20 6f 70 65 6e   is already open
6290: 20 77 68 65 6e 20 74 68 65 0a 77 72 69 74 65 2d   when the.write-
62a0: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 6f  transaction is o
62b0: 70 65 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  pened, then the 
62c0: 73 6e 61 70 73 68 6f 74 20 72 65 61 64 20 62 79  snapshot read by
62d0: 20 74 68 65 20 72 65 61 64 2d 74 72 61 6e 73 61   the read-transa
62e0: 63 74 69 6f 6e 0a 6d 75 73 74 20 63 6f 72 72 65  ction.must corre
62f0: 73 70 6f 6e 64 20 74 6f 20 74 68 65 20 6d 6f 73  spond to the mos
6300: 74 20 72 65 63 65 6e 74 20 76 65 72 73 69 6f 6e  t recent version
6310: 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
6320: 2e 20 4f 74 68 65 72 77 69 73 65 2c 0a 74 68 65  . Otherwise,.the
6330: 20 61 74 74 65 6d 70 74 20 74 6f 20 6f 70 65 6e   attempt to open
6340: 20 74 68 65 20 77 72 69 74 65 2d 74 72 61 6e 73   the write-trans
6350: 61 63 74 69 6f 6e 20 66 61 69 6c 73 20 28 4c 53  action fails (LS
6360: 4d 5f 42 55 53 59 29 2e 20 49 6e 20 6f 74 68 65  M_BUSY). In othe
6370: 72 20 77 6f 72 64 73 2c 0a 69 66 20 61 6e 79 20  r words,.if any 
6380: 6f 74 68 65 72 20 63 6c 69 65 6e 74 20 68 61 73  other client has
6390: 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20   written to the 
63a0: 64 61 74 61 62 61 73 65 20 73 69 6e 63 65 20 74  database since t
63b0: 68 65 20 63 75 72 72 65 6e 74 20 63 6c 69 65 6e  he current clien
63c0: 74 73 0a 72 65 61 64 2d 74 72 61 6e 73 61 63 74  ts.read-transact
63d0: 69 6f 6e 20 77 61 73 20 6f 70 65 6e 65 64 2c 20  ion was opened, 
63e0: 69 74 20 77 69 6c 6c 20 6e 6f 74 20 62 65 20 70  it will not be p
63f0: 6f 73 73 69 62 6c 65 20 74 6f 20 75 70 67 72 61  ossible to upgra
6400: 64 65 20 74 6f 20 61 0a 77 72 69 74 65 2d 74 72  de to a.write-tr
6410: 61 6e 73 61 63 74 69 6f 6e 2e 0a 0a 3c 70 3e 57  ansaction...<p>W
6420: 72 69 74 65 2d 74 72 61 6e 73 61 63 74 69 6f 6e  rite-transaction
6430: 73 20 6d 61 79 20 62 65 20 6f 70 65 6e 65 64 20  s may be opened 
6440: 65 69 74 68 65 72 20 69 6d 70 6c 69 63 69 74 6c  either implicitl
6450: 79 20 6f 72 20 65 78 70 6c 69 63 69 74 6c 79 2e  y or explicitly.
6460: 20 49 66 20 61 6e 79 0a 6f 66 20 74 68 65 20 66   If any.of the f
6470: 6f 6c 6c 6f 77 69 6e 67 20 66 75 6e 63 74 69 6f  ollowing functio
6480: 6e 73 20 61 72 65 20 63 61 6c 6c 65 64 20 74 6f  ns are called to
6490: 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 64 61   write to the da
64a0: 74 61 62 61 73 65 20 77 68 65 6e 20 74 68 65 72  tabase when ther
64b0: 65 20 0a 69 73 20 6e 6f 20 77 72 69 74 65 2d 74  e .is no write-t
64c0: 72 61 6e 73 61 63 74 69 6f 6e 20 6f 70 65 6e 2c  ransaction open,
64d0: 20 74 68 65 6e 20 61 6e 20 69 6d 70 6c 69 63 69   then an implici
64e0: 74 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74  t write-transact
64f0: 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 20 61 6e  ion is opened an
6500: 64 0a 63 6c 6f 73 65 64 20 28 63 6f 6d 6d 69 74  d.closed (commit
6510: 74 65 64 29 20 77 69 74 68 69 6e 20 74 68 65 20  ted) within the 
6520: 63 61 6c 6c 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  call:..<ul>.  <l
6530: 69 3e 20 6c 73 6d 5f 69 6e 73 65 72 74 28 29 0a  i> lsm_insert().
6540: 20 20 3c 6c 69 3e 20 6c 73 6d 5f 64 65 6c 65 74    <li> lsm_delet
6550: 65 28 29 0a 20 20 3c 6c 69 3e 20 6c 73 6d 5f 64  e().  <li> lsm_d
6560: 65 6c 65 74 65 5f 72 61 6e 67 65 28 29 0a 3c 2f  elete_range().</
6570: 75 6c 3e 0a 0a 3c 70 3e 54 68 69 73 20 6d 65 61  ul>..<p>This mea
6580: 6e 73 2c 20 6f 66 20 63 6f 75 72 73 65 2c 20 74  ns, of course, t
6590: 68 61 74 20 61 6c 6c 20 74 68 72 65 65 20 6f 66  hat all three of
65a0: 20 74 68 65 20 61 62 6f 76 65 20 6d 61 79 20 72   the above may r
65b0: 65 74 75 72 6e 20 4c 53 4d 5f 42 55 53 59 2e 0a  eturn LSM_BUSY..
65c0: 49 6e 64 69 63 61 74 69 6e 67 20 65 69 74 68 65  Indicating eithe
65d0: 72 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20 63  r that another c
65e0: 6c 69 65 6e 74 20 63 75 72 72 65 6e 74 6c 79 20  lient currently 
65f0: 68 61 73 20 61 6e 20 6f 70 65 6e 20 77 72 69 74  has an open writ
6600: 65 2d 74 72 61 6e 73 61 63 74 69 6f 6e 2c 0a 6f  e-transaction,.o
6610: 72 20 74 68 61 74 20 74 68 65 72 65 20 69 73 20  r that there is 
6620: 63 75 72 72 65 6e 74 6c 79 20 61 6e 20 6f 70 65  currently an ope
6630: 6e 20 72 65 61 64 2d 74 72 61 6e 73 61 63 74 69  n read-transacti
6640: 6f 6e 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  on and some othe
6650: 72 20 63 6c 69 65 6e 74 0a 68 61 73 20 77 72 69  r client.has wri
6660: 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tten to the data
6670: 62 61 73 65 20 73 69 6e 63 65 20 69 74 20 77 61  base since it wa
6680: 73 20 6f 70 65 6e 65 64 2e 20 0a 0a 3c 70 3e 57  s opened. ..<p>W
6690: 68 65 6e 20 61 6e 20 65 78 70 6c 69 63 69 74 6c  hen an explicitl
66a0: 79 20 6f 70 65 6e 65 64 20 74 72 61 6e 73 61 63  y opened transac
66b0: 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2c 20  tion is closed, 
66c0: 69 74 20 6d 61 79 20 65 69 74 68 65 72 20 62 65  it may either be
66d0: 20 0a 63 6f 6d 6d 69 74 74 65 64 20 6f 72 20 72   .committed or r
66e0: 6f 6c 6c 65 64 20 62 61 63 6b 20 28 72 65 76 65  olled back (reve
66f0: 72 74 65 64 20 2d 20 73 6f 20 74 68 61 74 20 74  rted - so that t
6700: 68 65 20 73 74 61 74 65 20 6f 66 20 74 68 65 20  he state of the 
6710: 64 61 74 61 62 61 73 65 20 69 73 0a 75 6e 63 68  database is.unch
6720: 61 6e 67 65 64 29 2e 20 57 69 74 68 69 6e 20 61  anged). Within a
6730: 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74 69   write-transacti
6740: 6f 6e 20 74 68 65 72 65 20 6d 61 79 20 61 6c 73  on there may als
6750: 6f 20 62 65 20 61 20 68 69 65 72 61 72 63 68 79  o be a hierarchy
6760: 20 6f 66 20 0a 6e 65 73 74 65 64 20 73 75 62 2d   of .nested sub-
6770: 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 74 68 61  transactions tha
6780: 74 20 6d 61 79 20 62 65 20 72 6f 6c 6c 65 64 20  t may be rolled 
6790: 62 61 63 6b 20 6f 72 20 63 6f 6d 6d 69 74 74 65  back or committe
67a0: 64 20 69 6e 64 65 70 65 6e 64 65 6e 74 6c 79 2e  d independently.
67b0: 0a 41 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63  .A write-transac
67c0: 74 69 6f 6e 20 69 73 20 61 20 70 72 6f 70 65 72  tion is a proper
67d0: 74 79 20 6f 66 20 61 20 64 61 74 61 62 61 73 65  ty of a database
67e0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 2d 20 61 6c   connection - al
67f0: 6c 20 77 72 69 74 65 73 0a 6d 61 64 65 20 62 79  l writes.made by
6800: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
6810: 62 65 63 6f 6d 65 20 70 61 72 74 20 6f 66 20 74  become part of t
6820: 68 65 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73  he current trans
6830: 61 63 74 69 6f 6e 20 28 61 6e 64 20 70 6f 73 73  action (and poss
6840: 69 62 6c 79 0a 73 75 62 2d 74 72 61 6e 73 61 63  ibly.sub-transac
6850: 74 69 6f 6e 29 2e 0a 0a 3c 70 3e 54 68 65 20 66  tion)...<p>The f
6860: 75 6e 63 74 69 6f 6e 73 20 75 73 65 64 20 74 6f  unctions used to
6870: 20 6f 70 65 6e 2c 20 63 6f 6d 6d 69 74 20 61 6e   open, commit an
6880: 64 20 72 6f 6c 6c 62 61 63 6b 20 65 78 70 6c 69  d rollback expli
6890: 63 69 74 79 20 74 72 61 6e 73 61 63 74 69 6f 6e  city transaction
68a0: 73 0a 61 6e 64 20 73 75 62 2d 74 72 61 6e 73 61  s.and sub-transa
68b0: 63 74 69 6f 6e 73 20 61 72 65 2c 20 72 65 73 70  ctions are, resp
68c0: 65 63 74 69 76 65 6c 79 3a 0a 0a 3c 76 65 72 62  ectively:..<verb
68d0: 61 74 69 6d 3e 0a 20 20 69 6e 74 20 6c 73 6d 5f  atim>.  int lsm_
68e0: 62 65 67 69 6e 28 6c 73 6d 5f 64 62 20 2a 2c 20  begin(lsm_db *, 
68f0: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 6c 73 6d 5f  int);.  int lsm_
6900: 63 6f 6d 6d 69 74 28 6c 73 6d 5f 64 62 20 2a 2c  commit(lsm_db *,
6910: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 6c 73 6d   int);.  int lsm
6920: 5f 72 6f 6c 6c 62 61 63 6b 28 6c 73 6d 5f 64 62  _rollback(lsm_db
6930: 20 2a 2c 20 69 6e 74 29 3b 0a 3c 2f 76 65 72 62   *, int);.</verb
6940: 61 74 69 6d 3e 0a 0a 3c 70 3e 49 6e 20 61 6c 6c  atim>..<p>In all
6950: 20 63 61 73 65 73 2c 20 74 68 65 20 73 65 63 6f   cases, the seco
6960: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
6970: 65 69 74 68 65 72 20 74 68 65 20 6d 61 78 69 6d  either the maxim
6980: 75 6d 20 28 6c 73 6d 5f 63 6f 6d 6d 69 74 28 29  um (lsm_commit()
6990: 2c 0a 6c 73 6d 5f 72 6f 6c 6c 62 61 63 6b 28 29  ,.lsm_rollback()
69a0: 29 20 6f 72 20 6d 69 6e 69 6d 75 6d 20 28 6c 73  ) or minimum (ls
69b0: 6d 5f 62 65 67 69 6e 28 29 29 20 74 68 65 20 6e  m_begin()) the n
69c0: 75 6d 62 65 72 20 6f 66 20 6e 65 73 74 65 64 0a  umber of nested.
69d0: 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74 69 6f  write-transactio
69e0: 6e 73 20 74 68 61 74 20 77 69 6c 6c 20 65 78 69  ns that will exi
69f0: 73 74 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 65  st following the
6a00: 20 63 61 6c 6c 20 28 61 73 73 75 6d 69 6e 67 20   call (assuming 
6a10: 69 74 20 73 75 63 63 65 65 64 73 29 2e 0a 49 66  it succeeds)..If
6a20: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
6a30: 6d 65 74 65 72 20 70 61 73 73 65 64 20 69 73 20  meter passed is 
6a40: 3c 69 3e 4e 3c 2f 69 3e 2c 20 20 0a 0a 3c 75 6c  <i>N</i>,  ..<ul
6a50: 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e 43 61 6c 6c  >.  <li> <p>Call
6a60: 69 6e 67 20 3c 62 3e 6c 73 6d 5f 62 65 67 69 6e  ing <b>lsm_begin
6a70: 28 64 62 2c 20 3c 69 3e 4e 3c 2f 69 3e 29 3c 2f  (db, <i>N</i>)</
6a80: 62 3e 20 61 74 74 65 6d 70 74 73 20 6f 70 65 6e  b> attempts open
6a90: 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 0a 20  s zero or more. 
6aa0: 20 20 20 20 20 20 6e 65 73 74 65 64 20 77 72 69        nested wri
6ab0: 74 65 2d 74 72 61 6e 73 61 63 74 69 6f 6e 73 20  te-transactions 
6ac0: 73 6f 20 74 68 61 74 20 74 68 65 20 64 61 74 61  so that the data
6ad0: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
6ae0: 69 73 20 6c 65 66 74 20 77 69 74 68 0a 20 20 20  is left with.   
6af0: 20 20 20 20 61 74 20 6c 65 61 73 74 20 3c 69 3e      at least <i>
6b00: 4e 3c 2f 69 3e 20 6f 70 65 6e 20 6e 65 73 74 65  N</i> open neste
6b10: 64 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74  d write-transact
6b20: 69 6f 6e 73 2e 20 49 66 20 74 68 65 72 65 20 61  ions. If there a
6b30: 72 65 20 61 6c 72 65 61 64 79 0a 20 20 20 20 20  re already.     
6b40: 20 20 3c 69 3e 4e 3c 2f 69 3e 20 6f 72 20 6d 6f    <i>N</i> or mo
6b50: 72 65 20 6f 70 65 6e 20 6e 65 73 74 65 64 20 77  re open nested w
6b60: 72 69 74 65 2d 74 72 61 6e 73 61 63 74 69 6f 6e  rite-transaction
6b70: 73 20 6f 70 65 6e 2c 20 74 68 65 6e 20 6c 73 6d  s open, then lsm
6b80: 5f 62 65 67 69 6e 28 64 62 2c 0a 20 20 20 20 20  _begin(db,.     
6b90: 20 20 3c 69 3e 4e 3c 2f 69 3e 29 20 69 73 20 61    <i>N</i>) is a
6ba0: 20 6e 6f 2d 6f 70 2e 20 6c 73 6d 5f 62 65 67 69   no-op. lsm_begi
6bb0: 6e 28 64 62 2c 20 30 29 20 69 73 20 61 6c 77 61  n(db, 0) is alwa
6bc0: 79 73 20 61 20 6e 6f 2d 6f 70 2e 20 43 61 6c 6c  ys a no-op. Call
6bd0: 69 6e 67 0a 20 20 20 20 20 20 20 6c 73 6d 5f 62  ing.       lsm_b
6be0: 65 67 69 6e 28 64 62 2c 20 31 29 20 77 68 65 6e  egin(db, 1) when
6bf0: 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6f 70 65   there is no ope
6c00: 6e 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74  n write-transact
6c10: 69 6f 6e 20 6f 70 65 6e 73 20 61 0a 20 20 20 20  ion opens a.    
6c20: 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 77 72 69     top-level wri
6c30: 74 65 2d 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a  te-transaction..
6c40: 0a 20 20 3c 6c 69 3e 20 3c 70 3e 43 61 6c 6c 69  .  <li> <p>Calli
6c50: 6e 67 20 3c 62 3e 6c 73 6d 5f 63 6f 6d 6d 69 74  ng <b>lsm_commit
6c60: 28 64 62 2c 20 3c 69 3e 4e 3c 2f 69 3e 29 3c 2f  (db, <i>N</i>)</
6c70: 62 3e 20 63 6f 6d 6d 69 74 73 20 7a 65 72 6f 20  b> commits zero 
6c80: 6f 72 20 6d 6f 72 65 20 6e 65 73 74 65 64 0a 20  or more nested. 
6c90: 20 20 20 20 20 20 77 72 69 74 65 2d 74 72 61 6e        write-tran
6ca0: 73 61 63 74 69 6f 6e 73 20 73 6f 20 74 68 61 74  sactions so that
6cb0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
6cc0: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6c 65 66 74  nnection is left
6cd0: 20 77 69 74 68 20 61 74 20 6d 6f 73 74 0a 20 20   with at most.  
6ce0: 20 20 20 20 20 3c 69 3e 4e 3c 2f 69 3e 20 6f 70       <i>N</i> op
6cf0: 65 6e 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63  en write-transac
6d00: 74 69 6f 6e 73 2e 20 49 66 20 74 68 65 20 63 6f  tions. If the co
6d10: 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 3c 69 3e  nnection has <i>
6d20: 4e 3c 2f 69 3e 20 6f 72 0a 20 20 20 20 20 20 20  N</i> or.       
6d30: 66 65 77 65 72 20 6f 70 65 6e 20 6e 65 73 74 65  fewer open neste
6d40: 64 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74  d write-transact
6d50: 69 6f 6e 73 2c 20 74 68 65 6e 20 6c 73 6d 5f 63  ions, then lsm_c
6d60: 6f 6d 6d 69 74 28 64 62 2c 20 3c 69 3e 4e 3c 2f  ommit(db, <i>N</
6d70: 69 3e 29 20 69 73 20 61 0a 20 20 20 20 20 20 20  i>) is a.       
6d80: 6e 6f 2d 6f 70 2e 20 43 61 6c 6c 69 6e 67 20 6c  no-op. Calling l
6d90: 73 6d 5f 63 6f 6d 6d 69 74 28 64 62 2c 20 30 29  sm_commit(db, 0)
6da0: 20 63 6f 6d 6d 69 74 73 20 74 68 65 20 6f 75 74   commits the out
6db0: 65 72 6d 6f 73 74 20 74 72 61 6e 73 61 63 74 69  ermost transacti
6dc0: 6f 6e 0a 20 20 20 20 20 20 20 28 69 66 20 61 6e  on.       (if an
6dd0: 79 29 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e 43  y)...  <li> <p>C
6de0: 61 6c 6c 69 6e 67 20 3c 62 3e 6c 73 6d 5f 72 6f  alling <b>lsm_ro
6df0: 6c 6c 62 61 63 6b 28 64 62 2c 20 30 29 3c 2f 62  llback(db, 0)</b
6e00: 3e 20 63 6c 6f 73 65 73 20 61 6e 64 20 72 6f 6c  > closes and rol
6e10: 6c 73 20 62 61 63 6b 20 74 68 65 20 0a 20 20 20  ls back the .   
6e20: 20 20 20 20 74 6f 70 2d 6c 65 76 65 6c 20 77 72      top-level wr
6e30: 69 74 65 2d 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ite-transaction.
6e40: 20 43 61 6c 6c 69 6e 67 20 6c 73 6d 5f 72 6f 6c   Calling lsm_rol
6e50: 6c 62 61 63 6b 28 64 62 2c 20 3c 69 3e 4e 3c 2f  lback(db, <i>N</
6e60: 69 3e 29 0a 20 20 20 20 20 20 20 66 6f 72 20 61  i>).       for a
6e70: 6e 79 20 76 61 6c 75 65 20 6f 66 20 3c 69 3e 4e  ny value of <i>N
6e80: 3c 2f 69 3e 20 67 72 65 61 74 65 72 20 74 68 61  </i> greater tha
6e90: 6e 20 7a 65 72 6f 20 63 6c 6f 73 65 73 20 7a 65  n zero closes ze
6ea0: 72 6f 20 6f 72 20 6d 6f 72 65 20 6e 65 73 74 65  ro or more neste
6eb0: 64 0a 20 20 20 20 20 20 20 77 72 69 74 65 2d 74  d.       write-t
6ec0: 72 61 6e 73 61 63 74 69 6f 6e 73 20 73 6f 20 74  ransactions so t
6ed0: 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
6ee0: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6c   connection is l
6ef0: 65 66 74 20 77 69 74 68 20 61 74 20 6d 6f 73 74  eft with at most
6f00: 0a 20 20 20 20 20 20 20 3c 69 3e 4e 3c 2f 69 3e  .       <i>N</i>
6f10: 20 6f 70 65 6e 20 74 72 61 6e 73 61 63 74 69 6f   open transactio
6f20: 6e 73 2e 20 49 66 2c 20 66 6f 6c 6c 6f 77 69 6e  ns. If, followin
6f30: 67 20 74 68 69 73 2c 20 74 68 65 20 64 61 74 61  g this, the data
6f40: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
6f50: 20 20 20 20 20 20 20 68 61 73 20 65 78 61 63 74         has exact
6f60: 6c 79 20 3c 69 3e 4e 3c 2f 69 3e 20 6f 70 65 6e  ly <i>N</i> open
6f70: 20 6e 65 73 74 65 64 20 77 72 69 74 65 2d 74 72   nested write-tr
6f80: 61 6e 73 61 63 74 69 6f 6e 73 2c 20 74 68 65 20  ansactions, the 
6f90: 6f 75 74 65 72 6d 6f 73 74 20 69 73 0a 20 20 20  outermost is.   
6fa0: 20 20 20 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2c      rolled back,
6fb0: 20 62 75 74 20 6e 6f 74 20 63 6c 6f 73 65 64 2e   but not closed.
6fc0: 20 43 61 6c 6c 69 6e 67 20 6c 73 6d 5f 72 6f 6c   Calling lsm_rol
6fd0: 6c 62 61 63 6b 28 64 62 2c 20 31 29 20 72 6f 6c  lback(db, 1) rol
6fe0: 6c 73 20 62 61 63 6b 0a 20 20 20 20 20 20 20 28  ls back.       (
6ff0: 62 75 74 20 64 6f 65 73 20 6e 6f 74 20 63 6c 6f  but does not clo
7000: 73 65 29 20 74 68 65 20 74 6f 70 2d 6c 65 76 65  se) the top-leve
7010: 6c 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 0a 3c  l transaction..<
7020: 2f 75 6c 3e 0a 0a 3c 70 3e 45 78 61 6d 70 6c 65  /ul>..<p>Example
7030: 73 20 66 6f 6c 6c 6f 77 2e 20 57 69 74 68 20 65  s follow. With e
7040: 72 72 6f 72 20 63 68 65 63 6b 69 6e 67 20 6f 6d  rror checking om
7050: 69 74 74 65 64 20 66 6f 72 20 62 72 65 76 69 74  itted for brevit
7060: 79 27 73 20 73 61 6b 65 2e 0a 0a 3c 76 65 72 62  y's sake...<verb
7070: 61 74 69 6d 3e 0a 20 20 2f 2a 20 4f 70 65 6e 20  atim>.  /* Open 
7080: 61 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74  a write-transact
7090: 69 6f 6e 2e 20 57 72 69 74 65 20 73 6f 6d 65 20  ion. Write some 
70a0: 64 61 74 61 20 74 6f 20 74 68 65 20 64 61 74 61  data to the data
70b0: 62 61 73 65 2e 20 54 68 65 6e 0a 20 20 2a 2a 20  base. Then.  ** 
70c0: 63 6f 6d 6d 69 74 20 61 6e 64 20 63 6c 6f 73 65  commit and close
70d0: 20 74 68 65 20 77 72 69 74 65 20 74 72 61 6e 73   the write trans
70e0: 61 63 74 69 6f 6e 2e 20 46 6f 6c 6c 6f 77 69 6e  action. Followin
70f0: 67 20 74 68 69 73 2c 20 74 68 65 20 64 61 74 61  g this, the data
7100: 62 61 73 65 0a 20 20 2a 2a 20 63 6f 6e 74 61 69  base.  ** contai
7110: 6e 73 3a 0a 20 20 2a 2a 0a 20 20 2a 2a 20 20 20  ns:.  **.  **   
7120: 22 6a 22 20 2d 3e 20 22 74 65 6e 22 0a 20 20 2a  "j" -> "ten".  *
7130: 2a 20 20 20 22 6b 22 20 2d 3e 20 22 65 6c 65 76  *   "k" -> "elev
7140: 65 6e 22 0a 20 20 2a 2f 0a 20 20 6c 73 6d 5f 62  en".  */.  lsm_b
7150: 65 67 69 6e 28 64 62 2c 20 31 29 3b 0a 20 20 6c  egin(db, 1);.  l
7160: 73 6d 5f 69 6e 73 65 72 74 28 64 62 2c 20 22 6a  sm_insert(db, "j
7170: 22 2c 20 31 2c 20 22 74 65 6e 22 2c 20 20 20 20  ", 1, "ten",    
7180: 33 29 3b 0a 20 20 6c 73 6d 5f 69 6e 73 65 72 74  3);.  lsm_insert
7190: 28 64 62 2c 20 22 6b 22 2c 20 31 2c 20 22 65 6c  (db, "k", 1, "el
71a0: 65 76 65 6e 22 2c 20 36 29 3b 0a 20 20 6c 73 6d  even", 6);.  lsm
71b0: 5f 63 6f 6d 6d 69 74 28 64 62 2c 20 30 29 3b 0a  _commit(db, 0);.
71c0: 0a 20 20 2f 2a 20 4f 70 65 6e 20 61 20 77 72 69  .  /* Open a wri
71d0: 74 65 2d 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20  te-transaction, 
71e0: 70 65 72 66 6f 72 6d 20 61 6c 6c 20 6d 61 6e 6e  perform all mann
71f0: 65 72 20 6f 66 20 77 72 69 74 65 73 20 61 6e 64  er of writes and
7200: 20 6f 74 68 65 72 0a 20 20 2a 2a 20 6f 70 65 72   other.  ** oper
7210: 61 74 69 6f 6e 73 20 28 6e 6f 74 20 73 68 6f 77  ations (not show
7220: 6e 29 2e 20 54 68 65 6e 20 72 6f 6c 6c 20 74 68  n). Then roll th
7230: 65 20 74 6f 70 2d 6c 65 76 65 6c 20 74 72 61 6e  e top-level tran
7240: 73 61 63 74 69 6f 6e 20 62 61 63 6b 2e 0a 20 20  saction back..  
7250: 2a 2a 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66  ** Regardless of
7260: 20 74 68 65 20 77 72 69 74 65 20 6f 70 65 72 61   the write opera
7270: 74 69 6f 6e 73 20 70 65 72 66 6f 72 6d 65 64 2c  tions performed,
7280: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 72 65   the database re
7290: 6d 61 69 6e 73 0a 20 20 2a 2a 20 75 6e 63 68 61  mains.  ** uncha
72a0: 6e 67 65 64 3a 0a 20 20 2a 2a 0a 20 20 2a 2a 20  nged:.  **.  ** 
72b0: 20 20 22 6a 22 20 2d 3e 20 22 74 65 6e 22 0a 20    "j" -> "ten". 
72c0: 20 2a 2a 20 20 20 22 6b 22 20 2d 3e 20 22 65 6c   **   "k" -> "el
72d0: 65 76 65 6e 22 0a 20 20 2a 2f 0a 20 20 6c 73 6d  even".  */.  lsm
72e0: 5f 62 65 67 69 6e 28 64 62 2c 20 31 29 3b 0a 20  _begin(db, 1);. 
72f0: 20 2f 2a 20 44 6f 20 61 6c 6c 20 6d 61 6e 6e 65   /* Do all manne
7300: 72 20 6f 66 20 77 72 69 74 65 73 2c 20 73 75 62  r of writes, sub
7310: 2d 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 65 74  -transactions et
7320: 63 2e 20 2a 2f 0a 20 20 6c 73 6d 5f 72 6f 6c 6c  c. */.  lsm_roll
7330: 62 61 63 6b 28 64 62 2c 20 30 29 3b 0a 0a 20 20  back(db, 0);..  
7340: 2f 2a 20 4f 70 65 6e 20 61 20 77 72 69 74 65 2d  /* Open a write-
7350: 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 57 72 69  transaction. Wri
7360: 74 65 20 73 6f 6d 65 20 64 61 74 61 20 74 6f 20  te some data to 
7370: 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 54 68  the database. Th
7380: 65 6e 0a 20 20 2a 2a 20 72 6f 6c 6c 62 61 63 6b  en.  ** rollback
7390: 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 20 74   the top level t
73a0: 72 61 6e 73 61 63 74 69 6f 6e 20 62 75 74 20 64  ransaction but d
73b0: 6f 20 6e 6f 74 20 63 6c 6f 73 65 20 69 74 2e 20  o not close it. 
73c0: 57 72 69 74 65 20 0a 20 20 2a 2a 20 64 69 66 66  Write .  ** diff
73d0: 65 72 65 6e 74 20 64 61 74 61 20 74 6f 20 74 68  erent data to th
73e0: 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 63  e database and c
73f0: 6f 6d 6d 69 74 2e 20 46 6f 6c 6c 6f 77 69 6e 67  ommit. Following
7400: 20 74 68 69 73 20 62 6c 6f 63 6b 2c 0a 20 20 2a   this block,.  *
7410: 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  * the database i
7420: 73 3a 0a 20 20 2a 2a 0a 20 20 2a 2a 20 20 20 22  s:.  **.  **   "
7430: 6a 22 20 2d 3e 20 22 74 65 6e 22 0a 20 20 2a 2a  j" -> "ten".  **
7440: 20 20 20 22 6b 22 20 2d 3e 20 22 65 6c 65 76 65     "k" -> "eleve
7450: 6e 22 0a 20 20 2a 2a 20 20 20 22 6d 22 20 2d 3e  n".  **   "m" ->
7460: 20 22 74 68 69 72 74 65 65 6e 22 0a 20 20 2a 2f   "thirteen".  */
7470: 0a 20 20 6c 73 6d 5f 62 65 67 69 6e 28 64 62 2c  .  lsm_begin(db,
7480: 20 31 29 3b 0a 20 20 6c 73 6d 5f 69 6e 73 65 72   1);.  lsm_inser
7490: 74 28 64 62 2c 20 22 6c 22 2c 20 31 2c 20 22 74  t(db, "l", 1, "t
74a0: 77 65 6c 76 65 22 2c 20 20 20 20 33 29 3b 0a 20  welve",    3);. 
74b0: 20 6c 73 6d 5f 72 6f 6c 6c 62 61 63 6b 28 64 62   lsm_rollback(db
74c0: 2c 20 31 29 3b 0a 20 20 6c 73 6d 5f 69 6e 73 65  , 1);.  lsm_inse
74d0: 72 74 28 64 62 2c 20 22 6d 22 2c 20 31 2c 20 22  rt(db, "m", 1, "
74e0: 74 68 69 72 74 65 65 6e 22 2c 20 36 29 3b 0a 20  thirteen", 6);. 
74f0: 20 6c 73 6d 5f 63 6f 6d 6d 69 74 28 64 62 2c 20   lsm_commit(db, 
7500: 30 29 3b 0a 0a 20 20 2f 2a 20 4f 70 65 6e 20 61  0);..  /* Open a
7510: 20 77 72 69 74 65 2d 74 72 61 6e 73 61 63 74 69   write-transacti
7520: 6f 6e 20 61 6e 64 20 32 20 6e 65 73 74 65 64 20  on and 2 nested 
7530: 73 75 62 2d 74 72 61 6e 73 61 63 74 69 6f 6e 73  sub-transactions
7540: 2e 20 44 65 6c 65 74 65 20 61 0a 20 20 2a 2a 20  . Delete a.  ** 
7550: 64 61 74 61 62 61 73 65 20 6b 65 79 2e 20 54 68  database key. Th
7560: 65 6e 20 63 6f 6d 6d 69 74 20 61 6e 64 20 63 6c  en commit and cl
7570: 6f 73 65 20 74 68 65 20 6f 75 74 65 72 6d 6f 73  ose the outermos
7580: 74 20 73 75 62 2d 74 72 61 6e 73 61 63 74 69 6f  t sub-transactio
7590: 6e 2e 0a 20 20 2a 2a 20 4f 70 65 6e 20 61 6e 6f  n..  ** Open ano
75a0: 74 68 65 72 20 73 75 62 2d 74 72 61 6e 73 61 63  ther sub-transac
75b0: 74 69 6f 6e 20 28 73 6f 20 74 68 61 74 20 74 68  tion (so that th
75c0: 65 72 65 20 61 72 65 20 61 67 61 69 6e 20 32 20  ere are again 2 
75d0: 6e 65 73 74 65 64 0a 20 20 2a 2a 20 73 75 62 2d  nested.  ** sub-
75e0: 74 72 61 6e 73 61 63 74 69 6f 6e 73 29 2e 20 44  transactions). D
75f0: 65 6c 65 74 65 20 61 20 64 69 66 66 65 72 65 6e  elete a differen
7600: 74 20 64 61 74 61 62 61 73 65 20 6b 65 79 2e 20  t database key. 
7610: 54 68 65 6e 20 72 6f 6c 6c 62 61 63 6b 0a 20 20  Then rollback.  
7620: 2a 2a 20 61 6e 64 20 63 6c 6f 73 65 20 74 68 65  ** and close the
7630: 20 6f 75 74 65 72 6d 6f 73 74 20 73 75 62 2d 74   outermost sub-t
7640: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 46 69 6e 61  ransaction. Fina
7650: 6c 6c 79 2c 20 64 65 6c 65 74 65 20 79 65 74 20  lly, delete yet 
7660: 61 6e 6f 74 68 65 72 0a 20 20 2a 2a 20 64 62 20  another.  ** db 
7670: 6b 65 79 20 61 6e 64 20 63 6f 6d 6d 69 74 20 74  key and commit t
7680: 68 65 20 6f 75 74 65 72 6d 6f 73 74 20 74 72 61  he outermost tra
7690: 6e 73 61 63 74 69 6f 6e 2e 20 4c 65 61 76 69 6e  nsaction. Leavin
76a0: 67 20 6a 75 73 74 3a 0a 20 20 2a 2a 0a 20 20 2a  g just:.  **.  *
76b0: 2a 20 20 20 22 6b 22 20 2d 3e 20 22 65 6c 65 76  *   "k" -> "elev
76c0: 65 6e 22 0a 20 20 2a 2f 0a 20 20 6c 73 6d 5f 62  en".  */.  lsm_b
76d0: 65 67 69 6e 28 64 62 2c 20 33 29 3b 0a 20 20 6c  egin(db, 3);.  l
76e0: 73 6d 5f 64 65 6c 65 74 65 28 64 62 2c 20 22 6a  sm_delete(db, "j
76f0: 22 2c 20 31 29 3b 0a 20 20 6c 73 6d 5f 63 6f 6d  ", 1);.  lsm_com
7700: 6d 69 74 28 64 62 2c 20 32 29 3b 0a 20 20 6c 73  mit(db, 2);.  ls
7710: 6d 5f 62 65 67 69 6e 28 64 62 2c 20 33 29 3b 0a  m_begin(db, 3);.
7720: 20 20 6c 73 6d 5f 64 65 6c 65 74 65 28 64 62 2c    lsm_delete(db,
7730: 20 22 6b 22 2c 20 31 29 3b 0a 20 20 6c 73 6d 5f   "k", 1);.  lsm_
7740: 72 6f 6c 6c 62 61 63 6b 28 64 62 2c 20 32 29 3b  rollback(db, 2);
7750: 0a 20 20 6c 73 6d 5f 64 65 6c 65 74 65 28 64 62  .  lsm_delete(db
7760: 2c 20 22 6d 22 2c 20 31 29 3b 0a 20 20 6c 73 6d  , "m", 1);.  lsm
7770: 5f 63 6f 6d 6d 69 74 28 64 62 2c 20 30 29 3b 0a  _commit(db, 0);.
7780: 20 20 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a    .</verbatim>..
7790: 3c 68 31 20 69 64 3d 64 61 74 61 5f 64 75 72 61  <h1 id=data_dura
77a0: 62 69 6c 69 74 79 3e 34 2e 20 44 61 74 61 20 44  bility>4. Data D
77b0: 75 72 61 62 69 6c 69 74 79 20 3c 2f 68 31 3e 0a  urability </h1>.
77c0: 0a 3c 70 3e 54 68 65 20 76 61 6c 75 65 20 6f 66  .<p>The value of
77d0: 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
77e0: 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 4c 53 4d  on parameter LSM
77f0: 5f 43 4f 4e 46 49 47 5f 53 41 46 45 54 59 20 64  _CONFIG_SAFETY d
7800: 65 74 65 72 6d 69 6e 65 73 0a 68 6f 77 20 6f 66  etermines.how of
7810: 74 65 6e 20 64 61 74 61 20 69 73 20 73 79 6e 63  ten data is sync
7820: 65 64 20 74 6f 20 64 69 73 6b 20 62 79 20 74 68  ed to disk by th
7830: 65 20 4c 53 4d 20 6c 69 62 72 61 72 79 2e 20 54  e LSM library. T
7840: 68 69 73 20 69 73 20 61 6e 20 69 6d 70 6f 72 74  his is an import
7850: 61 6e 74 0a 74 72 61 64 65 6f 66 66 20 2d 20 73  ant.tradeoff - s
7860: 79 6e 63 69 6e 67 20 6c 65 73 73 20 6f 66 74 65  yncing less ofte
7870: 6e 20 63 61 6e 20 6c 65 61 64 20 74 6f 20 6f 72  n can lead to or
7880: 64 65 72 73 20 6f 66 20 6d 61 67 6e 69 74 75 64  ders of magnitud
7890: 65 20 62 65 74 74 65 72 0a 70 65 72 66 6f 72 6d  e better.perform
78a0: 61 6e 63 65 2c 20 62 75 74 20 61 6c 73 6f 20 65  ance, but also e
78b0: 78 70 6f 73 65 73 20 74 68 65 20 61 70 70 6c 69  xposes the appli
78c0: 63 61 74 69 6f 6e 20 74 6f 20 74 68 65 20 72 69  cation to the ri
78d0: 73 6b 20 6f 66 20 70 61 72 74 69 61 6c 20 6f 72  sk of partial or
78e0: 20 74 6f 74 61 6c 0a 64 61 74 61 20 6c 6f 73 73   total.data loss
78f0: 20 69 6e 20 74 68 65 20 65 76 65 6e 74 20 6f 66   in the event of
7900: 20 61 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65   a power failure
7910: 3b 0a 0a 3c 74 61 62 6c 65 20 76 61 6c 69 67 6e  ;..<table valign
7920: 3d 74 6f 70 3e 0a 3c 74 72 3e 20 3c 74 64 20 76  =top>.<tr> <td v
7930: 61 6c 69 67 6e 3d 74 6f 70 3e 4c 53 4d 5f 53 41  align=top>LSM_SA
7940: 46 45 54 59 5f 4f 46 46 20 0a 20 20 20 20 20 3c  FETY_OFF .     <
7950: 74 64 20 76 61 6c 69 67 6e 3d 74 6f 70 20 73 74  td valign=top st
7960: 79 6c 65 3d 22 70 61 64 64 69 6e 67 2d 6c 65 66  yle="padding-lef
7970: 74 3a 31 65 78 3b 70 61 64 64 69 6e 67 2d 72 69  t:1ex;padding-ri
7980: 67 68 74 3a 31 65 78 22 3e 28 30 29 0a 20 20 20  ght:1ex">(0).   
7990: 20 20 3c 74 64 3e 20 44 6f 20 6e 6f 74 20 73 79    <td> Do not sy
79a0: 6e 63 20 74 6f 20 64 69 73 6b 20 61 74 20 61 6c  nc to disk at al
79b0: 6c 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 66  l. This is the f
79c0: 61 73 74 65 73 74 20 6d 6f 64 65 2e 0a 20 20 20  astest mode..   
79d0: 20 20 20 20 20 20 20 3c 70 3e 49 66 20 61 20 70         <p>If a p
79e0: 6f 77 65 72 20 66 61 69 6c 75 72 65 20 6f 63 63  ower failure occ
79f0: 75 72 73 20 77 68 69 6c 65 20 77 72 69 74 69 6e  urs while writin
7a00: 67 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  g to the databas
7a10: 65 2c 20 0a 20 20 20 20 20 20 20 20 20 20 66 6f  e, .          fo
7a20: 6c 6c 6f 77 69 6e 67 20 72 65 63 6f 76 65 72 79  llowing recovery
7a30: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6d 61   the database ma
7a40: 79 20 62 65 20 63 6f 72 72 75 70 74 2e 20 41 6c  y be corrupt. Al
7a50: 6c 20 6f 72 20 73 6f 6d 65 20 64 61 74 61 20 6d  l or some data m
7a60: 61 79 0a 20 20 20 20 20 20 20 20 20 20 62 65 20  ay.          be 
7a70: 72 65 63 6f 76 65 72 61 62 6c 65 2e 0a 0a 3c 74  recoverable...<t
7a80: 72 3e 20 3c 74 64 20 76 61 6c 69 67 6e 3d 74 6f  r> <td valign=to
7a90: 70 3e 4c 53 4d 5f 53 41 46 45 54 59 5f 4e 4f 52  p>LSM_SAFETY_NOR
7aa0: 4d 41 4c 20 0a 20 20 20 20 20 3c 74 64 20 76 61  MAL .     <td va
7ab0: 6c 69 67 6e 3d 74 6f 70 20 73 74 79 6c 65 3d 22  lign=top style="
7ac0: 70 61 64 64 69 6e 67 2d 6c 65 66 74 3a 31 65 78  padding-left:1ex
7ad0: 3b 70 61 64 64 69 6e 67 2d 72 69 67 68 74 3a 31  ;padding-right:1
7ae0: 65 78 22 3e 28 31 29 0a 20 20 20 20 20 3c 74 64  ex">(1).     <td
7af0: 3e 20 53 79 6e 63 20 6f 6e 6c 79 20 61 73 20 6d  > Sync only as m
7b00: 75 63 68 20 61 73 20 69 73 20 6e 65 63 65 73 73  uch as is necess
7b10: 61 72 79 20 74 6f 20 70 72 65 76 65 6e 74 20 64  ary to prevent d
7b20: 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
7b30: 6f 6e 2e 0a 20 20 20 20 20 20 20 20 20 54 68 69  on..         Thi
7b40: 73 20 69 73 20 74 68 65 20 64 65 66 61 75 6c 74  s is the default
7b50: 20 73 65 74 74 69 6e 67 2e 20 41 6c 74 68 6f 75   setting. Althou
7b60: 67 68 20 73 6c 6f 77 65 72 20 74 68 61 6e 20 4c  gh slower than L
7b70: 53 4d 5f 53 41 46 45 54 59 5f 4f 46 46 2c 20 0a  SM_SAFETY_OFF, .
7b80: 20 20 20 20 20 20 20 20 20 74 68 69 73 20 6d 6f           this mo
7b90: 64 65 20 69 73 20 73 74 69 6c 6c 20 6d 75 63 68  de is still much
7ba0: 20 66 61 73 74 65 72 20 74 68 61 6e 20 4c 53 4d   faster than LSM
7bb0: 5f 53 41 46 45 54 59 5f 46 55 4c 4c 2e 0a 20 20  _SAFETY_FULL..  
7bc0: 20 20 20 3c 70 3e 20 49 66 20 61 20 70 6f 77 65     <p> If a powe
7bd0: 72 20 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73  r failure occurs
7be0: 20 77 68 69 6c 65 20 77 72 69 74 69 6e 67 20 74   while writing t
7bf0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 2c 20  o the database, 
7c00: 66 6f 6c 6c 6f 77 69 6e 67 0a 20 20 20 20 20 20  following.      
7c10: 20 20 20 20 72 65 63 6f 76 65 72 79 20 73 6f 6d      recovery som
7c20: 65 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 6d 69  e recently commi
7c30: 74 74 65 64 20 74 72 61 6e 73 61 63 74 69 6f 6e  tted transaction
7c40: 73 20 6d 61 79 20 68 61 76 65 20 62 65 65 6e 20  s may have been 
7c50: 6c 6f 73 74 2e 0a 20 20 20 20 20 20 20 20 20 20  lost..          
7c60: 42 75 74 20 74 68 65 20 64 61 74 61 62 61 73 65  But the database
7c70: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 6e 6f 74   file should not
7c80: 20 62 65 20 63 6f 72 72 75 70 74 20 61 6e 64 20   be corrupt and 
7c90: 6f 6c 64 65 72 20 64 61 74 61 20 69 6e 74 61 63  older data intac
7ca0: 74 2e 0a 0a 3c 74 72 3e 20 3c 74 64 20 76 61 6c  t...<tr> <td val
7cb0: 69 67 6e 3d 74 6f 70 3e 4c 53 4d 5f 53 41 46 45  ign=top>LSM_SAFE
7cc0: 54 59 5f 46 55 4c 4c 20 0a 20 20 20 20 20 3c 74  TY_FULL .     <t
7cd0: 64 20 76 61 6c 69 67 6e 3d 74 6f 70 20 73 74 79  d valign=top sty
7ce0: 6c 65 3d 22 70 61 64 64 69 6e 67 2d 6c 65 66 74  le="padding-left
7cf0: 3a 31 65 78 3b 70 61 64 64 69 6e 67 2d 72 69 67  :1ex;padding-rig
7d00: 68 74 3a 31 65 78 22 3e 28 32 29 0a 20 20 20 20  ht:1ex">(2).    
7d10: 20 3c 74 64 3e 20 53 79 6e 63 20 65 76 65 72 79   <td> Sync every
7d20: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
7d30: 64 69 73 6b 20 61 73 20 70 61 72 74 20 6f 66 20  disk as part of 
7d40: 63 6f 6d 6d 69 74 74 69 6e 67 20 69 74 2e 20 54  committing it. T
7d50: 68 69 73 20 69 73 0a 20 20 20 20 20 20 20 20 20  his is.         
7d60: 20 74 68 65 20 73 6c 6f 77 65 73 74 20 6d 6f 64   the slowest mod
7d70: 65 2e 0a 20 20 20 20 20 20 20 3c 70 3e 49 66 20  e..       <p>If 
7d80: 61 20 70 6f 77 65 72 20 66 61 69 6c 75 72 65 20  a power failure 
7d90: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 77 72 69  occurs while wri
7da0: 74 69 6e 67 20 74 6f 20 74 68 65 20 64 61 74 61  ting to the data
7db0: 62 61 73 65 2c 20 61 6c 6c 0a 20 20 20 20 20 20  base, all.      
7dc0: 20 20 20 20 73 75 63 63 65 73 73 66 75 6c 6c 79      successfully
7dd0: 20 63 6f 6d 6d 69 74 74 65 64 20 74 72 61 6e 73   committed trans
7de0: 61 63 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 62  actions should b
7df0: 65 20 70 72 65 73 65 6e 74 2e 0a 20 20 20 20 20  e present..     
7e00: 20 20 20 20 20 54 68 65 20 64 61 74 61 62 61 73       The databas
7e10: 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 6e 6f  e file should no
7e20: 74 20 62 65 20 63 6f 72 72 75 70 74 2e 0a 3c 2f  t be corrupt..</
7e30: 74 61 62 6c 65 3e 0a 0a 3c 70 3e 54 68 65 20 66  table>..<p>The f
7e40: 6f 6c 6c 6f 77 69 6e 67 20 65 78 61 6d 70 6c 65  ollowing example
7e50: 20 63 6f 64 65 20 73 65 74 73 20 74 68 65 20 76   code sets the v
7e60: 61 6c 75 65 20 6f 66 20 74 68 65 20 4c 53 4d 5f  alue of the LSM_
7e70: 43 4f 4e 46 49 47 5f 53 41 46 45 54 59 20 0a 70  CONFIG_SAFETY .p
7e80: 61 72 61 6d 65 74 65 72 20 66 6f 72 20 63 6f 6e  arameter for con
7e90: 6e 65 63 74 69 6f 6e 20 64 62 20 74 6f 20 4c 53  nection db to LS
7ea0: 4d 5f 53 41 46 45 54 59 5f 46 55 4c 4c 3a 0a 0a  M_SAFETY_FULL:..
7eb0: 3c 76 65 72 62 61 74 69 6d 3e 0a 20 20 69 6e 74  <verbatim>.  int
7ec0: 20 69 53 61 66 65 74 79 20 3d 20 4c 53 4d 5f 53   iSafety = LSM_S
7ed0: 41 46 45 54 59 5f 46 55 4c 4c 3b 0a 20 20 6c 73  AFETY_FULL;.  ls
7ee0: 6d 5f 63 6f 6e 66 69 67 28 64 62 2c 20 4c 53 4d  m_config(db, LSM
7ef0: 5f 43 4f 4e 46 49 47 5f 53 41 46 45 54 59 2c 20  _CONFIG_SAFETY, 
7f00: 26 69 53 61 66 65 74 79 29 3b 0a 3c 2f 76 65 72  &iSafety);.</ver
7f10: 62 61 74 69 6d 3e 0a 0a 3c 70 3e 54 68 65 20 63  batim>..<p>The c
7f20: 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
7f30: 74 68 65 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 53  the LSM_CONFIG_S
7f40: 41 46 45 54 59 20 70 61 72 61 6d 65 74 65 72 20  AFETY parameter 
7f50: 63 61 6e 20 61 6c 73 6f 20 62 65 20 71 75 65 72  can also be quer
7f60: 69 65 64 0a 62 79 20 73 65 74 74 69 6e 67 20 74  ied.by setting t
7f70: 68 65 20 69 6e 69 74 69 61 6c 20 76 61 6c 75 65  he initial value
7f80: 20 6f 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74   of the argument
7f90: 20 74 6f 20 2d 31 20 28 6f 72 20 61 6e 79 20 6f   to -1 (or any o
7fa0: 74 68 65 72 20 6e 65 67 61 74 69 76 65 0a 76 61  ther negative.va
7fb0: 6c 75 65 29 2e 20 46 6f 72 20 65 78 61 6d 70 6c  lue). For exampl
7fc0: 65 3a 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20  e:..<verbatim>. 
7fd0: 20 69 6e 74 20 69 53 61 66 65 74 79 20 3d 20 2d   int iSafety = -
7fe0: 31 3b 0a 20 20 6c 73 6d 5f 63 6f 6e 66 69 67 28  1;.  lsm_config(
7ff0: 64 62 2c 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 53  db, LSM_CONFIG_S
8000: 41 46 45 54 59 2c 20 26 69 53 61 66 65 74 79 29  AFETY, &iSafety)
8010: 3b 0a 20 20 2f 2a 20 41 74 20 74 68 69 73 20 70  ;.  /* At this p
8020: 6f 69 6e 74 2c 20 76 61 72 69 61 62 6c 65 20 69  oint, variable i
8030: 53 61 66 65 74 79 20 69 73 20 73 65 74 20 74 6f  Safety is set to
8040: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 63   the currently c
8050: 6f 6e 66 69 67 75 72 65 64 20 76 61 6c 75 65 0a  onfigured value.
8060: 20 20 2a 2a 20 6f 66 20 74 68 65 20 4c 53 4d 5f    ** of the LSM_
8070: 43 4f 4e 46 49 47 5f 53 41 46 45 54 59 20 70 61  CONFIG_SAFETY pa
8080: 72 61 6d 65 74 65 72 20 28 65 69 74 68 65 72 20  rameter (either 
8090: 30 2c 20 31 20 6f 72 20 32 29 2e 20 20 2a 2f 0a  0, 1 or 2).  */.
80a0: 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70 3e  </verbatim>..<p>
80b0: 54 68 65 20 6c 73 6d 5f 63 6f 6e 66 69 67 28 29  The lsm_config()
80c0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 61 6c   function may al
80d0: 73 6f 20 62 65 20 75 73 65 64 20 74 6f 20 63 6f  so be used to co
80e0: 6e 66 69 67 75 72 65 20 6f 74 68 65 72 20 64 61  nfigure other da
80f0: 74 61 62 61 73 65 0a 63 6f 6e 6e 65 63 74 69 6f  tabase.connectio
8100: 6e 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 0a  n parameters.  .
8110: 0a 0a 3c 68 31 20 69 64 3d 63 6f 6d 70 72 65 73  ..<h1 id=compres
8120: 73 65 64 5f 61 6e 64 5f 65 6e 63 72 79 70 74 65  sed_and_encrypte
8130: 64 5f 64 61 74 61 62 61 73 65 73 3e 35 2e 20 43  d_databases>5. C
8140: 6f 6d 70 72 65 73 73 65 64 20 61 6e 64 20 45 6e  ompressed and En
8150: 63 72 79 70 74 65 64 20 44 61 74 61 62 61 73 65  crypted Database
8160: 73 20 3c 2f 68 31 3e 0a 0a 3c 70 3e 4c 53 4d 20  s </h1>..<p>LSM 
8170: 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69 64 65  does not provide
8180: 20 62 75 69 6c 74 2d 69 6e 20 6d 65 74 68 6f 64   built-in method
8190: 73 20 66 6f 72 20 63 72 65 61 74 69 6e 67 20 65  s for creating e
81a0: 6e 63 72 79 70 74 65 64 20 6f 72 20 63 6f 6d 70  ncrypted or comp
81b0: 72 65 73 73 65 64 0a 64 61 74 61 62 61 73 65 73  ressed.databases
81c0: 2e 20 49 6e 73 74 65 61 64 2c 20 69 74 20 61 6c  . Instead, it al
81d0: 6c 6f 77 73 20 74 68 65 20 75 73 65 72 20 74 6f  lows the user to
81e0: 20 70 72 6f 76 69 64 65 20 68 6f 6f 6b 73 20 74   provide hooks t
81f0: 6f 20 63 61 6c 6c 20 65 78 74 65 72 6e 61 6c 0a  o call external.
8200: 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 63 6f 6d  functions to com
8210: 70 72 65 73 73 20 61 6e 64 2f 6f 72 20 65 6e 63  press and/or enc
8220: 72 79 70 74 20 64 61 74 61 20 62 65 66 6f 72 65  rypt data before
8230: 20 69 74 20 69 73 20 77 72 69 74 74 65 6e 20 74   it is written t
8240: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 66  o the database.f
8250: 69 6c 65 2c 20 61 6e 64 20 74 6f 20 64 65 63 72  ile, and to decr
8260: 79 70 74 20 61 6e 64 2f 6f 72 20 75 6e 63 6f 6d  ypt and/or uncom
8270: 70 72 65 73 73 20 64 61 74 61 20 61 73 20 69 74  press data as it
8280: 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 74 68   is read from th
8290: 65 20 64 61 74 61 62 61 73 65 0a 66 69 6c 65 2e  e database.file.
82a0: 0a 0a 3c 70 3e 41 20 64 61 74 61 62 61 73 65 20  ..<p>A database 
82b0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6f  connection is co
82c0: 6e 66 69 67 75 72 65 64 20 74 6f 20 63 61 6c 6c  nfigured to call
82d0: 20 63 6f 6d 70 72 65 73 73 69 6f 6e 20 66 75 6e   compression fun
82e0: 63 74 69 6f 6e 73 20 75 73 69 6e 67 20 61 0a 63  ctions using a.c
82f0: 61 6c 6c 20 74 6f 20 6c 73 6d 5f 63 6f 6e 66 69  all to lsm_confi
8300: 67 28 29 20 77 69 74 68 20 74 68 65 20 73 65 63  g() with the sec
8310: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 73 65 74  ond argument set
8320: 20 74 6f 0a 4c 53 4d 5f 43 4f 4e 46 49 47 5f 53   to.LSM_CONFIG_S
8330: 45 54 5f 43 4f 4d 50 52 45 53 53 49 4f 4e 2e 20  ET_COMPRESSION. 
8340: 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
8350: 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20  nt should point 
8360: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 0a 6f  to an instance.o
8370: 66 20 74 79 70 65 20 6c 73 6d 5f 63 6f 6d 70 72  f type lsm_compr
8380: 65 73 73 2c 20 77 68 69 63 68 20 69 73 20 64 65  ess, which is de
8390: 66 69 6e 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73  fined as follows
83a0: 3a 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20 20  :..<verbatim>.  
83b0: 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 6c  typedef struct l
83c0: 73 6d 5f 63 6f 6d 70 72 65 73 73 20 6c 73 6d 5f  sm_compress lsm_
83d0: 63 6f 6d 70 72 65 73 73 3b 0a 20 20 73 74 72 75  compress;.  stru
83e0: 63 74 20 6c 73 6d 5f 63 6f 6d 70 72 65 73 73 20  ct lsm_compress 
83f0: 7b 0a 20 20 20 20 75 33 32 20 69 49 64 3b 0a 20  {.    u32 iId;. 
8400: 20 20 20 76 6f 69 64 20 2a 70 43 74 78 3b 0a 20     void *pCtx;. 
8410: 20 20 20 69 6e 74 20 28 2a 78 42 6f 75 6e 64 29     int (*xBound)
8420: 28 76 6f 69 64 20 2a 70 43 74 78 2c 20 69 6e 74  (void *pCtx, int
8430: 20 6e 49 6e 29 3b 0a 20 20 20 20 69 6e 74 20 28   nIn);.    int (
8440: 2a 78 43 6f 6d 70 72 65 73 73 29 28 76 6f 69 64  *xCompress)(void
8450: 20 2a 70 43 74 78 2c 20 76 6f 69 64 20 2a 70 4f   *pCtx, void *pO
8460: 75 74 2c 20 69 6e 74 20 2a 70 6e 4f 75 74 2c 20  ut, int *pnOut, 
8470: 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 49 6e 2c  const void *pIn,
8480: 20 69 6e 74 20 6e 49 6e 29 3b 0a 20 20 20 20 69   int nIn);.    i
8490: 6e 74 20 28 2a 78 55 6e 63 6f 6d 70 72 65 73 73  nt (*xUncompress
84a0: 29 28 76 6f 69 64 20 2a 70 43 74 78 2c 20 76 6f  )(void *pCtx, vo
84b0: 69 64 20 2a 70 4f 75 74 2c 20 69 6e 74 20 2a 70  id *pOut, int *p
84c0: 6e 4f 75 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64  nOut, const void
84d0: 20 2a 70 49 6e 2c 20 69 6e 74 20 6e 49 6e 29 3b   *pIn, int nIn);
84e0: 0a 20 20 20 20 76 6f 69 64 20 28 2a 78 46 72 65  .    void (*xFre
84f0: 65 29 28 76 6f 69 64 20 2a 70 43 74 78 29 3b 0a  e)(void *pCtx);.
8500: 20 20 7d 3b 0a 3c 2f 76 65 72 62 61 74 69 6d 3e    };.</verbatim>
8510: 0a 0a 3c 70 3e 3c 69 3e 20 45 78 70 6c 61 69 6e  ..<p><i> Explain
8520: 20 68 6f 77 20 74 68 65 20 68 6f 6f 6b 73 20 77   how the hooks w
8530: 6f 72 6b 20 68 65 72 65 20 28 73 61 6d 65 20 61  ork here (same a
8540: 73 20 7a 69 70 76 66 73 29 20 3c 2f 69 3e 0a 0a  s zipvfs) </i>..
8550: 3c 70 3e 3c 69 3e 20 45 78 61 6d 70 6c 65 20 63  <p><i> Example c
8560: 6f 64 65 3f 20 55 73 69 6e 67 20 7a 6c 69 62 3f  ode? Using zlib?
8570: 20 4f 72 20 73 6f 6d 65 74 68 69 6e 67 20 73 69   Or something si
8580: 6d 70 6c 65 20 6c 69 6b 65 20 61 6e 20 52 4c 45  mple like an RLE
8590: 0a 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 3f  .implementation?
85a0: 3c 2f 69 3e 0a 0a 3c 70 3e 54 68 65 20 64 61 74  </i>..<p>The dat
85b0: 61 62 61 73 65 20 66 69 6c 65 20 68 65 61 64 65  abase file heade
85c0: 72 20 6f 66 20 61 6e 79 20 4c 53 4d 20 64 61 74  r of any LSM dat
85d0: 61 62 61 73 65 20 63 6f 6e 74 61 69 6e 73 20 61  abase contains a
85e0: 20 33 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64   32-bit unsigned
85f0: 0a 22 63 6f 6d 70 72 65 73 73 69 6f 6e 20 69 64  ."compression id
8600: 22 20 66 69 65 6c 64 2e 20 49 66 20 74 68 65 20  " field. If the 
8610: 64 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 20  database is not 
8620: 61 20 63 6f 6d 70 72 65 73 73 65 64 20 64 61 74  a compressed dat
8630: 61 62 61 73 65 2c 20 74 68 69 73 0a 66 69 65 6c  abase, this.fiel
8640: 64 20 69 73 20 73 65 74 20 74 6f 20 31 2e 20 4f  d is set to 1. O
8650: 74 68 65 72 77 69 73 65 2c 20 69 74 20 69 73 20  therwise, it is 
8660: 73 65 74 20 74 6f 20 61 6e 20 61 70 70 6c 69 63  set to an applic
8670: 61 74 69 6f 6e 20 73 75 70 70 6c 69 65 64 20 76  ation supplied v
8680: 61 6c 75 65 0a 69 64 65 6e 74 69 66 79 69 6e 67  alue.identifying
8690: 20 74 68 65 20 63 6f 6d 70 72 65 73 73 69 6f 6e   the compression
86a0: 20 61 6e 64 2f 6f 72 20 65 6e 63 72 79 70 74 69   and/or encrypti
86b0: 6f 6e 20 73 63 68 65 6d 65 20 69 6e 20 75 73 65  on scheme in use
86c0: 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 0a 63 6f  . Application.co
86d0: 6d 70 72 65 73 73 69 6f 6e 20 73 63 68 65 6d 65  mpression scheme
86e0: 20 69 64 73 20 6d 75 73 74 20 62 65 20 67 72 65   ids must be gre
86f0: 61 74 65 72 20 74 68 61 6e 20 6f 72 20 65 71 75  ater than or equ
8700: 61 6c 20 74 6f 20 31 30 30 30 30 2e 20 56 61 6c  al to 10000. Val
8710: 75 65 73 20 73 6d 61 6c 6c 65 72 0a 74 68 61 6e  ues smaller.than
8720: 20 31 30 30 30 30 20 61 72 65 20 72 65 73 65 72   10000 are reser
8730: 76 65 64 20 66 6f 72 20 69 6e 74 65 72 6e 61 6c  ved for internal
8740: 20 75 73 65 2e 0a 0a 3c 70 3e 54 68 65 20 6c 73   use...<p>The ls
8750: 6d 5f 63 6f 6d 70 72 65 73 73 69 6f 6e 5f 69 64  m_compression_id
8760: 28 29 20 41 50 49 20 6d 61 79 20 62 65 20 75 73  () API may be us
8770: 65 64 20 74 6f 20 72 65 61 64 20 74 68 65 20 63  ed to read the c
8780: 6f 6d 70 72 65 73 73 69 6f 6e 20 69 64 20 66 72  ompression id fr
8790: 6f 6d 0a 61 20 64 61 74 61 62 61 73 65 20 63 6f  om.a database co
87a0: 6e 6e 65 63 74 69 6f 6e 2e 20 42 65 63 61 75 73  nnection. Becaus
87b0: 65 20 74 68 65 20 63 6f 6d 70 72 65 73 73 69 6f  e the compressio
87c0: 6e 20 69 64 20 69 73 20 73 74 6f 72 65 64 20 69  n id is stored i
87d0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 68  n the database.h
87e0: 65 61 64 65 72 2c 20 69 74 20 6d 61 79 20 62 65  eader, it may be
87f0: 20 72 65 61 64 20 62 65 66 6f 72 65 20 61 6e 79   read before any
8800: 20 72 65 71 75 69 72 65 64 20 63 6f 6d 70 72 65   required compre
8810: 73 73 69 6f 6e 20 6f 72 20 65 6e 63 72 79 70 74  ssion or encrypt
8820: 69 6f 6e 20 68 6f 6f 6b 73 0a 61 72 65 20 63 6f  ion hooks.are co
8830: 6e 66 69 67 75 72 65 64 2e 0a 0a 3c 76 65 72 62  nfigured...<verb
8840: 61 74 69 6d 3e 0a 20 20 23 64 65 66 69 6e 65 20  atim>.  #define 
8850: 4c 53 4d 5f 43 4f 4d 50 52 45 53 53 49 4f 4e 5f  LSM_COMPRESSION_
8860: 45 4d 50 54 59 20 20 20 20 30 0a 20 20 23 64 65  EMPTY    0.  #de
8870: 66 69 6e 65 20 4c 53 4d 5f 43 4f 4d 50 52 45 53  fine LSM_COMPRES
8880: 53 49 4f 4e 5f 4e 4f 4e 45 20 20 20 20 20 31 0a  SION_NONE     1.
8890: 20 20 69 6e 74 20 6c 73 6d 5f 63 6f 6d 70 72 65    int lsm_compre
88a0: 73 73 69 6f 6e 5f 69 64 28 6c 73 6d 5f 64 62 20  ssion_id(lsm_db 
88b0: 2a 64 62 2c 20 75 33 32 20 2a 70 69 49 64 29 3b  *db, u32 *piId);
88c0: 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70  .</verbatim>..<p
88d0: 3e 57 68 65 6e 20 61 20 64 61 74 61 62 61 73 65  >When a database
88e0: 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 74   is opened for t
88f0: 68 65 20 66 69 72 73 74 20 74 69 6d 65 2c 20 62  he first time, b
8900: 65 66 6f 72 65 20 69 74 20 69 73 20 66 69 72 73  efore it is firs
8910: 74 20 77 72 69 74 74 65 6e 2c 0a 74 68 65 20 63  t written,.the c
8920: 6f 6d 70 72 65 73 73 69 6f 6e 20 69 64 20 66 69  ompression id fi
8930: 65 6c 64 20 69 73 20 73 65 74 20 74 6f 20 4c 53  eld is set to LS
8940: 4d 5f 43 4f 4d 50 52 45 53 53 49 4f 4e 5f 45 4d  M_COMPRESSION_EM
8950: 50 54 59 20 28 30 29 2e 20 54 68 65 20 66 69 72  PTY (0). The fir
8960: 73 74 20 74 69 6d 65 0a 61 20 74 72 61 6e 73 61  st time.a transa
8970: 63 74 69 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74  ction is committ
8980: 65 64 2c 20 74 68 65 20 64 61 74 61 62 61 73 65  ed, the database
8990: 20 63 6f 6d 70 72 65 73 73 69 6f 6e 20 69 64 20   compression id 
89a0: 69 73 20 73 65 74 20 74 6f 20 61 20 63 6f 70 79  is set to a copy
89b0: 20 6f 66 20 0a 74 68 65 20 6c 73 6d 5f 63 6f 6d   of .the lsm_com
89c0: 70 72 65 73 73 2e 69 49 64 20 66 69 65 6c 64 20  press.iId field 
89d0: 6f 66 20 74 68 65 20 63 6f 6d 70 72 65 73 73 69  of the compressi
89e0: 6f 6e 20 68 6f 6f 6b 73 20 66 6f 72 20 74 68 65  on hooks for the
89f0: 20 64 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   database handle
8a00: 0a 63 6f 6d 6d 69 74 74 69 6e 67 20 74 68 65 20  .committing the 
8a10: 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 6f 72 20  transaction, or 
8a20: 74 6f 20 4c 53 4d 5f 43 4f 4d 50 52 45 53 53 49  to LSM_COMPRESSI
8a30: 4f 4e 5f 4e 4f 4e 45 20 28 31 29 20 69 66 20 6e  ON_NONE (1) if n
8a40: 6f 20 63 6f 6d 70 72 65 73 73 69 6f 6e 0a 68 6f  o compression.ho
8a50: 6f 6b 73 20 61 72 65 20 63 6f 6e 66 69 67 75 72  oks are configur
8a60: 65 64 2e 0a 0a 3c 70 3e 4f 6e 63 65 20 74 68 65  ed...<p>Once the
8a70: 20 63 6f 6d 70 72 65 73 73 69 6f 6e 20 69 64 20   compression id 
8a80: 69 73 20 73 65 74 20 74 6f 20 73 6f 6d 65 74 68  is set to someth
8a90: 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20 0a  ing other than .
8aa0: 4c 53 4d 5f 43 4f 4d 50 52 45 53 53 49 4f 4e 5f  LSM_COMPRESSION_
8ab0: 45 4d 50 54 59 2c 20 77 68 65 6e 20 61 20 64 61  EMPTY, when a da
8ac0: 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 6f 70  tabase handle op
8ad0: 65 6e 73 20 61 20 72 65 61 64 20 6f 72 20 77 72  ens a read or wr
8ae0: 69 74 65 20 0a 74 72 61 6e 73 61 63 74 69 6f 6e  ite .transaction
8af0: 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
8b00: 2c 20 74 68 65 20 63 6f 6d 70 72 65 73 73 69 6f  , the compressio
8b10: 6e 20 69 64 20 69 73 20 63 6f 6d 70 61 72 65 64  n id is compared
8b20: 20 61 67 61 69 6e 73 74 20 74 68 65 20 0a 6c 73   against the .ls
8b30: 6d 5f 63 6f 6d 70 72 65 73 73 2e 69 49 64 20 66  m_compress.iId f
8b40: 69 65 6c 64 20 6f 66 20 74 68 65 20 63 6f 6e 66  ield of the conf
8b50: 69 67 75 72 65 64 20 63 6f 6d 70 72 65 73 73 69  igured compressi
8b60: 6f 6e 20 68 6f 6f 6b 73 2c 20 6f 72 20 61 67 61  on hooks, or aga
8b70: 69 6e 73 74 20 4c 53 4d 5f 43 4f 4d 50 52 45 53  inst LSM_COMPRES
8b80: 53 49 4f 4e 5f 4e 4f 4e 45 20 69 66 20 6e 6f 20  SION_NONE if no 
8b90: 63 6f 6d 70 72 65 73 73 69 6f 6e 20 68 6f 6f 6b  compression hook
8ba0: 73 20 61 72 65 20 63 6f 6e 66 69 67 75 72 65 64  s are configured
8bb0: 2e 20 49 66 20 74 68 65 20 63 6f 6d 70 72 65 73  . If the compres
8bc0: 73 69 6f 6e 20 69 64 0a 64 6f 65 73 20 6e 6f 74  sion id.does not
8bd0: 20 6d 61 74 63 68 2c 20 74 68 65 6e 20 61 6e 20   match, then an 
8be0: 4c 53 4d 5f 4d 49 53 4d 41 54 43 48 20 65 72 72  LSM_MISMATCH err
8bf0: 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 61  or is returned a
8c00: 6e 64 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  nd the operation
8c10: 20 0a 66 61 69 6c 73 20 28 6e 6f 20 74 72 61 6e   .fails (no tran
8c20: 73 61 63 74 69 6f 6e 20 6f 72 20 64 61 74 61 62  saction or datab
8c30: 61 73 65 20 63 75 72 73 6f 72 20 69 73 20 6f 70  ase cursor is op
8c40: 65 6e 65 64 29 2e 0a 0a 3c 70 3e 3c 69 3e 4d 61  ened)...<p><i>Ma
8c50: 79 62 65 20 74 68 65 72 65 20 73 68 6f 75 6c 64  ybe there should
8c60: 20 62 65 20 61 20 77 61 79 20 74 6f 20 72 65 67   be a way to reg
8c70: 69 73 74 65 72 20 61 20 6d 69 73 6d 61 74 63 68  ister a mismatch
8c80: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
8c90: 6b 2e 0a 4f 74 68 65 72 77 69 73 65 2c 20 61 70  k..Otherwise, ap
8ca0: 70 6c 69 63 61 74 69 6f 6e 73 20 68 61 76 65 20  plications have 
8cb0: 74 6f 20 68 61 6e 64 6c 65 20 4c 53 4d 5f 4d 49  to handle LSM_MI
8cc0: 53 4d 41 54 43 48 20 65 76 65 72 79 77 68 65 72  SMATCH everywher
8cd0: 65 2e 2e 2e 0a 3c 2f 69 3e 0a 0a 0a 3c 68 31 20  e....</i>...<h1 
8ce0: 69 64 3d 70 65 72 66 6f 72 6d 61 6e 63 65 5f 74  id=performance_t
8cf0: 75 6e 69 6e 67 3e 36 2e 20 50 65 72 66 6f 72 6d  uning>6. Perform
8d00: 61 6e 63 65 20 54 75 6e 69 6e 67 3c 2f 68 31 3e  ance Tuning</h1>
8d10: 0a 0a 3c 70 3e 20 54 68 69 73 20 73 65 63 74 69  ..<p> This secti
8d20: 6f 6e 20 64 65 73 63 72 69 62 65 73 20 74 68 65  on describes the
8d30: 20 76 61 72 69 6f 75 73 20 6d 65 61 73 75 72 65   various measure
8d40: 73 20 74 68 61 74 20 63 61 6e 20 62 65 20 74 61  s that can be ta
8d50: 6b 65 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  ken in order to.
8d60: 66 69 6e 65 2d 74 75 6e 65 20 4c 53 4d 20 69 6e  fine-tune LSM in
8d70: 20 6f 72 64 65 72 20 74 6f 20 69 6d 70 72 6f 76   order to improv
8d80: 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 6e  e performance in
8d90: 20 73 70 65 63 69 66 69 63 20 63 69 72 63 75 6d   specific circum
8da0: 73 74 61 6e 63 65 73 2e 0a 53 75 62 2d 73 65 63  stances..Sub-sec
8db0: 74 69 6f 6e 20 36 2e 31 20 69 64 65 6e 74 69 66  tion 6.1 identif
8dc0: 69 65 73 20 74 68 65 20 0a 3c 61 20 68 72 65 66  ies the .<a href
8dd0: 3d 23 70 65 72 66 6f 72 6d 61 6e 63 65 5f 72 65  =#performance_re
8de0: 6c 61 74 65 64 5f 63 6f 6e 66 69 67 75 72 61 74  lated_configurat
8df0: 69 6f 6e 5f 6f 70 74 69 6f 6e 73 3e 20 63 6f 6e  ion_options> con
8e00: 66 69 67 75 72 61 74 69 6f 6e 0a 70 61 72 61 6d  figuration.param
8e10: 65 74 65 72 73 3c 2f 61 3e 20 74 68 61 74 20 63  eters</a> that c
8e20: 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69 6e  an be used to in
8e30: 66 6c 75 65 6e 63 65 20 64 61 74 61 62 61 73 65  fluence database
8e40: 20 70 65 72 66 6f 72 6d 61 6e 63 65 2e 20 0a 53   performance. .S
8e50: 75 62 2d 73 65 63 74 69 6f 6e 20 36 2e 32 20 64  ub-section 6.2 d
8e60: 69 73 63 75 73 73 65 73 20 6d 65 74 68 6f 64 73  iscusses methods
8e70: 20 66 6f 72 20 73 68 69 66 74 69 6e 67 20 74 68   for shifting th
8e80: 65 20 74 69 6d 65 2d 63 6f 6e 73 75 6d 69 6e 67  e time-consuming
8e90: 20 70 72 6f 63 65 73 73 65 73 20 6f 66 0a 61 63   processes of.ac
8ea0: 74 75 61 6c 6c 79 20 77 72 69 74 69 6e 67 20 61  tually writing a
8eb0: 6e 64 20 73 79 6e 63 69 6e 67 20 74 68 65 20 64  nd syncing the d
8ec0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f 20  atabase file to 
8ed0: 0a 3c 61 20 68 72 65 66 3d 23 75 73 69 6e 67 5f  .<a href=#using_
8ee0: 77 6f 72 6b 65 72 5f 74 68 72 65 61 64 73 5f 6f  worker_threads_o
8ef0: 72 5f 70 72 6f 63 65 73 73 65 73 3e 62 61 63 6b  r_processes>back
8f00: 67 72 6f 75 6e 64 20 74 68 72 65 61 64 73 20 6f  ground threads o
8f10: 72 20 70 72 6f 63 65 73 73 65 73 3c 2f 61 3e 20  r processes</a> 
8f20: 0a 69 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 6b  .in order to mak
8f30: 65 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65  e writing to the
8f40: 20 64 61 74 61 62 61 73 65 20 6d 6f 72 65 20 72   database more r
8f50: 65 73 70 6f 6e 73 69 76 65 2e 20 46 69 6e 61 6c  esponsive. Final
8f60: 6c 79 2c 20 36 2e 0a 33 20 69 6e 74 72 6f 64 75  ly, 6..3 introdu
8f70: 63 65 73 20 22 3c 61 20 68 72 65 66 3d 23 64 61  ces "<a href=#da
8f80: 74 61 62 61 73 65 5f 66 69 6c 65 5f 6f 70 74 69  tabase_file_opti
8f90: 6d 69 7a 61 74 69 6f 6e 3e 64 61 74 61 62 61 73  mization>databas
8fa0: 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 3c 2f  e optimization</
8fb0: 61 3e 22 0a 2d 20 74 68 65 20 70 72 6f 63 65 73  a>".- the proces
8fc0: 73 20 6f 66 20 72 65 6f 72 67 61 6e 69 7a 69 6e  s of reorganizin
8fd0: 67 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  g a database fil
8fe0: 65 20 69 6e 74 65 72 6e 61 6c 6c 79 20 73 6f 20  e internally so 
8ff0: 74 68 61 74 20 69 74 20 69 73 20 61 73 20 73 6d  that it is as sm
9000: 61 6c 6c 0a 61 73 20 70 6f 73 73 69 62 6c 65 20  all.as possible 
9010: 61 6e 64 20 6f 70 74 69 6d 69 7a 65 64 20 66 6f  and optimized fo
9020: 72 20 73 65 61 72 63 68 20 71 75 65 72 69 65 73  r search queries
9030: 2e 0a 0a 3c 68 32 20 69 64 3d 70 65 72 66 6f 72  ...<h2 id=perfor
9040: 6d 61 6e 63 65 5f 72 65 6c 61 74 65 64 5f 63 6f  mance_related_co
9050: 6e 66 69 67 75 72 61 74 69 6f 6e 5f 6f 70 74 69  nfiguration_opti
9060: 6f 6e 73 3e 36 2e 31 2e 20 50 65 72 66 6f 72 6d  ons>6.1. Perform
9070: 61 6e 63 65 20 52 65 6c 61 74 65 64 20 43 6f 6e  ance Related Con
9080: 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f  figuration Optio
9090: 6e 73 20 3c 2f 68 32 3e 0a 0a 3c 70 3e 54 68 65  ns </h2>..<p>The
90a0: 20 6f 70 74 69 6f 6e 73 20 69 6e 20 74 68 69 73   options in this
90b0: 20 73 65 63 74 69 6f 6e 20 61 6c 6c 20 74 61 6b   section all tak
90c0: 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73  e integer values
90d0: 2e 20 54 68 65 79 20 6d 61 79 20 62 65 20 62 6f  . They may be bo
90e0: 74 68 0a 73 65 74 20 61 6e 64 20 71 75 65 72 69  th.set and queri
90f0: 65 64 20 75 73 69 6e 67 20 74 68 65 20 3c 61 20  ed using the <a 
9100: 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69  href=lsmapi.wiki
9110: 23 6c 73 6d 5f 63 6f 6e 66 69 67 3e 6c 73 6d 5f  #lsm_config>lsm_
9120: 63 6f 6e 66 69 67 28 29 3c 2f 61 3e 0a 66 75 6e  config()</a>.fun
9130: 63 74 69 6f 6e 2e 20 54 6f 20 73 65 74 20 61 6e  ction. To set an
9140: 20 6f 70 74 69 6f 6e 20 74 6f 20 61 20 76 61 6c   option to a val
9150: 75 65 2c 20 6c 73 6d 5f 63 6f 6e 66 69 67 28 29  ue, lsm_config()
9160: 20 69 73 20 75 73 65 64 20 61 73 20 66 6f 6c 6c   is used as foll
9170: 6f 77 73 3a 0a 0a 3c 76 65 72 62 61 74 69 6d 3e  ows:..<verbatim>
9180: 0a 20 20 2f 2a 20 53 65 74 20 74 68 65 20 4c 53  .  /* Set the LS
9190: 4d 5f 43 4f 4e 46 49 47 5f 41 55 54 4f 46 4c 55  M_CONFIG_AUTOFLU
91a0: 53 48 20 6f 70 74 69 6f 6e 20 74 6f 20 31 4d 42  SH option to 1MB
91b0: 20 2a 2f 0a 20 20 69 6e 74 20 69 56 61 6c 20 3d   */.  int iVal =
91c0: 20 31 20 2a 20 31 30 32 34 20 2a 20 31 30 32 34   1 * 1024 * 1024
91d0: 3b 0a 20 20 72 63 20 3d 20 6c 73 6d 5f 63 6f 6e  ;.  rc = lsm_con
91e0: 66 69 67 28 64 62 2c 20 4c 53 4d 5f 43 4f 4e 46  fig(db, LSM_CONF
91f0: 49 47 5f 41 55 54 4f 46 4c 55 53 48 2c 20 26 69  IG_AUTOFLUSH, &i
9200: 56 61 6c 29 3b 0a 3c 2f 76 65 72 62 61 74 69 6d  Val);.</verbatim
9210: 3e 0a 0a 3c 70 3e 49 6e 20 6f 72 64 65 72 20 74  >..<p>In order t
9220: 6f 20 71 75 65 72 79 20 74 68 65 20 63 75 72 72  o query the curr
9230: 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 6e 20  ent value of an 
9240: 6f 70 74 69 6f 6e 2c 20 74 68 65 20 69 6e 69 74  option, the init
9250: 69 61 6c 20 76 61 6c 75 65 20 6f 66 0a 74 68 65  ial value of.the
9260: 20 70 61 72 61 6d 65 74 65 72 20 28 69 56 61 6c   parameter (iVal
9270: 20 69 6e 20 74 68 65 20 65 78 61 6d 70 6c 65 20   in the example 
9280: 63 6f 64 65 20 61 62 6f 76 65 29 20 73 68 6f 75  code above) shou
9290: 6c 64 20 62 65 20 73 65 74 20 74 6f 20 61 20 6e  ld be set to a n
92a0: 65 67 61 74 69 76 65 0a 76 61 6c 75 65 2e 20 4f  egative.value. O
92b0: 72 20 61 6e 79 20 6f 74 68 65 72 20 76 61 6c 75  r any other valu
92c0: 65 20 74 68 61 74 20 68 61 70 70 65 6e 73 20 74  e that happens t
92d0: 6f 20 62 65 20 6f 75 74 20 6f 66 20 72 61 6e 67  o be out of rang
92e0: 65 20 66 6f 72 20 74 68 65 20 70 61 72 61 6d 65  e for the parame
92f0: 74 65 72 20 2d 0a 6e 65 67 61 74 69 76 65 20 76  ter -.negative v
9300: 61 6c 75 65 73 20 6a 75 73 74 20 68 61 70 70 65  alues just happe
9310: 6e 20 74 6f 20 62 65 20 6f 75 74 20 6f 66 20 72  n to be out of r
9320: 61 6e 67 65 20 66 6f 72 20 61 6c 6c 20 69 6e 74  ange for all int
9330: 65 67 65 72 20 6c 73 6d 5f 63 6f 6e 66 69 67 28  eger lsm_config(
9340: 29 0a 70 61 72 61 6d 65 74 65 72 73 2e 0a 0a 3c  ).parameters...<
9350: 76 65 72 62 61 74 69 6d 3e 0a 20 20 2f 2a 20 53  verbatim>.  /* S
9360: 65 74 20 69 56 61 6c 20 74 6f 20 74 68 65 20 63  et iVal to the c
9370: 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20  urrent value of 
9380: 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55 54 4f 46  LSM_CONFIG_AUTOF
9390: 4c 55 53 48 20 2a 2f 0a 20 20 69 6e 74 20 69 56  LUSH */.  int iV
93a0: 61 6c 20 3d 20 2d 31 3b 0a 20 20 72 63 20 3d 20  al = -1;.  rc = 
93b0: 6c 73 6d 5f 63 6f 6e 66 69 67 28 64 62 2c 20 4c  lsm_config(db, L
93c0: 53 4d 5f 43 4f 4e 46 49 47 5f 41 55 54 4f 46 4c  SM_CONFIG_AUTOFL
93d0: 55 53 48 2c 20 26 69 56 61 6c 29 3b 0a 3c 2f 76  USH, &iVal);.</v
93e0: 65 72 62 61 74 69 6d 3e 0a 0a 3c 64 6c 3e 0a 20  erbatim>..<dl>. 
93f0: 20 3c 64 74 3e 20 3c 61 20 68 72 65 66 3d 6c 73   <dt> <a href=ls
9400: 6d 61 70 69 2e 77 69 6b 69 23 4c 53 4d 5f 43 4f  mapi.wiki#LSM_CO
9410: 4e 46 49 47 5f 4d 4d 41 50 3e 4c 53 4d 5f 43 4f  NFIG_MMAP>LSM_CO
9420: 4e 46 49 47 5f 4d 4d 41 50 3c 2f 61 3e 0a 20 20  NFIG_MMAP</a>.  
9430: 3c 64 64 3e 20 3c 70 20 73 74 79 6c 65 3d 6d 61  <dd> <p style=ma
9440: 72 67 69 6e 2d 74 6f 70 3a 30 3e 0a 20 20 20 20  rgin-top:0>.    
9450: 49 66 20 4c 53 4d 20 69 73 20 72 75 6e 6e 69 6e  If LSM is runnin
9460: 67 20 6f 6e 20 61 20 73 79 73 74 65 6d 20 77 69  g on a system wi
9470: 74 68 20 61 20 36 34 2d 62 69 74 20 61 64 64 72  th a 64-bit addr
9480: 65 73 73 20 73 70 61 63 65 2c 20 74 68 69 73 20  ess space, this 
9490: 6f 70 74 69 6f 6e 0a 20 20 20 20 6d 61 79 20 62  option.    may b
94a0: 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20  e set to either 
94b0: 31 20 28 74 72 75 65 29 20 6f 72 20 30 20 28 66  1 (true) or 0 (f
94c0: 61 6c 73 65 29 2e 20 4f 6e 20 61 20 33 32 2d 62  alse). On a 32-b
94d0: 69 74 20 70 6c 61 74 66 6f 72 6d 2c 20 69 74 20  it platform, it 
94e0: 69 73 0a 20 20 20 20 61 6c 77 61 79 73 20 73 65  is.    always se
94f0: 74 20 74 6f 20 30 2e 0a 20 20 20 20 3c 70 3e 20  t to 0..    <p> 
9500: 49 66 20 69 74 20 69 73 20 73 65 74 20 74 6f 20  If it is set to 
9510: 74 72 75 65 2c 20 74 68 65 20 65 6e 74 69 72 65  true, the entire
9520: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 69   database file i
9530: 73 20 6d 65 6d 6f 72 79 20 6d 61 70 70 65 64 2e  s memory mapped.
9540: 20 4f 72 2c 20 69 66 0a 20 20 20 20 69 74 20 69   Or, if.    it i
9550: 73 20 66 61 6c 73 65 2c 20 64 61 74 61 20 69 73  s false, data is
9560: 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
9570: 6f 72 64 69 6e 61 72 79 20 4f 53 20 66 69 6c 65  ordinary OS file
9580: 20 72 65 61 64 20 61 6e 64 20 77 72 69 74 65 0a   read and write.
9590: 20 20 20 20 70 72 69 6d 69 74 69 76 65 73 2e 20      primitives. 
95a0: 4d 65 6d 6f 72 79 20 6d 61 70 70 69 6e 67 20 74  Memory mapping t
95b0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
95c0: 20 63 61 6e 20 73 69 67 6e 69 66 69 63 61 6e 74   can significant
95d0: 6c 79 20 69 6d 70 72 6f 76 65 20 74 68 65 0a 20  ly improve the. 
95e0: 20 20 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f     performance o
95f0: 66 20 72 65 61 64 20 6f 70 65 72 61 74 69 6f 6e  f read operation
9600: 73 2c 20 61 73 20 64 61 74 61 62 61 73 65 20 70  s, as database p
9610: 61 67 65 73 20 64 6f 20 6e 6f 74 20 68 61 76 65  ages do not have
9620: 20 74 6f 20 62 65 20 63 6f 70 69 65 64 0a 20 20   to be copied.  
9630: 20 20 66 72 6f 6d 20 6f 70 65 72 61 74 69 6e 67    from operating
9640: 20 73 79 73 74 65 6d 20 62 75 66 66 65 72 73 20   system buffers 
9650: 69 6e 74 6f 20 75 73 65 72 20 73 70 61 63 65 20  into user space 
9660: 62 75 66 66 65 72 73 20 62 65 66 6f 72 65 20 74  buffers before t
9670: 68 65 79 20 63 61 6e 20 62 65 0a 20 20 20 20 65  hey can be.    e
9680: 78 61 6d 69 6e 65 64 2e 20 0a 20 20 20 20 3c 70  xamined. .    <p
9690: 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e  >This option can
96a0: 20 6f 6e 6c 79 20 62 65 20 73 65 74 20 62 65 66   only be set bef
96b0: 6f 72 65 20 6c 73 6d 5f 6f 70 65 6e 28 29 20 69  ore lsm_open() i
96c0: 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20  s called on the 
96d0: 64 61 74 61 62 61 73 65 0a 20 20 20 20 63 6f 6e  database.    con
96e0: 6e 65 63 74 69 6f 6e 2e 0a 20 20 20 20 3c 70 3e  nection..    <p>
96f0: 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
9700: 65 20 69 73 20 31 20 28 74 72 75 65 29 20 6f 6e  e is 1 (true) on
9710: 20 61 20 36 34 2d 62 69 74 20 70 6c 61 74 66 6f   a 64-bit platfo
9720: 72 6d 2c 20 61 6e 64 20 30 20 6f 74 68 65 72 77  rm, and 0 otherw
9730: 69 73 65 2e 0a 0a 20 20 3c 64 74 3e 20 3c 61 20  ise...  <dt> <a 
9740: 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69  href=lsmapi.wiki
9750: 23 4c 53 4d 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  #LSM_CONFIG_MULT
9760: 49 50 4c 45 5f 50 52 4f 43 45 53 53 45 53 3e 4c  IPLE_PROCESSES>L
9770: 53 4d 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 50  SM_CONFIG_MULTIP
9780: 4c 45 5f 50 52 4f 43 45 53 53 45 53 3c 2f 61 3e  LE_PROCESSES</a>
9790: 0a 20 20 3c 64 64 3e 20 3c 70 20 73 74 79 6c 65  .  <dd> <p style
97a0: 3d 6d 61 72 67 69 6e 2d 74 6f 70 3a 30 3e 0a 20  =margin-top:0>. 
97b0: 20 20 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 6d     This option m
97c0: 61 79 20 61 6c 73 6f 20 62 65 20 73 65 74 20 74  ay also be set t
97d0: 6f 20 65 69 74 68 65 72 20 31 20 28 74 72 75 65  o either 1 (true
97e0: 29 20 6f 72 20 30 20 28 66 61 6c 73 65 29 2e 20  ) or 0 (false). 
97f0: 49 66 20 69 74 20 69 73 0a 20 20 20 20 73 65 74  If it is.    set
9800: 20 74 6f 20 30 2c 20 74 68 65 6e 20 74 68 65 20   to 0, then the 
9810: 6c 69 62 72 61 72 79 20 61 73 73 75 6d 65 73 20  library assumes 
9820: 74 68 61 74 20 61 6c 6c 20 64 61 74 61 62 61 73  that all databas
9830: 65 20 63 6c 69 65 6e 74 73 20 61 72 65 20 6c 6f  e clients are lo
9840: 63 61 74 65 64 20 0a 20 20 20 20 77 69 74 68 69  cated .    withi
9850: 6e 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65  n the same proce
9860: 73 73 20 28 68 61 76 65 20 61 63 63 65 73 73 20  ss (have access 
9870: 74 6f 20 74 68 65 20 73 61 6d 65 20 6d 65 6d 6f  to the same memo
9880: 72 79 20 73 70 61 63 65 29 2e 20 41 73 73 75 6d  ry space). Assum
9890: 69 6e 67 0a 20 20 20 20 74 68 69 73 20 6d 65 61  ing.    this mea
98a0: 6e 73 20 74 68 65 20 6c 69 62 72 61 72 79 20 63  ns the library c
98b0: 61 6e 20 61 76 6f 69 64 20 75 73 69 6e 67 20 4f  an avoid using O
98c0: 53 20 66 69 6c 65 20 6c 6f 63 6b 69 6e 67 20 70  S file locking p
98d0: 72 69 6d 69 74 69 76 65 73 20 74 6f 20 6c 6f 63  rimitives to loc
98e0: 6b 0a 20 20 20 20 74 68 65 20 64 61 74 61 62 61  k.    the databa
98f0: 73 65 20 66 69 6c 65 2c 20 77 68 69 63 68 20 73  se file, which s
9900: 70 65 65 64 73 20 75 70 20 6f 70 65 6e 69 6e 67  peeds up opening
9910: 20 61 6e 64 20 63 6c 6f 73 69 6e 67 20 72 65 61   and closing rea
9920: 64 20 61 6e 64 20 77 72 69 74 65 0a 20 20 20 20  d and write.    
9930: 74 72 61 6e 73 61 63 74 69 6f 6e 73 2e 20 0a 0a  transactions. ..
9940: 20 20 20 20 3c 70 3e 54 68 69 73 20 6f 70 74 69      <p>This opti
9950: 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 73  on can only be s
9960: 65 74 20 62 65 66 6f 72 65 20 6c 73 6d 5f 6f 70  et before lsm_op
9970: 65 6e 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f  en() is called o
9980: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 20  n the database. 
9990: 20 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 0a     connection...
99a0: 20 20 20 20 3c 70 3e 54 68 65 20 64 65 66 61 75      <p>The defau
99b0: 6c 74 20 76 61 6c 75 65 20 69 73 20 31 20 28 74  lt value is 1 (t
99c0: 72 75 65 29 2e 0a 0a 20 20 3c 64 74 3e 20 3c 61  rue)...  <dt> <a
99d0: 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b   href=lsmapi.wik
99e0: 69 23 4c 53 4d 5f 43 4f 4e 46 49 47 5f 55 53 45  i#LSM_CONFIG_USE
99f0: 5f 4c 4f 47 3e 4c 53 4d 5f 43 4f 4e 46 49 47 5f  _LOG>LSM_CONFIG_
9a00: 55 53 45 5f 4c 4f 47 3c 2f 61 3e 0a 20 20 3c 64  USE_LOG</a>.  <d
9a10: 64 3e 20 3c 70 20 73 74 79 6c 65 3d 6d 61 72 67  d> <p style=marg
9a20: 69 6e 2d 74 6f 70 3a 30 3e 0a 20 20 20 20 54 68  in-top:0>.    Th
9a30: 69 73 20 69 73 20 61 6e 6f 74 68 65 72 20 6f 70  is is another op
9a40: 74 69 6f 6e 20 6d 61 79 20 61 6c 73 6f 20 62 65  tion may also be
9a50: 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 31   set to either 1
9a60: 20 28 74 72 75 65 29 20 6f 72 20 30 20 28 66 61   (true) or 0 (fa
9a70: 6c 73 65 29 2e 20 0a 20 20 20 20 49 66 20 69 74  lse). .    If it
9a80: 20 69 73 20 73 65 74 20 74 6f 20 66 61 6c 73 65   is set to false
9a90: 2c 20 74 68 65 6e 20 74 68 65 20 6c 69 62 72 61  , then the libra
9aa0: 72 79 20 64 6f 65 73 20 6e 6f 74 20 77 72 69 74  ry does not writ
9ab0: 65 20 64 61 74 61 20 69 6e 74 6f 20 74 68 65 0a  e data into the.
9ac0: 20 20 20 20 64 61 74 61 62 61 73 65 20 6c 6f 67      database log
9ad0: 20 66 69 6c 65 2e 20 54 68 69 73 20 6d 61 6b 65   file. This make
9ae0: 73 20 77 72 69 74 69 6e 67 20 66 61 73 74 65 72  s writing faster
9af0: 2c 20 62 75 74 20 61 6c 73 6f 20 6d 65 61 6e 73  , but also means
9b00: 20 74 68 61 74 20 69 66 0a 20 20 20 20 61 6e 20   that if.    an 
9b10: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 72 61 73  application cras
9b20: 68 20 6f 72 20 70 6f 77 65 72 20 66 61 69 6c 75  h or power failu
9b30: 72 65 20 6f 63 63 75 72 73 2c 20 69 74 20 69 73  re occurs, it is
9b40: 20 76 65 72 79 20 6c 69 6b 65 6c 79 20 74 68 61   very likely tha
9b50: 74 0a 20 20 20 20 61 6e 79 20 72 65 63 65 6e 74  t.    any recent
9b60: 6c 79 20 63 6f 6d 6d 69 74 74 65 64 20 74 72 61  ly committed tra
9b70: 6e 73 61 63 74 69 6f 6e 73 20 77 69 6c 6c 20 62  nsactions will b
9b80: 65 20 6c 6f 73 74 2e 0a 0a 20 20 20 20 3c 70 3e  e lost...    <p>
9b90: 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
9ba0: 73 20 73 65 74 20 74 6f 20 74 72 75 65 2c 20 74  s set to true, t
9bb0: 68 65 6e 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hen an applicati
9bc0: 6f 6e 20 63 72 61 73 68 20 63 61 6e 6e 6f 74 20  on crash cannot 
9bd0: 63 61 75 73 65 0a 20 20 20 20 64 61 74 61 20 6c  cause.    data l
9be0: 6f 73 73 2e 20 57 68 65 74 68 65 72 20 6f 72 20  oss. Whether or 
9bf0: 6e 6f 74 20 64 61 74 61 20 6c 6f 73 73 20 6d 61  not data loss ma
9c00: 79 20 6f 63 63 75 72 20 69 6e 20 74 68 65 20 65  y occur in the e
9c10: 76 65 6e 74 20 6f 66 20 61 20 70 6f 77 65 72 0a  vent of a power.
9c20: 20 20 20 20 66 61 69 6c 75 72 65 20 64 65 70 65      failure depe
9c30: 6e 64 73 20 6f 6e 20 74 68 65 20 76 61 6c 75 65  nds on the value
9c40: 20 6f 66 20 74 68 65 20 3c 61 20 68 72 65 66 3d   of the <a href=
9c50: 23 64 61 74 61 5f 64 75 72 61 62 69 6c 69 74 79  #data_durability
9c60: 3e 0a 20 20 20 20 4c 53 4d 5f 43 4f 4e 46 49 47  >.    LSM_CONFIG
9c70: 5f 53 41 46 45 54 59 3c 2f 61 3e 20 70 61 72 61  _SAFETY</a> para
9c80: 6d 65 74 65 72 2e 0a 0a 20 20 20 20 3c 70 3e 54  meter...    <p>T
9c90: 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 6f  his option can o
9ca0: 6e 6c 79 20 62 65 20 73 65 74 20 69 66 20 74 68  nly be set if th
9cb0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 64 6f 65  e connection doe
9cc0: 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20  s not currently 
9cd0: 68 61 76 65 0a 20 20 20 20 61 6e 20 6f 70 65 6e  have.    an open
9ce0: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
9cf0: 6f 6e 2e 0a 0a 20 20 20 20 3c 70 3e 54 68 65 20  on...    <p>The 
9d00: 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73  default value is
9d10: 20 31 20 28 74 72 75 65 29 2e 0a 0a 20 20 3c 64   1 (true)...  <d
9d20: 74 3e 20 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70  t> <a href=lsmap
9d30: 69 2e 77 69 6b 69 23 4c 53 4d 5f 43 4f 4e 46 49  i.wiki#LSM_CONFI
9d40: 47 5f 41 55 54 4f 46 4c 55 53 48 3e 4c 53 4d 5f  G_AUTOFLUSH>LSM_
9d50: 43 4f 4e 46 49 47 5f 41 55 54 4f 46 4c 55 53 48  CONFIG_AUTOFLUSH
9d60: 3c 2f 61 3e 0a 20 20 3c 64 64 3e 20 3c 70 20 73  </a>.  <dd> <p s
9d70: 74 79 6c 65 3d 6d 61 72 67 69 6e 2d 74 6f 70 3a  tyle=margin-top:
9d80: 30 3e 0a 20 20 20 20 57 68 65 6e 20 61 20 63 6c  0>.    When a cl
9d90: 69 65 6e 74 20 77 72 69 74 65 73 20 74 6f 20 61  ient writes to a
9da0: 6e 20 4c 53 4d 20 64 61 74 61 62 61 73 65 2c 20  n LSM database, 
9db0: 63 68 61 6e 67 65 73 20 61 72 65 20 62 75 66 66  changes are buff
9dc0: 65 72 65 64 20 69 6e 20 6d 65 6d 6f 72 79 20 0a  ered in memory .
9dd0: 20 20 20 20 62 65 66 6f 72 65 20 62 65 69 6e 67      before being
9de0: 20 77 72 69 74 74 65 6e 20 6f 75 74 20 74 6f 20   written out to 
9df0: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
9e00: 65 20 69 6e 20 61 20 62 61 74 63 68 2e 20 54 68  e in a batch. Th
9e10: 69 73 20 6f 70 74 69 6f 6e 0a 20 20 20 20 69 73  is option.    is
9e20: 20 73 65 74 20 74 6f 20 74 68 65 20 73 69 7a 65   set to the size
9e30: 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
9e40: 6e 20 62 79 74 65 73 2e 20 54 68 65 20 64 65 66  n bytes. The def
9e50: 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 31 30  ault value is 10
9e60: 34 38 35 37 36 2e 0a 20 20 20 20 49 6e 63 72 65  48576..    Incre
9e70: 61 73 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65  asing this value
9e80: 20 6d 61 79 20 69 6d 70 72 6f 76 65 20 6f 76 65   may improve ove
9e90: 72 61 6c 6c 20 77 72 69 74 65 20 74 68 72 6f 75  rall write throu
9ea0: 67 68 70 75 74 2e 20 44 65 63 72 65 61 73 69 6e  ghput. Decreasin
9eb0: 67 0a 20 20 20 20 69 74 20 72 65 64 75 63 65 73  g.    it reduces
9ec0: 20 6d 65 6d 6f 72 79 20 75 73 61 67 65 2e 0a 20   memory usage.. 
9ed0: 20 20 20 0a 0a 20 20 3c 64 74 3e 20 3c 61 20 68     ..  <dt> <a h
9ee0: 72 65 66 3d 6c 73 6d 61 70 69 2e 77 69 6b 69 23  ref=lsmapi.wiki#
9ef0: 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55 54 4f 43  LSM_CONFIG_AUTOC
9f00: 48 45 43 4b 50 4f 49 4e 54 3e 4c 53 4d 5f 43 4f  HECKPOINT>LSM_CO
9f10: 4e 46 49 47 5f 41 55 54 4f 43 48 45 43 4b 50 4f  NFIG_AUTOCHECKPO
9f20: 49 4e 54 3c 2f 61 3e 0a 20 20 3c 64 64 3e 20 3c  INT</a>.  <dd> <
9f30: 70 20 73 74 79 6c 65 3d 6d 61 72 67 69 6e 2d 74  p style=margin-t
9f40: 6f 70 3a 30 3e 0a 20 20 20 20 54 68 69 73 20 6f  op:0>.    This o
9f50: 70 74 69 6f 6e 20 64 65 74 65 72 6d 69 6e 65 73  ption determines
9f60: 20 68 6f 77 20 6f 66 74 65 6e 20 74 68 65 20 64   how often the d
9f70: 61 74 61 62 61 73 65 20 69 73 20 63 68 65 63 6b  atabase is check
9f80: 70 6f 69 6e 74 65 64 20 28 73 79 6e 63 65 64 20  pointed (synced 
9f90: 74 6f 0a 20 20 20 20 64 69 73 6b 29 2e 20 41 20  to.    disk). A 
9fa0: 63 68 65 63 6b 70 6f 69 6e 74 20 69 73 20 70 65  checkpoint is pe
9fb0: 72 66 6f 72 6d 65 64 20 61 66 74 65 72 20 65 61  rformed after ea
9fc0: 63 68 20 4e 20 62 79 74 65 73 20 28 61 70 70 72  ch N bytes (appr
9fd0: 6f 78 69 6d 61 74 65 6c 79 29 20 61 72 65 0a 20  oximately) are. 
9fe0: 20 20 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68     written to th
9ff0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
a000: 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
a010: 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 6f 70  value of this op
a020: 74 69 6f 6e 2e 20 54 68 65 0a 20 20 20 20 64 65  tion. The.    de
a030: 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20 32  fault value is 2
a040: 30 39 37 31 35 32 20 28 32 4d 42 29 2e 0a 0a 20  097152 (2MB)... 
a050: 20 20 20 3c 70 3e 0a 20 20 20 20 49 6e 63 72 65     <p>.    Incre
a060: 61 73 69 6e 67 20 74 68 69 73 20 76 61 6c 75 65  asing this value
a070: 20 28 73 61 79 20 74 6f 20 34 4d 42 20 6f 72 20   (say to 4MB or 
a080: 65 76 65 6e 20 38 4d 42 29 20 6d 61 79 20 69 6d  even 8MB) may im
a090: 70 72 6f 76 65 20 6f 76 65 72 61 6c 6c 20 77 72  prove overall wr
a0a0: 69 74 65 0a 20 20 20 20 74 68 72 6f 75 67 68 70  ite.    throughp
a0b0: 75 74 2e 20 48 6f 77 65 76 65 72 2c 20 69 74 20  ut. However, it 
a0c0: 69 73 20 69 6d 70 6f 72 74 61 6e 74 20 6e 6f 74  is important not
a0d0: 20 74 6f 20 63 68 65 63 6b 70 6f 69 6e 74 20 74   to checkpoint t
a0e0: 6f 6f 20 69 6e 66 72 65 71 75 65 6e 74 6c 79 2c  oo infrequently,
a0f0: 20 0a 20 20 20 20 61 73 3a 0a 20 20 20 20 3c 75   .    as:.    <u
a100: 6c 3e 0a 20 20 20 20 20 20 3c 6c 69 3e 20 3c 70  l>.      <li> <p
a110: 3e 0a 20 20 20 20 20 20 20 20 20 20 20 53 70 61  >.           Spa
a120: 63 65 20 69 6e 20 74 68 65 20 6c 6f 67 20 66 69  ce in the log fi
a130: 6c 65 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 72  le may only be r
a140: 65 75 73 65 64 20 66 6f 6c 6c 6f 77 69 6e 67 20  eused following 
a150: 61 20 63 68 65 63 6b 70 6f 69 6e 74 2e 0a 20 20  a checkpoint..  
a160: 20 20 20 20 20 20 20 20 20 4f 6e 63 65 20 61 20           Once a 
a170: 63 68 65 63 6b 70 6f 69 6e 74 20 68 61 73 20 62  checkpoint has b
a180: 65 65 6e 20 63 6f 6d 70 6c 65 74 65 64 2c 20 61  een completed, a
a190: 6c 6c 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  ll application d
a1a0: 61 74 61 20 77 72 69 74 74 65 6e 0a 20 20 20 20  ata written.    
a1b0: 20 20 20 20 20 20 20 62 65 66 6f 72 65 20 74 68         before th
a1c0: 65 20 63 68 65 63 6b 70 6f 69 6e 74 20 69 73 20  e checkpoint is 
a1d0: 73 61 66 65 6c 79 20 73 74 6f 72 65 64 20 69 6e  safely stored in
a1e0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a1f0: 6c 65 2e 20 54 68 69 73 0a 20 20 20 20 20 20 20  le. This.       
a200: 20 20 20 20 6d 65 61 6e 73 20 74 68 65 20 63 6f      means the co
a210: 6e 74 65 6e 74 73 20 6f 66 20 74 68 65 20 6c 6f  ntents of the lo
a220: 67 20 66 69 6c 65 20 61 72 65 20 6e 6f 20 6c 6f  g file are no lo
a230: 6e 67 65 72 20 72 65 71 75 69 72 65 64 2c 20 61  nger required, a
a240: 6e 64 20 73 6f 0a 20 20 20 20 20 20 20 20 20 20  nd so.          
a250: 20 74 68 65 20 6e 65 78 74 20 64 61 74 61 62 61   the next databa
a260: 73 65 20 77 72 69 74 65 72 20 6d 61 79 20 73 74  se writer may st
a270: 61 72 74 20 77 72 69 74 69 6e 67 20 61 20 6e 65  art writing a ne
a280: 77 20 6c 6f 67 20 69 6e 74 6f 20 74 68 65 0a 20  w log into the. 
a290: 20 20 20 20 20 20 20 20 20 20 73 74 61 72 74 20            start 
a2a0: 6f 66 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  of the existing 
a2b0: 66 69 6c 65 20 28 6f 76 65 72 77 72 69 74 69 6e  file (overwritin
a2c0: 67 20 74 68 65 20 6f 6c 64 20 64 61 74 61 29 2e  g the old data).
a2d0: 20 0a 20 20 20 20 20 20 20 20 20 20 20 41 73 20   .           As 
a2e0: 77 65 6c 6c 20 61 73 20 63 6f 6e 73 75 6d 69 6e  well as consumin
a2f0: 67 20 64 69 73 6b 20 73 70 61 63 65 2c 20 6c 61  g disk space, la
a300: 72 67 65 20 6c 6f 67 20 66 69 6c 65 73 20 61 72  rge log files ar
a310: 65 20 75 6e 64 65 73 69 72 61 62 6c 65 20 0a 20  e undesirable . 
a320: 20 20 20 20 20 20 20 20 20 20 61 73 20 6f 66 74            as oft
a330: 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 6c 6f  en the entire lo
a340: 67 20 66 69 6c 65 20 6d 75 73 74 20 62 65 20 72  g file must be r
a350: 65 61 64 20 64 75 72 69 6e 67 20 64 61 74 61 62  ead during datab
a360: 61 73 65 20 72 65 63 6f 76 65 72 79 0a 20 20 20  ase recovery.   
a370: 20 20 20 20 20 20 20 20 66 6f 6c 6c 6f 77 69 6e          followin
a380: 67 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  g an application
a390: 20 6f 72 20 73 79 73 74 65 6d 20 66 61 69 6c 75   or system failu
a3a0: 72 65 2e 0a 20 20 20 20 20 20 20 20 20 20 20 0a  re..           .
a3b0: 20 20 20 20 20 20 3c 6c 69 3e 20 3c 70 3e 0a 20        <li> <p>. 
a3c0: 20 20 20 20 20 20 20 20 20 20 53 69 6d 69 6c 61            Simila
a3d0: 72 6c 79 2c 20 73 70 61 63 65 20 69 6e 20 74 68  rly, space in th
a3e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a3f0: 66 72 65 65 64 20 62 79 20 74 68 65 20 63 6f 6e  freed by the con
a400: 74 69 6e 75 6f 75 73 0a 20 20 20 20 20 20 20 20  tinuous.        
a410: 20 20 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 72     incremental r
a420: 65 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 6f 66  eorganization of
a430: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a440: 6c 65 20 74 68 61 74 20 4c 53 4d 20 70 65 72 66  le that LSM perf
a450: 6f 72 6d 73 0a 20 20 20 20 20 20 20 20 20 20 20  orms.           
a460: 63 61 6e 6e 6f 74 20 62 65 20 72 65 75 73 65 64  cannot be reused
a470: 20 75 6e 74 69 6c 20 61 66 74 65 72 20 61 20 63   until after a c
a480: 68 65 63 6b 70 6f 69 6e 74 20 68 61 73 20 62 65  heckpoint has be
a490: 65 6e 20 70 65 72 66 6f 72 6d 65 64 2e 20 0a 20  en performed. . 
a4a0: 20 20 20 20 20 20 20 20 20 20 53 6f 20 69 6e 63            So inc
a4b0: 72 65 61 73 69 6e 67 20 74 68 65 20 76 61 6c 75  reasing the valu
a4c0: 65 20 6f 66 20 74 68 69 73 20 70 61 72 61 6d 65  e of this parame
a4d0: 74 65 72 20 63 61 75 73 65 73 20 74 68 65 20 73  ter causes the s
a4e0: 70 61 63 65 20 75 73 65 64 0a 20 20 20 20 20 20  pace used.      
a4f0: 20 20 20 20 20 62 79 20 74 68 65 20 70 72 65 2d       by the pre-
a500: 72 65 6f 72 67 61 6e 69 7a 61 74 69 6f 6e 20 76  reorganization v
a510: 65 72 73 69 6f 6e 73 20 6f 66 20 64 61 74 61 20  ersions of data 
a520: 73 74 72 75 63 74 75 72 65 73 20 77 69 74 68 69  structures withi
a530: 6e 20 74 68 65 0a 20 20 20 20 20 20 20 20 20 20  n the.          
a540: 20 66 69 6c 65 20 74 6f 20 62 65 20 72 65 63 79   file to be recy
a550: 63 6c 65 64 20 6d 6f 72 65 20 73 6c 6f 77 6c 79  cled more slowly
a560: 2e 20 49 6e 63 72 65 61 73 69 6e 67 20 74 68 65  . Increasing the
a570: 20 6f 76 65 72 61 6c 6c 20 73 69 7a 65 20 6f 66   overall size of
a580: 0a 20 20 20 20 20 20 20 20 20 20 20 64 61 74 61  .           data
a590: 62 61 73 65 20 66 69 6c 65 73 20 75 6e 64 65 72  base files under
a5a0: 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
a5b0: 63 65 73 2e 0a 20 20 20 20 3c 2f 75 6c 3e 0a 3c  ces..    </ul>.<
a5c0: 2f 64 6c 3e 0a 0a 3c 70 3e 54 68 65 20 72 6f 6c  /dl>..<p>The rol
a5d0: 65 73 20 6f 66 20 74 68 65 20 4c 53 4d 5f 43 4f  es of the LSM_CO
a5e0: 4e 46 49 47 5f 41 55 54 4f 46 4c 55 53 48 20 61  NFIG_AUTOFLUSH a
a5f0: 6e 64 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55  nd LSM_CONFIG_AU
a600: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20 6f 70 74  TOCHECKPOINT opt
a610: 69 6f 6e 73 20 0a 61 72 65 20 64 69 73 63 75 73  ions .are discus
a620: 73 65 64 20 69 6e 20 6d 6f 72 65 20 64 65 74 61  sed in more deta
a630: 69 6c 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77  il in the follow
a640: 69 6e 67 20 73 65 63 74 69 6f 6e 2e 0a 0a 3c 68  ing section...<h
a650: 32 20 69 64 3d 75 73 69 6e 67 5f 77 6f 72 6b 65  2 id=using_worke
a660: 72 5f 74 68 72 65 61 64 73 5f 6f 72 5f 70 72 6f  r_threads_or_pro
a670: 63 65 73 73 65 73 3e 36 2e 32 2e 20 55 73 69 6e  cesses>6.2. Usin
a680: 67 20 57 6f 72 6b 65 72 20 54 68 72 65 61 64 73  g Worker Threads
a690: 20 6f 72 20 50 72 6f 63 65 73 73 65 73 20 3c 2f   or Processes </
a6a0: 68 32 3e 0a 0a 3c 70 3e 55 73 75 61 6c 6c 79 2c  h2>..<p>Usually,
a6b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a6c0: 6c 65 20 69 73 20 75 70 64 61 74 65 64 20 6f 6e  le is updated on
a6d0: 20 64 69 73 6b 20 66 72 6f 6d 20 77 69 74 68 69   disk from withi
a6e0: 6e 20 63 61 6c 6c 73 20 74 6f 0a 77 72 69 74 65  n calls to.write
a6f0: 20 66 75 6e 63 74 69 6f 6e 73 20 2d 20 6c 73 6d   functions - lsm
a700: 5f 69 6e 73 65 72 74 28 29 2c 20 6c 73 6d 5f 64  _insert(), lsm_d
a710: 65 6c 65 74 65 28 29 2c 20 6c 73 6d 5f 64 65 6c  elete(), lsm_del
a720: 65 74 65 5f 72 61 6e 67 65 28 29 20 61 6e 64 0a  ete_range() and.
a730: 6c 73 6d 5f 63 6f 6d 6d 69 74 28 29 2e 20 54 68  lsm_commit(). Th
a740: 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 6f 63  is means that oc
a750: 63 61 73 69 6f 6e 61 6c 6c 79 2c 20 61 20 63 61  casionally, a ca
a760: 6c 6c 20 74 6f 20 6f 6e 65 20 6f 66 20 74 68 65  ll to one of the
a770: 73 65 20 66 6f 75 72 20 0a 66 75 6e 63 74 69 6f  se four .functio
a780: 6e 73 20 6d 61 79 20 74 61 6b 65 20 73 69 67 6e  ns may take sign
a790: 69 63 61 6e 74 6c 79 20 6c 6f 6e 67 65 72 20 74  icantly longer t
a7a0: 68 61 6e 20 75 73 75 61 6c 20 61 73 20 69 74 20  han usual as it 
a7b0: 70 61 75 73 65 73 20 74 6f 20 77 72 69 74 65 20  pauses to write 
a7c0: 6f 72 0a 73 79 6e 63 20 74 68 65 20 64 61 74 61  or.sync the data
a7d0: 62 61 73 65 20 66 69 6c 65 2e 20 3c 61 20 68 72  base file. <a hr
a7e0: 65 66 3d 23 61 75 74 6f 6d 61 74 69 63 5f 77 6f  ef=#automatic_wo
a7f0: 72 6b 5f 61 6e 64 5f 63 68 65 63 6b 70 6f 69 6e  rk_and_checkpoin
a800: 74 5f 73 63 68 65 64 75 6c 69 6e 67 3e 53 65 65  t_scheduling>See
a810: 0a 62 65 6c 6f 77 3c 2f 61 3e 20 66 6f 72 20 64  .below</a> for d
a820: 65 74 61 69 6c 73 2e 0a 0a 3c 70 3e 54 68 65 20  etails...<p>The 
a830: 61 6c 74 65 72 6e 61 74 69 76 65 20 74 6f 20 75  alternative to u
a840: 70 64 61 74 69 6e 67 20 74 68 65 20 64 61 74 61  pdating the data
a850: 62 61 73 65 20 66 69 6c 65 20 66 72 6f 6d 20 77  base file from w
a860: 69 74 68 69 6e 20 63 61 6c 6c 73 20 74 6f 20 77  ithin calls to w
a870: 72 69 74 65 0a 66 75 6e 63 74 69 6f 6e 73 20 69  rite.functions i
a880: 73 20 74 6f 20 75 73 65 20 6f 6e 65 20 6f 72 20  s to use one or 
a890: 6d 6f 72 65 20 62 61 63 6b 67 72 6f 75 6e 64 20  more background 
a8a0: 74 68 72 65 61 64 73 20 6f 72 20 70 72 6f 63 65  threads or proce
a8b0: 73 73 65 73 20 74 6f 20 70 65 72 66 6f 72 6d 20  sses to perform 
a8c0: 74 68 65 0a 61 63 74 75 61 6c 20 77 6f 72 6b 20  the.actual work 
a8d0: 6f 66 20 77 72 69 74 69 6e 67 20 74 6f 20 74 68  of writing to th
a8e0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
a8f0: 20 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 20 48   ..<ul>.  <li> H
a900: 61 76 65 20 61 6c 6c 20 63 6c 69 65 6e 74 20 63  ave all client c
a910: 6f 6e 6e 65 63 74 69 6f 6e 73 20 73 65 74 20 74  onnections set t
a920: 68 65 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55  he LSM_CONFIG_AU
a930: 54 4f 57 4f 52 4b 20 6f 70 74 69 6f 6e 20 74 6f  TOWORK option to
a940: 20 30 2e 0a 20 20 20 20 20 20 20 54 68 69 73 20   0..       This 
a950: 73 74 6f 70 73 20 74 68 65 6d 20 66 72 6f 6d 20  stops them from 
a960: 77 72 69 74 69 6e 67 20 74 6f 20 74 68 65 20 64  writing to the d
a970: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 0a 0a 20  atabase file... 
a980: 20 3c 6c 69 3e 20 41 72 72 61 6e 67 65 20 66 6f   <li> Arrange fo
a990: 72 20 61 20 62 61 63 6b 67 72 6f 75 6e 64 20 74  r a background t
a9a0: 68 72 65 61 64 20 6f 72 20 70 72 6f 63 65 73 73  hread or process
a9b0: 20 74 6f 20 63 6f 6e 6e 65 63 74 20 74 6f 20 74   to connect to t
a9c0: 68 65 20 64 61 74 61 62 61 73 65 0a 20 20 20 20  he database.    
a9d0: 20 20 20 61 6e 64 20 63 61 6c 6c 20 74 68 65 20     and call the 
a9e0: 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77  <a href=lsmapi.w
a9f0: 69 6b 69 23 6c 73 6d 5f 77 6f 72 6b 3e 6c 73 6d  iki#lsm_work>lsm
aa00: 5f 77 6f 72 6b 28 29 3c 2f 61 3e 20 66 75 6e 63  _work()</a> func
aa10: 74 69 6f 6e 20 0a 20 20 20 20 20 20 20 70 65 72  tion .       per
aa20: 69 6f 64 69 63 61 6c 6c 79 2e 0a 20 20 20 20 20  iodically..     
aa30: 20 20 62 65 6c 6f 77 3c 2f 61 3e 29 2e 0a 3c 2f    below</a>)..</
aa40: 75 6c 3e 0a 0a 3c 70 3e 46 75 72 74 68 65 72 20  ul>..<p>Further 
aa50: 65 78 70 6c 61 6e 61 74 69 6f 6e 20 6f 66 2c 20  explanation of, 
aa60: 61 6e 64 20 65 78 61 6d 70 6c 65 20 63 6f 64 65  and example code
aa70: 20 66 6f 72 2c 20 74 68 65 20 61 62 6f 76 65 20   for, the above 
aa80: 69 73 0a 3c 61 20 68 72 65 66 3d 23 65 78 70 6c  is.<a href=#expl
aa90: 69 63 69 74 5f 77 6f 72 6b 5f 61 6e 64 5f 63 68  icit_work_and_ch
aaa0: 65 63 6b 70 6f 69 6e 74 5f 73 63 68 65 64 75 6c  eckpoint_schedul
aab0: 69 6e 67 3e 61 76 61 69 6c 61 62 6c 65 20 62 65  ing>available be
aac0: 6c 6f 77 3c 2f 61 3e 2e 0a 0a 3c 70 3e 54 68 65  low</a>...<p>The
aad0: 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 75 62 2d 73   following sub-s
aae0: 65 63 74 69 6f 6e 73 20 70 72 6f 76 69 64 65 20  ections provide 
aaf0: 61 20 68 69 67 68 2d 6c 65 76 65 6c 20 64 65 73  a high-level des
ab00: 63 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 0a  cription of the.
ab10: 4c 53 4d 20 64 61 74 61 62 61 73 65 20 61 72 63  LSM database arc
ab20: 68 69 74 65 63 74 75 72 65 20 61 6e 64 20 64 65  hitecture and de
ab30: 73 63 72 69 70 74 69 6f 6e 73 20 6f 66 20 68 6f  scriptions of ho
ab40: 77 20 76 61 72 69 6f 75 73 20 70 61 72 61 6d 65  w various parame
ab50: 74 65 72 73 20 0a 61 66 66 65 63 74 20 74 68 65  ters .affect the
ab60: 20 77 61 79 20 63 6c 69 65 6e 74 73 20 77 72 69   way clients wri
ab70: 74 65 20 74 6f 20 74 68 65 20 64 61 74 61 62 61  te to the databa
ab80: 73 65 20 66 69 6c 65 2e 20 57 68 69 6c 65 20 74  se file. While t
ab90: 68 69 73 20 6d 61 79 20 73 65 65 6d 0a 69 6e 20  his may seem.in 
aba0: 73 6f 6d 65 20 77 61 79 73 20 61 6e 20 69 6e 63  some ways an inc
abb0: 6f 6e 76 65 6e 69 65 6e 74 20 61 6d 6f 75 6e 74  onvenient amount
abc0: 20 6f 66 20 64 65 74 61 69 6c 2c 20 69 74 20 6d   of detail, it m
abd0: 61 79 20 61 6c 73 6f 20 62 65 20 68 65 6c 70 66  ay also be helpf
abe0: 75 6c 0a 77 68 65 6e 20 64 69 61 67 6e 6f 73 69  ul.when diagnosi
abf0: 6e 67 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70  ng performance p
ac00: 72 6f 62 6c 65 6d 73 20 6f 72 20 61 6e 61 6c 79  roblems or analy
ac10: 7a 69 6e 67 20 62 65 6e 63 68 6d 61 72 6b 20 72  zing benchmark r
ac20: 65 73 75 6c 74 73 2e 0a 0a 3c 68 33 20 69 64 3d  esults...<h3 id=
ac30: 61 72 63 68 69 74 65 63 74 75 72 61 6c 5f 6f 76  architectural_ov
ac40: 65 72 76 69 65 77 3e 36 2e 32 2e 31 2e 20 41 72  erview>6.2.1. Ar
ac50: 63 68 69 74 65 63 74 75 72 61 6c 20 4f 76 65 72  chitectural Over
ac60: 76 69 65 77 20 3c 2f 68 33 3e 0a 0a 3c 70 3e 20  view </h3>..<p> 
ac70: 54 68 65 20 4c 53 4d 20 6c 69 62 72 61 72 79 20  The LSM library 
ac80: 69 6d 70 6c 65 6d 65 6e 74 73 20 74 77 6f 20 73  implements two s
ac90: 65 70 61 72 61 74 65 20 64 61 74 61 20 73 74 72  eparate data str
aca0: 75 63 74 75 72 65 73 20 74 68 61 74 20 61 72 65  uctures that are
acb0: 20 75 73 65 64 20 0a 74 6f 67 65 74 68 65 72 20   used .together 
acc0: 74 6f 20 73 74 6f 72 65 20 75 73 65 72 20 64 61  to store user da
acd0: 74 61 2e 20 57 68 65 6e 20 74 68 65 20 64 61 74  ta. When the dat
ace0: 61 62 61 73 65 20 69 73 20 71 75 65 72 69 65 64  abase is queried
acf0: 2c 20 74 68 65 20 6c 69 62 72 61 72 79 20 0a 61  , the library .a
ad00: 63 74 75 61 6c 6c 79 20 72 75 6e 73 20 70 61 72  ctually runs par
ad10: 61 6c 6c 65 6c 20 71 75 65 72 69 65 73 20 6f 6e  allel queries on
ad20: 20 62 6f 74 68 20 6f 66 20 74 68 65 73 65 20 64   both of these d
ad30: 61 74 61 20 73 74 6f 72 65 73 20 61 6e 64 20 6d  ata stores and m
ad40: 65 72 67 65 73 20 74 68 65 0a 72 65 73 75 6c 74  erges the.result
ad50: 73 20 74 6f 67 65 74 68 65 72 20 74 6f 20 72 65  s together to re
ad60: 74 75 72 6e 20 74 6f 20 74 68 65 20 75 73 65 72  turn to the user
ad70: 2e 20 54 68 65 20 64 61 74 61 20 73 74 72 75 63  . The data struc
ad80: 74 75 72 65 73 20 61 72 65 3a 0a 0a 3c 75 6c 3e  tures are:..<ul>
ad90: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 3c 62 3e 69  .  <li> The <b>i
ada0: 6e 2d 6d 65 6d 6f 72 79 20 74 72 65 65 3c 2f 62  n-memory tree</b
adb0: 3e 2e 20 54 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  >. The in-memory
adc0: 20 74 72 65 65 20 69 73 20 61 6e 20 61 70 70 65   tree is an appe
add0: 6e 64 2d 6f 6e 6c 79 20 62 2d 74 72 65 65 0a 20  nd-only b-tree. 
ade0: 20 20 20 20 20 20 76 61 72 69 61 6e 74 20 64 65        variant de
adf0: 73 69 67 6e 65 64 20 74 6f 20 62 65 20 73 74 6f  signed to be sto
ae00: 72 65 64 20 65 6e 74 69 72 65 6c 79 20 69 6e 20  red entirely in 
ae10: 6d 61 69 6e 2d 6d 65 6d 6f 72 79 20 28 69 2e 65  main-memory (i.e
ae20: 2e 20 6e 6f 74 20 0a 20 20 20 20 20 20 20 77 72  . not .       wr
ae30: 69 74 74 65 6e 20 6f 75 74 20 74 6f 20 64 69 73  itten out to dis
ae40: 6b 29 2e 20 54 68 65 20 6c 69 62 72 61 72 79 20  k). The library 
ae50: 73 74 72 69 76 65 73 20 74 6f 20 6c 69 6d 69 74  strives to limit
ae60: 20 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20   the total size 
ae70: 6f 66 20 0a 20 20 20 20 20 20 20 74 68 65 20 69  of .       the i
ae80: 6e 2d 6d 65 6d 6f 72 79 20 74 72 65 65 20 28 62  n-memory tree (b
ae90: 79 20 64 65 66 61 75 6c 74 20 74 6f 20 31 4d 42  y default to 1MB
aea0: 20 69 6e 20 74 6f 74 61 6c 29 2e 0a 0a 20 20 20   in total)...   
aeb0: 20 3c 70 3e 41 74 20 61 6e 79 20 6f 6e 65 20 74   <p>At any one t
aec0: 69 6d 65 2c 20 74 68 65 72 65 20 6d 61 79 20 61  ime, there may a
aed0: 63 74 75 61 6c 6c 79 20 62 65 20 74 77 6f 20 69  ctually be two i
aee0: 6e 2d 6d 65 6d 6f 72 79 20 74 72 65 65 20 73 74  n-memory tree st
aef0: 72 75 63 74 75 72 65 73 0a 20 20 20 20 20 20 20  ructures.       
af00: 70 72 65 73 65 6e 74 20 69 6e 20 6d 65 6d 6f 72  present in memor
af10: 79 2e 20 4f 6e 65 20 69 6d 6d 75 74 61 62 6c 65  y. One immutable
af20: 20 74 72 65 65 20 6d 61 72 6b 65 64 20 61 73 20   tree marked as 
af30: 22 6f 6c 64 22 20 77 61 69 74 69 6e 67 20 74 6f  "old" waiting to
af40: 20 62 65 0a 20 20 20 20 20 20 20 77 72 69 74 74   be.       writt
af50: 65 6e 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61  en into the data
af60: 62 61 73 65 20 66 69 6c 65 20 28 73 65 65 20 62  base file (see b
af70: 65 6c 6f 77 29 20 61 6e 64 20 6f 6e 65 20 22 6c  elow) and one "l
af80: 69 76 65 22 20 74 72 65 65 20 74 6f 20 0a 20 20  ive" tree to .  
af90: 20 20 20 20 20 77 68 69 63 68 20 6e 65 77 20 64       which new d
afa0: 61 74 61 20 6d 61 79 20 62 65 20 61 70 70 65 6e  ata may be appen
afb0: 64 65 64 2e 0a 0a 20 20 3c 6c 69 3e 20 3c 70 3e  ded...  <li> <p>
afc0: 54 68 65 20 3c 62 3e 6c 6f 67 2d 73 74 72 75 63  The <b>log-struc
afd0: 74 75 72 65 64 2d 6d 65 72 67 65 20 74 72 65 65  tured-merge tree
afe0: 3c 2f 62 3e 20 73 74 72 75 63 74 75 72 65 20 66  </b> structure f
aff0: 6f 72 20 77 68 69 63 68 20 4c 53 4d 20 69 73 20  or which LSM is 
b000: 0a 20 20 20 20 20 20 20 6e 61 6d 65 64 2e 20 54  .       named. T
b010: 68 69 73 20 64 61 74 61 20 73 74 72 75 63 74 75  his data structu
b020: 72 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 74  re is used to st
b030: 6f 72 65 20 64 61 74 61 20 77 69 74 68 69 6e 20  ore data within 
b040: 74 68 65 20 64 61 74 61 62 61 73 65 20 0a 20 20  the database .  
b050: 20 20 20 20 20 66 69 6c 65 20 6f 6e 20 64 69 73       file on dis
b060: 6b 2e 20 20 0a 0a 20 20 20 20 20 20 20 3c 70 3e  k.  ..       <p>
b070: 54 68 65 20 6c 6f 67 2d 73 74 72 75 63 74 75 72  The log-structur
b080: 65 64 2d 6d 65 72 67 65 20 74 72 65 65 20 69 73  ed-merge tree is
b090: 20 6d 61 64 65 20 75 70 20 6f 66 20 61 20 73 65   made up of a se
b0a0: 72 69 65 73 20 6f 66 20 22 73 65 67 6d 65 6e 74  ries of "segment
b0b0: 73 22 2e 0a 20 20 20 20 20 20 20 45 61 63 68 20  s"..       Each 
b0c0: 73 65 67 6d 65 6e 74 20 69 73 20 61 6e 20 69 6d  segment is an im
b0d0: 6d 75 74 61 62 6c 65 20 74 72 65 65 20 73 74 72  mutable tree str
b0e0: 75 63 74 75 72 65 20 73 74 6f 72 65 64 20 28 6d  ucture stored (m
b0f0: 6f 72 65 20 6f 72 20 6c 65 73 73 29 0a 20 20 20  ore or less).   
b100: 20 20 20 20 63 6f 6e 74 69 67 75 6f 75 73 6c 79      contiguously
b110: 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61   within the data
b120: 62 61 73 65 20 66 69 6c 65 2e 20 57 68 65 6e 20  base file. When 
b130: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
b140: 71 75 65 72 69 65 64 2c 20 74 68 65 0a 20 20 20  queried, the.   
b150: 20 20 20 20 6c 69 62 72 61 72 79 20 72 75 6e 73      library runs
b160: 20 70 61 72 61 6c 6c 65 6c 20 71 75 65 72 69 65   parallel querie
b170: 73 20 6f 6e 20 65 61 63 68 20 6f 66 20 74 68 65  s on each of the
b180: 20 73 65 67 6d 65 6e 74 73 20 69 6e 20 74 68 65   segments in the
b190: 20 64 61 74 61 62 61 73 65 0a 20 20 20 20 20 20   database.      
b1a0: 20 61 6e 64 20 6d 65 72 67 65 73 20 74 68 65 20   and merges the 
b1b0: 72 65 73 75 6c 74 73 20 74 6f 20 72 65 74 75 72  results to retur
b1c0: 6e 20 74 6f 20 74 68 65 20 75 73 65 72 2e 0a 0a  n to the user...
b1d0: 20 20 20 20 20 20 20 3c 70 3e 54 68 65 20 6f 6e         <p>The on
b1e0: 6c 79 20 77 61 79 20 74 6f 20 69 6e 73 65 72 74  ly way to insert
b1f0: 20 6e 65 77 20 64 61 74 61 20 74 6f 20 74 68 65   new data to the
b200: 20 64 61 74 61 62 61 73 65 20 69 73 20 74 6f 20   database is to 
b210: 61 64 64 20 61 20 6e 65 77 20 0a 20 20 20 20 20  add a new .     
b220: 20 20 73 65 67 6d 65 6e 74 2e 20 49 6e 20 6f 72    segment. In or
b230: 64 65 72 20 74 6f 20 70 72 65 76 65 6e 74 20 74  der to prevent t
b240: 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 65 67  he number of seg
b250: 6d 65 6e 74 73 20 66 72 6f 6d 20 67 72 6f 77 69  ments from growi
b260: 6e 67 20 74 6f 6f 0a 20 20 20 20 20 20 20 6c 61  ng too.       la
b270: 72 67 65 2c 20 74 77 6f 20 6f 72 20 6d 6f 72 65  rge, two or more
b280: 20 65 78 69 73 74 69 6e 67 20 73 65 67 6d 65 6e   existing segmen
b290: 74 73 20 6d 61 79 20 62 65 20 6d 65 72 67 65 64  ts may be merged
b2a0: 20 74 6f 67 65 74 68 65 72 20 69 6e 74 6f 20 61   together into a
b2b0: 0a 20 20 20 20 20 20 20 73 69 6e 67 6c 65 20 6c  .       single l
b2c0: 61 72 67 65 72 20 73 65 67 6d 65 6e 74 20 61 74  arger segment at
b2d0: 20 61 6e 79 20 70 6f 69 6e 74 2e 20 44 65 6c 65   any point. Dele
b2e0: 74 69 6e 67 20 65 78 69 73 74 69 6e 67 20 6b 65  ting existing ke
b2f0: 79 2d 76 61 6c 75 65 20 70 61 69 72 73 0a 20 20  y-value pairs.  
b300: 20 20 20 20 20 69 73 20 61 63 63 6f 6d 70 6c 69       is accompli
b310: 73 68 65 64 20 62 79 20 69 6e 73 65 72 74 69 6e  shed by insertin
b320: 67 20 22 64 65 6c 65 74 65 2d 6b 65 79 73 22 20  g "delete-keys" 
b330: 69 6e 74 6f 20 74 68 65 20 6e 65 77 20 73 65 67  into the new seg
b340: 6d 65 6e 74 2e 0a 0a 20 20 20 20 20 20 20 3c 70  ment...       <p
b350: 3e 54 68 65 20 6c 6f 67 2d 73 74 72 75 63 74 75  >The log-structu
b360: 72 65 64 2d 6d 65 72 67 65 20 74 72 65 65 20 73  red-merge tree s
b370: 74 72 75 63 74 75 72 65 20 69 73 20 64 65 73 63  tructure is desc
b380: 72 69 62 65 64 20 69 6e 20 6d 6f 72 65 20 64 65  ribed in more de
b390: 74 61 69 6c 20 0a 20 20 20 20 20 20 20 3c 69 3e  tail .       <i>
b3a0: 6c 69 6e 6b 20 74 6f 20 6c 73 6d 2e 77 69 6b 69  link to lsm.wiki
b3b0: 20 73 65 63 74 69 6f 6e 20 68 65 72 65 2e 3c 2f   section here.</
b3c0: 69 3e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 20 57 68  i>.</ul>..<p> Wh
b3d0: 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 63 6c  en a database cl
b3e0: 69 65 6e 74 20 77 72 69 74 65 73 20 61 20 74 72  ient writes a tr
b3f0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 74 68 65  ansaction to the
b400: 20 64 61 74 61 62 61 73 65 2c 20 74 68 65 20 6e   database, the n
b410: 65 77 0a 64 61 74 61 20 69 73 20 69 6e 73 65 72  ew.data is inser
b420: 74 65 64 20 69 6e 74 6f 20 74 68 65 20 22 6c 69  ted into the "li
b430: 76 65 22 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72  ve" in-memory tr
b440: 65 65 20 73 74 72 75 63 74 75 72 65 2e 20 41 74  ee structure. At
b450: 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2c 20   the same time, 
b460: 0a 74 68 65 20 6e 65 77 20 64 61 74 61 20 69 73  .the new data is
b470: 20 61 6c 73 6f 20 61 70 70 65 6e 64 65 64 20 74   also appended t
b480: 6f 20 74 68 65 20 6c 6f 67 20 66 69 6c 65 20 6f  o the log file o
b490: 6e 20 64 69 73 6b 2e 20 54 68 65 20 70 75 72 70  n disk. The purp
b4a0: 6f 73 65 20 6f 66 20 74 68 65 20 6c 6f 67 0a 66  ose of the log.f
b4b0: 69 6c 65 20 69 73 20 74 6f 20 70 72 6f 76 69 64  ile is to provid
b4c0: 65 20 61 20 70 65 72 73 69 73 74 65 6e 74 20 62  e a persistent b
b4d0: 61 63 6b 75 70 20 6f 66 20 61 6e 79 20 64 61 74  ackup of any dat
b4e0: 61 20 74 68 61 74 20 74 68 65 20 73 79 73 74 65  a that the syste
b4f0: 6d 20 64 6f 65 73 20 6e 6f 74 0a 63 6f 6e 73 69  m does not.consi
b500: 64 65 72 20 74 6f 20 68 61 76 65 20 62 65 65 6e  der to have been
b510: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 64 20 28   safely stored (
b520: 73 65 65 20 62 65 6c 6f 77 29 20 69 6e 20 74 68  see below) in th
b530: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
b540: 20 49 66 20 61 0a 63 72 61 73 68 20 6f 72 20 70   If a.crash or p
b550: 6f 77 65 72 20 66 61 69 6c 75 72 65 20 6f 63 63  ower failure occ
b560: 75 72 73 2c 20 74 68 69 73 20 64 61 74 61 20 69  urs, this data i
b570: 73 20 72 65 63 6f 76 65 72 65 64 20 62 79 20 72  s recovered by r
b580: 65 61 64 69 6e 67 20 74 68 65 20 6c 6f 67 20 0a  eading the log .
b590: 66 69 6c 65 2e 0a 20 0a 3c 70 3e 20 4f 6e 63 65  file.. .<p> Once
b5a0: 20 73 75 66 66 69 63 69 65 6e 74 20 64 61 74 61   sufficient data
b5b0: 20 68 61 73 20 61 63 63 75 6d 75 6c 61 74 65 64   has accumulated
b5c0: 20 77 69 74 68 69 6e 20 74 68 65 20 22 6c 69 76   within the "liv
b5d0: 65 22 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72 65  e" in-memory tre
b5e0: 65 2c 0a 69 74 20 69 73 20 6d 61 72 6b 65 64 20  e,.it is marked 
b5f0: 61 73 20 22 6f 6c 64 22 20 61 6e 64 20 61 20 6e  as "old" and a n
b600: 65 77 20 6c 69 76 65 20 74 72 65 65 20 63 72 65  ew live tree cre
b610: 61 74 65 64 2e 20 41 74 20 61 6e 79 20 70 6f 69  ated. At any poi
b620: 6e 74 20 74 68 65 72 65 61 66 74 65 72 2c 0a 74  nt thereafter,.t
b630: 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20 74  he contents of t
b640: 68 65 20 6f 6c 64 20 69 6e 2d 6d 65 6d 6f 72 79  he old in-memory
b650: 20 74 72 65 65 20 6d 61 79 20 62 65 20 75 73 65   tree may be use
b660: 64 20 74 6f 20 70 6f 70 75 6c 61 74 65 20 61 20  d to populate a 
b670: 6e 65 77 20 73 65 67 6d 65 6e 74 0a 77 69 74 68  new segment.with
b680: 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  in the database 
b690: 66 69 6c 65 20 61 6e 64 20 74 68 65 6e 20 64 69  file and then di
b6a0: 73 63 61 72 64 65 64 2e 20 57 68 65 6e 20 74 68  scarded. When th
b6b0: 69 73 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20  is happens, the 
b6c0: 6f 6c 64 0a 69 6e 2d 6d 65 6d 6f 72 79 20 74 72  old.in-memory tr
b6d0: 65 65 20 69 73 20 73 61 69 64 20 74 6f 20 68 61  ee is said to ha
b6e0: 76 65 20 62 65 65 6e 20 22 66 6c 75 73 68 65 64  ve been "flushed
b6f0: 20 74 6f 20 64 69 73 6b 22 2e 20 49 66 20 74 68   to disk". If th
b700: 65 72 65 20 69 73 20 61 6c 72 65 61 64 79 20 61  ere is already a
b710: 6e 0a 6f 6c 64 20 69 6e 2d 6d 65 6d 6f 72 79 20  n.old in-memory 
b720: 74 72 65 65 20 77 68 65 6e 20 74 68 65 20 6c 69  tree when the li
b730: 76 65 20 74 72 65 65 20 69 73 20 64 65 65 6d 65  ve tree is deeme
b740: 64 20 74 6f 20 68 61 76 65 20 61 63 63 75 6d 75  d to have accumu
b750: 6c 61 74 65 64 20 65 6e 6f 75 67 68 20 64 61 74  lated enough dat
b760: 61 0a 74 6f 20 69 74 73 65 6c 66 20 62 65 63 6f  a.to itself beco
b770: 6d 65 20 61 6e 20 6f 6c 64 20 74 72 65 65 2c 20  me an old tree, 
b780: 74 68 65 20 65 78 69 73 74 69 6e 67 20 6f 6c 64  the existing old
b790: 20 74 72 65 65 20 6d 75 73 74 20 66 69 72 73 74   tree must first
b7a0: 20 62 65 20 66 6c 75 73 68 65 64 20 74 6f 0a 64   be flushed to.d
b7b0: 69 73 6b 2e 0a 0a 3c 70 3e 20 54 68 65 20 73 65  isk...<p> The se
b7c0: 74 20 6f 66 20 73 65 67 6d 65 6e 74 73 20 74 68  t of segments th
b7d0: 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65 20 6c  at make up the l
b7e0: 6f 67 2d 73 74 72 75 63 74 75 72 65 64 2d 6d 65  og-structured-me
b7f0: 72 67 65 20 74 72 65 65 20 61 74 20 61 6e 79 20  rge tree at any 
b800: 74 69 6d 65 0a 61 6e 64 20 74 68 65 20 6f 72 64  time.and the ord
b810: 65 72 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  er in which they
b820: 20 73 68 6f 75 6c 64 20 62 65 20 71 75 65 72 69   should be queri
b830: 65 64 20 69 73 20 74 65 72 6d 65 64 20 61 20 22  ed is termed a "
b840: 73 6e 61 70 73 68 6f 74 22 2e 20 20 54 68 65 0a  snapshot".  The.
b850: 68 65 61 64 65 72 20 6f 66 20 74 68 65 20 64 61  header of the da
b860: 74 61 62 61 73 65 20 66 69 6c 65 20 63 6f 6e 74  tabase file cont
b870: 61 69 6e 73 20 61 20 73 6e 61 70 73 68 6f 74 2e  ains a snapshot.
b880: 20 41 20 73 6e 61 70 73 68 6f 74 20 69 73 20 61   A snapshot is a
b890: 6c 73 6f 20 73 74 6f 72 65 64 20 69 6e 0a 6d 61  lso stored in.ma
b8a0: 69 6e 20 6d 65 6d 6f 72 79 2e 20 57 68 65 6e 20  in memory. When 
b8b0: 73 65 74 20 6f 66 20 73 65 67 6d 65 6e 74 73 20  set of segments 
b8c0: 74 68 61 74 20 6d 61 6b 65 20 75 70 20 74 68 65  that make up the
b8d0: 20 6c 6f 67 2d 73 74 72 75 63 74 75 72 65 64 2d   log-structured-
b8e0: 6d 65 72 67 65 20 74 72 65 65 20 0a 69 73 20 6d  merge tree .is m
b8f0: 6f 64 69 66 69 65 64 2c 20 65 69 74 68 65 72 20  odified, either 
b900: 62 79 20 66 6c 75 73 68 69 6e 67 20 61 6e 20 6f  by flushing an o
b910: 6c 64 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72 65  ld in-memory tre
b920: 65 20 74 6f 20 64 69 73 6b 20 6f 72 20 62 79 20  e to disk or by 
b930: 6d 65 72 67 69 6e 67 20 0a 74 77 6f 20 6f 72 20  merging .two or 
b940: 6d 6f 72 65 20 65 78 69 73 74 69 6e 67 20 73 65  more existing se
b950: 67 6d 65 6e 74 73 2c 20 74 68 65 20 69 6e 2d 6d  gments, the in-m
b960: 65 6d 6f 72 79 20 73 6e 61 70 73 68 6f 74 20 69  emory snapshot i
b970: 73 20 75 70 64 61 74 65 64 20 69 6d 6d 65 64 69  s updated immedi
b980: 61 74 65 6c 79 2e 20 0a 54 68 69 73 20 69 73 20  ately. .This is 
b990: 74 68 65 20 73 6e 61 70 73 68 6f 74 20 74 68 61  the snapshot tha
b9a0: 74 20 64 61 74 61 62 61 73 65 20 63 6c 69 65 6e  t database clien
b9b0: 74 73 20 75 73 65 20 77 68 65 6e 20 71 75 65 72  ts use when quer
b9c0: 79 69 6e 67 20 6f 72 20 6f 74 68 65 72 77 69 73  ying or otherwis
b9d0: 65 0a 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 74  e.operating on t
b9e0: 68 65 20 64 61 74 61 62 61 73 65 2e 0a 0a 3c 70  he database...<p
b9f0: 3e 20 41 74 20 61 6e 79 20 70 6f 69 6e 74 20 61  > At any point a
ba00: 66 74 65 72 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  fter the in-memo
ba10: 72 79 20 73 6e 61 70 73 68 6f 74 20 68 61 73 20  ry snapshot has 
ba20: 62 65 65 6e 20 75 70 64 61 74 65 64 2c 20 74 68  been updated, th
ba30: 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 73 6e 61 70  e in-memory.snap
ba40: 73 68 6f 74 20 6d 61 79 20 62 65 20 77 72 69 74  shot may be writ
ba50: 74 65 6e 20 69 6e 74 6f 20 74 68 65 20 64 61 74  ten into the dat
ba60: 61 62 61 73 65 20 66 69 6c 65 20 68 65 61 64 65  abase file heade
ba70: 72 2e 20 54 68 69 73 20 69 73 20 6b 6e 6f 77 6e  r. This is known
ba80: 20 61 73 0a 22 63 68 65 63 6b 70 6f 69 6e 74 69   as."checkpointi
ba90: 6e 67 22 20 74 68 65 20 64 61 74 61 62 61 73 65  ng" the database
baa0: 2e 20 44 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  . Depending on t
bab0: 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
bac0: 0a 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e  .<a href=lsmapi.
bad0: 77 69 6b 69 23 4c 53 4d 5f 43 4f 4e 46 49 47 5f  wiki#LSM_CONFIG_
bae0: 53 41 46 45 54 59 3e 4c 53 4d 5f 43 4f 4e 46 49  SAFETY>LSM_CONFI
baf0: 47 5f 53 41 46 45 54 59 3c 2f 61 3e 20 70 61 72  G_SAFETY</a> par
bb00: 61 6d 65 74 65 72 2c 20 69 74 20 6d 61 79 0a 62  ameter, it may.b
bb10: 65 20 6e 65 63 65 73 73 61 72 79 20 74 6f 20 65  e necessary to e
bb20: 6e 73 75 72 65 20 74 68 61 74 20 61 6c 6c 20 73  nsure that all s
bb30: 65 67 6d 65 6e 74 73 20 72 65 66 65 72 65 6e 63  egments referenc
bb40: 65 64 20 62 79 20 74 68 65 20 73 6e 61 70 73 68  ed by the snapsh
bb50: 6f 74 20 68 61 76 65 20 62 65 65 6e 0a 73 79 6e  ot have been.syn
bb60: 63 65 64 20 74 6f 20 64 69 73 6b 20 28 73 61 66  ced to disk (saf
bb70: 65 6c 79 20 73 74 6f 72 65 64 20 6f 6e 20 74 68  ely stored on th
bb80: 65 20 70 65 72 73 69 73 74 65 6e 74 20 6d 65 64  e persistent med
bb90: 69 61 20 73 75 63 68 20 74 68 61 74 20 74 68 65  ia such that the
bba0: 79 20 77 69 6c 6c 20 6e 6f 74 0a 62 65 20 6c 6f  y will not.be lo
bbb0: 73 74 20 69 66 20 61 20 70 6f 77 65 72 20 66 61  st if a power fa
bbc0: 69 6c 75 72 65 20 6f 63 63 75 72 73 29 20 62 65  ilure occurs) be
bbd0: 66 6f 72 65 20 64 6f 69 6e 67 20 73 6f 2e 20 49  fore doing so. I
bbe0: 74 20 69 73 20 6e 6f 74 20 6e 65 63 65 73 73 61  t is not necessa
bbf0: 72 79 20 66 6f 72 0a 65 76 65 72 79 20 76 65 72  ry for.every ver
bc00: 73 69 6f 6e 20 6f 66 20 74 68 65 20 69 6e 2d 6d  sion of the in-m
bc10: 65 6d 6f 72 79 20 73 6e 61 70 73 68 6f 74 20 74  emory snapshot t
bc20: 6f 20 62 65 20 63 68 65 63 6b 70 6f 69 6e 74 65  o be checkpointe
bc30: 64 2e 20 54 68 65 20 69 6e 2d 6d 65 6d 6f 72 79  d. The in-memory
bc40: 0a 73 6e 61 70 73 68 6f 74 20 6d 61 79 20 62 65  .snapshot may be
bc50: 20 6d 6f 64 69 66 69 65 64 20 6d 75 6c 74 69 70   modified multip
bc60: 6c 65 20 74 69 6d 65 73 20 62 65 74 77 65 65 6e  le times between
bc70: 20 63 68 65 63 6b 70 6f 69 6e 74 73 2e 0a 0a 3c   checkpoints...<
bc80: 70 3e 0a 42 65 63 61 75 73 65 20 61 20 63 68 65  p>.Because a che
bc90: 63 6b 70 6f 69 6e 74 65 72 20 70 72 6f 63 65 73  ckpointer proces
bca0: 73 20 69 73 20 6f 66 74 65 6e 20 72 65 71 75 69  s is often requi
bcb0: 72 65 64 20 74 6f 20 73 79 6e 63 20 74 68 65 20  red to sync the 
bcc0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 62 65  database file.be
bcd0: 66 6f 72 65 20 75 70 64 61 74 69 6e 67 20 74 68  fore updating th
bce0: 65 20 64 61 74 61 62 61 73 65 20 68 65 61 64 65  e database heade
bcf0: 72 2c 20 22 63 68 65 63 6b 70 6f 69 6e 74 69 6e  r, "checkpointin
bd00: 67 22 20 6f 66 74 65 6e 20 61 70 70 65 61 72 73  g" often appears
bd10: 20 74 6f 20 62 65 20 74 68 65 0a 63 6f 73 74 6c   to be the.costl
bd20: 69 65 73 74 20 70 61 72 74 20 6f 66 20 74 72 61  iest part of tra
bd30: 6e 73 66 65 72 69 6e 67 20 64 61 74 61 20 74 6f  nsfering data to
bd40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
bd50: 6c 65 2c 20 61 74 20 6c 65 61 73 74 20 69 6e 20  le, at least in 
bd60: 74 65 72 6d 73 20 6f 66 0a 77 61 6c 6c 2d 63 6c  terms of.wall-cl
bd70: 6f 63 6b 20 74 69 6d 65 2e 0a 0a 3c 70 3e 20 52  ock time...<p> R
bd80: 65 67 75 6c 61 72 20 64 61 74 61 62 61 73 65 20  egular database 
bd90: 63 68 65 63 6b 70 6f 69 6e 74 73 20 61 72 65 20  checkpoints are 
bda0: 72 65 71 75 69 72 65 64 20 74 6f 20 65 6e 73 75  required to ensu
bdb0: 72 65 20 74 68 61 74 20 75 6e 75 73 65 64 20 73  re that unused s
bdc0: 70 61 63 65 0a 77 69 74 68 69 6e 20 74 68 65 20  pace.within the 
bdd0: 6c 6f 67 20 66 69 6c 65 20 61 6e 64 20 64 61 74  log file and dat
bde0: 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 20 62  abase file can b
bdf0: 65 20 72 65 75 73 65 64 20 69 6e 20 61 20 74 69  e reused in a ti
be00: 6d 65 6c 79 20 66 61 73 68 69 6f 6e 2e 0a 53 70  mely fashion..Sp
be10: 65 63 69 66 69 63 61 6c 6c 79 3a 0a 0a 3c 75 6c  ecifically:..<ul
be20: 3e 0a 20 20 3c 6c 69 3e 20 3c 70 3e 53 70 61 63  >.  <li> <p>Spac
be30: 65 20 77 69 74 68 69 6e 20 74 68 65 20 6c 6f 67  e within the log
be40: 20 66 69 6c 65 20 63 61 6e 6e 6f 74 20 62 65 20   file cannot be 
be50: 72 65 63 79 63 6c 65 64 20 75 6e 74 69 6c 20 74  recycled until t
be60: 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
be70: 0a 20 20 20 20 20 20 20 64 61 74 61 20 68 61 73  .       data has
be80: 20 62 65 65 6e 20 77 72 69 74 74 65 6e 20 69 6e   been written in
be90: 74 6f 20 61 20 64 61 74 61 62 61 73 65 20 73 65  to a database se
bea0: 67 6d 65 6e 74 20 61 6e 64 20 61 20 63 68 65 63  gment and a chec
beb0: 6b 70 6f 69 6e 74 20 0a 20 20 20 20 20 20 20 70  kpoint .       p
bec0: 65 72 66 6f 72 6d 65 64 2e 0a 0a 20 20 3c 6c 69  erformed...  <li
bed0: 3e 20 3c 70 3e 57 68 65 6e 20 74 77 6f 20 6f 72  > <p>When two or
bee0: 20 6d 6f 72 65 20 65 78 69 73 74 69 6e 67 20 73   more existing s
bef0: 65 67 6d 65 6e 74 73 20 61 72 65 20 6d 65 72 67  egments are merg
bf00: 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 64 61  ed within the da
bf10: 74 61 62 61 73 65 0a 20 20 20 20 20 20 20 66 69  tabase.       fi
bf20: 6c 65 2c 20 64 61 74 61 62 61 73 65 20 63 6c 69  le, database cli
bf30: 65 6e 74 73 20 6d 61 79 20 73 74 61 72 74 20 75  ents may start u
bf40: 73 69 6e 67 20 74 68 65 20 6e 65 77 2c 20 6c 61  sing the new, la
bf50: 72 67 65 72 2c 20 73 65 67 6d 65 6e 74 0a 20 20  rger, segment.  
bf60: 20 20 20 20 20 69 6d 6d 65 64 69 61 74 65 6c 79       immediately
bf70: 2e 20 20 48 6f 77 65 76 65 72 20 74 68 65 20 73  .  However the s
bf80: 70 61 63 65 20 6f 63 63 75 70 69 65 64 20 62 79  pace occupied by
bf90: 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 65   the original se
bfa0: 67 6d 65 6e 74 73 20 6d 61 79 0a 20 20 20 20 20  gments may.     
bfb0: 20 20 6e 6f 74 20 62 65 20 72 65 75 73 65 64 20    not be reused 
bfc0: 75 6e 74 69 6c 20 61 66 74 65 72 20 61 20 73 6e  until after a sn
bfd0: 61 70 73 68 6f 74 20 74 68 61 74 20 72 65 66 65  apshot that refe
bfe0: 72 73 20 74 6f 20 74 68 65 20 6e 65 77 20 73 65  rs to the new se
bff0: 67 6d 65 6e 74 2c 20 61 6e 64 0a 20 20 20 20 20  gment, and.     
c000: 20 20 6e 6f 74 20 74 68 65 20 6f 6c 64 20 6f 6e    not the old on
c010: 65 73 2c 20 68 61 73 20 62 65 65 6e 20 63 68 65  es, has been che
c020: 63 6b 70 6f 69 6e 74 65 64 2e 0a 3c 2f 75 6c 3e  ckpointed..</ul>
c030: 0a 0a 3c 70 3e 49 6e 20 6f 74 68 65 72 20 77 6f  ..<p>In other wo
c040: 72 64 73 2c 20 77 69 74 68 6f 75 74 20 63 68 65  rds, without che
c050: 63 6b 70 6f 69 6e 74 73 20 74 68 65 20 73 79 73  ckpoints the sys
c060: 74 65 6d 20 77 69 6c 6c 20 66 75 6e 63 74 69 6f  tem will functio
c070: 6e 2c 20 62 75 74 20 62 6f 74 68 20 74 68 65 0a  n, but both the.
c080: 6c 6f 67 20 61 6e 64 20 64 61 74 61 62 61 73 65  log and database
c090: 20 66 69 6c 65 73 20 77 69 6c 6c 20 67 72 6f 77   files will grow
c0a0: 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 20 61 73   indefinitely as
c0b0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
c0c0: 20 6d 6f 64 69 66 69 65 64 20 0a 28 65 76 65 6e   modified .(even
c0d0: 20 69 66 20 74 68 65 20 73 69 7a 65 20 6f 66 20   if the size of 
c0e0: 74 68 65 20 64 61 74 61 73 65 74 20 72 65 6d 61  the dataset rema
c0f0: 69 6e 73 20 63 6f 6e 73 74 61 6e 74 29 2e 20 41  ins constant). A
c100: 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20  dditionally, if 
c110: 61 20 63 72 61 73 68 0a 6f 72 20 70 6f 77 65 72  a crash.or power
c120: 20 66 61 69 6c 75 72 65 20 6f 63 63 75 72 73 2c   failure occurs,
c130: 20 74 68 65 20 6e 65 78 74 20 63 6c 69 65 6e 74   the next client
c140: 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
c150: 61 62 61 73 65 20 66 69 6c 65 20 68 61 73 20 74  abase file has t
c160: 6f 0a 70 72 6f 63 65 73 73 20 61 6c 6c 20 64 61  o.process all da
c170: 74 61 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68  ta written to th
c180: 65 20 6c 6f 67 20 66 69 6c 65 20 73 69 6e 63 65  e log file since
c190: 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
c1a0: 20 63 68 65 63 6b 70 6f 69 6e 74 2e 20 49 66 0a   checkpoint. If.
c1b0: 63 68 65 63 6b 70 6f 69 6e 74 73 20 61 72 65 20  checkpoints are 
c1c0: 70 65 72 66 6f 72 6d 65 64 20 69 6e 66 72 65 71  performed infreq
c1d0: 75 65 6e 74 6c 79 2c 20 74 68 69 73 20 63 61 6e  uently, this can
c1e0: 20 62 65 20 61 20 74 69 6d 65 20 63 6f 6e 73 75   be a time consu
c1f0: 6d 69 6e 67 20 65 78 65 72 63 69 73 65 2e 0a 0a  ming exercise...
c200: 3c 70 3e 49 6e 20 6f 72 64 65 72 20 74 6f 20 73  <p>In order to s
c210: 61 66 65 6c 79 20 77 72 69 74 65 20 64 61 74 61  afely write data
c220: 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d   into the in-mem
c230: 6f 72 79 20 74 72 65 65 20 28 62 79 20 63 61 6c  ory tree (by cal
c240: 6c 69 6e 67 20 0a 6c 73 6d 5f 69 6e 73 65 72 74  ling .lsm_insert
c250: 2c 20 6c 73 6d 5f 64 65 6c 65 74 65 20 6f 72 20  , lsm_delete or 
c260: 6c 73 6d 5f 64 65 6c 65 74 65 5f 72 61 6e 67 65  lsm_delete_range
c270: 29 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ), the database 
c280: 63 6c 69 65 6e 74 20 6d 75 73 74 20 68 6f 6c 64  client must hold
c290: 0a 74 68 65 20 64 61 74 61 62 61 73 65 20 57 52  .the database WR
c2a0: 49 54 45 52 20 6c 6f 63 6b 2e 20 41 74 20 6d 6f  ITER lock. At mo
c2b0: 73 74 20 6f 6e 65 20 63 6c 69 65 6e 74 20 6d 61  st one client ma
c2c0: 79 20 63 6f 6e 63 75 72 72 65 6e 74 6c 79 20 68  y concurrently h
c2d0: 6f 6c 64 20 74 68 65 20 57 52 49 54 45 52 20 0a  old the WRITER .
c2e0: 6c 6f 63 6b 2e 20 48 6f 6c 64 69 6e 67 20 74 68  lock. Holding th
c2f0: 65 20 57 52 49 54 45 52 20 6c 6f 63 6b 20 69 73  e WRITER lock is
c300: 20 73 79 6e 6f 6e 79 6d 6f 75 73 20 77 69 74 68   synonymous with
c310: 20 68 61 76 69 6e 67 20 61 6e 20 6f 70 65 6e 20   having an open 
c320: 77 72 69 74 65 0a 74 72 61 6e 73 61 63 74 69 6f  write.transactio
c330: 6e 20 2d 20 74 68 65 20 63 6c 69 65 6e 74 20 6f  n - the client o
c340: 62 74 61 69 6e 73 20 74 68 65 20 57 52 49 54 45  btains the WRITE
c350: 52 20 6c 6f 63 6b 20 77 68 65 6e 20 74 68 65 20  R lock when the 
c360: 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 0a  transaction is .
c370: 6f 70 65 6e 65 64 20 61 6e 64 20 72 65 6c 69 6e  opened and relin
c380: 71 75 69 73 68 65 73 20 69 74 20 77 68 65 6e 20  quishes it when 
c390: 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
c3a0: 69 73 20 63 6c 6f 73 65 64 2e 0a 0a 3c 70 3e 41  is closed...<p>A
c3b0: 73 20 77 65 6c 6c 20 61 73 20 74 68 65 20 57 52  s well as the WR
c3c0: 49 54 45 52 20 6c 6f 63 6b 2c 20 74 68 65 72 65  ITER lock, there
c3d0: 20 61 72 65 20 74 77 6f 20 6f 74 68 65 72 20 6c   are two other l
c3e0: 6f 63 6b 73 20 74 68 61 74 20 6d 61 79 20 62 65  ocks that may be
c3f0: 20 68 65 6c 64 20 62 79 0a 61 74 20 6d 6f 73 74   held by.at most
c400: 20 6f 6e 65 20 63 6c 69 65 6e 74 20 61 74 20 61   one client at a
c410: 6e 79 20 74 69 6d 65 20 2d 20 74 68 65 20 57 4f  ny time - the WO
c420: 52 4b 45 52 20 61 6e 64 20 43 48 45 43 4b 50 4f  RKER and CHECKPO
c430: 49 4e 54 45 52 20 6c 6f 63 6b 73 2e 20 54 68 65  INTER locks. The
c440: 20 72 6f 6c 65 73 0a 6f 66 20 74 68 65 20 74 68   roles.of the th
c450: 72 65 65 20 6c 6f 63 6b 73 20 61 72 65 20 72 6f  ree locks are ro
c460: 75 67 68 6c 79 20 61 73 20 66 6f 6c 6c 6f 77 73  ughly as follows
c470: 3a 0a 0a 3c 74 61 62 6c 65 20 76 61 6c 69 67 6e  :..<table valign
c480: 3d 74 6f 70 3e 0a 3c 74 72 3e 3c 74 64 20 76 61  =top>.<tr><td va
c490: 6c 69 67 6e 3d 74 6f 70 3e 57 52 49 54 45 52 3c  lign=top>WRITER<
c4a0: 74 64 20 73 74 79 6c 65 3d 22 77 69 64 74 68 3a  td style="width:
c4b0: 33 65 78 22 3e 3c 74 64 3e 0a 54 68 65 20 57 52  3ex"><td>.The WR
c4c0: 49 54 45 52 20 6c 6f 63 6b 20 69 73 20 72 65 71  ITER lock is req
c4d0: 75 69 72 65 64 20 74 6f 20 6d 6f 64 69 66 79 20  uired to modify 
c4e0: 74 68 65 20 63 6f 6e 74 65 6e 74 73 20 6f 66 20  the contents of 
c4f0: 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72  the in-memory tr
c500: 65 65 2e 0a 49 6e 63 6c 75 64 69 6e 67 20 6d 61  ee..Including ma
c510: 72 6b 69 6e 67 20 61 6e 20 69 6e 2d 6d 65 6d 6f  rking an in-memo
c520: 72 79 20 74 72 65 65 20 61 73 20 22 6f 6c 64 22  ry tree as "old"
c530: 20 61 6e 64 20 73 74 61 72 74 69 6e 67 20 61 20   and starting a 
c540: 6e 65 77 20 6c 69 76 65 20 74 72 65 65 2e 0a 49  new live tree..I
c550: 74 20 69 73 20 61 6c 73 6f 20 72 65 71 75 69 72  t is also requir
c560: 65 64 20 74 6f 20 77 72 69 74 65 20 74 6f 20 74  ed to write to t
c570: 68 65 20 6c 6f 67 20 66 69 6c 65 2e 0a 0a 3c 74  he log file...<t
c580: 72 3e 3c 74 64 20 76 61 6c 69 67 6e 3d 74 6f 70  r><td valign=top
c590: 3e 57 4f 52 4b 45 52 3c 74 64 3e 3c 74 64 3e 0a  >WORKER<td><td>.
c5a0: 54 68 65 20 57 4f 52 4b 45 52 20 6c 6f 63 6b 20  The WORKER lock 
c5b0: 69 73 20 72 65 71 75 69 72 65 64 20 74 6f 20 77  is required to w
c5c0: 72 69 74 65 20 74 6f 20 73 65 67 6d 65 6e 74 73  rite to segments
c5d0: 20 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61   within the data
c5e0: 62 61 73 65 20 66 69 6c 65 2e 0a 45 69 74 68 65  base file..Eithe
c5f0: 72 20 77 68 65 6e 20 6d 65 72 67 69 6e 67 20 74  r when merging t
c600: 77 6f 20 6f 72 20 6d 6f 72 65 20 65 78 69 73 74  wo or more exist
c610: 69 6e 67 20 73 65 67 6d 65 6e 74 73 20 77 69 74  ing segments wit
c620: 68 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hin the database
c630: 2c 20 6f 72 0a 77 68 65 6e 20 66 6c 75 73 68 69  , or.when flushi
c640: 6e 67 20 61 6e 20 69 6e 2d 6d 65 6d 6f 72 79 20  ng an in-memory 
c650: 74 72 65 65 20 74 6f 20 64 69 73 6b 20 74 6f 20  tree to disk to 
c660: 63 72 65 61 74 65 20 61 20 6e 65 77 20 73 65 67  create a new seg
c670: 6d 65 6e 74 2e 0a 54 68 65 20 57 4f 52 4b 45 52  ment..The WORKER
c680: 20 6c 6f 63 6b 20 69 73 20 61 6c 73 6f 20 72 65   lock is also re
c690: 71 75 69 72 65 64 20 74 6f 20 75 70 64 61 74 65  quired to update
c6a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 6e   the database sn
c6b0: 61 70 73 68 6f 74 20 73 74 6f 72 65 64 20 69 6e  apshot stored in
c6c0: 0a 6d 61 69 6e 20 6d 65 6d 6f 72 79 20 28 75 70  .main memory (up
c6d0: 64 61 74 65 64 20 73 6f 20 74 68 61 74 20 6e 65  dated so that ne
c6e0: 77 20 63 6c 69 65 6e 74 73 20 77 69 6c 6c 20 75  w clients will u
c6f0: 73 65 20 74 68 65 20 6e 65 77 20 73 65 67 6d 65  se the new segme
c700: 6e 74 73 20 74 68 65 20 77 6f 72 6b 65 72 0a 63  nts the worker.c
c710: 72 65 61 74 65 73 29 2e 0a 0a 3c 74 72 3e 3c 74  reates)...<tr><t
c720: 64 20 76 61 6c 69 67 6e 3d 74 6f 70 3e 43 48 45  d valign=top>CHE
c730: 43 4b 50 4f 49 4e 54 45 52 3c 74 64 3e 3c 74 64  CKPOINTER<td><td
c740: 3e 0a 54 68 65 20 43 48 45 43 4b 50 4f 49 4e 54  >.The CHECKPOINT
c750: 45 52 20 6c 6f 63 6b 20 69 73 20 72 65 71 75 69  ER lock is requi
c760: 72 65 64 20 74 6f 20 75 70 64 61 74 65 20 74 68  red to update th
c770: 65 20 73 6e 61 70 73 68 6f 74 20 73 74 6f 72 65  e snapshot store
c780: 64 20 69 6e 20 74 68 65 20 0a 64 61 74 61 62 61  d in the .databa
c790: 73 65 20 66 69 6c 65 20 68 65 61 64 65 72 20 28  se file header (
c7a0: 74 6f 20 63 68 65 63 6b 70 6f 69 6e 74 20 74 68  to checkpoint th
c7b0: 65 20 64 61 74 61 62 61 73 65 29 2e 20 0a 3c 2f  e database). .</
c7c0: 74 61 62 6c 65 3e 0a 0a 3c 70 3e 54 68 65 20 74  table>..<p>The t
c7d0: 61 73 6b 73 20 61 73 73 6f 63 69 61 74 65 64 20  asks associated 
c7e0: 77 69 74 68 20 65 61 63 68 20 6f 66 20 74 68 65  with each of the
c7f0: 20 6c 6f 63 6b 73 20 61 62 6f 76 65 20 6d 61 79   locks above may
c800: 20 62 65 20 70 65 72 66 6f 72 6d 65 64 0a 63 6f   be performed.co
c810: 6e 63 75 72 72 65 6e 74 6c 79 20 62 79 20 6d 75  ncurrently by mu
c820: 6c 74 69 70 6c 65 20 64 61 74 61 62 61 73 65 20  ltiple database 
c830: 63 6f 6e 6e 65 63 74 69 6f 6e 73 2c 20 6c 6f 63  connections, loc
c840: 61 74 65 64 20 65 69 74 68 65 72 20 69 6e 20 74  ated either in t
c850: 68 65 20 73 61 6d 65 0a 61 70 70 6c 69 63 61 74  he same.applicat
c860: 69 6f 6e 20 70 72 6f 63 65 73 73 20 6f 72 20 64  ion process or d
c870: 69 66 66 65 72 65 6e 74 20 70 72 6f 63 65 73 73  ifferent process
c880: 65 73 2e 0a 0a 3c 68 33 20 69 64 3d 61 75 74 6f  es...<h3 id=auto
c890: 6d 61 74 69 63 5f 77 6f 72 6b 5f 61 6e 64 5f 63  matic_work_and_c
c8a0: 68 65 63 6b 70 6f 69 6e 74 5f 73 63 68 65 64 75  heckpoint_schedu
c8b0: 6c 69 6e 67 3e 36 2e 32 2e 32 2e 20 41 75 74 6f  ling>6.2.2. Auto
c8c0: 6d 61 74 69 63 20 57 6f 72 6b 20 61 6e 64 20 43  matic Work and C
c8d0: 68 65 63 6b 70 6f 69 6e 74 20 53 63 68 65 64 75  heckpoint Schedu
c8e0: 6c 69 6e 67 3c 2f 68 33 3e 0a 0a 3c 70 3e 42 79  ling</h3>..<p>By
c8f0: 20 64 65 66 61 75 6c 74 2c 20 64 61 74 61 62 61   default, databa
c900: 73 65 20 22 77 6f 72 6b 22 20 28 74 68 65 20 66  se "work" (the f
c910: 6c 75 73 68 69 6e 67 20 61 6e 64 20 6d 65 72 67  lushing and merg
c920: 69 6e 67 20 6f 66 20 73 65 67 6d 65 6e 74 73 2c  ing of segments,
c930: 20 70 65 72 66 6f 72 6d 65 64 0a 62 79 20 63 6c   performed.by cl
c940: 69 65 6e 74 73 20 68 6f 6c 64 69 6e 67 20 74 68  ients holding th
c950: 65 20 57 4f 52 4b 45 52 20 6c 6f 63 6b 29 20 61  e WORKER lock) a
c960: 6e 64 20 63 68 65 63 6b 70 6f 69 6e 74 69 6e 67  nd checkpointing
c970: 20 61 72 65 20 73 63 68 65 64 75 6c 65 64 20 61   are scheduled a
c980: 6e 64 0a 70 65 72 66 6f 72 6d 65 64 20 61 75 74  nd.performed aut
c990: 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 6f 6d 20  omatically from 
c9a0: 77 69 74 68 69 6e 20 63 61 6c 6c 73 20 74 6f 20  within calls to 
c9b0: 22 77 72 69 74 65 22 20 41 50 49 20 66 75 6e 63  "write" API func
c9c0: 74 69 6f 6e 73 2e 20 54 68 65 20 0a 22 77 72 69  tions. The ."wri
c9d0: 74 65 22 20 66 75 6e 63 74 69 6f 6e 73 20 61 72  te" functions ar
c9e0: 65 3a 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c 69 3e 6c  e:..<ul>.  <li>l
c9f0: 73 6d 5f 69 6e 73 65 72 74 28 29 0a 20 20 3c 6c  sm_insert().  <l
ca00: 69 3e 6c 73 6d 5f 64 65 6c 65 74 65 28 29 0a 20  i>lsm_delete(). 
ca10: 20 3c 6c 69 3e 6c 73 6d 5f 64 65 6c 65 74 65 5f   <li>lsm_delete_
ca20: 72 61 6e 67 65 28 29 0a 20 20 3c 6c 69 3e 6c 73  range().  <li>ls
ca30: 6d 5f 63 6f 6d 6d 69 74 28 29 0a 3c 2f 75 6c 3e  m_commit().</ul>
ca40: 0a 0a 3c 70 3e 49 74 20 69 73 20 65 78 70 65 63  ..<p>It is expec
ca50: 74 65 64 20 74 68 61 74 20 61 75 74 6f 6d 61 74  ted that automat
ca60: 69 63 20 77 6f 72 6b 20 61 6e 64 20 63 68 65 63  ic work and chec
ca70: 6b 70 6f 69 6e 74 20 73 63 68 65 64 75 6c 69 6e  kpoint schedulin
ca80: 67 20 77 69 6c 6c 20 62 65 0a 73 75 69 74 61 62  g will be.suitab
ca90: 6c 65 20 66 6f 72 20 6d 6f 73 74 20 61 70 70 6c  le for most appl
caa0: 69 63 61 74 69 6f 6e 73 2e 20 54 68 65 20 61 64  ications. The ad
cab0: 76 61 6e 74 61 67 65 20 6f 66 20 74 68 69 73 20  vantage of this 
cac0: 6d 6f 64 65 6c 20 69 73 20 74 68 61 74 20 69 74  model is that it
cad0: 20 69 73 0a 73 69 6d 70 6c 65 20 74 6f 20 75 73   is.simple to us
cae0: 65 2e 20 48 6f 77 65 76 65 72 2c 20 61 6e 79 20  e. However, any 
caf0: 63 61 6c 6c 20 74 6f 20 6f 6e 65 20 6f 66 20 74  call to one of t
cb00: 68 65 20 66 75 6e 63 74 69 6f 6e 73 20 6c 69 73  he functions lis
cb10: 74 65 64 20 61 62 6f 76 65 20 6d 61 79 20 62 65  ted above may be
cb20: 0a 63 6f 2d 6f 70 74 65 64 20 62 79 20 74 68 65  .co-opted by the
cb30: 20 73 79 73 74 65 6d 20 74 6f 20 70 65 72 66 6f   system to perfo
cb40: 72 6d 20 64 61 74 61 62 61 73 65 20 77 6f 72 6b  rm database work
cb50: 20 6f 72 20 61 20 63 68 65 63 6b 70 6f 69 6e 74   or a checkpoint
cb60: 2c 20 63 61 75 73 69 6e 67 20 69 74 20 74 6f 0a  , causing it to.
cb70: 72 65 74 75 72 6e 20 6d 6f 72 65 20 73 6c 6f 77  return more slow
cb80: 6c 79 20 74 68 61 6e 20 69 74 20 6f 74 68 65 72  ly than it other
cb90: 77 69 73 65 20 77 6f 75 6c 64 2e 20 49 6e 20 73  wise would. In s
cba0: 6f 6d 65 20 73 69 74 75 61 74 69 6f 6e 73 2c 20  ome situations, 
cbb0: 66 6f 72 20 65 78 61 6d 70 6c 65 0a 77 68 65 6e  for example.when
cbc0: 20 61 20 77 72 69 74 65 72 20 74 68 72 65 61 64   a writer thread
cbd0: 20 69 73 20 61 6c 73 6f 20 72 65 73 70 6f 6e 73   is also respons
cbe0: 69 62 6c 65 20 66 6f 72 20 68 61 6e 64 6c 69 6e  ible for handlin
cbf0: 67 20 75 73 65 72 2d 69 6e 74 65 72 66 61 63 65  g user-interface
cc00: 20 65 76 65 6e 74 73 2c 0a 74 68 69 73 20 6d 61   events,.this ma
cc10: 79 20 62 65 20 75 6e 64 65 73 69 72 61 62 6c 65  y be undesirable
cc20: 2e 0a 0a 3c 70 3e 41 75 74 6f 6d 61 74 69 63 20  ...<p>Automatic 
cc30: 77 6f 72 6b 20 61 6e 64 20 63 68 65 63 6b 70 6f  work and checkpo
cc40: 69 6e 74 20 73 63 68 65 64 75 6c 69 6e 67 20 69  int scheduling i
cc50: 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20  s controlled by 
cc60: 66 6f 75 72 20 69 6e 74 65 67 65 72 0a 70 61 72  four integer.par
cc70: 61 6d 65 74 65 72 73 20 73 65 74 20 6f 72 20 71  ameters set or q
cc80: 75 65 72 69 65 64 20 75 73 69 6e 67 20 74 68 65  ueried using the
cc90: 20 6c 73 6d 5f 63 6f 6e 66 69 67 28 29 20 69 6e   lsm_config() in
cca0: 74 65 72 66 61 63 65 2e 20 54 68 65 20 70 61 72  terface. The par
ccb0: 61 6d 65 74 65 72 73 0a 61 72 65 3a 0a 0a 3c 64  ameters.are:..<d
ccc0: 6c 3e 0a 20 20 3c 64 74 3e 20 4c 53 4d 5f 43 4f  l>.  <dt> LSM_CO
ccd0: 4e 46 49 47 5f 41 55 54 4f 57 4f 52 4b 0a 20 20  NFIG_AUTOWORK.  
cce0: 3c 64 64 3e 20 3c 70 20 73 74 79 6c 65 3d 6d 61  <dd> <p style=ma
ccf0: 72 67 69 6e 2d 74 6f 70 3a 30 3e 0a 20 20 20 20  rgin-top:0>.    
cd00: 20 20 20 54 68 69 73 20 69 73 20 61 20 62 6f 6f     This is a boo
cd10: 6c 65 61 6e 20 70 61 72 61 6d 65 74 65 72 20 28  lean parameter (
cd20: 64 65 66 61 75 6c 74 20 31 29 2e 20 49 66 20 73  default 1). If s
cd30: 65 74 2c 20 61 75 74 6f 2d 77 6f 72 6b 20 6d 6f  et, auto-work mo
cd40: 64 65 20 69 73 0a 20 20 20 20 20 20 20 65 6e 61  de is.       ena
cd50: 62 6c 65 64 20 66 6f 72 20 74 68 65 20 64 61 74  bled for the dat
cd60: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
cd70: 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 69 74 20  . Otherwise, it 
cd80: 69 73 20 6e 6f 74 2e 0a 0a 20 20 3c 64 74 3e 20  is not...  <dt> 
cd90: 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55 54 4f 46  LSM_CONFIG_AUTOF
cda0: 4c 55 53 48 0a 20 20 3c 64 64 3e 20 3c 70 20 73  LUSH.  <dd> <p s
cdb0: 74 79 6c 65 3d 6d 61 72 67 69 6e 2d 74 6f 70 3a  tyle=margin-top:
cdc0: 30 3e 0a 20 20 20 20 20 20 20 41 6e 20 69 6e 74  0>.       An int
cdd0: 65 67 65 72 20 70 61 72 61 6d 65 74 65 72 20 28  eger parameter (
cde0: 64 65 66 61 75 6c 74 20 31 30 34 38 35 37 36 29  default 1048576)
cdf0: 2e 20 49 66 20 74 68 69 73 20 70 61 72 61 6d 65  . If this parame
ce00: 74 65 72 20 69 73 20 73 65 74 0a 20 20 20 20 20  ter is set.     
ce10: 20 20 74 6f 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20    to a non-zero 
ce20: 76 61 6c 75 65 2c 20 74 68 65 6e 20 61 66 74 65  value, then afte
ce30: 72 20 65 61 63 68 20 74 72 61 6e 73 61 63 74 69  r each transacti
ce40: 6f 6e 20 69 73 20 63 6f 6d 6d 69 74 74 65 64 2c  on is committed,
ce50: 20 74 68 65 0a 20 20 20 20 20 20 20 6c 69 62 72   the.       libr
ce60: 61 72 79 20 63 68 65 63 6b 73 20 74 68 65 20 74  ary checks the t
ce70: 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20 74 68 65  otal size of the
ce80: 20 6c 69 76 65 20 69 6e 2d 6d 65 6d 6f 72 79 20   live in-memory 
ce90: 74 72 65 65 2e 20 49 66 20 69 74 20 69 73 0a 20  tree. If it is. 
cea0: 20 20 20 20 20 20 65 71 75 61 6c 20 74 6f 20 6f        equal to o
ceb0: 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
cec0: 68 65 20 63 6f 6e 66 69 67 75 72 65 64 20 76 61  he configured va
ced0: 6c 75 65 20 6f 66 20 74 68 69 73 20 70 61 72 61  lue of this para
cee0: 6d 65 74 65 72 20 69 6e 0a 20 20 20 20 20 20 20  meter in.       
cef0: 62 79 74 65 73 20 61 6e 64 20 74 68 65 72 65 20  bytes and there 
cf00: 69 73 20 6e 6f 20 65 78 69 73 74 69 6e 67 20 6f  is no existing o
cf10: 6c 64 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72 65  ld in-memory tre
cf20: 65 2c 20 74 68 65 6e 20 74 68 65 20 63 75 72 72  e, then the curr
cf30: 65 6e 74 20 0a 20 20 20 20 20 20 20 6c 69 76 65  ent .       live
cf40: 20 74 72 65 65 20 69 73 20 6d 61 72 6b 65 64 20   tree is marked 
cf50: 61 73 20 6f 6c 64 2e 0a 0a 20 20 20 20 20 20 20  as old...       
cf60: 3c 70 3e 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c  <p>Additionally,
cf70: 20 69 66 20 74 68 65 20 4c 53 4d 5f 43 4f 4e 46   if the LSM_CONF
cf80: 49 47 5f 41 55 54 4f 57 4f 52 4b 20 70 61 72 61  IG_AUTOWORK para
cf90: 6d 65 74 65 72 20 69 73 20 73 65 74 2c 20 74 68  meter is set, th
cfa0: 65 20 0a 20 20 20 20 20 20 20 63 6f 6e 74 65 6e  e .       conten
cfb0: 74 73 20 6f 66 20 74 68 65 20 69 6e 2d 6d 65 6d  ts of the in-mem
cfc0: 6f 72 79 20 74 72 65 65 20 61 72 65 20 69 6d 6d  ory tree are imm
cfd0: 65 64 69 61 74 65 6c 79 20 66 6c 75 73 68 65 64  ediately flushed
cfe0: 20 74 6f 20 64 69 73 6b 2e 0a 0a 20 20 3c 64 74   to disk...  <dt
cff0: 3e 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55 54  > LSM_CONFIG_AUT
d000: 4f 4d 45 52 47 45 0a 20 20 3c 64 64 3e 20 3c 70  OMERGE.  <dd> <p
d010: 20 73 74 79 6c 65 3d 6d 61 72 67 69 6e 2d 74 6f   style=margin-to
d020: 70 3a 30 3e 0a 20 20 20 20 20 20 20 54 68 69 73  p:0>.       This
d030: 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
d040: 62 65 20 73 65 74 20 74 6f 20 61 6e 20 69 6e 74  be set to an int
d050: 65 67 65 72 20 76 61 6c 75 65 20 62 65 74 77 65  eger value betwe
d060: 65 6e 20 32 20 61 6e 64 20 38 2c 0a 20 20 20 20  en 2 and 8,.    
d070: 20 20 20 69 6e 63 6c 75 73 69 76 65 2e 20 49 74     inclusive. It
d080: 20 63 6f 6e 74 72 6f 6c 73 20 74 68 65 20 6e 75   controls the nu
d090: 6d 62 65 72 20 6f 66 20 65 78 69 73 74 69 6e 67  mber of existing
d0a0: 20 73 65 67 6d 65 6e 74 73 20 74 68 61 74 20 0a   segments that .
d0b0: 20 20 20 20 20 20 20 61 75 74 6f 2d 77 6f 72 6b         auto-work
d0c0: 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6d 65 72   attempts to mer
d0d0: 67 65 20 74 6f 67 65 74 68 65 72 20 61 74 20 61  ge together at a
d0e0: 20 74 69 6d 65 2e 20 54 68 65 20 64 65 66 61 75   time. The defau
d0f0: 6c 74 20 76 61 6c 75 65 20 69 73 20 34 2e 0a 0a  lt value is 4...
d100: 20 20 3c 64 74 3e 20 4c 53 4d 5f 43 4f 4e 46 49    <dt> LSM_CONFI
d110: 47 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54  G_AUTOCHECKPOINT
d120: 0a 20 20 3c 64 64 3e 20 3c 70 20 73 74 79 6c 65  .  <dd> <p style
d130: 3d 6d 61 72 67 69 6e 2d 74 6f 70 3a 30 3e 0a 20  =margin-top:0>. 
d140: 20 20 20 20 20 20 49 66 20 74 68 69 73 20 70 61        If this pa
d150: 72 61 6d 65 74 65 72 20 69 73 20 73 65 74 20 74  rameter is set t
d160: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 76 61 6c  o an integer val
d170: 75 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  ue greater than 
d180: 30 2c 20 74 68 65 6e 0a 20 20 20 20 20 20 20 61  0, then.       a
d190: 20 63 68 65 63 6b 70 6f 69 6e 74 20 69 73 20 61   checkpoint is a
d1a0: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 61 74 74  utomatically att
d1b0: 65 6d 70 74 65 64 20 61 66 74 65 72 20 74 68 69  empted after thi
d1c0: 73 20 6d 61 6e 79 20 62 79 74 65 73 20 61 72 65  s many bytes are
d1d0: 0a 20 20 20 20 20 20 20 77 72 69 74 74 65 6e 20  .       written 
d1e0: 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73  into the databas
d1f0: 65 20 66 69 6c 65 2e 20 54 68 65 20 64 65 66 61  e file. The defa
d200: 75 6c 74 20 76 61 6c 75 65 20 69 73 20 32 30 39  ult value is 209
d210: 37 31 35 32 2e 0a 3c 2f 64 6c 3e 0a 0a 3c 70 3e  7152..</dl>..<p>
d220: 45 61 63 68 20 73 65 67 6d 65 6e 74 20 69 6e 20  Each segment in 
d230: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
d240: 65 20 69 73 20 61 73 73 69 67 6e 65 64 20 61 6e  e is assigned an
d250: 20 22 61 67 65 22 20 2d 20 61 6e 20 69 6e 74 65   "age" - an inte
d260: 67 65 72 20 7a 65 72 6f 0a 6f 72 20 67 72 65 61  ger zero.or grea
d270: 74 65 72 20 69 6e 64 69 63 61 74 69 6e 67 20 68  ter indicating h
d280: 6f 77 20 6d 61 6e 79 20 74 69 6d 65 73 20 74 68  ow many times th
d290: 65 20 64 61 74 61 20 69 6e 20 74 68 65 20 73 65  e data in the se
d2a0: 67 6d 65 6e 74 20 68 61 73 20 62 65 65 6e 20 6d  gment has been m
d2b0: 65 72 67 65 64 2e 0a 41 20 73 65 67 6d 65 6e 74  erged..A segment
d2c0: 20 63 72 65 61 74 65 64 20 62 79 20 66 6c 75 73   created by flus
d2d0: 68 69 6e 67 20 74 68 65 20 69 6e 2d 6d 65 6d 6f  hing the in-memo
d2e0: 72 79 20 74 72 65 65 20 74 6f 20 64 69 73 6b 20  ry tree to disk 
d2f0: 69 73 20 61 73 73 69 67 6e 65 64 20 61 6e 20 61  is assigned an a
d300: 67 65 0a 6f 66 20 31 2e 20 57 68 65 6e 20 74 77  ge.of 1. When tw
d310: 6f 20 6f 72 20 6d 6f 72 65 20 73 65 67 6d 65 6e  o or more segmen
d320: 74 73 20 77 69 74 68 20 61 67 65 3d 31 20 61 72  ts with age=1 ar
d330: 65 20 6d 65 72 67 65 64 20 74 6f 67 65 74 68 65  e merged togethe
d340: 72 20 74 6f 20 63 72 65 61 74 65 20 61 0a 6c 61  r to create a.la
d350: 72 67 65 72 20 73 65 67 6d 65 6e 74 2c 20 69 74  rger segment, it
d360: 20 69 73 20 61 73 73 69 67 6e 65 64 20 61 6e 20   is assigned an 
d370: 61 67 65 20 6f 66 20 32 2e 20 41 6e 64 20 73 6f  age of 2. And so
d380: 20 6f 6e 2e 0a 0a 3c 70 3e 49 66 20 61 75 74 6f   on...<p>If auto
d390: 2d 77 6f 72 6b 20 69 73 20 65 6e 61 62 6c 65 64  -work is enabled
d3a0: 2c 20 74 68 65 20 6c 69 62 72 61 72 79 20 70 65  , the library pe
d3b0: 72 69 6f 64 69 63 61 6c 6c 79 20 63 68 65 63 6b  riodically check
d3c0: 73 20 74 68 65 20 73 74 61 74 65 20 6f 66 20 74  s the state of t
d3d0: 68 65 0a 64 61 74 61 62 61 73 65 20 66 69 6c 65  he.database file
d3e0: 20 74 6f 20 73 65 65 20 69 66 20 74 68 65 72 65   to see if there
d3f0: 20 65 78 69 73 74 20 4e 20 6f 72 20 6d 6f 72 65   exist N or more
d400: 20 73 65 67 6d 65 6e 74 73 20 77 69 74 68 20 74   segments with t
d410: 68 65 20 73 61 6d 65 20 61 67 65 0a 76 61 6c 75  he same age.valu
d420: 65 20 41 2c 20 77 68 65 72 65 20 4e 20 69 73 20  e A, where N is 
d430: 74 68 65 20 76 61 6c 75 65 20 61 73 73 69 67 6e  the value assign
d440: 65 64 20 74 6f 20 74 68 65 20 4c 53 4d 5f 43 4f  ed to the LSM_CO
d450: 4e 46 49 47 5f 41 55 54 4f 4d 45 52 47 45 20 70  NFIG_AUTOMERGE p
d460: 61 72 61 6d 65 74 65 72 2e 0a 49 66 20 73 6f 2c  arameter..If so,
d470: 20 77 6f 72 6b 20 69 73 20 64 6f 6e 65 20 74 6f   work is done to
d480: 20 6d 65 72 67 65 20 61 6c 6c 20 73 75 63 68 20   merge all such 
d490: 73 65 67 6d 65 6e 74 73 20 77 69 74 68 20 61 67  segments with ag
d4a0: 65 3d 41 20 69 6e 74 6f 20 61 20 6e 65 77 2c 20  e=A into a new, 
d4b0: 6c 61 72 67 65 72 0a 73 65 67 6d 65 6e 74 20 61  larger.segment a
d4c0: 73 73 69 67 6e 65 64 20 61 67 65 3d 41 2b 31 2e  ssigned age=A+1.
d4d0: 20 41 74 20 70 72 65 73 65 6e 74 2c 20 22 70 65   At present, "pe
d4e0: 72 69 6f 64 69 63 61 6c 6c 79 22 20 61 73 20 75  riodically" as u
d4f0: 73 65 64 20 61 62 6f 76 65 20 6d 65 61 6e 73 20  sed above means 
d500: 0a 72 6f 75 67 68 6c 79 20 6f 6e 63 65 20 66 6f  .roughly once fo
d510: 72 20 65 76 65 72 79 20 33 32 4b 42 20 6f 66 20  r every 32KB of 
d520: 64 61 74 61 20 28 69 6e 63 6c 75 64 69 6e 67 20  data (including 
d530: 6f 76 65 72 68 65 61 64 29 20 77 72 69 74 74 65  overhead) writte
d540: 6e 20 74 6f 20 74 68 65 0a 69 6e 2d 6d 65 6d 6f  n to the.in-memo
d550: 72 79 20 74 72 65 65 2e 20 54 68 65 20 6d 65 72  ry tree. The mer
d560: 67 65 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ge operation is 
d570: 6e 6f 74 20 6e 65 63 65 73 73 61 72 69 6c 79 20  not necessarily 
d580: 63 6f 6d 70 6c 65 74 65 64 20 77 69 74 68 69 6e  completed within
d590: 20 0a 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 20   .a single call 
d5a0: 74 6f 20 61 20 77 72 69 74 65 20 41 50 49 20 28  to a write API (
d5b0: 74 68 69 73 20 77 6f 75 6c 64 20 72 65 73 75 6c  this would resul
d5c0: 74 20 69 6e 20 62 6c 6f 63 6b 69 6e 67 20 74 68  t in blocking th
d5d0: 65 20 77 72 69 74 65 72 20 74 68 72 65 61 64 0a  e writer thread.
d5e0: 66 6f 72 20 74 6f 6f 20 6c 6f 6e 67 20 69 6e 20  for too long in 
d5f0: 6d 61 6e 79 20 63 61 73 65 73 20 2d 20 69 6e 20  many cases - in 
d600: 6c 61 72 67 65 20 64 61 74 61 62 61 73 65 73 20  large databases 
d610: 73 65 67 6d 65 6e 74 73 20 6d 61 79 20 67 72 6f  segments may gro
d620: 77 20 74 6f 20 62 65 20 6d 61 6e 79 20 47 42 0a  w to be many GB.
d630: 69 6e 20 73 69 7a 65 29 2e 20 43 75 72 72 65 6e  in size). Curren
d640: 74 6c 79 2c 20 74 68 65 20 61 6d 6f 75 6e 74 20  tly, the amount 
d650: 6f 66 20 64 61 74 61 20 77 72 69 74 74 65 6e 20  of data written 
d660: 62 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74 6f  by a single auto
d670: 2d 77 6f 72 6b 0a 6f 70 65 72 61 74 69 6f 6e 20  -work.operation 
d680: 69 73 20 72 6f 75 67 68 6c 79 20 33 32 4b 42 20  is roughly 32KB 
d690: 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 74 68  multiplied by th
d6a0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 73 65 67 6d  e number of segm
d6b0: 65 6e 74 73 20 69 6e 20 74 68 65 20 64 61 74 61  ents in the data
d6c0: 62 61 73 65 0a 66 69 6c 65 2e 20 54 68 69 73 20  base.file. This 
d6d0: 66 6f 72 6d 75 6c 61 20 6d 61 79 20 63 68 61 6e  formula may chan
d6e0: 67 65 20 2d 20 74 68 65 20 70 6f 69 6e 74 20 69  ge - the point i
d6f0: 73 20 74 68 61 74 20 74 68 65 20 6c 69 62 72 61  s that the libra
d700: 72 79 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c  ry attempts to l
d710: 69 6d 69 74 0a 74 68 65 20 61 6d 6f 75 6e 74 20  imit.the amount 
d720: 6f 66 20 64 61 74 61 20 77 72 69 74 74 65 6e 20  of data written 
d730: 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
d740: 64 20 62 6c 6f 63 6b 69 6e 67 20 74 68 65 20 77  d blocking the w
d750: 72 69 74 65 72 20 74 68 72 65 61 64 20 66 6f 72  riter thread for
d760: 20 74 6f 6f 0a 6c 6f 6e 67 20 77 69 74 68 69 6e   too.long within
d770: 20 61 20 73 69 6e 67 6c 65 20 41 50 49 20 63 61   a single API ca
d780: 6c 6c 2e 0a 0a 3c 70 3e 45 61 63 68 20 74 69 6d  ll...<p>Each tim
d790: 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  e a transaction 
d7a0: 69 73 20 63 6f 6d 6d 69 74 74 65 64 20 69 6e 20  is committed in 
d7b0: 61 75 74 6f 2d 77 6f 72 6b 20 6d 6f 64 65 2c 20  auto-work mode, 
d7c0: 74 68 65 20 6c 69 62 72 61 72 79 20 63 68 65 63  the library chec
d7d0: 6b 73 0a 74 6f 20 73 65 65 20 69 66 20 74 68 65  ks.to see if the
d7e0: 72 65 20 65 78 69 73 74 73 20 61 6e 20 22 6f 6c  re exists an "ol
d7f0: 64 22 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72 65  d" in-memory tre
d800: 65 20 28 73 65 65 20 74 68 65 20 4c 53 4d 5f 43  e (see the LSM_C
d810: 4f 4e 46 49 47 5f 41 55 54 4f 46 4c 55 53 48 0a  ONFIG_AUTOFLUSH.
d820: 6f 70 74 69 6f 6e 20 61 62 6f 76 65 29 2e 20 49  option above). I
d830: 66 20 73 6f 2c 20 69 74 20 61 74 74 65 6d 70 74  f so, it attempt
d840: 73 20 74 6f 20 66 6c 75 73 68 20 69 74 20 74 6f  s to flush it to
d850: 20 64 69 73 6b 20 69 6d 6d 65 64 69 61 74 65 6c   disk immediatel
d860: 79 2e 20 55 6e 6c 69 6b 65 0a 6d 65 72 67 65 73  y. Unlike.merges
d870: 20 6f 66 20 65 78 69 73 74 69 6e 67 20 73 65 67   of existing seg
d880: 6d 65 6e 74 73 2c 20 74 68 65 20 65 6e 74 69 72  ments, the entir
d890: 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72 65 65  e in-memory tree
d8a0: 20 6d 75 73 74 20 62 65 20 66 6c 75 73 68 65 64   must be flushed
d8b0: 20 74 6f 0a 64 69 73 6b 20 62 65 66 6f 72 65 20   to.disk before 
d8c0: 63 6f 6e 74 72 6f 6c 20 69 73 20 72 65 74 75 72  control is retur
d8d0: 6e 65 64 20 74 6f 20 74 68 65 20 75 73 65 72 2e  ned to the user.
d8e0: 20 49 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69   It is not possi
d8f0: 62 6c 65 20 74 6f 0a 69 6e 63 72 65 6d 65 6e 74  ble to.increment
d900: 61 6c 6c 79 20 66 6c 75 73 68 20 61 6e 20 69 6e  ally flush an in
d910: 2d 6d 65 6d 6f 72 79 20 74 72 65 65 20 69 6e 20  -memory tree in 
d920: 74 68 65 20 73 61 6d 65 20 77 61 79 73 20 61 73  the same ways as
d930: 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 20   it is possible 
d940: 74 6f 0a 69 6e 63 72 65 6d 65 6e 74 61 6c 6c 79  to.incrementally
d950: 20 6d 65 72 67 65 20 65 78 69 73 74 69 6e 67 20   merge existing 
d960: 64 61 74 61 62 61 73 65 20 73 65 67 6d 65 6e 74  database segment
d970: 73 20 74 6f 67 65 74 68 65 72 2e 0a 0a 3c 70 3e  s together...<p>
d980: 49 6e 20 6f 72 64 65 72 20 74 6f 20 70 65 72 66  In order to perf
d990: 6f 72 6d 20 61 75 74 6f 2d 77 6f 72 6b 20 6f 6e  orm auto-work on
d9a0: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
d9b0: 6c 65 2c 20 65 69 74 68 65 72 20 74 6f 20 66 6c  le, either to fl
d9c0: 75 73 68 20 74 68 65 0a 63 6f 6e 74 65 6e 74 73  ush the.contents
d9d0: 20 6f 66 20 61 6e 20 6f 6c 64 20 69 6e 2d 6d 65   of an old in-me
d9e0: 6d 6f 72 79 20 74 72 65 65 20 74 6f 20 64 69 73  mory tree to dis
d9f0: 6b 20 6f 72 20 74 6f 20 6d 65 72 67 65 20 65 78  k or to merge ex
da00: 69 73 74 69 6e 67 20 73 65 67 6d 65 6e 74 73 20  isting segments 
da10: 77 69 74 68 69 6e 0a 74 68 65 20 64 61 74 61 62  within.the datab
da20: 61 73 65 20 66 69 6c 65 20 74 6f 67 65 74 68 65  ase file togethe
da30: 72 2c 20 74 68 65 20 63 6c 69 65 6e 74 20 6d 75  r, the client mu
da40: 73 74 20 6f 62 74 61 69 6e 20 74 68 65 20 57 4f  st obtain the WO
da50: 52 4b 45 52 20 6c 6f 63 6b 2e 20 49 66 20 73 6f  RKER lock. If so
da60: 6d 65 0a 6f 74 68 65 72 20 63 6c 69 65 6e 74 20  me.other client 
da70: 69 73 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 69  is already holdi
da80: 6e 67 20 74 68 65 20 57 4f 52 4b 45 52 20 6c 6f  ng the WORKER lo
da90: 63 6b 2c 20 74 68 69 73 20 77 69 6c 6c 20 6e 6f  ck, this will no
daa0: 74 20 62 65 20 70 6f 73 73 69 62 6c 65 2e 0a 54  t be possible..T
dab0: 68 69 73 20 69 73 20 6e 6f 74 20 61 6e 20 65 72  his is not an er
dac0: 72 6f 72 2e 20 49 66 20 74 68 69 73 20 6f 63 63  ror. If this occ
dad0: 75 72 73 2c 20 74 68 65 20 77 72 69 74 65 72 20  urs, the writer 
dae0: 74 68 72 65 61 64 20 73 69 6d 70 6c 79 20 72 65  thread simply re
daf0: 74 75 72 6e 73 0a 69 6d 6d 65 64 69 61 74 65 6c  turns.immediatel
db00: 79 2c 20 77 69 74 68 6f 75 74 20 70 65 72 66 6f  y, without perfo
db10: 72 6d 69 6e 67 20 61 6e 79 20 77 6f 72 6b 20 6f  rming any work o
db20: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
db30: 69 6c 65 2e 0a 0a 3c 70 3e 41 73 73 75 6d 69 6e  ile...<p>Assumin
db40: 67 20 74 68 65 20 4c 53 4d 5f 43 4f 4e 46 49 47  g the LSM_CONFIG
db50: 5f 41 55 54 4f 43 48 45 43 4b 50 4f 49 4e 54 20  _AUTOCHECKPOINT 
db60: 70 61 72 61 6d 65 74 65 72 20 69 73 20 73 65 74  parameter is set
db70: 20 74 6f 20 61 20 76 61 6c 75 65 20 67 72 65 61   to a value grea
db80: 74 65 72 0a 74 68 61 6e 20 7a 65 72 6f 2c 20 61  ter.than zero, a
db90: 66 74 65 72 20 70 65 72 66 6f 72 6d 69 6e 67 20  fter performing 
dba0: 64 61 74 61 62 61 73 65 20 77 6f 72 6b 2c 20 74  database work, t
dbb0: 68 65 20 6c 69 62 72 61 72 79 20 61 75 74 6f 6d  he library autom
dbc0: 61 74 69 63 61 6c 6c 79 20 63 68 65 63 6b 73 0a  atically checks.
dbd0: 68 6f 77 20 6d 61 6e 79 20 62 79 74 65 73 20 6f  how many bytes o
dbe0: 66 20 72 61 77 20 64 61 74 61 20 68 61 76 65 20  f raw data have 
dbf0: 62 65 65 6e 20 77 72 69 74 74 65 6e 20 74 6f 20  been written to 
dc00: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
dc10: 65 20 73 69 6e 63 65 20 74 68 65 0a 6c 61 73 74  e since the.last
dc20: 20 63 68 65 63 6b 70 6f 69 6e 74 20 28 62 79 20   checkpoint (by 
dc30: 61 6e 79 20 63 6c 69 65 6e 74 2c 20 6e 6f 74 20  any client, not 
dc40: 6a 75 73 74 20 62 79 20 74 68 65 20 63 75 72 72  just by the curr
dc50: 65 6e 74 20 63 6c 69 65 6e 74 29 2e 20 49 66 20  ent client). If 
dc60: 74 68 69 73 0a 76 61 6c 75 65 20 69 73 20 67 72  this.value is gr
dc70: 65 61 74 65 72 20 74 68 61 6e 20 74 68 65 20 76  eater than the v
dc80: 61 6c 75 65 20 6f 66 20 74 68 65 20 4c 53 4d 5f  alue of the LSM_
dc90: 43 4f 4e 46 49 47 5f 41 55 54 4f 43 48 45 43 4b  CONFIG_AUTOCHECK
dca0: 50 4f 49 4e 54 20 70 61 72 61 6d 65 74 65 72 2c  POINT parameter,
dcb0: 0a 61 20 63 68 65 63 6b 70 6f 69 6e 74 20 69 73  .a checkpoint is
dcc0: 20 61 74 74 65 6d 70 74 65 64 2e 20 49 74 20 69   attempted. It i
dcd0: 73 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 69  s not an error i
dce0: 66 20 74 68 65 20 61 74 74 65 6d 70 74 20 66 61  f the attempt fa
dcf0: 69 6c 73 20 62 65 63 61 75 73 65 20 74 68 65 0a  ils because the.
dd00: 43 48 45 43 4b 50 4f 49 4e 54 45 52 20 6c 6f 63  CHECKPOINTER loc
dd10: 6b 20 63 61 6e 6e 6f 74 20 62 65 20 6f 62 74 61  k cannot be obta
dd20: 69 6e 65 64 2e 0a 0a 3c 68 33 20 69 64 3d 65 78  ined...<h3 id=ex
dd30: 70 6c 69 63 69 74 5f 77 6f 72 6b 5f 61 6e 64 5f  plicit_work_and_
dd40: 63 68 65 63 6b 70 6f 69 6e 74 5f 73 63 68 65 64  checkpoint_sched
dd50: 75 6c 69 6e 67 3e 36 2e 32 2e 33 2e 20 45 78 70  uling>6.2.3. Exp
dd60: 6c 69 63 69 74 20 57 6f 72 6b 20 61 6e 64 20 43  licit Work and C
dd70: 68 65 63 6b 70 6f 69 6e 74 20 53 63 68 65 64 75  heckpoint Schedu
dd80: 6c 69 6e 67 3c 2f 68 33 3e 0a 0a 3c 70 3e 54 68  ling</h3>..<p>Th
dd90: 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20 74 6f  e alternative to
dda0: 20 61 75 74 6f 6d 61 74 69 63 20 73 63 68 65 64   automatic sched
ddb0: 75 6c 69 6e 67 20 6f 66 20 77 6f 72 6b 20 61 6e  uling of work an
ddc0: 64 20 63 68 65 63 6b 70 6f 69 6e 74 20 6f 70 65  d checkpoint ope
ddd0: 72 61 74 69 6f 6e 73 0a 69 73 20 74 6f 20 65 78  rations.is to ex
dde0: 70 6c 69 63 69 74 6c 79 20 73 63 68 65 64 75 6c  plicitly schedul
ddf0: 65 20 74 68 65 6d 2e 20 50 6f 73 73 69 62 6c 79  e them. Possibly
de00: 20 69 6e 20 61 20 62 61 63 6b 67 72 6f 75 6e 64   in a background
de10: 20 74 68 72 65 61 64 20 6f 72 20 64 65 64 69 63   thread or dedic
de20: 61 74 65 64 0a 61 70 70 6c 69 63 61 74 69 6f 6e  ated.application
de30: 20 70 72 6f 63 65 73 73 2e 20 49 6e 20 6f 72 64   process. In ord
de40: 65 72 20 74 6f 20 64 69 73 61 62 6c 65 20 61 75  er to disable au
de50: 74 6f 6d 61 74 69 63 20 77 6f 72 6b 2c 20 61 20  tomatic work, a 
de60: 63 6c 69 65 6e 74 20 6d 75 73 74 20 73 65 74 0a  client must set.
de70: 74 68 65 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41  the LSM_CONFIG_A
de80: 55 54 4f 57 4f 52 4b 20 70 61 72 61 6d 65 74 65  UTOWORK paramete
de90: 72 20 74 6f 20 7a 65 72 6f 2e 20 54 68 69 73 20  r to zero. This 
dea0: 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 70  parameter is a p
deb0: 72 6f 70 65 72 74 79 20 6f 66 0a 61 20 64 61 74  roperty of.a dat
dec0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ded0: 2c 20 6e 6f 74 20 6f 66 20 61 20 64 61 74 61 62  , not of a datab
dee0: 61 73 65 20 69 74 73 65 6c 66 2c 20 73 6f 20 69  ase itself, so i
def0: 74 20 6d 75 73 74 20 62 65 20 63 6c 65 61 72 65  t must be cleare
df00: 64 0a 73 65 70 61 72 61 74 65 6c 79 20 62 79 20  d.separately by 
df10: 61 6c 6c 20 70 72 6f 63 65 73 73 65 73 20 74 68  all processes th
df20: 61 74 20 6d 61 79 20 77 72 69 74 65 20 74 6f 20  at may write to 
df30: 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 4f 74  the database. Ot
df40: 68 65 72 77 69 73 65 2c 20 74 68 65 79 0a 6d 61  herwise, they.ma
df50: 79 20 61 74 74 65 6d 70 74 20 61 75 74 6f 6d 61  y attempt automa
df60: 74 69 63 20 64 61 74 61 62 61 73 65 20 77 6f 72  tic database wor
df70: 6b 20 6f 72 20 63 68 65 63 6b 70 6f 69 6e 74 73  k or checkpoints
df80: 2e 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20 20  ...<verbatim>.  
df90: 2f 2a 20 44 69 73 61 62 6c 65 20 61 75 74 6f 2d  /* Disable auto-
dfa0: 77 6f 72 6b 20 6f 6e 20 63 6f 6e 6e 65 63 74 69  work on connecti
dfb0: 6f 6e 20 64 62 20 2a 2f 0a 20 20 69 6e 74 20 69  on db */.  int i
dfc0: 56 61 6c 20 3d 20 30 3b 0a 20 20 6c 73 6d 5f 63  Val = 0;.  lsm_c
dfd0: 6f 6e 66 69 67 28 64 62 2c 20 4c 53 4d 5f 43 4f  onfig(db, LSM_CO
dfe0: 4e 46 49 47 5f 41 55 54 4f 57 4f 52 4b 2c 20 26  NFIG_AUTOWORK, &
dff0: 69 56 61 6c 29 3b 0a 3c 2f 76 65 72 62 61 74 69  iVal);.</verbati
e000: 6d 3e 0a 0a 3c 70 3e 54 68 65 20 6c 73 6d 5f 77  m>..<p>The lsm_w
e010: 6f 72 6b 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ork() function i
e020: 73 20 75 73 65 64 20 74 6f 20 65 78 70 6c 69 63  s used to explic
e030: 69 74 6c 79 20 70 65 72 66 6f 72 6d 20 77 6f 72  itly perform wor
e040: 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
e050: 65 3a 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20  e:..<verbatim>. 
e060: 20 69 6e 74 20 6c 73 6d 5f 77 6f 72 6b 28 6c 73   int lsm_work(ls
e070: 6d 5f 64 62 20 2a 64 62 2c 20 69 6e 74 20 6e 4d  m_db *db, int nM
e080: 65 72 67 65 2c 20 69 6e 74 20 6e 42 79 74 65 2c  erge, int nByte,
e090: 20 69 6e 74 20 2a 70 6e 57 72 69 74 65 29 3b 0a   int *pnWrite);.
e0a0: 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70 3e  </verbatim>..<p>
e0b0: 50 61 72 61 6d 65 74 65 72 20 6e 42 79 74 65 20  Parameter nByte 
e0c0: 69 73 20 70 61 73 73 65 64 20 61 20 6c 69 6d 69  is passed a limi
e0d0: 74 20 6f 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  t on the number 
e0e0: 6f 66 20 62 79 74 65 73 20 6f 66 20 64 61 74 61  of bytes of data
e0f0: 20 74 68 61 74 20 0a 73 68 6f 75 6c 64 20 62 65   that .should be
e100: 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20   written to the 
e110: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 62 65  database file be
e120: 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 72 65  fore the call re
e130: 74 75 72 6e 73 2e 20 49 74 20 69 73 20 61 20 0a  turns. It is a .
e140: 68 69 6e 74 20 6f 6e 6c 79 2c 20 74 68 65 20 6c  hint only, the l
e150: 69 62 72 61 72 79 20 64 6f 65 73 20 6e 6f 74 20  ibrary does not 
e160: 68 6f 6e 6f 72 20 74 68 69 73 20 6c 69 6d 69 74  honor this limit
e170: 20 73 74 72 69 63 74 6c 79 2e 0a 0a 3c 70 3e 49   strictly...<p>I
e180: 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 68  f the database h
e190: 61 73 20 61 6e 20 6f 6c 64 20 69 6e 2d 6d 65 6d  as an old in-mem
e1a0: 6f 72 79 20 74 72 65 65 20 77 68 65 6e 20 6c 73  ory tree when ls
e1b0: 6d 5f 77 6f 72 6b 28 29 20 69 73 20 63 61 6c 6c  m_work() is call
e1c0: 65 64 2c 20 69 74 20 69 73 0a 66 6c 75 73 68 65  ed, it is.flushe
e1d0: 64 20 74 6f 20 64 69 73 6b 2e 20 49 66 20 74 68  d to disk. If th
e1e0: 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 6d 6f  is means that mo
e1f0: 72 65 20 74 68 61 6e 20 6e 42 79 74 65 20 62 79  re than nByte by
e200: 74 65 73 20 6f 66 20 64 61 74 61 20 69 73 20 77  tes of data is w
e210: 72 69 74 74 65 6e 0a 74 6f 20 74 68 65 20 64 61  ritten.to the da
e220: 74 61 62 61 73 65 20 66 69 6c 65 2c 20 6e 6f 20  tabase file, no 
e230: 66 75 72 74 68 65 72 20 77 6f 72 6b 20 69 73 20  further work is 
e240: 70 65 72 66 6f 72 6d 65 64 2e 20 4f 74 68 65 72  performed. Other
e250: 77 69 73 65 2c 20 74 68 65 20 6e 75 6d 62 65 72  wise, the number
e260: 0a 6f 66 20 62 79 74 65 73 20 77 72 69 74 74 65  .of bytes writte
e270: 6e 20 69 73 20 73 75 62 74 72 61 63 74 65 64 20  n is subtracted 
e280: 66 72 6f 6d 20 6e 42 79 74 65 20 62 65 66 6f 72  from nByte befor
e290: 65 20 70 72 6f 63 65 65 64 69 6e 67 2e 0a 0a 3c  e proceeding...<
e2a0: 70 3e 49 66 20 70 61 72 61 6d 65 74 65 72 20 6e  p>If parameter n
e2b0: 4d 65 72 67 65 20 69 73 20 67 72 65 61 74 65 72  Merge is greater
e2c0: 20 74 68 61 6e 20 31 2c 20 74 68 65 6e 20 74 68   than 1, then th
e2d0: 65 20 6c 69 62 72 61 72 79 20 73 65 61 72 63 68  e library search
e2e0: 65 73 20 66 6f 72 20 0a 6e 4d 65 72 67 65 20 6f  es for .nMerge o
e2f0: 72 20 6d 6f 72 65 20 73 65 67 6d 65 6e 74 73 20  r more segments 
e300: 6f 66 20 74 68 65 20 73 61 6d 65 20 61 67 65 20  of the same age 
e310: 77 69 74 68 69 6e 20 74 68 65 20 64 61 74 61 62  within the datab
e320: 61 73 65 20 66 69 6c 65 20 61 6e 64 20 70 65 72  ase file and per
e330: 66 6f 72 6d 73 0a 75 70 20 74 6f 20 6e 42 79 74  forms.up to nByt
e340: 65 20 62 79 74 65 73 20 6f 66 20 77 6f 72 6b 20  e bytes of work 
e350: 74 6f 20 6d 65 72 67 65 20 74 68 65 6d 20 74 6f  to merge them to
e360: 67 65 74 68 65 72 2e 20 49 66 20 74 68 65 20 6d  gether. If the m
e370: 65 72 67 65 20 69 73 20 63 6f 6d 70 6c 65 74 65  erge is complete
e380: 64 0a 62 65 66 6f 72 65 20 74 68 65 20 6e 42 79  d.before the nBy
e390: 74 65 20 6c 69 6d 69 74 20 69 73 20 65 78 63 65  te limit is exce
e3a0: 65 64 65 64 2c 20 74 68 65 20 6c 69 62 72 61 72  eded, the librar
e3b0: 79 20 73 65 61 72 63 68 65 73 20 66 6f 72 20 61  y searches for a
e3c0: 6e 6f 74 68 65 72 20 73 65 74 20 6f 66 0a 6e 4d  nother set of.nM
e3d0: 65 72 67 65 20 6f 72 20 6d 6f 72 65 20 73 65 67  erge or more seg
e3e0: 6d 65 6e 74 73 20 74 6f 20 77 6f 72 6b 20 6f 6e  ments to work on
e3f0: 2c 20 61 6e 64 20 73 6f 20 6f 6e 2e 20 49 66 20  , and so on. If 
e400: 61 74 20 61 6e 79 20 70 6f 69 6e 74 20 6e 6f 20  at any point no 
e410: 73 75 63 68 20 73 65 74 20 6f 66 0a 6e 4d 65 72  such set of.nMer
e420: 67 65 20 73 65 67 6d 65 6e 74 73 20 63 61 6e 20  ge segments can 
e430: 62 65 20 66 6f 75 6e 64 2c 20 74 68 65 20 63 61  be found, the ca
e440: 6c 6c 20 72 65 74 75 72 6e 73 20 77 69 74 68 6f  ll returns witho
e450: 75 74 20 70 65 72 66 6f 72 6d 69 6e 67 20 61 6e  ut performing an
e460: 79 20 0a 66 75 72 74 68 65 72 20 77 6f 72 6b 2e  y .further work.
e470: 0a 0a 3c 70 3e 43 61 6c 6c 69 6e 67 20 6c 73 6d  ..<p>Calling lsm
e480: 5f 77 6f 72 6b 28 29 20 77 69 74 68 20 74 68 65  _work() with the
e490: 20 6e 4d 65 72 67 65 20 61 72 67 75 6d 65 6e 74   nMerge argument
e4a0: 20 73 65 74 20 74 6f 20 31 20 69 73 20 75 73 65   set to 1 is use
e4b0: 64 20 74 6f 20 22 6f 70 74 69 6d 69 7a 65 22 0a  d to "optimize".
e4c0: 74 68 65 20 64 61 74 61 62 61 73 65 20 28 73 65  the database (se
e4d0: 65 20 62 65 6c 6f 77 29 2e 20 50 61 73 73 69 6e  e below). Passin
e4e0: 67 20 61 20 76 61 6c 75 65 20 6f 66 20 7a 65 72  g a value of zer
e4f0: 6f 20 6f 72 20 6c 65 73 73 20 66 6f 72 20 74 68  o or less for th
e500: 65 20 6e 4d 65 72 67 65 0a 70 61 72 61 6d 65 74  e nMerge.paramet
e510: 65 72 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 0a  er is an error..
e520: 0a 3c 70 3e 49 6e 20 61 6e 79 20 63 61 73 65 2c  .<p>In any case,
e530: 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
e540: 67 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 2a  g the value of *
e550: 70 6e 57 72 69 74 65 20 69 73 20 73 65 74 20 74  pnWrite is set t
e560: 6f 20 74 68 65 20 61 63 74 75 61 6c 0a 6e 75 6d  o the actual.num
e570: 62 65 72 20 6f 66 20 62 79 74 65 73 20 77 72 69  ber of bytes wri
e580: 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tten to the data
e590: 62 61 73 65 20 66 69 6c 65 2e 0a 0a 3c 70 3e 54  base file...<p>T
e5a0: 68 65 20 65 78 61 6d 70 6c 65 20 63 6f 64 65 20  he example code 
e5b0: 62 65 6c 6f 77 20 6d 69 67 68 74 20 62 65 20 65  below might be e
e5c0: 78 65 63 75 74 65 64 20 69 6e 20 61 20 62 61 63  xecuted in a bac
e5d0: 6b 67 72 6f 75 6e 64 20 74 68 72 65 61 64 20 6f  kground thread o
e5e0: 72 20 70 72 6f 63 65 73 73 0a 69 6e 20 6f 72 64  r process.in ord
e5f0: 65 72 20 74 6f 20 70 65 72 66 6f 72 6d 20 64 61  er to perform da
e600: 74 61 62 61 73 65 20 77 6f 72 6b 20 61 6e 64 20  tabase work and 
e610: 63 68 65 63 6b 70 6f 69 6e 74 69 6e 67 2e 20 49  checkpointing. I
e620: 6e 20 74 68 69 73 20 63 61 73 65 20 61 6c 6c 20  n this case all 
e630: 6f 74 68 65 72 0a 63 6c 69 65 6e 74 73 20 73 68  other.clients sh
e640: 6f 75 6c 64 20 73 65 74 20 74 68 65 20 4c 53 4d  ould set the LSM
e650: 5f 43 4f 4e 46 49 47 5f 41 55 54 4f 57 4f 52 4b  _CONFIG_AUTOWORK
e660: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 7a 65   parameter to ze
e670: 72 6f 2e 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a  ro...<verbatim>.
e680: 20 20 69 6e 74 20 72 63 3b 0a 20 20 6c 73 6d 5f    int rc;.  lsm_
e690: 64 62 20 2a 64 62 3b 0a 20 20 69 6e 74 20 6e 43  db *db;.  int nC
e6a0: 6b 70 74 20 3d 20 34 2a 31 30 32 34 2a 31 30 32  kpt = 4*1024*102
e6b0: 34 3b 0a 0a 20 20 2f 2a 20 4f 70 65 6e 20 61 20  4;..  /* Open a 
e6c0: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
e6d0: 69 6f 6e 20 74 6f 20 64 61 74 61 62 61 73 65 20  ion to database 
e6e0: 22 74 65 73 74 2e 64 62 22 2e 20 0a 20 20 2a 2a  "test.db". .  **
e6f0: 0a 20 20 2a 2a 20 43 6f 6e 66 69 67 75 72 65 20  .  ** Configure 
e700: 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  the connection t
e710: 6f 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  o automatically 
e720: 63 68 65 63 6b 70 6f 69 6e 74 20 74 68 65 20 64  checkpoint the d
e730: 61 74 61 62 61 73 65 20 61 66 74 65 72 0a 20 20  atabase after.  
e740: 2a 2a 20 77 72 69 74 69 6e 67 20 65 61 63 68 20  ** writing each 
e750: 34 4d 42 20 6f 66 20 64 61 74 61 20 74 6f 20 69  4MB of data to i
e760: 74 20 28 69 6e 73 74 65 61 64 20 6f 66 20 74 68  t (instead of th
e770: 65 20 64 65 66 61 75 6c 74 20 32 4d 42 29 2e 20  e default 2MB). 
e780: 41 73 20 77 65 6c 6c 0a 20 20 2a 2a 20 61 73 20  As well.  ** as 
e790: 74 6f 20 61 75 74 6f 2d 77 6f 72 6b 2c 20 74 68  to auto-work, th
e7a0: 65 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55 54  e LSM_CONFIG_AUT
e7b0: 4f 43 48 45 43 4b 50 4f 49 4e 54 20 70 61 72 61  OCHECKPOINT para
e7c0: 6d 65 74 65 72 20 61 70 70 6c 69 65 73 20 74 6f  meter applies to
e7d0: 20 64 61 74 61 0a 20 20 2a 2a 20 77 72 69 74 74   data.  ** writt
e7e0: 65 6e 20 62 79 20 65 78 70 6c 69 63 69 74 20 63  en by explicit c
e7f0: 61 6c 6c 73 20 74 6f 20 6c 73 6d 5f 77 6f 72 6b  alls to lsm_work
e800: 28 29 2e 0a 20 20 2a 2f 0a 20 20 6c 73 6d 5f 6e  ()..  */.  lsm_n
e810: 65 77 28 30 2c 20 26 64 62 29 3b 0a 20 20 6c 73  ew(0, &db);.  ls
e820: 6d 5f 63 6f 6e 66 69 67 28 64 62 2c 20 4c 53 4d  m_config(db, LSM
e830: 5f 43 4f 4e 46 49 47 5f 41 55 54 4f 43 48 45 43  _CONFIG_AUTOCHEC
e840: 4b 50 4f 49 4e 54 2c 20 26 6e 43 6b 70 74 29 3b  KPOINT, &nCkpt);
e850: 0a 20 20 6c 73 6d 5f 6f 70 65 6e 28 64 62 2c 20  .  lsm_open(db, 
e860: 22 74 65 73 74 2e 64 62 22 29 3b 0a 0a 20 20 77  "test.db");..  w
e870: 68 69 6c 65 28 20 31 20 29 7b 0a 20 20 20 20 69  hile( 1 ){.    i
e880: 6e 74 20 6e 57 72 69 74 65 3b 0a 0a 20 20 20 20  nt nWrite;..    
e890: 2f 2a 20 41 74 74 65 6d 70 74 20 75 70 20 74 6f  /* Attempt up to
e8a0: 20 35 31 32 4b 42 20 6f 66 20 77 6f 72 6b 2e 20   512KB of work. 
e8b0: 53 65 74 20 6e 57 72 69 74 65 20 74 6f 20 74 68  Set nWrite to th
e8c0: 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
e8d0: 73 0a 20 20 20 20 2a 2a 20 61 63 74 75 61 6c 6c  s.    ** actuall
e8e0: 79 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73  y written to dis
e8f0: 6b 2e 20 20 2a 2f 0a 20 20 20 20 72 63 20 3d 20  k.  */.    rc = 
e900: 6c 73 6d 5f 77 6f 72 6b 28 64 62 2c 20 32 2c 20  lsm_work(db, 2, 
e910: 35 31 32 2a 31 30 32 34 2c 20 26 6e 57 72 69 74  512*1024, &nWrit
e920: 65 29 3b 0a 20 20 20 20 69 66 28 20 72 63 21 3d  e);.    if( rc!=
e930: 4c 53 4d 5f 4f 4b 20 26 26 20 72 63 21 3d 4c 53  LSM_OK && rc!=LS
e940: 4d 5f 42 55 53 59 20 29 7b 0a 20 20 20 20 20 20  M_BUSY ){.      
e950: 2f 2a 20 41 6e 79 74 68 69 6e 67 20 6f 74 68 65  /* Anything othe
e960: 72 20 74 68 61 6e 20 4c 53 4d 5f 4f 4b 20 6f 72  r than LSM_OK or
e970: 20 4c 53 4d 5f 42 55 53 59 20 69 73 20 61 20 70   LSM_BUSY is a p
e980: 72 6f 62 6c 65 6d 2e 20 4c 53 4d 5f 42 55 53 59  roblem. LSM_BUSY
e990: 0a 20 20 20 20 20 20 2a 2a 20 69 6e 64 69 63 61  .      ** indica
e9a0: 74 65 73 20 74 68 61 74 20 73 6f 6d 65 20 6f 74  tes that some ot
e9b0: 68 65 72 20 63 6c 69 65 6e 74 20 68 61 73 20 74  her client has t
e9c0: 61 6b 65 6e 20 74 68 65 20 57 4f 52 4b 45 52 20  aken the WORKER 
e9d0: 6c 6f 63 6b 2e 20 41 6e 79 0a 20 20 20 20 20 20  lock. Any.      
e9e0: 2a 2a 20 6f 74 68 65 72 20 65 72 72 6f 72 20 69  ** other error i
e9f0: 6e 64 69 63 61 74 65 73 20 73 6f 6d 65 74 68 69  ndicates somethi
ea00: 6e 67 20 68 61 73 20 67 6f 6e 65 20 71 75 69 74  ng has gone quit
ea10: 65 20 77 72 6f 6e 67 2e 20 20 2a 2f 0a 20 20 20  e wrong.  */.   
ea20: 20 20 20 6c 73 6d 5f 63 6c 6f 73 65 28 64 62 29     lsm_close(db)
ea30: 3b 0a 20 20 20 20 20 20 72 65 74 75 72 6e 20 72  ;.      return r
ea40: 63 3b 0a 20 20 20 20 7d 0a 0a 20 20 20 20 2f 2a  c;.    }..    /*
ea50: 20 6e 57 72 69 74 65 20 6d 61 79 20 62 65 20 73   nWrite may be s
ea60: 65 74 20 74 6f 20 7a 65 72 6f 20 68 65 72 65 20  et to zero here 
ea70: 69 6e 20 74 77 6f 20 73 63 65 6e 61 72 69 6f 73  in two scenarios
ea80: 2e 20 6c 73 6d 5f 77 6f 72 6b 28 29 0a 20 20 20  . lsm_work().   
ea90: 20 2a 2a 20 6d 61 79 20 68 61 76 65 20 66 61 69   ** may have fai
eaa0: 6c 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  led to obtain th
eab0: 65 20 57 4f 52 4b 45 52 20 6c 6f 63 6b 20 61 6e  e WORKER lock an
eac0: 64 20 72 65 74 75 72 6e 65 64 20 4c 53 4d 5f 42  d returned LSM_B
ead0: 55 53 59 2c 0a 20 20 20 20 2a 2a 20 69 6e 64 69  USY,.    ** indi
eae0: 63 61 74 69 6e 67 20 74 68 61 74 20 73 6f 6d 65  cating that some
eaf0: 20 6f 74 68 65 72 20 63 6f 6e 6e 65 63 74 69 6f   other connectio
eb00: 6e 20 69 73 20 77 6f 72 6b 69 6e 67 20 6f 6e 20  n is working on 
eb10: 74 68 65 20 64 61 74 61 62 61 73 65 2e 0a 20 20  the database..  
eb20: 20 20 2a 2a 20 41 6c 74 65 72 6e 61 74 69 76 65    ** Alternative
eb30: 6c 79 2c 20 69 74 20 6d 61 79 20 62 65 20 74 68  ly, it may be th
eb40: 61 74 20 74 68 65 72 65 20 77 61 73 20 6e 6f 20  at there was no 
eb50: 6f 6c 64 20 69 6e 2d 6d 65 6d 6f 72 79 20 74 72  old in-memory tr
eb60: 65 65 20 74 6f 0a 20 20 20 20 2a 2a 20 66 6c 75  ee to.    ** flu
eb70: 73 68 20 61 6e 64 20 6e 6f 20 74 77 6f 20 73 65  sh and no two se
eb80: 67 6d 65 6e 74 73 20 6f 66 20 74 68 65 20 73 61  gments of the sa
eb90: 6d 65 20 61 67 65 20 77 69 74 68 69 6e 20 74 68  me age within th
eba0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c  e database file,
ebb0: 0a 20 20 20 20 2a 2a 20 6d 65 61 6e 69 6e 67 20  .    ** meaning 
ebc0: 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  the function cou
ebd0: 6c 64 20 66 69 6e 64 20 6e 6f 20 77 6f 72 6b 20  ld find no work 
ebe0: 74 6f 20 64 6f 2e 0a 20 20 20 20 2a 2a 0a 20 20  to do..    **.  
ebf0: 20 20 2a 2a 20 49 6e 20 65 69 74 68 65 72 20 63    ** In either c
ec00: 61 73 65 2c 20 74 68 65 72 65 20 69 73 20 6e 6f  ase, there is no
ec10: 20 70 6f 69 6e 74 20 69 6e 20 63 61 6c 6c 69 6e   point in callin
ec20: 67 20 6c 73 6d 5f 77 6f 72 6b 28 29 20 61 67 61  g lsm_work() aga
ec30: 69 6e 20 0a 20 20 20 20 2a 2a 20 69 6d 6d 65 64  in .    ** immed
ec40: 69 61 74 65 6c 79 2e 20 49 6e 73 74 65 61 64 2c  iately. Instead,
ec50: 20 73 6c 65 65 70 20 66 6f 72 20 61 20 73 65 63   sleep for a sec
ec60: 6f 6e 64 20 62 65 66 6f 72 65 20 63 6f 6e 74 69  ond before conti
ec70: 6e 75 69 6e 67 2e 20 42 79 20 74 68 61 74 0a 20  nuing. By that. 
ec80: 20 20 20 2a 2a 20 74 69 6d 65 2c 20 74 68 69 6e     ** time, thin
ec90: 67 73 20 6d 61 79 20 68 61 76 65 20 63 68 61 6e  gs may have chan
eca0: 67 65 64 20 28 74 68 65 20 6f 74 68 65 72 20 70  ged (the other p
ecb0: 72 6f 63 65 73 73 20 6d 61 79 20 68 61 76 65 20  rocess may have 
ecc0: 72 65 6c 69 6e 71 75 69 73 68 65 64 0a 20 20 20  relinquished.   
ecd0: 20 2a 2a 20 74 68 65 20 57 4f 52 4b 45 52 20 6c   ** the WORKER l
ece0: 6f 63 6b 2c 20 6f 72 20 61 6e 20 69 6e 2d 6d 65  ock, or an in-me
ecf0: 6d 6f 72 79 20 74 72 65 65 20 6d 61 79 20 68 61  mory tree may ha
ed00: 76 65 20 62 65 65 6e 20 6d 61 72 6b 65 64 20 61  ve been marked a
ed10: 73 20 6f 6c 64 29 2e 0a 20 20 20 20 2a 2f 0a 20  s old)..    */. 
ed20: 20 20 20 69 66 28 20 6e 57 72 69 74 65 3d 3d 30     if( nWrite==0
ed30: 20 29 20 73 6c 65 65 70 28 31 29 3b 0a 20 20 7d   ) sleep(1);.  }
ed40: 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70  .</verbatim>..<p
ed50: 3e 43 68 65 63 6b 70 6f 69 6e 74 73 20 63 61 6e  >Checkpoints can
ed60: 20 61 6c 73 6f 20 62 65 20 72 65 71 75 65 73 74   also be request
ed70: 65 64 20 65 78 70 6c 69 63 69 74 6c 79 2c 20 75  ed explicitly, u
ed80: 73 69 6e 67 20 74 68 65 20 6c 73 6d 5f 63 68 65  sing the lsm_che
ed90: 63 6b 70 6f 69 6e 74 28 29 0a 41 50 49 3a 0a 0a  ckpoint().API:..
eda0: 3c 76 65 72 62 61 74 69 6d 3e 0a 20 20 69 6e 74  <verbatim>.  int
edb0: 20 6c 73 6d 5f 63 68 65 63 6b 70 6f 69 6e 74 28   lsm_checkpoint(
edc0: 6c 73 6d 5f 64 62 20 2a 64 62 2c 20 69 6e 74 20  lsm_db *db, int 
edd0: 2a 70 6e 43 6b 70 74 29 3b 0a 3c 2f 76 65 72 62  *pnCkpt);.</verb
ede0: 61 74 69 6d 3e 0a 0a 3c 70 3e 49 66 20 6e 6f 20  atim>..<p>If no 
edf0: 77 6f 72 6b 20 68 61 73 20 62 65 65 6e 20 70 65  work has been pe
ee00: 72 66 6f 72 6d 65 64 20 6f 6e 20 74 68 65 20 64  rformed on the d
ee10: 61 74 61 62 61 73 65 20 73 69 6e 63 65 20 74 68  atabase since th
ee20: 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a 63 68  e most recent.ch
ee30: 65 63 6b 70 6f 69 6e 74 20 28 69 6d 70 6c 79 69  eckpoint (implyi
ee40: 6e 67 20 74 68 61 74 20 74 68 65 20 73 6e 61 70  ng that the snap
ee50: 73 68 6f 74 20 68 61 73 20 6e 6f 74 20 63 68 61  shot has not cha
ee60: 6e 67 65 64 20 61 6e 64 20 74 68 65 72 65 20 69  nged and there i
ee70: 73 20 6e 6f 20 6e 65 65 64 0a 74 6f 20 77 72 69  s no need.to wri
ee80: 74 65 20 69 74 20 69 6e 74 6f 20 74 68 65 20 64  te it into the d
ee90: 61 74 61 62 61 73 65 20 66 69 6c 65 29 2c 20 6c  atabase file), l
eea0: 73 6d 5f 63 68 65 63 6b 70 6f 69 6e 74 28 29 20  sm_checkpoint() 
eeb0: 73 65 74 73 20 2a 70 6e 43 6b 70 74 20 74 6f 20  sets *pnCkpt to 
eec0: 7a 65 72 6f 0a 61 6e 64 20 72 65 74 75 72 6e 73  zero.and returns
eed0: 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 20 4f 74   immediately. Ot
eee0: 68 65 72 77 69 73 65 2c 20 69 74 20 63 68 65 63  herwise, it chec
eef0: 6b 70 6f 69 6e 74 73 20 74 68 65 20 64 61 74 61  kpoints the data
ef00: 62 61 73 65 20 61 6e 64 20 73 65 74 73 0a 2a 70  base and sets.*p
ef10: 6e 43 6b 70 74 20 74 6f 20 74 68 65 20 6e 75 6d  nCkpt to the num
ef20: 62 65 72 20 6f 66 20 62 79 74 65 73 20 77 72 69  ber of bytes wri
ef30: 74 74 65 6e 20 74 6f 20 74 68 65 20 64 61 74 61  tten to the data
ef40: 62 61 73 65 20 66 69 6c 65 20 73 69 6e 63 65 20  base file since 
ef50: 74 68 65 0a 70 72 65 76 69 6f 75 73 20 63 68 65  the.previous che
ef60: 63 6b 70 6f 69 6e 74 2e 0a 0a 3c 70 3e 54 68 65  ckpoint...<p>The
ef70: 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
ef80: 20 77 72 69 74 74 65 6e 20 74 6f 20 74 68 65 20   written to the 
ef90: 64 61 74 61 62 61 73 65 20 73 69 6e 63 65 20 74  database since t
efa0: 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
efb0: 68 65 63 6b 70 6f 69 6e 74 0a 63 61 6e 20 61 6c  heckpoint.can al
efc0: 73 6f 20 62 65 20 75 73 69 6e 67 20 74 68 65 20  so be using the 
efd0: 3c 61 20 68 72 65 66 3d 6c 73 6d 61 70 69 2e 77  <a href=lsmapi.w
efe0: 69 6b 69 23 6c 73 6d 5f 69 6e 66 6f 3e 6c 73 6d  iki#lsm_info>lsm
eff0: 5f 69 6e 66 6f 28 29 3c 2f 61 3e 20 41 50 49 20  _info()</a> API 
f000: 0a 66 75 6e 63 74 69 6f 6e 2e 20 41 73 20 66 6f  .function. As fo
f010: 6c 6c 6f 77 73 3a 0a 0a 3c 76 65 72 62 61 74 69  llows:..<verbati
f020: 6d 3e 0a 20 20 69 6e 74 20 6e 43 6b 70 74 3b 0a  m>.  int nCkpt;.
f030: 20 20 72 63 20 3d 20 6c 73 6d 5f 69 6e 66 6f 28    rc = lsm_info(
f040: 64 62 2c 20 4c 53 4d 5f 49 4e 46 4f 5f 43 48 45  db, LSM_INFO_CHE
f050: 43 4b 50 4f 49 4e 54 5f 53 49 5a 45 2c 20 26 6e  CKPOINT_SIZE, &n
f060: 43 6b 70 74 29 3b 0a 3c 2f 76 65 72 62 61 74 69  Ckpt);.</verbati
f070: 6d 3e 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20  m>..<verbatim>. 
f080: 20 69 6e 74 20 6e 4f 6c 64 2c 20 6e 4c 69 76 65   int nOld, nLive
f090: 3b 0a 20 20 72 63 20 3d 20 6c 73 6d 5f 69 6e 66  ;.  rc = lsm_inf
f0a0: 6f 28 64 62 2c 20 4c 53 4d 5f 49 4e 46 4f 5f 54  o(db, LSM_INFO_T
f0b0: 52 45 45 5f 53 49 5a 45 2c 20 26 6e 4f 6c 64 2c  REE_SIZE, &nOld,
f0c0: 20 26 6e 4c 69 76 65 29 3b 0a 3c 2f 76 65 72 62   &nLive);.</verb
f0d0: 61 74 69 6d 3e 0a 0a 3c 68 33 20 69 64 3d 63 6f  atim>..<h3 id=co
f0e0: 6d 70 75 6c 73 61 72 79 5f 77 6f 72 6b 5f 61 6e  mpulsary_work_an
f0f0: 64 5f 63 68 65 63 6b 70 6f 69 6e 74 5f 73 63 68  d_checkpoint_sch
f100: 65 64 75 6c 69 6e 67 3e 36 2e 32 2e 34 2e 20 43  eduling>6.2.4. C
f110: 6f 6d 70 75 6c 73 61 72 79 20 57 6f 72 6b 20 61  ompulsary Work a
f120: 6e 64 20 43 68 65 63 6b 70 6f 69 6e 74 20 53 63  nd Checkpoint Sc
f130: 68 65 64 75 6c 69 6e 67 3c 2f 68 33 3e 0a 0a 3c  heduling</h3>..<
f140: 70 3e 41 70 61 72 74 20 66 72 6f 6d 20 74 68 65  p>Apart from the
f150: 20 73 63 65 6e 61 72 69 6f 73 20 64 65 73 63 72   scenarios descr
f160: 69 62 65 64 20 61 62 6f 76 65 2c 20 74 68 65 72  ibed above, ther
f170: 65 20 61 72 65 20 74 77 6f 20 74 68 65 72 65 20  e are two there 
f180: 61 72 65 20 74 77 6f 20 0a 73 63 65 6e 61 72 69  are two .scenari
f190: 6f 73 20 77 68 65 72 65 20 64 61 74 61 62 61 73  os where databas
f1a0: 65 20 77 6f 72 6b 20 6f 72 20 63 68 65 63 6b 70  e work or checkp
f1b0: 6f 69 6e 74 69 6e 67 20 6d 61 79 20 62 65 20 70  ointing may be p
f1c0: 65 72 66 6f 72 6d 65 64 20 61 75 74 6f 6d 61 74  erformed automat
f1d0: 69 63 61 6c 6c 79 2c 0a 72 65 67 61 72 64 6c 65  ically,.regardle
f1e0: 73 73 20 6f 66 20 74 68 65 20 76 61 6c 75 65 20  ss of the value 
f1f0: 6f 66 20 74 68 65 20 4c 53 4d 5f 43 4f 4e 46 49  of the LSM_CONFI
f200: 47 5f 41 55 54 4f 57 4f 52 4b 20 70 61 72 61 6d  G_AUTOWORK param
f210: 65 74 65 72 2e 0a 0a 3c 75 6c 3e 0a 20 20 3c 6c  eter...<ul>.  <l
f220: 69 3e 20 57 68 65 6e 20 63 6c 6f 73 69 6e 67 20  i> When closing 
f230: 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
f240: 63 74 69 6f 6e 2c 20 61 6e 64 20 0a 20 20 3c 6c  ction, and .  <l
f250: 69 3e 20 57 68 65 6e 20 74 68 65 20 6e 75 6d 62  i> When the numb
f260: 65 72 20 6f 66 20 73 65 67 6d 65 6e 74 73 20 77  er of segments w
f270: 69 74 68 20 61 20 63 6f 6d 6d 6f 6e 20 61 67 65  ith a common age
f280: 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   in the database
f290: 20 66 69 6c 65 20 67 72 6f 77 73 0a 20 20 20 20   file grows.    
f2a0: 20 20 20 75 6e 61 63 63 65 70 74 61 62 6c 79 20     unacceptably 
f2b0: 68 69 67 68 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e  high..</ul>..<p>
f2c0: 57 68 65 6e 65 76 65 72 20 61 6e 20 6c 73 6d 5f  Whenever an lsm_
f2d0: 63 6c 6f 73 65 28 29 20 63 61 6c 6c 20 77 6f 75  close() call wou
f2e0: 6c 64 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ld mean that the
f2f0: 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66   total number of
f300: 20 0a 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f   .connections to
f310: 20 61 20 64 61 74 61 62 61 73 65 20 64 72 6f 70   a database drop
f320: 73 20 74 6f 20 7a 65 72 6f 2c 20 74 68 65 20 63  s to zero, the c
f330: 6f 6e 6e 65 63 74 69 6f 6e 20 63 68 65 63 6b 73  onnection checks
f340: 20 69 66 20 74 68 65 20 0a 69 6e 2d 6d 65 6d 6f   if the .in-memo
f350: 72 79 20 74 72 65 65 20 69 73 20 65 6d 70 74 79  ry tree is empty
f360: 2e 20 49 66 20 6e 6f 74 2c 20 69 74 20 69 73 20  . If not, it is 
f370: 66 6c 75 73 68 65 64 20 74 6f 20 64 69 73 6b 2e  flushed to disk.
f380: 20 42 6f 74 68 20 74 68 65 20 6c 69 76 65 20 61   Both the live a
f390: 6e 64 20 0a 6f 6c 64 20 69 6e 2d 6d 65 6d 6f 72  nd .old in-memor
f3a0: 79 20 74 72 65 65 73 20 61 72 65 20 66 6c 75 73  y trees are flus
f3b0: 68 65 64 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  hed to disk in t
f3c0: 68 69 73 20 63 61 73 65 2e 20 49 74 20 61 6c 73  his case. It als
f3d0: 6f 20 63 68 65 63 6b 73 20 69 66 20 74 68 65 0a  o checks if the.
f3e0: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68 61  database file ha
f3f0: 73 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 20  s been modified 
f400: 73 69 6e 63 65 20 74 68 65 20 6d 6f 73 74 20 72  since the most r
f410: 65 63 65 6e 74 20 63 68 65 63 6b 70 6f 69 6e 74  ecent checkpoint
f420: 20 77 61 73 20 0a 70 65 72 66 6f 72 6d 65 64 2e   was .performed.
f430: 20 49 66 20 73 6f 2c 20 69 74 20 61 6c 73 6f 20   If so, it also 
f440: 70 65 72 66 6f 72 6d 73 20 61 20 63 68 65 63 6b  performs a check
f450: 70 6f 69 6e 74 2e 20 41 6e 64 2c 20 61 73 73 75  point. And, assu
f460: 6d 69 6e 67 20 6e 6f 20 65 72 72 6f 72 0a 68 61  ming no error.ha
f470: 73 20 6f 63 63 75 72 72 65 64 2c 20 64 65 6c 65  s occurred, dele
f480: 74 65 73 20 74 68 65 20 6c 6f 67 20 66 69 6c 65  tes the log file
f490: 2e 0a 0a 3c 70 3e 41 64 64 69 74 69 6f 6e 61 6c  ...<p>Additional
f4a0: 6c 79 2c 20 77 68 65 6e 65 76 65 72 20 61 20 77  ly, whenever a w
f4b0: 6f 72 6b 65 72 20 77 69 73 68 65 73 20 74 6f 20  orker wishes to 
f4c0: 66 6c 75 73 68 20 61 6e 20 69 6e 2d 6d 65 6d 6f  flush an in-memo
f4d0: 72 79 20 74 72 65 65 20 74 6f 20 61 20 6e 65 77  ry tree to a new
f4e0: 0a 61 67 65 3d 31 20 73 65 67 6d 65 6e 74 2c 20  .age=1 segment, 
f4f0: 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 65 6e  it must first en
f500: 73 75 72 65 20 74 68 61 74 20 74 68 65 72 65 20  sure that there 
f510: 61 72 65 20 6c 65 73 73 20 74 68 61 6e 20 4e 20  are less than N 
f520: 65 78 69 73 74 69 6e 67 20 61 67 65 3d 31 0a 73  existing age=1.s
f530: 65 67 6d 65 6e 74 73 2c 20 77 68 65 72 65 20 4e  egments, where N
f540: 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74 68   is the value th
f550: 61 74 20 74 68 65 20 4c 53 4d 5f 43 4f 4e 46 49  at the LSM_CONFI
f560: 47 5f 41 55 54 4f 4d 45 52 47 45 20 70 61 72 61  G_AUTOMERGE para
f570: 6d 65 74 65 72 20 69 73 0a 73 65 74 20 74 6f 2e  meter is.set to.
f580: 20 49 66 20 74 68 65 72 65 20 61 72 65 20 61 6c   If there are al
f590: 72 65 61 64 79 20 4e 20 6f 72 20 6d 6f 72 65 20  ready N or more 
f5a0: 61 67 65 3d 31 20 73 65 67 6d 65 6e 74 73 2c 20  age=1 segments, 
f5b0: 74 68 65 79 20 6d 75 73 74 20 62 65 20 6d 65 72  they must be mer
f5c0: 67 65 64 0a 69 6e 74 6f 20 61 6e 20 61 67 65 3d  ged.into an age=
f5d0: 32 20 73 65 67 6d 65 6e 74 20 62 65 66 6f 72 65  2 segment before
f5e0: 20 61 20 6e 65 77 20 61 67 65 3d 31 20 73 65 67   a new age=1 seg
f5f0: 6d 65 6e 74 20 63 61 6e 20 62 65 20 63 72 65 61  ment can be crea
f600: 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 0a 64  ted within the.d
f610: 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20 53 69  atabase file. Si
f620: 6d 69 6c 61 72 20 72 75 6c 65 73 20 61 70 70 6c  milar rules appl
f630: 79 20 74 6f 20 73 65 67 6d 65 6e 74 73 20 6f 66  y to segments of
f640: 20 6f 74 68 65 72 20 61 67 65 73 20 2d 20 69 74   other ages - it
f650: 20 69 73 20 6e 6f 74 0a 70 6f 73 73 69 62 6c 65   is not.possible
f660: 20 74 6f 20 63 72 65 61 74 65 20 61 20 6e 65 77   to create a new
f670: 20 61 67 65 3d 49 20 73 65 67 6d 65 6e 74 20 69   age=I segment i
f680: 66 20 74 68 65 72 65 20 61 72 65 20 61 6c 72 65  f there are alre
f690: 61 64 79 20 4e 20 73 65 67 6d 65 6e 74 73 20 77  ady N segments w
f6a0: 69 74 68 0a 61 67 65 3d 49 20 69 6e 20 74 68 65  ith.age=I in the
f6b0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e 20   database file. 
f6c0: 54 68 69 73 20 68 61 73 20 74 77 6f 20 69 6d 70  This has two imp
f6d0: 6c 69 63 61 74 69 6f 6e 73 3a 0a 0a 3c 75 6c 3e  lications:..<ul>
f6e0: 0a 20 20 3c 6c 69 3e 20 54 68 65 20 64 61 74 61  .  <li> The data
f6f0: 62 61 73 65 20 69 73 20 70 72 65 76 65 6e 74 65  base is prevente
f700: 64 20 66 72 6f 6d 20 61 63 63 75 6d 75 6c 61 74  d from accumulat
f710: 69 6e 67 20 74 6f 6f 20 6d 61 6e 79 20 73 65 67  ing too many seg
f720: 6d 65 6e 74 73 2c 0a 20 20 20 20 20 20 20 72 65  ments,.       re
f730: 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
f740: 68 65 72 20 6f 72 20 6e 6f 74 20 61 75 74 6f 2d  her or not auto-
f750: 77 6f 72 6b 20 69 73 20 65 6e 61 62 6c 65 64 20  work is enabled 
f760: 6f 72 20 68 6f 77 20 69 6e 66 72 65 71 75 65 6e  or how infrequen
f770: 74 6c 79 0a 20 20 20 20 20 20 20 6c 73 6d 5f 77  tly.       lsm_w
f780: 6f 72 6b 28 29 20 69 73 20 63 61 6c 6c 65 64 2c  ork() is called,
f790: 20 61 6e 64 0a 0a 20 20 3c 6c 69 3e 20 49 66 20   and..  <li> If 
f7a0: 61 75 74 6f 2d 77 6f 72 6b 20 69 73 20 64 69 73  auto-work is dis
f7b0: 61 62 6c 65 64 20 61 6e 64 20 6c 73 6d 5f 77 6f  abled and lsm_wo
f7c0: 72 6b 28 29 20 69 73 20 6e 6f 74 20 63 61 6c 6c  rk() is not call
f7d0: 65 64 20 66 72 65 71 75 65 6e 74 6c 79 20 65 6e  ed frequently en
f7e0: 6f 75 67 68 2c 0a 20 20 20 20 20 20 20 69 74 20  ough,.       it 
f7f0: 69 73 20 70 6f 73 73 69 62 6c 65 20 74 68 61 74  is possible that
f800: 20 66 6c 75 73 68 69 6e 67 20 61 6e 20 69 6e 2d   flushing an in-
f810: 6d 65 6d 6f 72 79 20 74 72 65 65 20 6d 61 79 20  memory tree may 
f820: 72 65 71 75 69 72 65 64 20 77 72 69 74 69 6e 67  required writing
f830: 20 61 0a 20 20 20 20 20 20 20 74 72 65 6d 65 6e   a.       tremen
f840: 64 6f 75 73 20 61 6d 6f 75 6e 74 20 6f 66 20 64  dous amount of d
f850: 61 74 61 20 74 6f 20 64 69 73 6b 20 28 70 6f 73  ata to disk (pos
f860: 73 69 62 6c 79 20 65 76 65 6e 20 72 65 77 72 69  sibly even rewri
f870: 74 69 6e 67 20 74 68 65 20 65 6e 74 69 72 65 0a  ting the entire.
f880: 20 20 20 20 20 20 20 64 61 74 61 62 61 73 65 20         database 
f890: 66 69 6c 65 29 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70  file)..</ul>..<p
f8a0: 3e 46 69 6e 61 6c 6c 79 2c 20 72 65 67 61 72 64  >Finally, regard
f8b0: 6c 65 73 73 20 6f 66 20 61 67 65 2c 20 61 20 64  less of age, a d
f8c0: 61 74 61 62 61 73 65 20 69 73 20 6c 69 6d 69 74  atabase is limit
f8d0: 65 64 20 74 6f 20 61 20 6d 61 78 69 6d 75 6d 20  ed to a maximum 
f8e0: 6f 66 20 36 34 0a 73 65 67 6d 65 6e 74 73 20 69  of 64.segments i
f8f0: 6e 20 74 6f 74 61 6c 2e 20 49 66 20 61 6e 20 61  n total. If an a
f900: 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20 74  ttempt is made t
f910: 6f 20 66 6c 75 73 68 20 61 6e 20 69 6e 2d 6d 65  o flush an in-me
f920: 6d 6f 72 79 20 74 72 65 65 20 74 6f 20 64 69 73  mory tree to dis
f930: 6b 0a 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  k.when the datab
f940: 61 73 65 20 61 6c 72 65 61 64 79 20 63 6f 6e 74  ase already cont
f950: 61 69 6e 73 20 36 34 20 73 65 67 6d 65 6e 74 73  ains 64 segments
f960: 2c 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 65 78  , two or more ex
f970: 69 73 74 69 6e 67 20 73 65 67 6d 65 6e 74 73 0a  isting segments.
f980: 6d 75 73 74 20 62 65 20 6d 65 72 67 65 64 20 74  must be merged t
f990: 6f 67 65 74 68 65 72 20 62 65 66 6f 72 65 20 74  ogether before t
f9a0: 68 65 20 6e 65 77 20 73 65 67 6d 65 6e 74 20 63  he new segment c
f9b0: 61 6e 20 62 65 20 63 72 65 61 74 65 64 2e 0a 0a  an be created...
f9c0: 3c 68 32 20 69 64 3d 64 61 74 61 62 61 73 65 5f  <h2 id=database_
f9d0: 66 69 6c 65 5f 6f 70 74 69 6d 69 7a 61 74 69 6f  file_optimizatio
f9e0: 6e 3e 36 2e 33 2e 20 44 61 74 61 62 61 73 65 20  n>6.3. Database 
f9f0: 46 69 6c 65 20 4f 70 74 69 6d 69 7a 61 74 69 6f  File Optimizatio
fa00: 6e 3c 2f 68 32 3e 0a 0a 3c 70 3e 44 61 74 61 62  n</h2>..<p>Datab
fa10: 61 73 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e  ase optimization
fa20: 20 74 72 61 6e 73 66 6f 72 6d 73 20 74 68 65 20   transforms the 
fa30: 63 6f 6e 74 65 6e 74 73 20 6f 66 20 64 61 74 61  contents of data
fa40: 62 61 73 65 20 66 69 6c 65 20 73 6f 20 74 68 61  base file so tha
fa50: 74 0a 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  t.the following 
fa60: 61 72 65 20 74 72 75 65 3a 0a 0a 3c 75 6c 3e 0a  are true:..<ul>.
fa70: 20 20 3c 6c 69 3e 20 3c 70 3e 41 6c 6c 20 64 61    <li> <p>All da
fa80: 74 61 62 61 73 65 20 63 6f 6e 74 65 6e 74 20 69  tabase content i
fa90: 73 20 73 74 6f 72 65 64 20 69 6e 20 61 20 73 69  s stored in a si
faa0: 6e 67 6c 65 20 0a 20 20 20 20 20 20 20 3c 61 20  ngle .       <a 
fab0: 68 72 65 66 3d 23 61 72 63 68 69 74 65 63 74 75  href=#architectu
fac0: 72 61 6c 5f 6f 76 65 72 76 69 65 77 3e 73 65 67  ral_overview>seg
fad0: 6d 65 6e 74 3c 2f 61 3e 2e 20 54 68 69 73 20 6d  ment</a>. This m
fae0: 61 6b 65 73 20 74 68 65 0a 20 20 20 20 20 20 20  akes the.       
faf0: 64 61 74 61 62 61 73 65 20 65 66 66 65 63 74 69  database effecti
fb00: 76 65 6c 79 20 65 71 75 69 76 61 6c 65 6e 74 20  vely equivalent 
fb10: 74 6f 20 61 6e 20 6f 70 74 69 6d 61 6c 6c 79 20  to an optimally 
fb20: 70 61 63 6b 65 64 20 62 2d 74 72 65 65 20 73 74  packed b-tree st
fb30: 75 63 74 75 72 65 0a 20 20 20 20 20 20 20 66 6f  ucture.       fo
fb40: 72 20 73 65 61 72 63 68 20 6f 70 65 72 61 74 69  r search operati
fb50: 6f 6e 73 20 2d 20 6d 69 6e 69 6d 69 7a 69 6e 67  ons - minimizing
fb60: 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64   the number of d
fb70: 69 73 6b 20 73 65 63 74 6f 72 73 20 74 68 61 74  isk sectors that
fb80: 20 6e 65 65 64 0a 20 20 20 20 20 20 20 74 6f 20   need.       to 
fb90: 62 65 20 76 69 73 74 65 64 20 77 68 65 6e 20 73  be visted when s
fba0: 65 61 72 63 68 69 6e 67 20 74 68 65 20 64 61 74  earching the dat
fbb0: 61 62 61 73 65 2e 0a 0a 20 20 3c 6c 69 3e 20 3c  abase...  <li> <
fbc0: 70 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 66  p>The database f
fbd0: 69 6c 65 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ile contains no 
fbe0: 28 6f 72 20 61 73 20 6c 69 74 74 6c 65 20 61 73  (or as little as
fbf0: 20 70 6f 73 73 69 62 6c 65 29 20 66 72 65 65 20   possible) free 
fc00: 73 70 61 63 65 2e 0a 20 20 20 20 20 20 20 49 6e  space..       In
fc10: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 74   other words, it
fc20: 20 69 73 20 6e 6f 20 6c 61 72 67 65 72 20 74 68   is no larger th
fc30: 61 6e 20 72 65 71 75 69 72 65 64 20 74 6f 20 63  an required to c
fc40: 6f 6e 74 61 69 6e 20 74 68 65 20 73 69 6e 67 6c  ontain the singl
fc50: 65 0a 20 20 20 20 20 20 20 73 65 67 6d 65 6e 74  e.       segment
fc60: 2e 0a 3c 2f 75 6c 3e 0a 0a 3c 70 3e 3c 69 3e 20  ..</ul>..<p><i> 
fc70: 53 68 6f 75 6c 64 20 77 65 20 61 64 64 20 61 20  Should we add a 
fc80: 63 6f 6e 76 65 6e 69 65 6e 63 65 20 66 75 6e 63  convenience func
fc90: 74 69 6f 6e 20 6c 73 6d 5f 6f 70 74 69 6d 69 7a  tion lsm_optimiz
fca0: 65 28 29 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  e() that does no
fcb0: 74 20 0a 72 65 74 75 72 6e 20 75 6e 74 69 6c 20  t .return until 
fcc0: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
fcd0: 63 6f 6d 70 6c 65 74 65 6c 79 20 6f 70 74 69 6d  completely optim
fce0: 69 7a 65 64 3f 20 4f 6e 65 20 74 68 61 74 20 6d  ized? One that m
fcf0: 6f 72 65 20 6f 72 20 6c 65 73 73 20 64 6f 65 73  ore or less does
fd00: 0a 74 68 65 20 73 61 6d 65 20 61 73 20 74 68 65  .the same as the
fd10: 20 65 78 61 6d 70 6c 65 20 63 6f 64 65 20 62 65   example code be
fd20: 6c 6f 77 20 61 6e 64 20 64 65 61 6c 73 20 77 69  low and deals wi
fd30: 74 68 20 74 68 65 20 41 55 54 4f 43 48 45 43 4b  th the AUTOCHECK
fd40: 50 4f 49 4e 54 20 69 73 73 75 65 3f 0a 54 68 69  POINT issue?.Thi
fd50: 73 20 77 6f 75 6c 64 20 68 65 6c 70 20 77 69 74  s would help wit
fd60: 68 20 74 68 69 73 20 75 73 65 72 20 6d 61 6e 75  h this user manu
fd70: 61 6c 20 69 66 20 6e 6f 74 68 69 6e 67 20 65 6c  al if nothing el
fd80: 73 65 2c 20 61 73 20 69 74 20 6d 65 61 6e 73 20  se, as it means 
fd90: 61 20 6d 65 74 68 6f 64 0a 66 6f 72 20 64 61 74  a method.for dat
fda0: 61 62 61 73 65 20 6f 70 74 69 6d 69 7a 61 74 69  abase optimizati
fdb0: 6f 6e 20 63 61 6e 20 62 65 20 70 72 65 73 65 6e  on can be presen
fdc0: 74 65 64 20 77 69 74 68 6f 75 74 20 64 65 70 65  ted without depe
fdd0: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 70 72 65  nding on the pre
fde0: 76 69 6f 75 73 0a 73 65 63 74 69 6f 6e 2e 0a 0a  vious.section...
fdf0: 3c 2f 69 3e 0a 0a 3c 70 3e 49 6e 20 6f 72 64 65  </i>..<p>In orde
fe00: 72 20 74 6f 20 6f 70 74 69 6d 69 7a 65 20 74 68  r to optimize th
fe10: 65 20 64 61 74 61 62 61 73 65 2c 20 6c 73 6d 5f  e database, lsm_
fe20: 77 6f 72 6b 28 29 20 73 68 6f 75 6c 64 20 62 65  work() should be
fe30: 20 63 61 6c 6c 65 64 20 72 65 70 65 61 74 65 64   called repeated
fe40: 6c 79 0a 77 69 74 68 20 74 68 65 20 6e 4d 65 72  ly.with the nMer
fe50: 67 65 20 61 72 67 75 6d 65 6e 74 20 73 65 74 20  ge argument set 
fe60: 74 6f 20 31 20 75 6e 74 69 6c 20 69 74 20 72 65  to 1 until it re
fe70: 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20 77 72  turns without wr
fe80: 69 74 69 6e 67 20 61 6e 79 20 64 61 74 61 0a 74  iting any data.t
fe90: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
fea0: 69 6c 65 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65  ile. For example
feb0: 3a 0a 0a 3c 76 65 72 62 61 74 69 6d 3e 0a 20 20  :..<verbatim>.  
fec0: 69 6e 74 20 6e 57 72 69 74 65 3b 0a 20 20 69 6e  int nWrite;.  in
fed0: 74 20 72 63 3b 0a 20 20 64 6f 20 7b 0a 20 20 20  t rc;.  do {.   
fee0: 20 72 63 20 3d 20 6c 73 6d 5f 77 6f 72 6b 28 64   rc = lsm_work(d
fef0: 62 2c 20 31 2c 20 32 2a 31 30 32 34 2a 31 30 32  b, 1, 2*1024*102
ff00: 34 2c 20 26 6e 57 72 69 74 65 29 3b 0a 20 20 7d  4, &nWrite);.  }
ff10: 77 68 69 6c 65 28 20 72 63 3d 3d 4c 53 4d 5f 4f  while( rc==LSM_O
ff20: 4b 20 26 26 20 6e 57 72 69 74 65 3e 30 20 29 3b  K && nWrite>0 );
ff30: 0a 3c 2f 76 65 72 62 61 74 69 6d 3e 0a 0a 3c 70  .</verbatim>..<p
ff40: 3e 57 68 65 6e 20 6f 70 74 69 6d 69 7a 69 6e 67  >When optimizing
ff50: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 73   the database as
ff60: 20 61 62 6f 76 65 2c 20 65 69 74 68 65 72 20 74   above, either t
ff70: 68 65 20 4c 53 4d 5f 43 4f 4e 46 49 47 5f 41 55  he LSM_CONFIG_AU
ff80: 54 4f 43 48 45 43 4b 50 4f 49 4e 54 0a 70 61 72  TOCHECKPOINT.par
ff90: 61 6d 65 74 65 72 20 73 68 6f 75 6c 64 20 62 65  ameter should be
ffa0: 20 73 65 74 20 74 6f 20 61 20 6e 6f 6e 2d 7a 65   set to a non-ze
ffb0: 72 6f 20 76 61 6c 75 65 20 6f 72 20 6c 73 6d 5f  ro value or lsm_
ffc0: 63 68 65 63 6b 70 6f 69 6e 74 28 29 20 73 68 6f  checkpoint() sho
ffd0: 75 6c 64 20 62 65 0a 63 61 6c 6c 65 64 20 70 65  uld be.called pe
ffe0: 72 69 6f 64 69 63 61 6c 6c 79 2e 20 4f 74 68 65  riodically. Othe
fff0: 72 77 69 73 65 2c 20 6e 6f 20 63 68 65 63 6b 70  rwise, no checkp
10000 6f 69 6e 74 73 20 77 69 6c 6c 20 62 65 20 70 65  oints will be pe
10010 72 66 6f 72 6d 65 64 2c 20 70 72 65 76 65 6e 74  rformed, prevent
10020 69 6e 67 0a 74 68 65 20 6c 69 62 72 61 72 79 20  ing.the library 
10030 66 72 6f 6d 20 72 65 75 73 69 6e 67 20 61 6e 79  from reusing any
10040 20 73 70 61 63 65 20 6f 63 63 75 70 69 65 64 20   space occupied 
10050 62 79 20 6f 6c 64 20 73 65 67 6d 65 6e 74 73 20  by old segments 
10060 65 76 65 6e 20 61 66 74 65 72 20 74 68 65 69 72  even after their
10070 0a 63 6f 6e 74 65 6e 74 20 68 61 73 20 62 65 65  .content has bee
10080 6e 20 6d 65 72 67 65 64 20 69 6e 74 6f 20 74 68  n merged into th
10090 65 20 6e 65 77 20 73 65 67 6d 65 6e 74 2e 20 54  e new segment. T
100a0 68 65 20 72 65 73 75 6c 74 20 2d 20 61 20 64 61  he result - a da
100b0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 61 74  tabase file that
100c0 0a 69 73 20 6f 70 74 69 6d 69 7a 65 64 2c 20 65  .is optimized, e
100d0 78 63 65 70 74 20 74 68 61 74 20 69 74 20 69 73  xcept that it is
100e0 20 75 70 20 74 6f 20 74 77 69 63 65 20 61 73 20   up to twice as 
100f0 6c 61 72 67 65 20 61 73 20 69 74 20 6f 74 68 65  large as it othe
10100 72 77 69 73 65 20 77 6f 75 6c 64 20 62 65 2e 0a  rwise would be..
10110 0a 0a                                            ..