/ Hex Artifact Content
Login

Artifact a21e1252deb14a2c211f0e165c4b9122a8f1f344:


0000: 0a 23 69 66 6e 64 65 66 20 5f 5f 53 51 4c 49 54  .#ifndef __SQLIT
0010: 45 41 53 59 4e 43 5f 48 5f 0a 23 64 65 66 69 6e  EASYNC_H_.#defin
0020: 65 20 5f 5f 53 51 4c 49 54 45 41 53 59 4e 43 5f  e __SQLITEASYNC_
0030: 48 5f 20 31 0a 0a 2f 2a 0a 2a 2a 20 4d 61 6b 65  H_ 1../*.** Make
0040: 20 73 75 72 65 20 77 65 20 63 61 6e 20 63 61 6c   sure we can cal
0050: 6c 20 74 68 69 73 20 73 74 75 66 66 20 66 72 6f  l this stuff fro
0060: 6d 20 43 2b 2b 2e 0a 2a 2f 0a 23 69 66 64 65 66  m C++..*/.#ifdef
0070: 20 5f 5f 63 70 6c 75 73 70 6c 75 73 0a 65 78 74   __cplusplus.ext
0080: 65 72 6e 20 22 43 22 20 7b 0a 23 65 6e 64 69 66  ern "C" {.#endif
0090: 0a 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ..#define SQLITE
00a0: 41 53 59 4e 43 5f 56 46 53 4e 41 4d 45 20 22 73  ASYNC_VFSNAME "s
00b0: 71 6c 69 74 65 33 61 73 79 6e 63 22 0a 0a 2f 2a  qlite3async"../*
00c0: 0a 2a 2a 20 54 48 52 45 41 44 20 53 41 46 45 54  .** THREAD SAFET
00d0: 59 20 4e 4f 54 45 53 3a 0a 2a 2a 0a 2a 2a 20 4f  Y NOTES:.**.** O
00e0: 66 20 74 68 65 20 66 6f 75 72 20 41 50 49 20 66  f the four API f
00f0: 75 6e 63 74 69 6f 6e 73 20 69 6e 20 74 68 69 73  unctions in this
0100: 20 66 69 6c 65 2c 20 74 68 65 20 66 6f 6c 6c 6f   file, the follo
0110: 77 69 6e 67 20 61 72 65 20 6e 6f 74 20 74 68 72  wing are not thr
0120: 65 61 64 73 61 66 65 3a 0a 2a 2a 0a 2a 2a 20 20  eadsafe:.**.**  
0130: 20 73 71 6c 69 74 65 33 61 73 79 6e 63 5f 69 6e   sqlite3async_in
0140: 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 20 20  itialize().**   
0150: 73 71 6c 69 74 65 33 61 73 79 6e 63 5f 73 68 75  sqlite3async_shu
0160: 74 64 6f 77 6e 28 29 0a 2a 2a 0a 2a 2a 20 43 61  tdown().**.** Ca
0170: 72 65 20 6d 75 73 74 20 62 65 20 74 61 6b 65 6e  re must be taken
0180: 20 74 68 61 74 20 6e 65 69 74 68 65 72 20 6f 66   that neither of
0190: 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
01a0: 20 69 73 20 63 61 6c 6c 65 64 20 77 68 69 6c 65   is called while
01b0: 20 0a 2a 2a 20 61 6e 6f 74 68 65 72 20 74 68 72   .** another thr
01c0: 65 61 64 20 6d 61 79 20 62 65 20 63 61 6c 6c 69  ead may be calli
01d0: 6e 67 20 65 69 74 68 65 72 20 61 6e 79 20 73 71  ng either any sq
01e0: 6c 69 74 65 33 61 73 79 6e 63 5f 58 58 58 28 29  lite3async_XXX()
01f0: 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20   function.** or 
0200: 61 6e 20 73 71 6c 69 74 65 33 5f 58 58 58 28 29  an sqlite3_XXX()
0210: 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 20 72 65   API function re
0220: 6c 61 74 65 64 20 74 6f 20 61 20 64 61 74 61 62  lated to a datab
0230: 61 73 65 20 68 61 6e 64 6c 65 20 74 68 61 74 0a  ase handle that.
0240: 2a 2a 20 69 73 20 75 73 69 6e 67 20 74 68 65 20  ** is using the 
0250: 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f 20  asynchronous IO 
0260: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  VFS..**.** These
0270: 20 66 75 6e 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a   functions:.**.*
0280: 2a 20 20 20 73 71 6c 69 74 65 33 61 73 79 6e 63  *   sqlite3async
0290: 5f 72 75 6e 28 29 0a 2a 2a 20 20 20 73 71 6c 69  _run().**   sqli
02a0: 74 65 33 61 73 79 6e 63 5f 63 6f 6e 74 72 6f 6c  te3async_control
02b0: 28 29 0a 2a 2a 0a 2a 2a 20 61 72 65 20 74 68 72  ().**.** are thr
02c0: 65 61 64 73 61 66 65 2e 20 49 74 20 69 73 20 71  eadsafe. It is q
02d0: 75 69 74 65 20 73 61 66 65 20 74 6f 20 63 61 6c  uite safe to cal
02e0: 6c 20 65 69 74 68 65 72 20 6f 66 20 74 68 65 73  l either of thes
02f0: 65 20 66 75 6e 63 74 69 6f 6e 73 20 65 76 65 6e  e functions even
0300: 0a 2a 2a 20 69 66 20 61 6e 6f 74 68 65 72 20 74  .** if another t
0310: 68 72 65 61 64 20 6d 61 79 20 61 6c 73 6f 20 62  hread may also b
0320: 65 20 63 61 6c 6c 69 6e 67 20 6f 6e 65 20 6f 66  e calling one of
0330: 20 74 68 65 6d 20 6f 72 20 61 6e 20 73 71 6c 69   them or an sqli
0340: 74 65 33 5f 58 58 58 28 29 0a 2a 2a 20 66 75 6e  te3_XXX().** fun
0350: 63 74 69 6f 6e 20 72 65 6c 61 74 65 64 20 74 6f  ction related to
0360: 20 61 20 64 61 74 61 62 61 73 65 20 68 61 6e 64   a database hand
0370: 6c 65 20 74 68 61 74 20 75 73 65 73 20 74 68 65  le that uses the
0380: 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f   asynchronous IO
0390: 20 56 46 53 2e 0a 2a 2f 0a 0a 2f 2a 0a 2a 2a 20   VFS..*/../*.** 
03a0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 61  Initialize the a
03b0: 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f 20 56  synchronous IO V
03c0: 46 53 20 61 6e 64 20 72 65 67 69 73 74 65 72 20  FS and register 
03d0: 69 74 20 77 69 74 68 20 53 51 4c 69 74 65 20 75  it with SQLite u
03e0: 73 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  sing.** sqlite3_
03f0: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 2e 20  vfs_register(). 
0400: 49 66 20 74 68 65 20 61 73 79 6e 63 68 72 6f 6e  If the asynchron
0410: 6f 75 73 20 56 46 53 20 69 73 20 61 6c 72 65 61  ous VFS is alrea
0420: 64 79 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  dy initialized.*
0430: 2a 20 61 6e 64 20 72 65 67 69 73 74 65 72 65 64  * and registered
0440: 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
0450: 69 73 20 61 20 6e 6f 2d 6f 70 2e 20 54 68 65 20  is a no-op. The 
0460: 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f 20  asynchronous IO 
0470: 56 46 53 0a 2a 2a 20 69 73 20 72 65 67 69 73 74  VFS.** is regist
0480: 65 72 65 64 20 61 73 20 22 73 71 6c 69 74 65 33  ered as "sqlite3
0490: 61 73 79 6e 63 22 2e 0a 2a 2a 0a 2a 2a 20 54 68  async"..**.** Th
04a0: 65 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49  e asynchronous I
04b0: 4f 20 56 46 53 20 64 6f 65 73 20 6e 6f 74 20 6d  O VFS does not m
04c0: 61 6b 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ake operating sy
04d0: 73 74 65 6d 20 49 4f 20 72 65 71 75 65 73 74 73  stem IO requests
04e0: 20 0a 2a 2a 20 64 69 72 65 63 74 6c 79 2e 20 49   .** directly. I
04f0: 6e 73 74 65 61 64 2c 20 69 74 20 75 73 65 73 20  nstead, it uses 
0500: 61 6e 20 65 78 69 73 74 69 6e 67 20 56 46 53 20  an existing VFS 
0510: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
0520: 6f 72 20 61 6c 6c 0a 2a 2a 20 72 65 71 75 69 72  or all.** requir
0530: 65 64 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 6f  ed file-system o
0540: 70 65 72 61 74 69 6f 6e 73 2e 20 49 66 20 74 68  perations. If th
0550: 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
0560: 72 20 74 6f 20 74 68 69 73 20 66 75 6e 63 74 69  r to this functi
0570: 6f 6e 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74  on.** is NULL, t
0580: 68 65 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  hen the current 
0590: 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 75  default VFS is u
05a0: 73 65 64 20 66 6f 72 20 49 4f 2e 20 49 66 20 69  sed for IO. If i
05b0: 74 20 69 73 20 6e 6f 74 0a 2a 2a 20 4e 55 4c 4c  t is not.** NULL
05c0: 2c 20 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62  , then it must b
05d0: 65 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 6e  e the name of an
05e0: 20 65 78 69 73 74 69 6e 67 20 56 46 53 2e 20 49   existing VFS. I
05f0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74  n other words, t
0600: 68 65 0a 2a 2a 20 66 69 72 73 74 20 61 72 67 75  he.** first argu
0610: 6d 65 6e 74 20 74 6f 20 74 68 69 73 20 66 75 6e  ment to this fun
0620: 63 74 69 6f 6e 20 69 73 20 70 61 73 73 65 64 20  ction is passed 
0630: 74 6f 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  to sqlite3_vfs_f
0640: 69 6e 64 28 29 20 74 6f 0a 2a 2a 20 6c 6f 63 61  ind() to.** loca
0650: 74 65 20 74 68 65 20 56 46 53 20 74 6f 20 75 73  te the VFS to us
0660: 65 20 66 6f 72 20 61 6c 6c 20 72 65 61 6c 20 49  e for all real I
0670: 4f 20 6f 70 65 72 61 74 69 6f 6e 73 2e 20 54 68  O operations. Th
0680: 69 73 20 56 46 53 20 69 73 20 6b 6e 6f 77 6e 0a  is VFS is known.
0690: 2a 2a 20 61 73 20 74 68 65 20 22 70 61 72 65 6e  ** as the "paren
06a0: 74 20 56 46 53 22 2e 0a 2a 2a 0a 2a 2a 20 49 66  t VFS"..**.** If
06b0: 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
06c0: 6d 65 74 65 72 20 74 6f 20 74 68 69 73 20 66 75  meter to this fu
06d0: 6e 63 74 69 6f 6e 20 69 73 20 6e 6f 6e 2d 7a 65  nction is non-ze
06e0: 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 0a 2a 2a  ro, then the .**
06f0: 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f   asynchronous IO
0700: 20 56 46 53 20 69 73 20 72 65 67 69 73 74 65 72   VFS is register
0710: 65 64 20 61 73 20 74 68 65 20 64 65 66 61 75 6c  ed as the defaul
0720: 74 20 56 46 53 20 66 6f 72 20 61 6c 6c 20 53 51  t VFS for all SQ
0730: 4c 69 74 65 20 0a 2a 2a 20 64 61 74 61 62 61 73  Lite .** databas
0740: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 77 69  e connections wi
0750: 74 68 69 6e 20 74 68 65 20 70 72 6f 63 65 73 73  thin the process
0760: 2e 20 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65  . Otherwise, the
0770: 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f   asynchronous IO
0780: 0a 2a 2a 20 56 46 53 20 69 73 20 6f 6e 6c 79 20  .** VFS is only 
0790: 75 73 65 64 20 62 79 20 63 6f 6e 6e 65 63 74 69  used by connecti
07a0: 6f 6e 73 20 6f 70 65 6e 65 64 20 75 73 69 6e 67  ons opened using
07b0: 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
07c0: 28 29 20 74 68 61 74 0a 2a 2a 20 73 70 65 63 69  () that.** speci
07d0: 66 69 63 61 6c 6c 79 20 72 65 71 75 65 73 74 20  fically request 
07e0: 56 46 53 20 22 73 71 6c 69 74 65 33 61 73 79 6e  VFS "sqlite3asyn
07f0: 63 22 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 70  c"..**.** If a p
0800: 61 72 65 6e 74 20 56 46 53 20 63 61 6e 6e 6f 74  arent VFS cannot
0810: 20 62 65 20 6c 6f 63 61 74 65 64 2c 20 74 68 65   be located, the
0820: 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69  n SQLITE_ERROR i
0830: 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 49  s returned..** I
0840: 6e 20 74 68 65 20 75 6e 6c 69 6b 65 6c 79 20 65  n the unlikely e
0850: 76 65 6e 74 20 74 68 61 74 20 6f 70 65 72 61 74  vent that operat
0860: 69 6e 67 20 73 79 73 74 65 6d 20 73 70 65 63 69  ing system speci
0870: 66 69 63 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  fic initializati
0880: 6f 6e 0a 2a 2a 20 66 61 69 6c 73 20 28 77 69 6e  on.** fails (win
0890: 33 32 20 73 79 73 74 65 6d 73 20 63 72 65 61 74  32 systems creat
08a0: 65 20 74 68 65 20 72 65 71 75 69 72 65 64 20 63  e the required c
08b0: 72 69 74 69 63 61 6c 20 73 65 63 74 69 6f 6e 20  ritical section 
08c0: 61 6e 64 20 65 76 65 6e 74 20 0a 2a 2a 20 6f 62  and event .** ob
08d0: 6a 65 63 74 73 20 77 69 74 68 69 6e 20 74 68 69  jects within thi
08e0: 73 20 66 75 6e 63 74 69 6f 6e 29 2c 20 74 68 65  s function), the
08f0: 6e 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 69  n SQLITE_ERROR i
0900: 73 20 61 6c 73 6f 20 72 65 74 75 72 6e 65 64 2e  s also returned.
0910: 0a 2a 2a 20 46 69 6e 61 6c 6c 79 2c 20 69 66 20  .** Finally, if 
0920: 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
0930: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
0940: 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  () returns an er
0950: 72 6f 72 2c 20 74 68 65 6e 20 0a 2a 2a 20 74 68  ror, then .** th
0960: 65 20 65 72 72 6f 72 20 63 6f 64 65 20 69 73 20  e error code is 
0970: 72 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20  returned to the 
0980: 75 73 65 72 20 62 79 20 74 68 69 73 20 66 75 6e  user by this fun
0990: 63 74 69 6f 6e 2e 20 49 6e 20 61 6c 6c 20 74 68  ction. In all th
09a0: 72 65 65 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  ree.** of these 
09b0: 63 61 73 65 73 2c 20 69 6e 74 69 61 6c 69 7a 61  cases, intializa
09c0: 74 69 6f 6e 20 68 61 73 20 66 61 69 6c 65 64 20  tion has failed 
09d0: 61 6e 64 20 74 68 65 20 61 73 79 6e 63 68 72 6f  and the asynchro
09e0: 6e 6f 75 73 20 49 4f 20 56 46 53 0a 2a 2a 20 69  nous IO VFS.** i
09f0: 73 20 6e 6f 74 20 72 65 67 69 73 74 65 72 65 64  s not registered
0a00: 20 77 69 74 68 20 53 51 4c 69 74 65 2e 0a 2a 2a   with SQLite..**
0a10: 0a 2a 2a 20 4f 74 68 65 72 77 69 73 65 2c 20 69  .** Otherwise, i
0a20: 66 20 6e 6f 20 65 72 72 6f 72 20 6f 63 63 75 72  f no error occur
0a30: 73 2c 20 53 51 4c 49 54 45 5f 4f 4b 20 69 73 20  s, SQLITE_OK is 
0a40: 72 65 74 75 72 6e 65 64 2e 0a 2a 2f 20 0a 69 6e  returned..*/ .in
0a50: 74 20 73 71 6c 69 74 65 33 61 73 79 6e 63 5f 69  t sqlite3async_i
0a60: 6e 69 74 69 61 6c 69 7a 65 28 63 6f 6e 73 74 20  nitialize(const 
0a70: 63 68 61 72 20 2a 7a 50 61 72 65 6e 74 2c 20 69  char *zParent, i
0a80: 6e 74 20 69 73 44 65 66 61 75 6c 74 29 3b 0a 0a  nt isDefault);..
0a90: 2f 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74  /*.** This funct
0aa0: 69 6f 6e 20 75 6e 72 65 67 69 73 74 65 72 73 20  ion unregisters 
0ab0: 74 68 65 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73  the asynchronous
0ac0: 20 49 4f 20 56 46 53 20 75 73 69 6e 67 20 0a 2a   IO VFS using .*
0ad0: 2a 20 73 71 6c 69 74 65 33 5f 76 66 73 5f 75 6e  * sqlite3_vfs_un
0ae0: 72 65 67 69 73 74 65 72 28 29 2e 0a 2a 2a 0a 2a  register()..**.*
0af0: 2a 20 4f 6e 20 77 69 6e 33 32 20 70 6c 61 74 66  * On win32 platf
0b00: 6f 72 6d 73 2c 20 74 68 69 73 20 66 75 6e 63 74  orms, this funct
0b10: 69 6f 6e 20 61 6c 73 6f 20 72 65 6c 65 61 73 65  ion also release
0b20: 73 20 74 68 65 20 73 6d 61 6c 6c 20 6e 75 6d 62  s the small numb
0b30: 65 72 20 6f 66 20 0a 2a 2a 20 63 72 69 74 69 63  er of .** critic
0b40: 61 6c 20 73 65 63 74 69 6f 6e 20 61 6e 64 20 65  al section and e
0b50: 76 65 6e 74 20 6f 62 6a 65 63 74 73 20 63 72 65  vent objects cre
0b60: 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 61  ated by sqlite3a
0b70: 73 79 6e 63 5f 69 6e 69 74 69 61 6c 69 7a 65 28  sync_initialize(
0b80: 29 2e 0a 2a 2f 20 0a 76 6f 69 64 20 73 71 6c 69  )..*/ .void sqli
0b90: 74 65 33 61 73 79 6e 63 5f 73 68 75 74 64 6f 77  te3async_shutdow
0ba0: 6e 28 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 69 73  n();../*.** This
0bb0: 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 6f 6e   function may on
0bc0: 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65  ly be called whe
0bd0: 6e 20 74 68 65 20 61 73 79 6e 63 68 72 6f 6e 6f  n the asynchrono
0be0: 75 73 20 49 4f 20 56 46 53 20 69 73 20 0a 2a 2a  us IO VFS is .**
0bf0: 20 69 6e 73 74 61 6c 6c 65 64 20 28 61 66 74 65   installed (afte
0c00: 72 20 61 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  r a call to sqli
0c10: 74 65 33 61 73 79 6e 63 5f 69 6e 69 74 69 61 6c  te3async_initial
0c20: 69 7a 65 28 29 29 2e 20 49 74 20 70 72 6f 63 65  ize()). It proce
0c30: 73 73 65 73 0a 2a 2a 20 7a 65 72 6f 20 6f 72 20  sses.** zero or 
0c40: 6d 6f 72 65 20 71 75 65 75 65 64 20 77 72 69 74  more queued writ
0c50: 65 20 6f 70 65 72 61 74 69 6f 6e 73 20 62 65 66  e operations bef
0c60: 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 20 49  ore returning. I
0c70: 74 20 69 73 20 65 78 70 65 63 74 65 64 0a 2a 2a  t is expected.**
0c80: 20 28 62 75 74 20 6e 6f 74 20 72 65 71 75 69 72   (but not requir
0c90: 65 64 29 20 74 68 61 74 20 74 68 69 73 20 66 75  ed) that this fu
0ca0: 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 63  nction will be c
0cb0: 61 6c 6c 65 64 20 62 79 20 61 20 64 69 66 66 65  alled by a diffe
0cc0: 72 65 6e 74 20 0a 2a 2a 20 74 68 72 65 61 64 20  rent .** thread 
0cd0: 74 68 61 6e 20 74 68 6f 73 65 20 74 68 72 65 61  than those threa
0ce0: 64 73 20 74 68 61 74 20 75 73 65 20 53 51 4c 69  ds that use SQLi
0cf0: 74 65 2e 20 54 68 65 20 22 62 61 63 6b 67 72 6f  te. The "backgro
0d00: 75 6e 64 20 74 68 72 65 61 64 22 0a 2a 2a 20 74  und thread".** t
0d10: 68 61 74 20 70 65 72 66 6f 72 6d 73 20 49 4f 2e  hat performs IO.
0d20: 0a 2a 2a 0a 2a 2a 20 48 6f 77 20 6d 61 6e 79 20  .**.** How many 
0d30: 71 75 65 75 65 64 20 77 72 69 74 65 20 6f 70 65  queued write ope
0d40: 72 61 74 69 6f 6e 73 20 61 72 65 20 70 65 72 66  rations are perf
0d50: 6f 72 6d 65 64 20 62 65 66 6f 72 65 20 72 65 74  ormed before ret
0d60: 75 72 6e 69 6e 67 20 0a 2a 2a 20 64 65 70 65 6e  urning .** depen
0d70: 64 73 20 6f 6e 20 74 68 65 20 67 6c 6f 62 61 6c  ds on the global
0d80: 20 73 65 74 74 69 6e 67 20 63 6f 6e 66 69 67 75   setting configu
0d90: 72 65 64 20 62 79 20 70 61 73 73 69 6e 67 20 74  red by passing t
0da0: 68 65 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 48  he SQLITEASYNC_H
0db0: 41 4c 54 0a 2a 2a 20 76 65 72 62 20 74 6f 20 73  ALT.** verb to s
0dc0: 71 6c 69 74 65 33 61 73 79 6e 63 5f 63 6f 6e 74  qlite3async_cont
0dd0: 72 6f 6c 28 29 20 28 73 65 65 20 62 65 6c 6f 77  rol() (see below
0de0: 20 66 6f 72 20 64 65 74 61 69 6c 73 29 2e 20 42   for details). B
0df0: 79 20 64 65 66 61 75 6c 74 0a 2a 2a 20 74 68 69  y default.** thi
0e00: 73 20 66 75 6e 63 74 69 6f 6e 20 6e 65 76 65 72  s function never
0e10: 20 72 65 74 75 72 6e 73 20 2d 20 69 74 20 70 72   returns - it pr
0e20: 6f 63 65 73 73 65 73 20 61 6c 6c 20 70 65 6e 64  ocesses all pend
0e30: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ing operations a
0e40: 6e 64 20 0a 2a 2a 20 74 68 65 6e 20 62 6c 6f 63  nd .** then bloc
0e50: 6b 73 20 77 61 69 74 69 6e 67 20 66 6f 72 20 6e  ks waiting for n
0e60: 65 77 20 6f 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 49  ew ones..**.** I
0e70: 66 20 6d 75 6c 74 69 70 6c 65 20 73 69 6d 75 6c  f multiple simul
0e80: 74 61 6e 65 6f 75 73 20 63 61 6c 6c 73 20 61 72  taneous calls ar
0e90: 65 20 6d 61 64 65 20 74 6f 20 73 71 6c 69 74 65  e made to sqlite
0ea0: 33 61 73 79 6e 63 5f 72 75 6e 28 29 20 66 72 6f  3async_run() fro
0eb0: 6d 20 74 77 6f 0a 2a 2a 20 6f 72 20 6d 6f 72 65  m two.** or more
0ec0: 20 74 68 72 65 61 64 73 2c 20 74 68 65 6e 20 74   threads, then t
0ed0: 68 65 20 63 61 6c 6c 73 20 61 72 65 20 73 65 72  he calls are ser
0ee0: 69 61 6c 69 7a 65 64 20 69 6e 74 65 72 6e 61 6c  ialized internal
0ef0: 6c 79 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ly..*/.void sqli
0f00: 74 65 33 61 73 79 6e 63 5f 72 75 6e 28 29 3b 0a  te3async_run();.
0f10: 0a 2f 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  ./*.** This func
0f20: 74 69 6f 6e 20 6d 61 79 20 6f 6e 6c 79 20 62 65  tion may only be
0f30: 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68 65   called when the
0f40: 20 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f   asynchronous IO
0f50: 20 56 46 53 20 69 73 20 0a 2a 2a 20 69 6e 73 74   VFS is .** inst
0f60: 61 6c 6c 65 64 20 28 61 66 74 65 72 20 61 20 63  alled (after a c
0f70: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 61 73  all to sqlite3as
0f80: 79 6e 63 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  ync_initialize()
0f90: 29 2e 20 49 74 20 69 73 20 75 73 65 64 20 0a 2a  ). It is used .*
0fa0: 2a 20 74 6f 20 71 75 65 72 79 20 6f 72 20 63 6f  * to query or co
0fb0: 6e 66 69 67 75 72 65 20 76 61 72 69 6f 75 73 20  nfigure various 
0fc0: 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
0fd0: 61 66 66 65 63 74 20 74 68 65 20 6f 70 65 72 61  affect the opera
0fe0: 74 69 6f 6e 20 0a 2a 2a 20 6f 66 20 74 68 65 20  tion .** of the 
0ff0: 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f 20  asynchronous IO 
1000: 56 46 53 2e 20 41 74 20 70 72 65 73 65 6e 74 20  VFS. At present 
1010: 74 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  there are three 
1020: 70 61 72 61 6d 65 74 65 72 73 20 0a 2a 2a 20 73  parameters .** s
1030: 75 70 70 6f 72 74 65 64 3a 0a 2a 2a 0a 2a 2a 20  upported:.**.** 
1040: 20 20 2a 20 54 68 65 20 22 68 61 6c 74 22 20 70    * The "halt" p
1050: 61 72 61 6d 65 74 65 72 2c 20 77 68 69 63 68 20  arameter, which 
1060: 63 6f 6e 66 69 67 75 72 65 73 20 74 68 65 20 63  configures the c
1070: 69 72 63 75 6d 73 74 61 6e 63 65 73 20 75 6e 64  ircumstances und
1080: 65 72 0a 2a 2a 20 20 20 20 20 77 68 69 63 68 20  er.**     which 
1090: 74 68 65 20 73 71 6c 69 74 65 33 61 73 79 6e 63  the sqlite3async
10a0: 5f 72 75 6e 28 29 20 70 61 72 61 6d 65 74 65 72  _run() parameter
10b0: 20 69 73 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a   is configured..
10c0: 2a 2a 0a 2a 2a 20 20 20 2a 20 54 68 65 20 22 64  **.**   * The "d
10d0: 65 6c 61 79 22 20 70 61 72 61 6d 65 74 65 72 2e  elay" parameter.
10e0: 20 53 65 74 74 69 6e 67 20 74 68 65 20 64 65 6c   Setting the del
10f0: 61 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ay parameter to 
1100: 61 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 20 20  a non-zero.**   
1110: 20 20 76 61 6c 75 65 20 63 61 75 73 65 73 20 74    value causes t
1120: 68 65 20 73 71 6c 69 74 65 33 61 73 79 6e 63 5f  he sqlite3async_
1130: 72 75 6e 28 29 20 66 75 6e 63 74 69 6f 6e 20 74  run() function t
1140: 6f 20 73 6c 65 65 70 20 66 6f 72 20 74 68 65 0a  o sleep for the.
1150: 2a 2a 20 20 20 20 20 63 6f 6e 66 69 67 75 72 65  **     configure
1160: 64 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  d number of mill
1170: 69 73 65 63 6f 6e 64 73 20 62 65 74 77 65 65 6e  iseconds between
1180: 20 65 61 63 68 20 71 75 65 75 65 64 20 77 72 69   each queued wri
1190: 74 65 20 0a 2a 2a 20 20 20 20 20 6f 70 65 72 61  te .**     opera
11a0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 20 20 2a 20  tion..**.**   * 
11b0: 54 68 65 20 22 6c 6f 63 6b 66 69 6c 65 73 22 20  The "lockfiles" 
11c0: 70 61 72 61 6d 65 74 65 72 2e 20 54 68 69 73 20  parameter. This 
11d0: 70 61 72 61 6d 65 74 65 72 20 64 65 74 65 72 6d  parameter determ
11e0: 69 6e 65 73 20 77 68 65 74 68 65 72 20 6f 72 20  ines whether or 
11f0: 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 74 68 65 20  .**     not the 
1200: 61 73 79 6e 63 68 72 6f 6e 6f 75 73 20 49 4f 20  asynchronous IO 
1210: 56 46 53 20 6c 6f 63 6b 73 20 74 68 65 20 64 61  VFS locks the da
1220: 74 61 62 61 73 65 20 66 69 6c 65 73 20 69 74 20  tabase files it 
1230: 6f 70 65 72 61 74 65 73 0a 2a 2a 20 20 20 20 20  operates.**     
1240: 6f 6e 2e 20 44 69 73 61 62 6c 69 6e 67 20 66 69  on. Disabling fi
1250: 6c 65 20 6c 6f 63 6b 69 6e 67 20 63 61 6e 20 69  le locking can i
1260: 6d 70 72 6f 76 65 20 74 68 72 6f 75 67 68 70 75  mprove throughpu
1270: 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75  t..**.** This fu
1280: 6e 63 74 69 6f 6e 20 69 73 20 61 6c 77 61 79 73  nction is always
1290: 20 70 61 73 73 65 64 20 74 77 6f 20 61 72 67 75   passed two argu
12a0: 6d 65 6e 74 73 2e 20 57 68 65 6e 20 73 65 74 74  ments. When sett
12b0: 69 6e 67 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  ing the value.**
12c0: 20 6f 66 20 61 20 70 61 72 61 6d 65 74 65 72 2c   of a parameter,
12d0: 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
12e0: 65 6e 74 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ent must be one 
12f0: 6f 66 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 48  of SQLITEASYNC_H
1300: 41 4c 54 2c 0a 2a 2a 20 53 51 4c 49 54 45 41 53  ALT,.** SQLITEAS
1310: 59 4e 43 5f 44 45 4c 41 59 20 6f 72 20 53 51 4c  YNC_DELAY or SQL
1320: 49 54 45 41 53 59 4e 43 5f 4c 4f 43 4b 46 49 4c  ITEASYNC_LOCKFIL
1330: 45 53 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 61  ES. The second a
1340: 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20  rgument must.** 
1350: 62 65 20 70 61 73 73 65 64 20 74 68 65 20 6e 65  be passed the ne
1360: 77 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  w value for the 
1370: 70 61 72 61 6d 65 74 65 72 20 61 73 20 74 79 70  parameter as typ
1380: 65 20 22 69 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 57  e "int"..**.** W
1390: 68 65 6e 20 71 75 65 72 79 69 6e 67 20 74 68 65  hen querying the
13a0: 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20 6f   current value o
13b0: 66 20 61 20 70 61 72 61 6d 74 65 72 2c 20 74 68  f a paramter, th
13c0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
13d0: 20 6d 75 73 74 0a 2a 2a 20 62 65 20 6f 6e 65 20   must.** be one 
13e0: 6f 66 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 47  of SQLITEASYNC_G
13f0: 45 54 5f 48 41 4c 54 2c 20 47 45 54 5f 44 45 4c  ET_HALT, GET_DEL
1400: 41 59 20 6f 72 20 47 45 54 5f 4c 4f 43 4b 46 49  AY or GET_LOCKFI
1410: 4c 45 53 2e 20 54 68 65 20 73 65 63 6f 6e 64 20  LES. The second 
1420: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
1430: 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 6d 75  this function mu
1440: 73 74 20 62 65 20 6f 66 20 74 79 70 65 20 28 69  st be of type (i
1450: 6e 74 20 2a 29 2e 20 54 68 65 20 63 75 72 72 65  nt *). The curre
1460: 6e 74 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  nt value.** of t
1470: 68 65 20 71 75 65 72 69 65 64 20 70 61 72 61 6d  he queried param
1480: 65 74 65 72 20 69 73 20 63 6f 70 69 65 64 20 74  eter is copied t
1490: 6f 20 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69  o the memory poi
14a0: 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 0a 2a  nted to by the.*
14b0: 2a 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  * second argumen
14c0: 74 2e 20 46 6f 72 20 65 78 61 6d 70 6c 65 3a 0a  t. For example:.
14d0: 2a 2a 0a 2a 2a 20 20 20 69 6e 74 20 65 43 75 72  **.**   int eCur
14e0: 72 65 6e 74 48 61 6c 74 3b 0a 2a 2a 20 20 20 69  rentHalt;.**   i
14f0: 6e 74 20 65 4e 65 77 48 61 6c 74 20 3d 20 53 51  nt eNewHalt = SQ
1500: 4c 49 54 45 41 53 59 4e 43 5f 48 41 4c 54 5f 49  LITEASYNC_HALT_I
1510: 44 4c 45 3b 0a 2a 2a 0a 2a 2a 20 20 20 73 71 6c  DLE;.**.**   sql
1520: 69 74 65 33 61 73 79 6e 63 5f 63 6f 6e 74 72 6f  ite3async_contro
1530: 6c 28 53 51 4c 49 54 45 41 53 59 4e 43 5f 48 41  l(SQLITEASYNC_HA
1540: 4c 54 2c 20 65 4e 65 77 48 61 6c 74 29 3b 0a 2a  LT, eNewHalt);.*
1550: 2a 20 20 20 73 71 6c 69 74 65 33 61 73 79 6e 63  *   sqlite3async
1560: 5f 63 6f 6e 74 72 6f 6c 28 53 51 4c 49 54 45 41  _control(SQLITEA
1570: 53 59 4e 43 5f 47 45 54 5f 48 41 4c 54 2c 20 26  SYNC_GET_HALT, &
1580: 65 43 75 72 72 65 6e 74 48 61 6c 74 29 3b 0a 2a  eCurrentHalt);.*
1590: 2a 20 20 20 61 73 73 65 72 74 28 20 65 4e 65 77  *   assert( eNew
15a0: 48 61 6c 74 3d 3d 65 43 75 72 72 65 6e 74 48 61  Halt==eCurrentHa
15b0: 6c 74 20 29 3b 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lt );.**.** See 
15c0: 62 65 6c 6f 77 20 66 6f 72 20 6d 6f 72 65 20 64  below for more d
15d0: 65 74 61 69 6c 20 6f 6e 20 65 61 63 68 20 63 6f  etail on each co
15e0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 70 61 72 61  nfiguration para
15f0: 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  meter..**.** SQL
1600: 49 54 45 41 53 59 4e 43 5f 48 41 4c 54 3a 0a 2a  ITEASYNC_HALT:.*
1610: 2a 0a 2a 2a 20 20 20 54 68 69 73 20 69 73 20 75  *.**   This is u
1620: 73 65 64 20 74 6f 20 73 65 74 20 74 68 65 20 76  sed to set the v
1630: 61 6c 75 65 20 6f 66 20 74 68 65 20 22 68 61 6c  alue of the "hal
1640: 74 22 20 70 61 72 61 6d 65 74 65 72 2e 20 54 68  t" parameter. Th
1650: 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 20 20 61 72  e second.**   ar
1660: 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 6f  gument must be o
1670: 6e 65 20 6f 66 20 74 68 65 20 53 51 4c 49 54 45  ne of the SQLITE
1680: 41 53 59 4e 43 5f 48 41 4c 54 5f 58 58 58 20 73  ASYNC_HALT_XXX s
1690: 79 6d 62 6f 6c 73 20 64 65 66 69 6e 65 64 0a 2a  ymbols defined.*
16a0: 2a 20 20 20 62 65 6c 6f 77 20 28 65 69 74 68 65  *   below (eithe
16b0: 72 20 4e 45 56 45 52 2c 20 49 44 4c 45 20 61 6e  r NEVER, IDLE an
16c0: 64 20 4e 4f 57 29 2e 0a 2a 2a 0a 2a 2a 20 20 20  d NOW)..**.**   
16d0: 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
16e0: 20 69 73 20 73 65 74 20 74 6f 20 4e 45 56 45 52   is set to NEVER
16f0: 2c 20 74 68 65 6e 20 63 61 6c 6c 73 20 74 6f 20  , then calls to 
1700: 73 71 6c 69 74 65 33 61 73 79 6e 63 5f 72 75 6e  sqlite3async_run
1710: 28 29 0a 2a 2a 20 20 20 6e 65 76 65 72 20 72 65  ().**   never re
1720: 74 75 72 6e 2e 20 54 68 69 73 20 69 73 20 74 68  turn. This is th
1730: 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
1740: 67 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  g. If the parame
1750: 74 65 72 20 69 73 20 73 65 74 0a 2a 2a 20 20 20  ter is set.**   
1760: 74 6f 20 49 44 4c 45 2c 20 74 68 65 6e 20 63 61  to IDLE, then ca
1770: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 61 73  lls to sqlite3as
1780: 79 6e 63 5f 72 75 6e 28 29 20 72 65 74 75 72 6e  ync_run() return
1790: 20 61 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 0a   as soon as the.
17a0: 2a 2a 20 20 20 71 75 65 75 65 20 6f 66 20 70 65  **   queue of pe
17b0: 6e 64 69 6e 67 20 77 72 69 74 65 20 6f 70 65 72  nding write oper
17c0: 61 74 69 6f 6e 73 20 69 73 20 65 6d 70 74 79 2e  ations is empty.
17d0: 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
17e0: 72 20 69 73 20 73 65 74 0a 2a 2a 20 20 20 74 6f  r is set.**   to
17f0: 20 4e 4f 57 2c 20 74 68 65 6e 20 63 61 6c 6c 73   NOW, then calls
1800: 20 74 6f 20 73 71 6c 69 74 65 33 61 73 79 6e 63   to sqlite3async
1810: 5f 72 75 6e 28 29 20 72 65 74 75 72 6e 20 61 73  _run() return as
1820: 20 71 75 69 63 6b 6c 79 20 61 73 20 0a 2a 2a 20   quickly as .** 
1830: 20 20 70 6f 73 73 69 62 6c 65 2c 20 77 69 74 68    possible, with
1840: 6f 75 74 20 70 72 6f 63 65 73 73 69 6e 67 20 61  out processing a
1850: 6e 79 20 70 65 6e 64 69 6e 67 20 77 72 69 74 65  ny pending write
1860: 20 72 65 71 75 65 73 74 73 2e 0a 2a 2a 0a 2a 2a   requests..**.**
1870: 20 20 20 49 66 20 61 6e 20 61 74 74 65 6d 70 74     If an attempt
1880: 20 69 73 20 6d 61 64 65 20 74 6f 20 73 65 74 20   is made to set 
1890: 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
18a0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 76 61 6c  o an integer val
18b0: 75 65 20 6f 74 68 65 72 0a 2a 2a 20 20 20 74 68  ue other.**   th
18c0: 61 6e 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 48  an SQLITEASYNC_H
18d0: 41 4c 54 5f 4e 45 56 45 52 2c 20 49 44 4c 45 20  ALT_NEVER, IDLE 
18e0: 6f 72 20 4e 4f 57 2c 20 74 68 65 6e 20 73 71 6c  or NOW, then sql
18f0: 69 74 65 33 61 73 79 6e 63 5f 63 6f 6e 74 72 6f  ite3async_contro
1900: 6c 28 29 20 0a 2a 2a 20 20 20 72 65 74 75 72 6e  l() .**   return
1910: 73 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20  s SQLITE_MISUSE 
1920: 61 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74 20  and the current 
1930: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 70 61 72  value of the par
1940: 61 6d 65 74 65 72 20 69 73 20 6e 6f 74 20 0a 2a  ameter is not .*
1950: 2a 20 20 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  *   modified..**
1960: 0a 2a 2a 20 20 20 4d 6f 64 69 66 79 69 6e 67 20  .**   Modifying 
1970: 74 68 65 20 22 68 61 6c 74 22 20 70 61 72 61 6d  the "halt" param
1980: 65 74 65 72 20 61 66 66 65 63 74 73 20 63 61 6c  eter affects cal
1990: 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 61 73 79  ls to sqlite3asy
19a0: 6e 63 5f 72 75 6e 28 29 20 0a 2a 2a 20 20 20 6d  nc_run() .**   m
19b0: 61 64 65 20 62 79 20 6f 74 68 65 72 20 74 68 72  ade by other thr
19c0: 65 61 64 73 20 74 68 61 74 20 61 72 65 20 63 75  eads that are cu
19d0: 72 72 65 6e 74 6c 79 20 69 6e 20 70 72 6f 67 72  rrently in progr
19e0: 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 49 54  ess..**.** SQLIT
19f0: 45 41 53 59 4e 43 5f 44 45 4c 41 59 3a 0a 2a 2a  EASYNC_DELAY:.**
1a00: 0a 2a 2a 20 20 20 54 68 69 73 20 69 73 20 75 73  .**   This is us
1a10: 65 64 20 74 6f 20 73 65 74 20 74 68 65 20 76 61  ed to set the va
1a20: 6c 75 65 20 6f 66 20 74 68 65 20 22 64 65 6c 61  lue of the "dela
1a30: 79 22 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  y" parameter. If
1a40: 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 61 20 6e   set to.**   a n
1a50: 6f 6e 2d 7a 65 72 6f 20 76 61 6c 75 65 2c 20 74  on-zero value, t
1a60: 68 65 6e 20 61 66 74 65 72 20 63 6f 6d 70 6c 65  hen after comple
1a70: 74 69 6e 67 20 61 20 70 65 6e 64 69 6e 67 20 77  ting a pending w
1a80: 72 69 74 65 20 72 65 71 75 65 73 74 2c 20 74 68  rite request, th
1a90: 65 0a 2a 2a 20 20 20 73 71 6c 69 74 65 33 61 73  e.**   sqlite3as
1aa0: 79 6e 63 5f 72 75 6e 28 29 20 66 75 6e 63 74 69  ync_run() functi
1ab0: 6f 6e 20 73 6c 65 65 70 73 20 66 6f 72 20 74 68  on sleeps for th
1ac0: 65 20 63 6f 6e 66 69 67 75 72 65 64 20 6e 75 6d  e configured num
1ad0: 62 65 72 20 6f 66 20 0a 2a 2a 20 20 20 6d 69 6c  ber of .**   mil
1ae0: 6c 69 73 65 63 6f 6e 64 73 2e 0a 2a 2a 0a 2a 2a  liseconds..**.**
1af0: 20 20 20 49 66 20 61 6e 20 61 74 74 65 6d 70 74     If an attempt
1b00: 20 69 73 20 6d 61 64 65 20 74 6f 20 73 65 74 20   is made to set 
1b10: 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 74  this parameter t
1b20: 6f 20 61 20 6e 65 67 61 74 69 76 65 20 76 61 6c  o a negative val
1b30: 75 65 2c 0a 2a 2a 20 20 20 73 71 6c 69 74 65 33  ue,.**   sqlite3
1b40: 61 73 79 6e 63 5f 63 6f 6e 74 72 6f 6c 28 29 20  async_control() 
1b50: 72 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 4d  returns SQLITE_M
1b60: 49 53 55 53 45 20 61 6e 64 20 74 68 65 20 63 75  ISUSE and the cu
1b70: 72 72 65 6e 74 20 76 61 6c 75 65 0a 2a 2a 20 20  rrent value.**  
1b80: 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
1b90: 72 20 69 73 20 6e 6f 74 20 6d 6f 64 69 66 69 65  r is not modifie
1ba0: 64 2e 0a 2a 2a 0a 2a 2a 20 20 20 4d 6f 64 69 66  d..**.**   Modif
1bb0: 79 69 6e 67 20 74 68 65 20 22 64 65 6c 61 79 22  ying the "delay"
1bc0: 20 70 61 72 61 6d 65 74 65 72 20 61 66 66 65 63   parameter affec
1bd0: 74 73 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  ts calls to sqli
1be0: 74 65 33 61 73 79 6e 63 5f 72 75 6e 28 29 20 0a  te3async_run() .
1bf0: 2a 2a 20 20 20 6d 61 64 65 20 62 79 20 6f 74 68  **   made by oth
1c00: 65 72 20 74 68 72 65 61 64 73 20 74 68 61 74 20  er threads that 
1c10: 61 72 65 20 63 75 72 72 65 6e 74 6c 79 20 69 6e  are currently in
1c20: 20 70 72 6f 67 72 65 73 73 2e 0a 2a 2a 0a 2a 2a   progress..**.**
1c30: 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 4c 4f 43   SQLITEASYNC_LOC
1c40: 4b 46 49 4c 45 53 3a 0a 2a 2a 0a 2a 2a 20 20 20  KFILES:.**.**   
1c50: 54 68 69 73 20 69 73 20 75 73 65 64 20 74 6f 20  This is used to 
1c60: 73 65 74 20 74 68 65 20 76 61 6c 75 65 20 6f 66  set the value of
1c70: 20 74 68 65 20 22 6c 6f 63 6b 66 69 6c 65 73 22   the "lockfiles"
1c80: 20 70 61 72 61 6d 65 74 65 72 2e 20 54 68 69 73   parameter. This
1c90: 0a 2a 2a 20 20 20 70 61 72 61 6d 65 74 65 72 20  .**   parameter 
1ca0: 6d 75 73 74 20 62 65 20 73 65 74 20 74 6f 20 65  must be set to e
1cb0: 69 74 68 65 72 20 30 20 6f 72 20 31 2e 20 49 66  ither 0 or 1. If
1cc0: 20 73 65 74 20 74 6f 20 31 2c 20 74 68 65 6e 20   set to 1, then 
1cd0: 74 68 65 0a 2a 2a 20 20 20 61 73 79 6e 63 68 72  the.**   asynchr
1ce0: 6f 6e 6f 75 73 20 49 4f 20 56 46 53 20 75 73 65  onous IO VFS use
1cf0: 73 20 74 68 65 20 78 4c 6f 63 6b 28 29 20 61 6e  s the xLock() an
1d00: 64 20 78 55 6e 6c 6f 63 6b 28 29 20 6d 65 74 68  d xUnlock() meth
1d10: 6f 64 73 20 6f 66 20 74 68 65 0a 2a 2a 20 20 20  ods of the.**   
1d20: 70 61 72 65 6e 74 20 56 46 53 20 74 6f 20 6c 6f  parent VFS to lo
1d30: 63 6b 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ck database file
1d40: 73 20 62 65 69 6e 67 20 72 65 61 64 20 61 6e 64  s being read and
1d50: 2f 6f 72 20 77 72 69 74 74 65 6e 2e 20 49 66 0a  /or written. If.
1d60: 2a 2a 20 20 20 74 68 65 20 70 61 72 61 6d 65 74  **   the paramet
1d70: 65 72 20 69 73 20 73 65 74 20 74 6f 20 30 2c 20  er is set to 0, 
1d80: 74 68 65 6e 20 74 68 65 73 65 20 6c 6f 63 6b 73  then these locks
1d90: 20 61 72 65 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a   are omitted..**
1da0: 0a 2a 2a 20 20 20 54 68 69 73 20 70 61 72 61 6d  .**   This param
1db0: 65 74 65 72 20 6d 61 79 20 6f 6e 6c 79 20 62 65  eter may only be
1dc0: 20 73 65 74 20 77 68 65 6e 20 74 68 65 72 65 20   set when there 
1dd0: 61 72 65 20 6e 6f 20 6f 70 65 6e 20 64 61 74 61  are no open data
1de0: 62 61 73 65 0a 2a 2a 20 20 20 63 6f 6e 6e 65 63  base.**   connec
1df0: 74 69 6f 6e 73 20 75 73 69 6e 67 20 74 68 65 20  tions using the 
1e00: 56 46 53 20 61 6e 64 20 74 68 65 20 71 75 65 75  VFS and the queu
1e10: 65 20 6f 66 20 70 65 6e 64 69 6e 67 20 77 72 69  e of pending wri
1e20: 74 65 20 72 65 71 75 65 73 74 73 0a 2a 2a 20 20  te requests.**  
1e30: 20 69 73 20 65 6d 70 74 79 2e 20 41 74 74 65 6d   is empty. Attem
1e40: 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69 74 20  pting to set it 
1e50: 77 68 65 6e 20 74 68 69 73 20 69 73 20 6e 6f 74  when this is not
1e60: 20 74 72 75 65 2c 20 6f 72 20 74 6f 20 73 65 74   true, or to set
1e70: 20 69 74 20 0a 2a 2a 20 20 20 74 6f 20 61 20 76   it .**   to a v
1e80: 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20  alue other than 
1e90: 30 20 6f 72 20 31 20 63 61 75 73 65 73 20 73 71  0 or 1 causes sq
1ea0: 6c 69 74 65 33 61 73 79 6e 63 5f 63 6f 6e 74 72  lite3async_contr
1eb0: 6f 6c 28 29 20 74 6f 20 72 65 74 75 72 6e 0a 2a  ol() to return.*
1ec0: 2a 20 20 20 53 51 4c 49 54 45 5f 4d 49 53 55 53  *   SQLITE_MISUS
1ed0: 45 20 61 6e 64 20 74 68 65 20 76 61 6c 75 65 20  E and the value 
1ee0: 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  of the parameter
1ef0: 20 74 6f 20 72 65 6d 61 69 6e 20 75 6e 63 68 61   to remain uncha
1f00: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 20 20 49 66  nged..**.**   If
1f10: 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20   this parameter 
1f20: 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2c 20  is set to zero, 
1f30: 74 68 65 6e 20 69 74 20 69 73 20 6f 6e 6c 79 20  then it is only 
1f40: 73 61 66 65 20 74 6f 20 61 63 63 65 73 73 20 74  safe to access t
1f50: 68 65 0a 2a 2a 20 20 20 64 61 74 61 62 61 73 65  he.**   database
1f60: 20 76 69 61 20 74 68 65 20 61 73 79 6e 63 68 72   via the asynchr
1f70: 6f 6e 6f 75 73 20 49 4f 20 56 46 53 20 66 72 6f  onous IO VFS fro
1f80: 6d 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c  m within a singl
1f90: 65 20 70 72 6f 63 65 73 73 2e 20 49 66 0a 2a 2a  e process. If.**
1fa0: 20 20 20 77 68 69 6c 65 20 77 72 69 74 69 6e 67     while writing
1fb0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
1fc0: 20 76 69 61 20 74 68 65 20 61 73 79 6e 63 68 72   via the asynchr
1fd0: 6f 6e 6f 75 73 20 49 4f 20 56 46 53 20 74 68 65  onous IO VFS the
1fe0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 69   database.**   i
1ff0: 73 20 61 6c 73 6f 20 72 65 61 64 20 6f 72 20 77  s also read or w
2000: 72 69 74 74 65 6e 20 66 72 6f 6d 20 77 69 74 68  ritten from with
2010: 69 6e 20 61 6e 6f 74 68 65 72 20 70 72 6f 63 65  in another proce
2020: 73 73 2c 20 6f 72 20 76 69 61 20 61 6e 6f 74 68  ss, or via anoth
2030: 65 72 0a 2a 2a 20 20 20 63 6f 6e 6e 65 63 74 69  er.**   connecti
2040: 6f 6e 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  on that does not
2050: 20 75 73 65 20 74 68 65 20 61 73 79 6e 63 68 72   use the asynchr
2060: 6f 6e 6f 75 73 20 49 4f 20 56 46 53 20 77 69 74  onous IO VFS wit
2070: 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  hin the same.** 
2080: 20 20 70 72 6f 63 65 73 73 2c 20 74 68 65 20 72    process, the r
2090: 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
20a0: 69 6e 65 64 20 28 61 6e 64 20 6d 61 79 20 69 6e  ined (and may in
20b0: 63 6c 75 64 65 20 63 72 61 73 68 65 73 20 6f 72  clude crashes or
20c0: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 63   database.**   c
20d0: 6f 72 72 75 70 74 69 6f 6e 29 2e 0a 2a 2a 0a 2a  orruption)..**.*
20e0: 2a 20 20 20 41 6c 74 65 72 6e 61 74 69 76 65 6c  *   Alternativel
20f0: 79 2c 20 69 66 20 74 68 69 73 20 70 61 72 61 6d  y, if this param
2100: 65 74 65 72 20 69 73 20 73 65 74 20 74 6f 20 31  eter is set to 1
2110: 2c 20 74 68 65 6e 20 69 74 20 69 73 20 73 61 66  , then it is saf
2120: 65 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 20  e to access.**  
2130: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 72   the database fr
2140: 6f 6d 20 6d 75 6c 74 69 70 6c 65 20 63 6f 6e 6e  om multiple conn
2150: 65 63 74 69 6f 6e 73 20 77 69 74 68 69 6e 20 6d  ections within m
2160: 75 6c 74 69 70 6c 65 20 70 72 6f 63 65 73 73 65  ultiple processe
2170: 73 20 75 73 69 6e 67 0a 2a 2a 20 20 20 65 69 74  s using.**   eit
2180: 68 65 72 20 74 68 65 20 61 73 79 6e 63 68 72 6f  her the asynchro
2190: 6e 6f 75 73 20 49 4f 20 56 46 53 20 6f 72 20 74  nous IO VFS or t
21a0: 68 65 20 70 61 72 65 6e 74 20 56 46 53 20 64 69  he parent VFS di
21b0: 72 65 63 74 6c 79 2e 0a 2a 2f 0a 69 6e 74 20 73  rectly..*/.int s
21c0: 71 6c 69 74 65 33 61 73 79 6e 63 5f 63 6f 6e 74  qlite3async_cont
21d0: 72 6f 6c 28 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  rol(int op, ...)
21e0: 3b 0a 0a 2f 2a 0a 2a 2a 20 56 61 6c 75 65 73 20  ;../*.** Values 
21f0: 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
2200: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
2210: 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65  gument to sqlite
2220: 33 61 73 79 6e 63 5f 63 6f 6e 74 72 6f 6c 28 29  3async_control()
2230: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
2240: 49 54 45 41 53 59 4e 43 5f 48 41 4c 54 20 20 20  ITEASYNC_HALT   
2250: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
2260: 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 47 45 54   SQLITEASYNC_GET
2270: 5f 48 41 4c 54 20 20 20 20 20 20 32 0a 23 64 65  _HALT      2.#de
2280: 66 69 6e 65 20 53 51 4c 49 54 45 41 53 59 4e 43  fine SQLITEASYNC
2290: 5f 44 45 4c 41 59 20 20 20 20 20 20 20 20 20 33  _DELAY         3
22a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 41  .#define SQLITEA
22b0: 53 59 4e 43 5f 47 45 54 5f 44 45 4c 41 59 20 20  SYNC_GET_DELAY  
22c0: 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
22d0: 49 54 45 41 53 59 4e 43 5f 4c 4f 43 4b 46 49 4c  ITEASYNC_LOCKFIL
22e0: 45 53 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65  ES     5.#define
22f0: 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 47 45 54   SQLITEASYNC_GET
2300: 5f 4c 4f 43 4b 46 49 4c 45 53 20 36 0a 0a 2f 2a  _LOCKFILES 6../*
2310: 0a 2a 2a 20 49 66 20 74 68 65 20 66 69 72 73 74  .** If the first
2320: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
2330: 69 74 65 33 61 73 79 6e 63 5f 63 6f 6e 74 72 6f  ite3async_contro
2340: 6c 28 29 20 69 73 20 53 51 4c 49 54 45 41 53 59  l() is SQLITEASY
2350: 4e 43 5f 48 41 4c 54 2c 0a 2a 2a 20 74 68 65 20  NC_HALT,.** the 
2360: 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2370: 73 68 6f 75 6c 64 20 62 65 20 6f 6e 65 20 6f 66  should be one of
2380: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 2e 0a   the following..
2390: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
23a0: 45 41 53 59 4e 43 5f 48 41 4c 54 5f 4e 45 56 45  EASYNC_HALT_NEVE
23b0: 52 20 30 20 20 20 20 20 20 20 2f 2a 20 4e 65 76  R 0       /* Nev
23c0: 65 72 20 68 61 6c 74 20 28 64 65 66 61 75 6c 74  er halt (default
23d0: 20 76 61 6c 75 65 29 20 2a 2f 0a 23 64 65 66 69   value) */.#defi
23e0: 6e 65 20 53 51 4c 49 54 45 41 53 59 4e 43 5f 48  ne SQLITEASYNC_H
23f0: 41 4c 54 5f 4e 4f 57 20 20 20 31 20 20 20 20 20  ALT_NOW   1     
2400: 20 20 2f 2a 20 48 61 6c 74 20 61 73 20 73 6f 6f    /* Halt as soo
2410: 6e 20 61 73 20 70 6f 73 73 69 62 6c 65 20 2a 2f  n as possible */
2420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 41  .#define SQLITEA
2430: 53 59 4e 43 5f 48 41 4c 54 5f 49 44 4c 45 20 20  SYNC_HALT_IDLE  
2440: 32 20 20 20 20 20 20 20 2f 2a 20 48 61 6c 74 20  2       /* Halt 
2450: 77 68 65 6e 20 77 72 69 74 65 2d 71 75 65 75 65  when write-queue
2460: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 0a 23 69   is empty */..#i
2470: 66 64 65 66 20 5f 5f 63 70 6c 75 73 70 6c 75 73  fdef __cplusplus
2480: 0a 7d 20 20 2f 2a 20 45 6e 64 20 6f 66 20 74 68  .}  /* End of th
2490: 65 20 27 65 78 74 65 72 6e 20 22 43 22 27 20 62  e 'extern "C"' b
24a0: 6c 6f 63 6b 20 2a 2f 0a 23 65 6e 64 69 66 0a 23  lock */.#endif.#
24b0: 65 6e 64 69 66 20 20 20 20 20 20 20 20 2f 2a 20  endif        /* 
24c0: 69 66 6e 64 65 66 20 5f 5f 53 51 4c 49 54 45 41  ifndef __SQLITEA
24d0: 53 59 4e 43 5f 48 5f 20 2a 2f 0a 0a              SYNC_H_ */..