/ Hex Artifact Content
Login

Artifact e12275968f6fde133a80e04387d0e839b0c51f91:


0000: 4e 4f 54 45 20 28 32 30 31 32 2d 31 31 2d 32 39  NOTE (2012-11-29
0010: 29 3a 0a 0a 54 68 65 20 66 75 6e 63 74 69 6f 6e  ):..The function
0020: 61 6c 69 74 79 20 69 6d 70 6c 65 6d 65 6e 74 65  ality implemente
0030: 64 20 62 79 20 74 68 69 73 20 65 78 74 65 6e 73  d by this extens
0040: 69 6f 6e 20 68 61 73 20 62 65 65 6e 20 73 75 70  ion has been sup
0050: 65 72 73 65 64 65 64 0a 62 79 20 57 41 4c 2d 6d  erseded.by WAL-m
0060: 6f 64 65 2e 20 20 54 68 69 73 20 6d 6f 64 75 6c  ode.  This modul
0070: 65 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 73  e is no longer s
0080: 75 70 70 6f 72 74 65 64 20 6f 72 20 6d 61 69 6e  upported or main
0090: 74 61 69 6e 65 64 2e 20 20 54 68 65 0a 63 6f 64  tained.  The.cod
00a0: 65 20 69 73 20 72 65 74 61 69 6e 65 64 20 66 6f  e is retained fo
00b0: 72 20 68 69 73 74 6f 72 69 63 61 6c 20 72 65 66  r historical ref
00c0: 65 72 65 6e 63 65 20 6f 6e 6c 79 2e 0a 0a 2d 2d  erence only...--
00d0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
00e0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
00f0: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
0100: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
0110: 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 0a 4e 6f  ------------..No
0120: 72 6d 61 6c 6c 79 2c 20 77 68 65 6e 20 53 51 4c  rmally, when SQL
0130: 69 74 65 20 77 72 69 74 65 73 20 74 6f 20 61 20  ite writes to a 
0140: 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20 69  database file, i
0150: 74 20 77 61 69 74 73 20 75 6e 74 69 6c 20 74 68  t waits until th
0160: 65 20 77 72 69 74 65 0a 6f 70 65 72 61 74 69 6f  e write.operatio
0170: 6e 20 69 73 20 66 69 6e 69 73 68 65 64 20 62 65  n is finished be
0180: 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 20 63  fore returning c
0190: 6f 6e 74 72 6f 6c 20 74 6f 20 74 68 65 20 63 61  ontrol to the ca
01a0: 6c 6c 69 6e 67 20 61 70 70 6c 69 63 61 74 69 6f  lling applicatio
01b0: 6e 2e 0a 53 69 6e 63 65 20 77 72 69 74 69 6e 67  n..Since writing
01c0: 20 74 6f 20 74 68 65 20 66 69 6c 65 2d 73 79 73   to the file-sys
01d0: 74 65 6d 20 69 73 20 75 73 75 61 6c 6c 79 20 76  tem is usually v
01e0: 65 72 79 20 73 6c 6f 77 20 63 6f 6d 70 61 72 65  ery slow compare
01f0: 64 20 77 69 74 68 20 43 50 55 0a 62 6f 75 6e 64  d with CPU.bound
0200: 20 6f 70 65 72 61 74 69 6f 6e 73 2c 20 74 68 69   operations, thi
0210: 73 20 63 61 6e 20 62 65 20 61 20 70 65 72 66 6f  s can be a perfo
0220: 72 6d 61 6e 63 65 20 62 6f 74 74 6c 65 6e 65 63  rmance bottlenec
0230: 6b 2e 20 54 68 69 73 20 64 69 72 65 63 74 6f 72  k. This director
0240: 79 0a 63 6f 6e 74 61 69 6e 73 20 61 6e 20 65 78  y.contains an ex
0250: 74 65 6e 73 69 6f 6e 20 74 68 61 74 20 63 61 75  tension that cau
0260: 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 70 65  ses SQLite to pe
0270: 72 66 6f 72 6d 20 61 6c 6c 20 77 72 69 74 65 20  rform all write 
0280: 72 65 71 75 65 73 74 73 0a 75 73 69 6e 67 20 61  requests.using a
0290: 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
02a0: 20 72 75 6e 6e 69 6e 67 20 69 6e 20 74 68 65 20   running in the 
02b0: 62 61 63 6b 67 72 6f 75 6e 64 2e 20 41 6c 74 68  background. Alth
02c0: 6f 75 67 68 20 74 68 69 73 20 64 6f 65 73 20 6e  ough this does n
02d0: 6f 74 0a 72 65 64 75 63 65 20 74 68 65 20 6f 76  ot.reduce the ov
02e0: 65 72 61 6c 6c 20 73 79 73 74 65 6d 20 72 65 73  erall system res
02f0: 6f 75 72 63 65 73 20 28 43 50 55 2c 20 64 69 73  ources (CPU, dis
0300: 6b 20 62 61 6e 64 77 69 64 74 68 20 65 74 63 2e  k bandwidth etc.
0310: 29 20 61 74 20 61 6c 6c 2c 20 69 74 0a 61 6c 6c  ) at all, it.all
0320: 6f 77 73 20 53 51 4c 69 74 65 20 74 6f 20 72 65  ows SQLite to re
0330: 74 75 72 6e 20 63 6f 6e 74 72 6f 6c 20 74 6f 20  turn control to 
0340: 74 68 65 20 63 61 6c 6c 65 72 20 71 75 69 63 6b  the caller quick
0350: 6c 79 20 65 76 65 6e 20 77 68 65 6e 20 77 72 69  ly even when wri
0360: 74 69 6e 67 20 74 6f 0a 74 68 65 20 64 61 74 61  ting to.the data
0370: 62 61 73 65 2c 20 65 6c 69 6d 69 6e 61 74 69 6e  base, eliminatin
0380: 67 20 74 68 65 20 62 6f 74 74 6c 65 6e 65 63 6b  g the bottleneck
0390: 2e 0a 0a 20 20 31 2e 20 46 75 6e 63 74 69 6f 6e  ...  1. Function
03a0: 61 6c 69 74 79 0a 0a 20 20 20 20 31 2e 31 20 48  ality..    1.1 H
03b0: 6f 77 20 69 74 20 57 6f 72 6b 73 0a 20 20 20 20  ow it Works.    
03c0: 31 2e 32 20 4c 69 6d 69 74 61 74 69 6f 6e 73 0a  1.2 Limitations.
03d0: 20 20 20 20 31 2e 33 20 4c 6f 63 6b 69 6e 67 20      1.3 Locking 
03e0: 61 6e 64 20 43 6f 6e 63 75 72 72 65 6e 63 79 0a  and Concurrency.
03f0: 0a 20 20 32 2e 20 43 6f 6d 70 69 6c 61 74 69 6f  .  2. Compilatio
0400: 6e 20 61 6e 64 20 55 73 61 67 65 0a 0a 20 20 33  n and Usage..  3
0410: 2e 20 50 6f 72 74 69 6e 67 0a 0a 0a 0a 31 2e 20  . Porting....1. 
0420: 46 55 4e 43 54 49 4f 4e 41 4c 49 54 59 0a 0a 20  FUNCTIONALITY.. 
0430: 20 57 69 74 68 20 61 73 79 6e 63 68 72 6f 6e 6f   With asynchrono
0440: 75 73 20 49 2f 4f 2c 20 77 72 69 74 65 20 72 65  us I/O, write re
0450: 71 75 65 73 74 73 20 61 72 65 20 68 61 6e 64 6c  quests are handl
0460: 65 64 20 62 79 20 61 20 73 65 70 61 72 61 74 65  ed by a separate
0470: 20 74 68 72 65 61 64 0a 20 20 72 75 6e 6e 69 6e   thread.  runnin
0480: 67 20 69 6e 20 74 68 65 20 62 61 63 6b 67 72 6f  g in the backgro
0490: 75 6e 64 2e 20 20 54 68 69 73 20 6d 65 61 6e 73  und.  This means
04a0: 20 74 68 61 74 20 74 68 65 20 74 68 72 65 61 64   that the thread
04b0: 20 74 68 61 74 20 69 6e 69 74 69 61 74 65 73 0a   that initiates.
04c0: 20 20 61 20 64 61 74 61 62 61 73 65 20 77 72 69    a database wri
04d0: 74 65 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  te does not have
04e0: 20 74 6f 20 77 61 69 74 20 66 6f 72 20 28 73 6f   to wait for (so
04f0: 6d 65 74 69 6d 65 73 20 73 6c 6f 77 29 20 64 69  metimes slow) di
0500: 73 6b 20 49 2f 4f 0a 20 20 74 6f 20 6f 63 63 75  sk I/O.  to occu
0510: 72 2e 20 20 54 68 65 20 77 72 69 74 65 20 73 65  r.  The write se
0520: 65 6d 73 20 74 6f 20 68 61 70 70 65 6e 20 76 65  ems to happen ve
0530: 72 79 20 71 75 69 63 6b 6c 79 2c 20 74 68 6f 75  ry quickly, thou
0540: 67 68 20 69 6e 20 72 65 61 6c 69 74 79 0a 20 20  gh in reality.  
0550: 69 74 20 69 73 20 68 61 70 70 65 6e 69 6e 67 20  it is happening 
0560: 61 74 20 69 74 73 20 75 73 75 61 6c 20 73 6c 6f  at its usual slo
0570: 77 20 70 61 63 65 20 69 6e 20 74 68 65 20 62 61  w pace in the ba
0580: 63 6b 67 72 6f 75 6e 64 2e 0a 0a 20 20 41 73 79  ckground...  Asy
0590: 6e 63 68 72 6f 6e 6f 75 73 20 49 2f 4f 20 61 70  nchronous I/O ap
05a0: 70 65 61 72 73 20 74 6f 20 67 69 76 65 20 62 65  pears to give be
05b0: 74 74 65 72 20 72 65 73 70 6f 6e 73 69 76 65 6e  tter responsiven
05c0: 65 73 73 2c 20 62 75 74 20 61 74 20 61 20 70 72  ess, but at a pr
05d0: 69 63 65 2e 0a 20 20 59 6f 75 20 6c 6f 73 65 20  ice..  You lose 
05e0: 74 68 65 20 44 75 72 61 62 6c 65 20 70 72 6f 70  the Durable prop
05f0: 65 72 74 79 2e 20 20 57 69 74 68 20 74 68 65 20  erty.  With the 
0600: 64 65 66 61 75 6c 74 20 49 2f 4f 20 62 61 63 6b  default I/O back
0610: 65 6e 64 20 6f 66 20 53 51 4c 69 74 65 2c 0a 20  end of SQLite,. 
0620: 20 6f 6e 63 65 20 61 20 77 72 69 74 65 20 63 6f   once a write co
0630: 6d 70 6c 65 74 65 73 2c 20 79 6f 75 20 6b 6e 6f  mpletes, you kno
0640: 77 20 74 68 61 74 20 74 68 65 20 69 6e 66 6f 72  w that the infor
0650: 6d 61 74 69 6f 6e 20 79 6f 75 20 77 72 6f 74 65  mation you wrote
0660: 20 69 73 0a 20 20 73 61 66 65 6c 79 20 6f 6e 20   is.  safely on 
0670: 64 69 73 6b 2e 20 20 57 69 74 68 20 74 68 65 20  disk.  With the 
0680: 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 2f 4f  asynchronous I/O
0690: 2c 20 74 68 69 73 20 69 73 20 6e 6f 74 20 74 68  , this is not th
06a0: 65 20 63 61 73 65 2e 20 20 49 66 0a 20 20 79 6f  e case.  If.  yo
06b0: 75 72 20 70 72 6f 67 72 61 6d 20 63 72 61 73 68  ur program crash
06c0: 65 73 20 6f 72 20 69 66 20 61 20 70 6f 77 65 72  es or if a power
06d0: 20 6c 6f 73 73 20 6f 63 63 75 72 73 20 61 66 74   loss occurs aft
06e0: 65 72 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  er the database.
06f0: 20 20 77 72 69 74 65 20 62 75 74 20 62 65 66 6f    write but befo
0700: 72 65 20 74 68 65 20 61 73 79 6e 63 68 72 6f 6e  re the asynchron
0710: 6f 75 73 20 77 72 69 74 65 20 74 68 72 65 61 64  ous write thread
0720: 20 68 61 73 20 63 6f 6d 70 6c 65 74 65 64 2c 20   has completed, 
0730: 74 68 65 6e 20 74 68 65 0a 20 20 64 61 74 61 62  then the.  datab
0740: 61 73 65 20 63 68 61 6e 67 65 20 6d 69 67 68 74  ase change might
0750: 20 6e 65 76 65 72 20 6d 61 6b 65 20 69 74 20 74   never make it t
0760: 6f 20 64 69 73 6b 20 61 6e 64 20 74 68 65 20 6e  o disk and the n
0770: 65 78 74 20 75 73 65 72 20 6f 66 20 74 68 65 0a  ext user of the.
0780: 20 20 64 61 74 61 62 61 73 65 20 6d 69 67 68 74    database might
0790: 20 6e 6f 74 20 73 65 65 20 79 6f 75 72 20 63 68   not see your ch
07a0: 61 6e 67 65 2e 0a 0a 20 20 59 6f 75 20 6c 6f 73  ange...  You los
07b0: 65 20 44 75 72 61 62 69 6c 69 74 79 20 77 69 74  e Durability wit
07c0: 68 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49  h asynchronous I
07d0: 2f 4f 2c 20 62 75 74 20 79 6f 75 20 73 74 69 6c  /O, but you stil
07e0: 6c 20 72 65 74 61 69 6e 20 74 68 65 0a 20 20 6f  l retain the.  o
07f0: 74 68 65 72 20 70 61 72 74 73 20 6f 66 20 41 43  ther parts of AC
0800: 49 44 3a 20 20 41 74 6f 6d 69 63 2c 20 20 43 6f  ID:  Atomic,  Co
0810: 6e 73 69 73 74 65 6e 74 2c 20 61 6e 64 20 49 73  nsistent, and Is
0820: 6f 6c 61 74 65 64 2e 20 20 4d 61 6e 79 0a 20 20  olated.  Many.  
0830: 61 70 70 6c 69 61 74 69 6f 6e 73 20 67 65 74 20  appliations get 
0840: 61 6c 6f 6e 67 20 66 69 6e 65 20 77 69 74 68 6f  along fine witho
0850: 75 74 20 74 68 65 20 44 75 72 61 62 6c 69 74 79  ut the Durablity
0860: 2e 0a 0a 20 20 31 2e 31 20 48 6f 77 20 69 74 20  ...  1.1 How it 
0870: 57 6f 72 6b 73 0a 0a 20 20 20 20 41 73 79 6e 63  Works..    Async
0880: 68 72 6f 6e 6f 75 73 20 49 2f 4f 20 77 6f 72 6b  hronous I/O work
0890: 73 20 62 79 20 63 72 65 61 74 69 6e 67 20 61 20  s by creating a 
08a0: 73 70 65 63 69 61 6c 20 53 51 4c 69 74 65 20 22  special SQLite "
08b0: 76 66 73 22 20 73 74 72 75 63 74 75 72 65 0a 20  vfs" structure. 
08c0: 20 20 20 61 6e 64 20 72 65 67 69 73 74 65 72 69     and registeri
08d0: 6e 67 20 69 74 20 77 69 74 68 20 73 71 6c 69 74  ng it with sqlit
08e0: 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28  e3_vfs_register(
08f0: 29 2e 20 57 68 65 6e 20 66 69 6c 65 73 20 6f 70  ). When files op
0900: 65 6e 65 64 20 76 69 61 20 0a 20 20 20 20 74 68  ened via .    th
0910: 69 73 20 76 66 73 20 61 72 65 20 77 72 69 74 74  is vfs are writt
0920: 65 6e 20 74 6f 20 28 75 73 69 6e 67 20 74 68 65  en to (using the
0930: 20 76 66 73 20 78 57 72 69 74 65 28 29 20 6d 65   vfs xWrite() me
0940: 74 68 6f 64 29 2c 20 74 68 65 20 64 61 74 61 20  thod), the data 
0950: 69 73 20 6e 6f 74 20 0a 20 20 20 20 77 72 69 74  is not .    writ
0960: 74 65 6e 20 64 69 72 65 63 74 6c 79 20 74 6f 20  ten directly to 
0970: 64 69 73 6b 2c 20 62 75 74 20 69 73 20 70 6c 61  disk, but is pla
0980: 63 65 64 20 69 6e 20 74 68 65 20 22 77 72 69 74  ced in the "writ
0990: 65 2d 71 75 65 75 65 22 20 74 6f 20 62 65 0a 20  e-queue" to be. 
09a0: 20 20 20 68 61 6e 64 6c 65 64 20 62 79 20 74 68     handled by th
09b0: 65 20 62 61 63 6b 67 72 6f 75 6e 64 20 74 68 72  e background thr
09c0: 65 61 64 2e 0a 0a 20 20 20 20 57 68 65 6e 20 66  ead...    When f
09d0: 69 6c 65 73 20 6f 70 65 6e 65 64 20 77 69 74 68  iles opened with
09e0: 20 74 68 65 20 61 73 79 6e 63 68 72 6f 6e 6f 75   the asynchronou
09f0: 73 20 76 66 73 20 61 72 65 20 72 65 61 64 20 66  s vfs are read f
0a00: 72 6f 6d 20 0a 20 20 20 20 28 75 73 69 6e 67 20  rom .    (using 
0a10: 74 68 65 20 76 66 73 20 78 52 65 61 64 28 29 20  the vfs xRead() 
0a20: 6d 65 74 68 6f 64 29 2c 20 74 68 65 20 64 61 74  method), the dat
0a30: 61 20 69 73 20 72 65 61 64 20 66 72 6f 6d 20 74  a is read from t
0a40: 68 65 20 66 69 6c 65 20 6f 6e 20 0a 20 20 20 20  he file on .    
0a50: 64 69 73 6b 20 61 6e 64 20 74 68 65 20 77 72 69  disk and the wri
0a60: 74 65 2d 71 75 65 75 65 2c 20 73 6f 20 74 68 61  te-queue, so tha
0a70: 74 20 66 72 6f 6d 20 74 68 65 20 70 6f 69 6e 74  t from the point
0a80: 20 6f 66 20 76 69 65 77 20 6f 66 0a 20 20 20 20   of view of.    
0a90: 74 68 65 20 76 66 73 20 72 65 61 64 65 72 20 74  the vfs reader t
0aa0: 68 65 20 78 57 72 69 74 65 28 29 20 61 70 70 65  he xWrite() appe
0ab0: 61 72 73 20 74 6f 20 68 61 76 65 20 61 6c 72 65  ars to have alre
0ac0: 61 64 79 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 0a  ady completed...
0ad0: 20 20 20 20 54 68 65 20 73 70 65 63 69 61 6c 20      The special 
0ae0: 76 66 73 20 69 73 20 72 65 67 69 73 74 65 72 65  vfs is registere
0af0: 64 20 28 61 6e 64 20 75 6e 72 65 67 69 73 74 65  d (and unregiste
0b00: 72 65 64 29 20 62 79 20 63 61 6c 6c 73 20 74 6f  red) by calls to
0b10: 20 74 68 65 20 0a 20 20 20 20 41 50 49 20 66 75   the .    API fu
0b20: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 61  nctions sqlite3a
0b30: 73 79 6e 63 5f 69 6e 69 74 69 61 6c 69 7a 65 28  sync_initialize(
0b40: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 61 73 79  ) and sqlite3asy
0b50: 6e 63 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 20  nc_shutdown().. 
0b60: 20 20 20 53 65 65 20 73 65 63 74 69 6f 6e 20 22     See section "
0b70: 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 61 6e 64 20  Compilation and 
0b80: 55 73 61 67 65 22 20 62 65 6c 6f 77 20 66 6f 72  Usage" below for
0b90: 20 64 65 74 61 69 6c 73 2e 0a 0a 20 20 31 2e 32   details...  1.2
0ba0: 20 4c 69 6d 69 74 61 74 69 6f 6e 73 0a 0a 20 20   Limitations..  
0bb0: 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 67 61    In order to ga
0bc0: 69 6e 20 65 78 70 65 72 69 65 6e 63 65 20 77 69  in experience wi
0bd0: 74 68 20 74 68 65 20 6d 61 69 6e 20 69 64 65 61  th the main idea
0be0: 73 20 73 75 72 72 6f 75 6e 64 69 6e 67 20 61 73  s surrounding as
0bf0: 79 6e 63 68 72 6f 6e 6f 75 73 20 0a 20 20 20 20  ynchronous .    
0c00: 49 4f 2c 20 74 68 69 73 20 69 6d 70 6c 65 6d 65  IO, this impleme
0c10: 6e 74 61 74 69 6f 6e 20 69 73 20 64 65 6c 69 62  ntation is delib
0c20: 65 72 61 74 65 6c 79 20 6b 65 70 74 20 73 69 6d  erately kept sim
0c30: 70 6c 65 2e 20 41 64 64 69 74 69 6f 6e 61 6c 20  ple. Additional 
0c40: 0a 20 20 20 20 63 61 70 61 62 69 6c 69 74 69 65  .    capabilitie
0c50: 73 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69  s may be added i
0c60: 6e 20 74 68 65 20 66 75 74 75 72 65 2e 0a 0a 20  n the future... 
0c70: 20 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20     For example, 
0c80: 61 73 20 63 75 72 72 65 6e 74 6c 79 20 69 6d 70  as currently imp
0c90: 6c 65 6d 65 6e 74 65 64 2c 20 69 66 20 77 72 69  lemented, if wri
0ca0: 74 65 73 20 61 72 65 20 68 61 70 70 65 6e 69 6e  tes are happenin
0cb0: 67 20 61 74 20 61 20 0a 20 20 20 20 73 74 65 61  g at a .    stea
0cc0: 64 79 20 73 74 72 65 61 6d 20 74 68 61 74 20 65  dy stream that e
0cd0: 78 63 65 65 64 73 20 74 68 65 20 49 2f 4f 20 63  xceeds the I/O c
0ce0: 61 70 61 62 69 6c 69 74 79 20 6f 66 20 74 68 65  apability of the
0cf0: 20 62 61 63 6b 67 72 6f 75 6e 64 20 77 72 69 74   background writ
0d00: 65 72 0a 20 20 20 20 74 68 72 65 61 64 2c 20 74  er.    thread, t
0d10: 68 65 20 71 75 65 75 65 20 6f 66 20 70 65 6e 64  he queue of pend
0d20: 69 6e 67 20 77 72 69 74 65 20 6f 70 65 72 61 74  ing write operat
0d30: 69 6f 6e 73 20 77 69 6c 6c 20 67 72 6f 77 20 77  ions will grow w
0d40: 69 74 68 6f 75 74 20 62 6f 75 6e 64 2e 0a 20 20  ithout bound..  
0d50: 20 20 49 66 20 74 68 69 73 20 67 6f 65 73 20 6f    If this goes o
0d60: 6e 20 66 6f 72 20 6c 6f 6e 67 20 65 6e 6f 75 67  n for long enoug
0d70: 68 2c 20 74 68 65 20 68 6f 73 74 20 73 79 73 74  h, the host syst
0d80: 65 6d 20 63 6f 75 6c 64 20 72 75 6e 20 6f 75 74  em could run out
0d90: 20 6f 66 20 6d 65 6d 6f 72 79 2e 20 0a 20 20 20   of memory. .   
0da0: 20 41 20 6d 6f 72 65 20 73 6f 70 68 69 73 74 69   A more sophisti
0db0: 63 61 74 65 64 20 6d 6f 64 75 6c 65 20 63 6f 75  cated module cou
0dc0: 6c 64 20 74 6f 20 6b 65 65 70 20 74 72 61 63 6b  ld to keep track
0dd0: 20 6f 66 20 74 68 65 20 71 75 61 6e 74 69 74 79   of the quantity
0de0: 20 6f 66 20 0a 20 20 20 20 70 65 6e 64 69 6e 67   of .    pending
0df0: 20 77 72 69 74 65 73 20 61 6e 64 20 73 74 6f 70   writes and stop
0e00: 20 61 63 63 65 70 74 69 6e 67 20 6e 65 77 20 77   accepting new w
0e10: 72 69 74 65 20 72 65 71 75 65 73 74 73 20 77 68  rite requests wh
0e20: 65 6e 20 74 68 65 20 71 75 65 75 65 20 6f 66 20  en the queue of 
0e30: 0a 20 20 20 20 70 65 6e 64 69 6e 67 20 77 72 69  .    pending wri
0e40: 74 65 73 20 67 72 6f 77 73 20 74 6f 6f 20 6c 61  tes grows too la
0e50: 72 67 65 2e 0a 0a 20 20 31 2e 33 20 4c 6f 63 6b  rge...  1.3 Lock
0e60: 69 6e 67 20 61 6e 64 20 43 6f 6e 63 75 72 72 65  ing and Concurre
0e70: 6e 63 79 0a 0a 20 20 20 20 4d 75 6c 74 69 70 6c  ncy..    Multipl
0e80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 72  e connections fr
0e90: 6f 6d 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67  om within a sing
0ea0: 6c 65 20 70 72 6f 63 65 73 73 20 74 68 61 74 20  le process that 
0eb0: 75 73 65 20 74 68 69 73 0a 20 20 20 20 69 6d 70  use this.    imp
0ec0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61  lementation of a
0ed0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f 20 6d  synchronous IO m
0ee0: 61 79 20 61 63 63 65 73 73 20 61 20 73 69 6e 67  ay access a sing
0ef0: 6c 65 20 64 61 74 61 62 61 73 65 0a 20 20 20 20  le database.    
0f00: 66 69 6c 65 20 63 6f 6e 63 75 72 72 65 6e 74 6c  file concurrentl
0f10: 79 2e 20 46 72 6f 6d 20 74 68 65 20 70 6f 69 6e  y. From the poin
0f20: 74 20 6f 66 20 76 69 65 77 20 6f 66 20 74 68 65  t of view of the
0f30: 20 75 73 65 72 2c 20 69 66 20 61 6c 6c 0a 20 20   user, if all.  
0f40: 20 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 61 72    connections ar
0f50: 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 61 20  e from within a 
0f60: 73 69 6e 67 6c 65 20 70 72 6f 63 65 73 73 2c 20  single process, 
0f70: 74 68 65 72 65 20 69 73 20 6e 6f 20 64 69 66 66  there is no diff
0f80: 65 72 65 6e 63 65 0a 20 20 20 20 62 65 74 77 65  erence.    betwe
0f90: 65 6e 20 74 68 65 20 63 6f 6e 63 75 72 72 65 6e  en the concurren
0fa0: 63 79 20 6f 66 66 65 72 65 64 20 62 79 20 22 6e  cy offered by "n
0fb0: 6f 72 6d 61 6c 22 20 53 51 4c 69 74 65 20 61 6e  ormal" SQLite an
0fc0: 64 20 53 51 4c 69 74 65 0a 20 20 20 20 75 73 69  d SQLite.    usi
0fd0: 6e 67 20 74 68 65 20 61 73 79 6e 63 68 72 6f 6e  ng the asynchron
0fe0: 6f 75 73 20 62 61 63 6b 65 6e 64 2e 0a 0a 20 20  ous backend...  
0ff0: 20 20 49 66 20 66 69 6c 65 2d 6c 6f 63 6b 69 6e    If file-lockin
1000: 67 20 69 73 20 65 6e 61 62 6c 65 64 20 28 69 74  g is enabled (it
1010: 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 20 64   is enabled by d
1020: 65 66 61 75 6c 74 29 2c 20 74 68 65 6e 20 63 6f  efault), then co
1030: 6e 6e 65 63 74 69 6f 6e 73 0a 20 20 20 20 66 72  nnections.    fr
1040: 6f 6d 20 6d 75 6c 74 69 70 6c 65 20 70 72 6f 63  om multiple proc
1050: 65 73 73 65 73 20 6d 61 79 20 61 6c 73 6f 20 72  esses may also r
1060: 65 61 64 20 61 6e 64 20 77 72 69 74 65 20 74 68  ead and write th
1070: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  e database file.
1080: 0a 20 20 20 20 48 6f 77 65 76 65 72 20 63 6f 6e  .    However con
1090: 63 75 72 72 65 6e 63 79 20 69 73 20 72 65 64 75  currency is redu
10a0: 63 65 64 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ced as follows:.
10b0: 0a 20 20 20 20 20 20 2a 20 57 68 65 6e 20 61 20  .      * When a 
10c0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e 67  connection using
10d0: 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f   asynchronous IO
10e0: 20 62 65 67 69 6e 73 20 61 20 64 61 74 61 62 61   begins a databa
10f0: 73 65 0a 20 20 20 20 20 20 20 20 74 72 61 6e 73  se.        trans
1100: 61 63 74 69 6f 6e 2c 20 74 68 65 20 64 61 74 61  action, the data
1110: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 69  base is locked i
1120: 6d 6d 65 64 69 61 74 65 6c 79 2e 20 48 6f 77 65  mmediately. Howe
1130: 76 65 72 20 74 68 65 0a 20 20 20 20 20 20 20 20  ver the.        
1140: 6c 6f 63 6b 20 69 73 20 6e 6f 74 20 72 65 6c 65  lock is not rele
1150: 61 73 65 64 20 75 6e 74 69 6c 20 61 66 74 65 72  ased until after
1160: 20 61 6c 6c 20 72 65 6c 65 76 61 6e 74 20 6f 70   all relevant op
1170: 65 72 61 74 69 6f 6e 73 0a 20 20 20 20 20 20 20  erations.       
1180: 20 69 6e 20 74 68 65 20 77 72 69 74 65 2d 71 75   in the write-qu
1190: 65 75 65 20 68 61 76 65 20 62 65 65 6e 20 66 6c  eue have been fl
11a0: 75 73 68 65 64 20 74 6f 20 64 69 73 6b 2e 20 54  ushed to disk. T
11b0: 68 69 73 20 6d 65 61 6e 73 0a 20 20 20 20 20 20  his means.      
11c0: 20 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 29 20    (for example) 
11d0: 74 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73  that the databas
11e0: 65 20 6d 61 79 20 72 65 6d 61 69 6e 20 6c 6f 63  e may remain loc
11f0: 6b 65 64 20 66 6f 72 20 73 6f 6d 65 20 0a 20 20  ked for some .  
1200: 20 20 20 20 20 20 74 69 6d 65 20 61 66 74 65 72        time after
1210: 20 61 20 22 43 4f 4d 4d 49 54 22 20 6f 72 20 22   a "COMMIT" or "
1220: 52 4f 4c 4c 42 41 43 4b 22 20 69 73 20 69 73 73  ROLLBACK" is iss
1230: 75 65 64 2e 0a 0a 20 20 20 20 20 20 2a 20 49 66  ued...      * If
1240: 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
1250: 75 73 69 6e 67 20 61 73 79 6e 63 68 72 6f 6e 6f  using asynchrono
1260: 75 73 20 49 4f 20 65 78 65 63 75 74 65 73 20 74  us IO executes t
1270: 72 61 6e 73 61 63 74 69 6f 6e 73 0a 20 20 20 20  ransactions.    
1280: 20 20 20 20 69 6e 20 71 75 69 63 6b 20 73 75 63      in quick suc
1290: 63 65 73 73 69 6f 6e 2c 20 6f 74 68 65 72 20 64  cession, other d
12a0: 61 74 61 62 61 73 65 20 75 73 65 72 73 20 6d 61  atabase users ma
12b0: 79 20 62 65 20 65 66 66 65 63 74 69 76 65 6c 79  y be effectively
12c0: 0a 20 20 20 20 20 20 20 20 6c 6f 63 6b 65 64 20  .        locked 
12d0: 6f 75 74 20 6f 66 20 74 68 65 20 64 61 74 61 62  out of the datab
12e0: 61 73 65 2e 20 54 68 69 73 20 69 73 20 62 65 63  ase. This is bec
12f0: 61 75 73 65 20 77 68 65 6e 20 61 20 42 45 47 49  ause when a BEGI
1300: 4e 0a 20 20 20 20 20 20 20 20 69 73 20 65 78 65  N.        is exe
1310: 63 75 74 65 64 2c 20 61 20 64 61 74 61 62 61 73  cuted, a databas
1320: 65 20 6c 6f 63 6b 20 69 73 20 65 73 74 61 62 6c  e lock is establ
1330: 69 73 68 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  ished immediatel
1340: 79 2e 20 42 75 74 0a 20 20 20 20 20 20 20 20 77  y. But.        w
1350: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
1360: 6e 64 69 6e 67 20 43 4f 4d 4d 49 54 20 6f 72 20  nding COMMIT or 
1370: 52 4f 4c 4c 42 41 43 4b 20 6f 63 63 75 72 73 2c  ROLLBACK occurs,
1380: 20 74 68 65 20 6c 6f 63 6b 0a 20 20 20 20 20 20   the lock.      
1390: 20 20 69 73 20 6e 6f 74 20 72 65 6c 65 61 73 65    is not release
13a0: 64 20 75 6e 74 69 6c 20 74 68 65 20 72 65 6c 65  d until the rele
13b0: 76 61 6e 74 20 70 61 72 74 20 6f 66 20 74 68 65  vant part of the
13c0: 20 77 72 69 74 65 2d 71 75 65 75 65 20 0a 20 20   write-queue .  
13d0: 20 20 20 20 20 20 68 61 73 20 62 65 65 6e 20 66        has been f
13e0: 6c 75 73 68 65 64 20 74 68 72 6f 75 67 68 2e 20  lushed through. 
13f0: 41 73 20 61 20 72 65 73 75 6c 74 2c 20 69 66 20  As a result, if 
1400: 61 20 43 4f 4d 4d 49 54 20 69 73 20 66 6f 6c 6c  a COMMIT is foll
1410: 6f 77 65 64 0a 20 20 20 20 20 20 20 20 62 79 20  owed.        by 
1420: 61 20 42 45 47 49 4e 20 62 65 66 6f 72 65 20 74  a BEGIN before t
1430: 68 65 20 77 72 69 74 65 2d 71 75 65 75 65 20 69  he write-queue i
1440: 73 20 66 6c 75 73 68 65 64 20 74 68 72 6f 75 67  s flushed throug
1450: 68 2c 20 74 68 65 20 64 61 74 61 62 61 73 65 20  h, the database 
1460: 0a 20 20 20 20 20 20 20 20 69 73 20 6e 65 76 65  .        is neve
1470: 72 20 75 6e 6c 6f 63 6b 65 64 2c 70 72 65 76 65  r unlocked,preve
1480: 6e 74 69 6e 67 20 6f 74 68 65 72 20 70 72 6f 63  nting other proc
1490: 65 73 73 65 73 20 66 72 6f 6d 20 61 63 63 65 73  esses from acces
14a0: 73 69 6e 67 20 0a 20 20 20 20 20 20 20 20 74 68  sing .        th
14b0: 65 20 64 61 74 61 62 61 73 65 2e 0a 0a 20 20 20  e database...   
14c0: 20 46 69 6c 65 2d 6c 6f 63 6b 69 6e 67 20 6d 61   File-locking ma
14d0: 79 20 62 65 20 64 69 73 61 62 6c 65 64 20 61 74  y be disabled at
14e0: 20 72 75 6e 74 69 6d 65 20 75 73 69 6e 67 20 74   runtime using t
14f0: 68 65 20 73 71 6c 69 74 65 33 61 73 79 6e 63 5f  he sqlite3async_
1500: 63 6f 6e 74 72 6f 6c 28 29 0a 20 20 20 20 41 50  control().    AP
1510: 49 20 28 73 65 65 20 62 65 6c 6f 77 29 2e 20 54  I (see below). T
1520: 68 69 73 20 6d 61 79 20 69 6d 70 72 6f 76 65 20  his may improve 
1530: 70 65 72 66 6f 72 6d 61 6e 63 65 20 77 68 65 6e  performance when
1540: 20 61 6e 20 4e 46 53 20 6f 72 20 6f 74 68 65 72   an NFS or other
1550: 20 0a 20 20 20 20 6e 65 74 77 6f 72 6b 20 66 69   .    network fi
1560: 6c 65 2d 73 79 73 74 65 6d 2c 20 61 73 20 74 68  le-system, as th
1570: 65 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 72 6f  e synchronous ro
1580: 75 6e 64 2d 74 72 69 70 73 20 74 6f 20 74 68 65  und-trips to the
1590: 20 73 65 72 76 65 72 20 62 65 20 0a 20 20 20 20   server be .    
15a0: 72 65 71 75 69 72 65 64 20 74 6f 20 65 73 74 61  required to esta
15b0: 62 6c 69 73 68 20 66 69 6c 65 20 6c 6f 63 6b 73  blish file locks
15c0: 20 61 72 65 20 61 76 6f 69 64 65 64 2e 20 48 6f   are avoided. Ho
15d0: 77 65 76 65 72 2c 20 69 66 20 6d 75 6c 74 69 70  wever, if multip
15e0: 6c 65 20 0a 20 20 20 20 63 6f 6e 6e 65 63 74 69  le .    connecti
15f0: 6f 6e 73 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ons attempt to a
1600: 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 64  ccess the same d
1610: 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 68 65  atabase file whe
1620: 6e 20 66 69 6c 65 2d 6c 6f 63 6b 69 6e 67 0a 20  n file-locking. 
1630: 20 20 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20     is disabled, 
1640: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 72 61 73  application cras
1650: 68 65 73 20 61 6e 64 20 64 61 74 61 62 61 73 65  hes and database
1660: 20 63 6f 72 72 75 70 74 69 6f 6e 20 69 73 20 61   corruption is a
1670: 20 6c 69 6b 65 6c 79 0a 20 20 20 20 6f 75 74 63   likely.    outc
1680: 6f 6d 65 2e 0a 0a 0a 32 2e 20 43 4f 4d 50 49 4c  ome....2. COMPIL
1690: 41 54 49 4f 4e 20 41 4e 44 20 55 53 41 47 45 0a  ATION AND USAGE.
16a0: 0a 20 20 54 68 65 20 61 73 79 6e 63 68 72 6f 6e  .  The asynchron
16b0: 6f 75 73 20 49 4f 20 65 78 74 65 6e 73 69 6f 6e  ous IO extension
16c0: 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 20 73   consists of a s
16d0: 69 6e 67 6c 65 20 66 69 6c 65 20 6f 66 20 43 20  ingle file of C 
16e0: 63 6f 64 65 0a 20 20 28 73 71 6c 69 74 65 33 61  code.  (sqlite3a
16f0: 73 79 6e 63 2e 63 29 2c 20 61 6e 64 20 61 20 68  sync.c), and a h
1700: 65 61 64 65 72 20 66 69 6c 65 20 28 73 71 6c 69  eader file (sqli
1710: 74 65 33 61 73 79 6e 63 2e 68 29 20 74 68 61 74  te3async.h) that
1720: 20 64 65 66 69 6e 65 73 20 74 68 65 20 0a 20 20   defines the .  
1730: 43 20 41 50 49 20 75 73 65 64 20 62 79 20 61 70  C API used by ap
1740: 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61 63  plications to ac
1750: 74 69 76 61 74 65 20 61 6e 64 20 63 6f 6e 74 72  tivate and contr
1760: 6f 6c 20 74 68 65 20 6d 6f 64 75 6c 65 73 20 0a  ol the modules .
1770: 20 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74 79 2e    functionality.
1780: 0a 0a 20 20 54 6f 20 75 73 65 20 74 68 65 20 61  ..  To use the a
1790: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f 20 65  synchronous IO e
17a0: 78 74 65 6e 73 69 6f 6e 2c 20 63 6f 6d 70 69 6c  xtension, compil
17b0: 65 20 73 71 6c 69 74 65 33 61 73 79 6e 63 2e 63  e sqlite3async.c
17c0: 20 61 73 0a 20 20 70 61 72 74 20 6f 66 20 74 68   as.  part of th
17d0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 68  e application th
17e0: 61 74 20 75 73 65 73 20 53 51 4c 69 74 65 2e 20  at uses SQLite. 
17f0: 54 68 65 6e 20 75 73 65 20 74 68 65 20 41 50 49  Then use the API
1800: 20 64 65 66 69 6e 65 64 0a 20 20 69 6e 20 73 71   defined.  in sq
1810: 6c 69 74 65 33 61 73 79 6e 63 2e 68 20 74 6f 20  lite3async.h to 
1820: 69 6e 69 74 69 61 6c 69 7a 65 20 61 6e 64 20 63  initialize and c
1830: 6f 6e 66 69 67 75 72 65 20 74 68 65 20 6d 6f 64  onfigure the mod
1840: 75 6c 65 2e 0a 0a 20 20 54 68 65 20 61 73 79 6e  ule...  The asyn
1850: 63 68 72 6f 6e 6f 75 73 20 49 4f 20 56 46 53 20  chronous IO VFS 
1860: 41 50 49 20 69 73 20 64 65 73 63 72 69 62 65 64  API is described
1870: 20 69 6e 20 64 65 74 61 69 6c 20 69 6e 20 63 6f   in detail in co
1880: 6d 6d 65 6e 74 73 20 69 6e 20 0a 20 20 73 71 6c  mments in .  sql
1890: 69 74 65 33 61 73 79 6e 63 2e 68 2e 20 55 73 69  ite3async.h. Usi
18a0: 6e 67 20 74 68 65 20 41 50 49 20 75 73 75 61 6c  ng the API usual
18b0: 6c 79 20 63 6f 6e 73 69 73 74 73 20 6f 66 20 74  ly consists of t
18c0: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 73 74 65  he following ste
18d0: 70 73 3a 0a 0a 20 20 20 20 31 2e 20 52 65 67 69  ps:..    1. Regi
18e0: 73 74 65 72 20 74 68 65 20 61 73 79 6e 63 68 72  ster the asynchr
18f0: 6f 6e 6f 75 73 20 49 4f 20 56 46 53 20 77 69 74  onous IO VFS wit
1900: 68 20 53 51 4c 69 74 65 20 62 79 20 63 61 6c 6c  h SQLite by call
1910: 69 6e 67 20 74 68 65 0a 20 20 20 20 20 20 20 73  ing the.       s
1920: 71 6c 69 74 65 33 61 73 79 6e 63 5f 69 6e 69 74  qlite3async_init
1930: 69 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  ialize() functio
1940: 6e 2e 0a 0a 20 20 20 20 32 2e 20 43 72 65 61 74  n...    2. Creat
1950: 65 20 61 20 62 61 63 6b 67 72 6f 75 6e 64 20 74  e a background t
1960: 68 72 65 61 64 20 74 6f 20 70 65 72 66 6f 72 6d  hread to perform
1970: 20 77 72 69 74 65 20 6f 70 65 72 61 74 69 6f 6e   write operation
1980: 73 20 61 6e 64 20 63 61 6c 6c 0a 20 20 20 20 20  s and call.     
1990: 20 20 73 71 6c 69 74 65 33 61 73 79 6e 63 5f 72    sqlite3async_r
19a0: 75 6e 28 29 2e 0a 0a 20 20 20 20 33 2e 20 55 73  un()...    3. Us
19b0: 65 20 74 68 65 20 6e 6f 72 6d 61 6c 20 53 51 4c  e the normal SQL
19c0: 69 74 65 20 41 50 49 20 74 6f 20 72 65 61 64 20  ite API to read 
19d0: 61 6e 64 20 77 72 69 74 65 20 74 6f 20 64 61 74  and write to dat
19e0: 61 62 61 73 65 73 20 76 69 61 20 0a 20 20 20 20  abases via .    
19f0: 20 20 20 74 68 65 20 61 73 79 6e 63 68 72 6f 6e     the asynchron
1a00: 6f 75 73 20 49 4f 20 56 46 53 2e 0a 0a 20 20 52  ous IO VFS...  R
1a10: 65 66 65 72 20 74 6f 20 73 71 6c 69 74 65 33 61  efer to sqlite3a
1a20: 73 79 6e 63 2e 68 20 66 6f 72 20 64 65 74 61 69  sync.h for detai
1a30: 6c 73 2e 0a 0a 0a 33 2e 20 50 4f 52 54 49 4e 47  ls....3. PORTING
1a40: 0a 0a 20 20 43 75 72 72 65 6e 74 6c 79 20 74 68  ..  Currently th
1a50: 65 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49  e asynchronous I
1a60: 4f 20 65 78 74 65 6e 73 69 6f 6e 20 69 73 20 63  O extension is c
1a70: 6f 6d 70 61 74 69 62 6c 65 20 77 69 74 68 20 77  ompatible with w
1a80: 69 6e 33 32 20 73 79 73 74 65 6d 73 0a 20 20 61  in32 systems.  a
1a90: 6e 64 20 73 79 73 74 65 6d 73 20 74 68 61 74 20  nd systems that 
1aa0: 73 75 70 70 6f 72 74 20 74 68 65 20 70 74 68 72  support the pthr
1ab0: 65 61 64 73 20 69 6e 74 65 72 66 61 63 65 2c 20  eads interface, 
1ac0: 69 6e 63 6c 75 64 69 6e 67 20 4d 61 63 20 4f 53  including Mac OS
1ad0: 58 2c 20 4c 69 6e 75 78 2c 20 0a 20 20 61 6e 64  X, Linux, .  and
1ae0: 20 6f 74 68 65 72 20 76 61 72 69 65 74 69 65 73   other varieties
1af0: 20 6f 66 20 55 6e 69 78 2e 20 0a 0a 20 20 54 6f   of Unix. ..  To
1b00: 20 70 6f 72 74 20 74 68 65 20 61 73 79 6e 63 68   port the asynch
1b10: 72 6f 6e 6f 75 73 20 49 4f 20 65 78 74 65 6e 73  ronous IO extens
1b20: 69 6f 6e 20 74 6f 20 61 6e 6f 74 68 65 72 20 70  ion to another p
1b30: 6c 61 74 66 6f 72 6d 2c 20 74 68 65 20 75 73 65  latform, the use
1b40: 72 20 6d 75 73 74 0a 20 20 69 6d 70 6c 65 6d 65  r must.  impleme
1b50: 6e 74 20 6d 75 74 65 78 20 61 6e 64 20 63 6f 6e  nt mutex and con
1b60: 64 69 74 69 6f 6e 20 76 61 72 69 61 62 6c 65 20  dition variable 
1b70: 70 72 69 6d 69 74 69 76 65 73 20 66 6f 72 20 74  primitives for t
1b80: 68 65 20 6e 65 77 20 70 6c 61 74 66 6f 72 6d 2e  he new platform.
1b90: 0a 20 20 43 75 72 72 65 6e 74 6c 79 20 74 68 65  .  Currently the
1ba0: 72 65 20 69 73 20 6e 6f 20 65 78 74 65 72 6e 61  re is no externa
1bb0: 6c 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 6e  lly available in
1bc0: 74 65 72 66 61 63 65 20 74 6f 20 61 6c 6c 6f 77  terface to allow
1bd0: 20 74 68 69 73 2c 20 62 75 74 0a 20 20 6d 6f 64   this, but.  mod
1be0: 69 66 79 69 6e 67 20 74 68 65 20 63 6f 64 65 20  ifying the code 
1bf0: 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 61 73  within sqlite3as
1c00: 79 6e 63 2e 63 20 74 6f 20 69 6e 63 6c 75 64 65  ync.c to include
1c10: 20 74 68 65 20 6e 65 77 20 70 6c 61 74 66 6f 72   the new platfor
1c20: 6d 73 0a 20 20 63 6f 6e 63 75 72 72 65 6e 63 79  ms.  concurrency
1c30: 20 70 72 69 6d 69 74 69 76 65 73 20 69 73 20 72   primitives is r
1c40: 65 6c 61 74 69 76 65 6c 79 20 65 61 73 79 2e 20  elatively easy. 
1c50: 53 65 61 72 63 68 20 77 69 74 68 69 6e 20 73 71  Search within sq
1c60: 6c 69 74 65 33 61 73 79 6e 63 2e 63 0a 20 20 66  lite3async.c.  f
1c70: 6f 72 20 74 68 65 20 63 6f 6d 6d 65 6e 74 20 73  or the comment s
1c80: 74 72 69 6e 67 20 22 50 4f 52 54 49 4e 47 20 46  tring "PORTING F
1c90: 55 4e 43 54 49 4f 4e 53 22 20 66 6f 72 20 64 65  UNCTIONS" for de
1ca0: 74 61 69 6c 73 2e 20 54 68 65 6e 20 69 6d 70 6c  tails. Then impl
1cb0: 65 6d 65 6e 74 0a 20 20 6e 65 77 20 76 65 72 73  ement.  new vers
1cc0: 69 6f 6e 73 20 6f 66 20 65 61 63 68 20 6f 66 20  ions of each of 
1cd0: 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 3a 0a 0a  the following:..
1ce0: 20 20 20 20 73 74 61 74 69 63 20 76 6f 69 64 20      static void 
1cf0: 61 73 79 6e 63 5f 6d 75 74 65 78 5f 65 6e 74 65  async_mutex_ente
1d00: 72 28 69 6e 74 20 65 4d 75 74 65 78 29 3b 0a 20  r(int eMutex);. 
1d10: 20 20 20 73 74 61 74 69 63 20 76 6f 69 64 20 61     static void a
1d20: 73 79 6e 63 5f 6d 75 74 65 78 5f 6c 65 61 76 65  sync_mutex_leave
1d30: 28 69 6e 74 20 65 4d 75 74 65 78 29 3b 0a 20 20  (int eMutex);.  
1d40: 20 20 73 74 61 74 69 63 20 76 6f 69 64 20 61 73    static void as
1d50: 79 6e 63 5f 63 6f 6e 64 5f 77 61 69 74 28 69 6e  ync_cond_wait(in
1d60: 74 20 65 43 6f 6e 64 2c 20 69 6e 74 20 65 4d 75  t eCond, int eMu
1d70: 74 65 78 29 3b 0a 20 20 20 20 73 74 61 74 69 63  tex);.    static
1d80: 20 76 6f 69 64 20 61 73 79 6e 63 5f 63 6f 6e 64   void async_cond
1d90: 5f 73 69 67 6e 61 6c 28 69 6e 74 20 65 43 6f 6e  _signal(int eCon
1da0: 64 29 3b 0a 20 20 20 20 73 74 61 74 69 63 20 76  d);.    static v
1db0: 6f 69 64 20 61 73 79 6e 63 5f 73 63 68 65 64 5f  oid async_sched_
1dc0: 79 69 65 6c 64 28 76 6f 69 64 29 3b 0a 0a 20 20  yield(void);..  
1dd0: 54 68 65 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74  The functionalit
1de0: 79 20 72 65 71 75 69 72 65 64 20 6f 66 20 65 61  y required of ea
1df0: 63 68 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ch of the above 
1e00: 66 75 6e 63 74 69 6f 6e 73 20 69 73 20 64 65 73  functions is des
1e10: 63 72 69 62 65 64 0a 20 20 69 6e 20 63 6f 6d 6d  cribed.  in comm
1e20: 65 6e 74 73 20 69 6e 20 73 71 6c 69 74 65 33 61  ents in sqlite3a
1e30: 73 79 6e 63 2e 63 2e 0a                          sync.c..