libcwal  Hex Artifact Content

Artifact 494f21100a59b8d24dcd6db676da0516b546749b:

Wiki page [cwal] by stephan 2017-12-01 09:50:30.
0000: 44 20 32 30 31 37 2d 31 32 2d 30 31 54 30 39 3a  D 2017-12-01T09:
0010: 35 30 3a 33 30 2e 35 36 30 0a 4c 20 63 77 61 6c  50:30.560.L cwal
0020: 0a 50 20 62 31 35 32 39 33 33 30 38 32 34 34 66  .P b15293308244f
0030: 32 63 64 30 61 36 37 33 36 30 34 31 31 63 36 37  2cd0a67360411c67
0040: 30 61 37 65 37 61 62 30 61 62 65 0a 55 20 73 74  0a7e7ab0abe.U st
0050: 65 70 68 61 6e 0a 57 20 31 30 36 37 35 0a 3c 68  ephan.W 10675.<h
0060: 31 3e 63 77 61 6c 3a 20 53 63 72 69 70 74 69 6e  1>cwal: Scriptin
0070: 67 20 45 6e 67 69 6e 65 20 57 69 74 68 6f 75 74  g Engine Without
0080: 20 41 20 4c 61 6e 67 75 61 67 65 3c 2f 68 31 3e   A Language</h1>
0090: 0d 0a 0d 0a 63 77 61 6c 20 28 70 72 6f 6e 6f 75  ....cwal (pronou
00a0: 6e 63 65 64 20 22 73 65 61 20 77 61 6c 6c 22 29  nced "sea wall")
00b0: 20 69 73 20 61 6e 20 65 78 70 65 72 69 6d 65 6e   is an experimen
00c0: 74 61 6c 20 73 63 72 69 70 74 69 6e 67 20 65 6e  tal scripting en
00d0: 67 69 6e 65 2f 67 61 72 62 61 67 65 2d 63 6f 6c  gine/garbage-col
00e0: 6c 65 63 74 69 6f 6e 20 6c 69 62 72 61 72 79 20  lection library 
00f0: 69 6d 70 6c 65 6d 65 6e 74 65 64 20 69 6e 20 43  implemented in C
0100: 20 28 77 68 69 63 68 20 69 73 20 77 68 65 72 65   (which is where
0110: 20 74 68 65 20 22 63 22 20 63 6f 6d 65 73 20 66   the "c" comes f
0120: 72 6f 6d 20 2d 20 69 74 73 20 6f 72 69 67 69 6e  rom - its origin
0130: 61 6c 20 6e 61 6d 65 20 77 61 73 20 22 73 65 77  al name was "sew
0140: 61 6c 22 29 2e 20 63 77 61 6c 20 69 74 73 65 6c  al"). cwal itsel
0150: 66 20 64 6f 65 73 20 6e 6f 74 20 70 72 6f 76 69  f does not provi
0160: 64 65 20 61 20 73 63 72 69 70 74 69 6e 67 20 6c  de a scripting l
0170: 61 6e 67 75 61 67 65 2c 20 6f 6e 6c 79 20 74 68  anguage, only th
0180: 65 20 70 69 65 63 65 73 20 6e 65 65 64 65 64 20  e pieces needed 
0190: 66 6f 72 20 61 20 63 75 73 74 6f 6d 20 73 63 72  for a custom scr
01a0: 69 70 74 20 70 61 72 73 65 72 20 74 6f 20 6d 61  ipt parser to ma
01b0: 6e 61 67 65 20 69 74 73 20 6d 65 6d 6f 72 79 2c  nage its memory,
01c0: 20 73 63 6f 70 69 6e 67 2c 20 76 61 72 69 61 62   scoping, variab
01d0: 6c 65 73 2c 20 61 20 76 61 6c 75 65 20 74 79 70  les, a value typ
01e0: 65 20 73 79 73 74 65 6d 20 77 69 74 68 20 77 68  e system with wh
01f0: 69 63 68 20 74 6f 20 63 6f 6d 6d 75 6e 69 63 61  ich to communica
0200: 74 65 20 76 61 6c 75 65 73 20 62 65 74 77 65 65  te values betwee
0210: 6e 20 73 63 72 69 70 74 20 63 6f 64 65 20 61 6e  n script code an
0220: 64 20 6e 61 74 69 76 65 20 63 6f 64 65 2c 20 65  d native code, e
0230: 74 63 2e 20 28 54 68 61 74 20 73 61 69 64 2c 20  tc. (That said, 
0240: 73 65 65 20 5b 73 32 5d 20 66 6f 72 20 61 20 73  see [s2] for a s
0250: 63 72 69 70 74 69 6e 67 20 6c 61 6e 67 75 61 67  cripting languag
0260: 65 20 62 75 69 6c 74 20 6f 6e 20 74 6f 70 20 6f  e built on top o
0270: 66 20 63 77 61 6c 2e 29 20 49 74 20 63 6f 75 6c  f cwal.) It coul
0280: 64 20 61 6c 73 6f 20 62 65 20 75 73 65 64 20 61  d also be used a
0290: 73 20 61 20 66 6f 72 6d 20 6f 66 20 67 61 72 62  s a form of garb
02a0: 61 67 65 20 63 6f 6c 6c 65 63 74 6f 72 20 66 6f  age collector fo
02b0: 72 20 63 6c 69 65 6e 74 20 61 70 70 73 2c 20 69  r client apps, i
02c0: 6e 64 65 70 65 6e 64 65 6e 74 20 6f 66 20 61 6e  ndependent of an
02d0: 79 20 73 63 72 69 70 74 69 6e 67 2d 72 65 6c 61  y scripting-rela
02e0: 74 65 64 20 66 75 6e 63 74 69 6f 6e 61 6c 69 74  ted functionalit
02f0: 79 20 28 74 68 65 72 65 27 73 20 61 20 62 69 67  y (there's a big
0300: 20 6f 76 65 72 6c 61 70 29 2e 20 63 77 61 6c 20   overlap). cwal 
0310: 75 73 65 73 20 61 20 68 79 62 72 69 64 20 6f 66  uses a hybrid of
0320: 20 72 65 66 65 72 65 6e 63 65 2d 63 6f 75 6e 74   reference-count
0330: 69 6e 67 20 77 69 74 68 20 43 2b 2b 2d 6c 69 6b  ing with C++-lik
0340: 65 20 73 63 6f 70 69 6e 67 20 66 6f 72 20 64 65  e scoping for de
0350: 74 65 72 6d 69 6e 69 73 74 69 63 20 66 69 6e 61  terministic fina
0360: 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20 73 75 70  lization and sup
0370: 70 6f 72 74 73 20 74 68 65 20 70 72 6f 70 65 72  ports the proper
0380: 20 74 72 61 63 6b 69 6e 67 20 61 6e 64 20 63 6c   tracking and cl
0390: 65 61 6e 69 6e 67 20 75 70 20 63 79 63 6c 69 63  eaning up cyclic
03a0: 20 73 74 72 75 63 74 75 72 65 73 2e 0d 0a 0d 0a   structures.....
03b0: 63 77 61 6c 20 77 61 73 20 73 74 61 72 74 65 64  cwal was started
03c0: 20 69 6e 20 6c 61 74 65 20 4a 75 6c 79 2c 20 32   in late July, 2
03d0: 30 31 32 20 61 73 20 61 20 66 6f 72 6b 20 6f 66  012 as a fork of
03e0: 20 5b 68 74 74 70 3a 2f 2f 66 6f 73 73 69 6c 2e   [http://fossil.
03f0: 77 61 6e 64 65 72 69 6e 67 68 6f 72 73 65 2e 6e  wanderinghorse.n
0400: 65 74 2f 77 69 6b 69 73 2f 63 73 6f 6e 7c 63 73  et/wikis/cson|cs
0410: 6f 6e 5d 2c 20 61 20 4a 53 4f 4e 20 6c 69 62 72  on], a JSON libr
0420: 61 72 79 20 66 6f 72 20 43 2c 20 66 72 6f 6d 20  ary for C, from 
0430: 77 68 69 63 68 20 63 77 61 6c 20 69 6e 69 74 69  which cwal initi
0440: 61 6c 6c 79 20 64 65 72 69 76 65 64 20 69 74 73  ally derived its
0450: 20 64 61 74 61 20 74 79 70 65 20 73 79 73 74 65   data type syste
0460: 6d 20 61 6e 64 20 6d 75 63 68 20 6f 66 20 74 68  m and much of th
0470: 65 20 72 65 6c 61 74 65 64 20 63 6f 64 65 2e 20  e related code. 
0480: 49 74 20 77 61 73 20 6c 61 72 67 65 6c 79 20 69  It was largely i
0490: 6e 73 70 69 72 65 64 20 62 79 20 74 68 65 20 5b  nspired by the [
04a0: 68 74 74 70 3a 2f 2f 66 6f 73 73 69 6c 2e 77 61  http://fossil.wa
04b0: 6e 64 65 72 69 6e 67 68 6f 72 73 65 2e 6e 65 74  nderinghorse.net
04c0: 2f 72 65 70 6f 73 2f 74 68 31 2d 73 67 62 2f 7c  /repos/th1-sgb/|
04d0: 54 48 31 20 73 63 72 69 70 74 69 6e 67 20 65 6e  TH1 scripting en
04e0: 67 69 6e 65 5d 20 6f 72 69 67 69 6e 61 6c 6c 79  gine] originally
04f0: 20 66 6f 75 6e 64 20 69 6e 20 74 68 65 20 5b 68   found in the [h
0500: 74 74 70 3a 2f 2f 66 6f 73 73 69 6c 2d 73 63 6d  ttp://fossil-scm
0510: 2e 6f 72 67 7c 46 6f 73 73 69 6c 20 53 43 4d 5d  .org|Fossil SCM]
0520: 2c 20 61 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65  , and one of the
0530: 20 67 6f 61 6c 73 20 6f 66 20 63 77 61 6c 20 69   goals of cwal i
0540: 73 20 74 6f 20 62 65 20 75 73 65 64 20 61 73 20  s to be used as 
0550: 74 68 65 20 62 61 73 69 73 20 66 6f 72 20 73 75  the basis for su
0560: 63 68 20 61 70 70 2f 6c 69 62 72 61 72 79 20 22  ch app/library "
0570: 67 6c 75 65 20 6c 61 6e 67 75 61 67 65 73 2c 22  glue languages,"
0580: 20 70 72 69 6d 61 72 69 6c 79 20 77 69 74 68 20   primarily with 
0590: 74 68 65 20 67 6f 61 6c 20 6f 66 20 73 63 72 69  the goal of scri
05a0: 70 74 69 6e 67 20 75 6e 69 74 20 74 65 73 74 73  pting unit tests
05b0: 20 28 54 48 31 27 73 20 6f 72 69 67 69 6e 61 6c   (TH1's original
05c0: 20 70 75 72 70 6f 73 65 29 2e 20 63 77 61 6c 20   purpose). cwal 
05d0: 72 65 70 72 65 73 65 6e 74 73 2c 20 77 69 74 68  represents, with
05e0: 6f 75 74 20 61 20 64 6f 75 62 74 2c 20 6d 79 20  out a doubt, my 
05f0: 6d 6f 73 74 20 69 6e 74 72 69 63 61 74 65 20 43  most intricate C
0600: 20 63 6f 64 65 20 74 6f 20 64 61 74 65 20 28 61   code to date (a
0610: 6e 64 20 69 73 20 61 6d 6f 6e 67 73 74 20 74 68  nd is amongst th
0620: 65 20 63 6c 65 61 6e 65 73 74 2c 20 61 73 20 77  e cleanest, as w
0630: 65 6c 6c 29 2e 0d 0a 0d 0a 3c 62 3e 4c 69 63 65  ell).....<b>Lice
0640: 6e 73 65 3c 2f 62 3e 3a 20 44 75 61 6c 20 50 75  nse</b>: Dual Pu
0650: 62 6c 69 63 20 44 6f 6d 61 69 6e 2f 4d 49 54 2e  blic Domain/MIT.
0660: 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   The underlying 
0670: 4a 53 4f 4e 20 70 61 72 73 65 72 20 63 6f 64 65  JSON parser code
0680: 20 68 61 73 20 61 20 42 53 44 2d 69 73 68 20 22   has a BSD-ish "
0690: 6b 65 65 70 20 74 68 69 73 20 63 6f 70 79 72 69  keep this copyri
06a0: 67 68 74 20 69 6e 20 70 6c 61 63 65 22 20 6c 69  ght in place" li
06b0: 63 65 6e 73 65 20 77 69 74 68 20 61 20 22 64 6f  cense with a "do
06c0: 20 6e 6f 20 65 76 69 6c 22 20 73 75 62 63 6c 61   no evil" subcla
06d0: 75 73 65 2e 20 28 4f 74 68 65 72 77 69 73 65 20  use. (Otherwise 
06e0: 65 76 69 6c 64 6f 65 72 73 20 6d 75 73 74 20 62  evildoers must b
06f0: 65 20 73 75 72 65 20 74 6f 20 72 65 70 6c 61 63  e sure to replac
0700: 65 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  e the underlying
0710: 20 70 61 72 73 65 72 20 62 65 66 6f 72 65 20 75   parser before u
0720: 73 69 6e 67 20 74 68 69 73 20 63 6f 64 65 2e 20  sing this code. 
0730: 41 6c 74 65 72 6e 61 74 65 6c 79 2c 20 65 76 69  Alternately, evi
0740: 6c 64 6f 65 72 73 20 6d 61 79 20 64 69 73 61 62  ldoers may disab
0750: 6c 65 20 74 68 6f 73 65 20 62 69 74 73 20 61 74  le those bits at
0760: 20 62 75 69 6c 64 2d 74 69 6d 65 3a 20 73 65 65   build-time: see
0770: 20 5b 2f 66 69 6e 66 6f 2f 69 6e 63 6c 75 64 65   [/finfo/include
0780: 2f 77 68 2f 63 77 61 6c 2f 63 77 61 6c 5f 63 6f  /wh/cwal/cwal_co
0790: 6e 66 69 67 2e 68 7c 63 77 61 6c 5f 63 6f 6e 66  nfig.h|cwal_conf
07a0: 69 67 2e 68 5d 20 66 6f 72 20 64 65 74 61 69 6c  ig.h] for detail
07b0: 73 2e 29 0d 0a 0d 0a 3c 62 3e 41 75 74 68 6f 72  s.)....<b>Author
07c0: 3c 2f 62 3e 3a 20 5b 68 74 74 70 3a 2f 2f 77 61  </b>: [http://wa
07d0: 6e 64 65 72 69 6e 67 68 6f 72 73 65 2e 6e 65 74  nderinghorse.net
07e0: 2f 68 6f 6d 65 2f 73 74 65 70 68 61 6e 2f 7c 73  /home/stephan/|s
07f0: 74 65 70 68 61 6e 20 62 65 61 6c 5d 0d 0a 0d 0a  tephan beal]....
0800: 3c 62 3e 43 6f 64 65 20 73 74 61 74 75 73 3c 2f  <b>Code status</
0810: 62 3e 3a 20 3c 65 6d 3e 68 69 67 68 6c 79 20 65  b>: <em>highly e
0820: 78 70 65 72 69 6d 65 6e 74 61 6c 3c 2f 65 6d 3e  xperimental</em>
0830: 2c 20 62 75 74 20 68 61 73 20 62 65 65 6e 20 69  , but has been i
0840: 6e 20 68 65 61 76 79 20 75 73 65 20 66 6f 72 20  n heavy use for 
0850: 77 65 6c 6c 20 6f 76 65 72 20 61 20 79 65 61 72  well over a year
0860: 20 28 61 73 20 6f 66 20 73 75 6d 6d 65 72 2c 20   (as of summer, 
0870: 32 30 31 34 29 2e 20 54 68 65 20 63 6f 72 65 20  2014). The core 
0880: 65 6e 67 69 6e 65 20 77 6f 72 6b 73 20 71 75 69  engine works qui
0890: 74 65 20 77 65 6c 6c 20 77 68 65 6e 20 75 73 65  te well when use
08a0: 64 20 61 73 20 61 64 76 65 72 74 69 7a 65 64 2e  d as advertized.
08b0: 20 57 6f 72 6b 20 6f 6e 20 74 68 65 20 5b 74 68   Work on the [th
08c0: 31 69 73 68 7c 74 68 31 69 73 68 20 73 63 72 69  1ish|th1ish scri
08d0: 70 74 69 6e 67 20 65 6e 67 69 6e 65 5d 20 28 62  pting engine] (b
08e0: 61 73 65 64 20 6f 6e 20 63 77 61 6c 2c 20 6f 66  ased on cwal, of
08f0: 20 63 6f 75 72 73 65 29 20 68 61 73 20 70 72 6f   course) has pro
0900: 76 65 6e 20 74 68 61 74 20 63 77 61 6c 27 73 20  ven that cwal's 
0910: 67 65 6e 65 72 61 6c 20 6c 69 66 65 74 69 6d 65  general lifetime
0920: 20 6d 6f 64 65 6c 20 77 6f 72 6b 73 2e 20 4d 6f   model works. Mo
0930: 72 65 20 72 65 63 65 6e 74 6c 79 20 28 73 75 6d  re recently (sum
0940: 6d 65 72 2c 20 32 30 31 34 29 2c 20 5b 73 32 7c  mer, 2014), [s2|
0950: 73 32 20 73 68 6f 77 73 20 65 76 65 6e 20 6d 6f  s2 shows even mo
0960: 72 65 20 70 72 6f 6d 69 73 65 5d 2c 20 73 75 70  re promise], sup
0970: 65 72 73 65 64 69 6e 67 20 74 68 31 69 73 68 20  erseding th1ish 
0980: 69 6e 20 65 73 73 65 6e 74 69 61 6c 6c 79 20 65  in essentially e
0990: 76 65 72 79 20 77 61 79 2e 20 54 68 65 20 76 65  very way. The ve
09a0: 72 64 69 63 74 20 69 73 20 73 74 69 6c 6c 20 6f  rdict is still o
09b0: 75 74 20 61 73 20 74 6f 20 77 68 65 74 68 65 72  ut as to whether
09c0: 20 63 77 61 6c 20 63 61 6e 20 72 65 61 6c 6c 79   cwal can really
09d0: 20 73 63 61 6c 65 20 74 6f 20 62 65 20 61 62 6c   scale to be abl
09e0: 65 20 74 6f 20 62 65 20 75 73 65 66 75 6c 20 69  e to be useful i
09f0: 6e 20 61 6e 79 20 22 72 65 61 6c 6c 79 20 69 6e  n any "really in
0a00: 74 65 72 65 73 74 69 6e 67 22 20 73 63 72 69 70  teresting" scrip
0a10: 74 69 6e 67 20 77 6f 72 6b 2c 20 62 75 74 20 68  ting work, but h
0a20: 61 73 20 62 65 65 6e 20 73 68 6f 77 6e 20 74 6f  as been shown to
0a30: 20 61 74 20 6c 65 61 73 74 20 62 65 20 76 69 61   at least be via
0a40: 62 6c 65 20 66 6f 72 20 73 75 63 68 20 74 61 73  ble for such tas
0a50: 6b 73 20 61 73 20 5b 68 74 74 70 3a 2f 2f 66 6f  ks as [http://fo
0a60: 73 73 69 6c 2e 77 61 6e 64 65 72 69 6e 67 68 6f  ssil.wanderingho
0a70: 72 73 65 2e 6e 65 74 2f 72 65 70 6f 73 2f 6c 69  rse.net/repos/li
0a80: 62 66 6f 73 73 69 6c 2f 63 67 69 64 65 6d 6f 2f  bfossil/cgidemo/
0a90: 7c 63 72 65 61 74 69 6e 67 20 77 65 62 20 73 69  |creating web si
0aa0: 74 65 73 5d 2e 20 54 68 61 74 20 73 69 74 65 20  tes]. That site 
0ab0: 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 65  is implemented e
0ac0: 6e 74 69 72 65 6c 79 20 69 6e 20 74 68 31 69 73  ntirely in th1is
0ad0: 68 2c 20 70 75 73 68 69 6e 67 20 69 74 20 3c 65  h, pushing it <e
0ae0: 6d 3e 77 65 6c 6c 20 62 65 79 6f 6e 64 3c 2f 65  m>well beyond</e
0af0: 6d 3e 20 61 6e 79 20 69 6e 69 74 69 61 6c 6c 79  m> any initially
0b00: 20 65 6e 76 69 73 69 6f 6e 65 64 20 75 73 65 73   envisioned uses
0b10: 2e 20 53 65 65 20 74 68 65 20 6c 69 6e 6b 73 20  . See the links 
0b20: 61 74 20 74 68 65 20 62 6f 74 74 6f 6d 20 6f 66  at the bottom of
0b30: 20 74 68 6f 73 65 20 70 61 67 65 73 20 66 6f 72   those pages for
0b40: 20 74 68 65 20 73 63 72 69 70 74 20 63 6f 64 65   the script code
0b50: 20 28 62 75 74 20 6e 6f 74 65 20 74 68 61 74 20   (but note that 
0b60: 5b 73 32 5d 20 68 61 73 20 73 75 70 65 72 73 65  [s2] has superse
0b70: 64 65 64 20 5b 74 68 31 69 73 68 5d 20 69 6e 20  ded [th1ish] in 
0b80: 74 68 65 20 6d 65 61 6e 20 74 69 6d 65 29 2e 0d  the mean time)..
0b90: 0a 0d 0a 3c 62 3e 53 65 65 20 61 6c 73 6f 3a 3c  ...<b>See also:<
0ba0: 2f 62 3e 20 5b 64 6f 77 6e 6c 6f 61 64 5d 2c 20  /b> [download], 
0bb0: 5b 63 77 61 6c 5f 67 63 5d 2c 20 5b 48 6f 77 54  [cwal_gc], [HowT
0bc0: 6f 5d 2c 20 5b 4d 65 6d 6f 72 79 4d 6f 64 65 6c  o], [MemoryModel
0bd0: 5d 2c 20 5b 44 61 74 61 54 79 70 65 73 5d 2c 20  ], [DataTypes], 
0be0: 5b 54 6f 44 6f 5d 2c 20 5b 74 68 31 69 73 68 5d  [ToDo], [th1ish]
0bf0: 2c 20 5b 63 77 61 6c 5f 77 65 61 6b 5f 72 65 66  , [cwal_weak_ref
0c00: 5d 2c 20 5b 73 32 5d 2c 20 5b 43 77 61 6c 42 65  ], [s2], [CwalBe
0c10: 73 74 50 72 61 63 74 69 63 65 73 5d 2e 0d 0a 0d  stPractices]....
0c20: 0a 54 68 65 20 70 72 69 6d 61 72 79 20 70 72 6f  .The primary pro
0c30: 70 65 72 74 69 65 73 20 6f 66 20 63 77 61 6c 20  perties of cwal 
0c40: 69 6e 63 6c 75 64 65 3a 0d 0a 0d 0a 20 20 20 2a  include:....   *
0c50: 20 20 44 65 73 69 67 6e 65 64 20 74 6f 20 62 65    Designed to be
0c60: 20 65 6d 62 65 64 64 65 64 20 69 6e 20 61 70 70   embedded in app
0c70: 6c 69 63 61 74 69 6f 6e 73 20 6f 72 20 6c 69 62  lications or lib
0c80: 72 61 72 69 65 73 2e 0d 0a 20 20 20 2a 20 20 50  raries...   *  P
0c90: 6f 72 74 61 62 6c 65 20 43 38 39 20 63 6f 64 65  ortable C89 code
0ca0: 2c 20 77 69 74 68 20 61 20 64 65 70 65 6e 64 65  , with a depende
0cb0: 6e 63 79 20 6f 6e 20 74 68 65 20 43 39 39 2d 73  ncy on the C99-s
0cc0: 70 65 63 69 66 69 65 64 20 3c 74 74 3e 69 6e 74  pecified <tt>int
0cd0: 74 79 70 65 73 2e 68 3c 2f 74 74 3e 20 66 6f 72  types.h</tt> for
0ce0: 20 66 69 78 65 64 2d 73 69 7a 65 20 69 6e 74 65   fixed-size inte
0cf0: 67 65 72 20 74 79 70 65 73 20 61 6e 64 20 70 6f  ger types and po
0d00: 72 74 61 62 6c 65 20 70 72 69 6e 74 66 2f 73 63  rtable printf/sc
0d10: 61 6e 66 20 66 6f 72 6d 61 74 20 73 70 65 63 69  anf format speci
0d20: 66 69 65 72 73 2e 20 28 4d 69 63 72 6f 73 6f 66  fiers. (Microsof
0d30: 74 20 63 6f 6d 70 69 6c 65 72 73 20 64 6f 20 6e  t compilers do n
0d40: 6f 74 20 68 61 76 65 20 74 68 65 73 65 20 62 75  ot have these bu
0d50: 74 20 74 68 65 72 65 20 69 73 20 61 20 66 72 65  t there is a fre
0d60: 65 20 64 72 6f 70 2d 69 6e 20 72 65 70 6c 61 63  e drop-in replac
0d70: 65 6d 65 6e 74 20 61 76 61 69 6c 61 62 6c 65 20  ement available 
0d80: 61 74 20 5b 68 74 74 70 3a 2f 2f 63 6f 64 65 2e  at [http://code.
0d90: 67 6f 6f 67 6c 65 2e 63 6f 6d 2f 70 2f 6d 73 69  google.com/p/msi
0da0: 6e 74 74 79 70 65 73 2f 5d 29 2e 0d 0a 20 20 20  nttypes/])...   
0db0: 2a 20 20 48 61 73 20 6e 6f 20 28 6d 75 74 61 62  *  Has no (mutab
0dc0: 6c 65 29 20 67 6c 6f 62 61 6c 20 73 74 61 74 65  le) global state
0dd0: 20 2d 20 61 6c 6c 20 6d 65 6d 6f 72 79 20 69 73   - all memory is
0de0: 20 6d 61 6e 61 67 65 64 20 77 69 74 68 69 6e 20   managed within 
0df0: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 61  the context of a
0e00: 6e 20 22 65 6e 67 69 6e 65 22 20 69 6e 73 74 61  n "engine" insta
0e10: 6e 63 65 2e 0d 0a 20 20 20 2a 20 20 46 61 69 72  nce...   *  Fair
0e20: 6c 79 20 73 6d 61 6c 6c 2e 20 54 68 65 20 63 6f  ly small. The co
0e30: 72 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  re is currently 
0e40: 28 4a 61 6e 75 61 72 79 20 32 30 31 36 29 20 31  (January 2016) 1
0e50: 37 20 4b 53 4c 4f 43 20 61 6e 64 20 63 6f 6d 70  7 KSLOC and comp
0e60: 69 6c 65 73 20 69 6e 20 77 65 6c 6c 20 75 6e 64  iles in well und
0e70: 65 72 20 31 30 20 73 65 63 6f 6e 64 73 20 77 69  er 10 seconds wi
0e80: 74 68 20 67 63 63 20 6f 6e 20 6d 79 20 32 30 30  th gcc on my 200
0e90: 39 2d 6d 6f 64 65 6c 20 6e 65 74 62 6f 6f 6b 20  9-model netbook 
0ea0: 28 75 6e 64 65 72 20 32 20 73 65 63 6f 6e 64 73  (under 2 seconds
0eb0: 20 6f 6e 20 61 20 6d 6f 72 65 20 6d 6f 64 65 72   on a more moder
0ec0: 6e 20 6d 61 63 68 69 6e 65 29 2e 20 73 32 27 73  n machine). s2's
0ed0: 20 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 20 69 73   amalgamation is
0ee0: 2c 20 62 79 20 63 6f 6d 70 61 72 69 73 6f 6e 2c  , by comparison,
0ef0: 20 33 34 20 4b 53 4c 4f 43 2e 0d 0a 20 20 20 2a   34 KSLOC...   *
0f00: 20 20 59 6f 75 72 20 52 41 4d 20 69 73 20 68 6f    Your RAM is ho
0f10: 6c 79 2c 20 61 6e 64 20 63 77 61 6c 20 74 72 65  ly, and cwal tre
0f20: 61 74 73 20 69 74 20 6c 69 6b 65 20 61 20 72 61  ats it like a ra
0f30: 72 65 20 63 6f 6d 6d 6f 64 69 74 79 2e 20 54 68  re commodity. Th
0f40: 65 20 65 6e 67 69 6e 65 20 69 74 73 65 6c 66 20  e engine itself 
0f50: 69 73 20 75 6e 64 65 72 20 32 6b 62 20 61 6e 64  is under 2kb and
0f60: 20 6d 61 79 20 62 65 20 73 74 61 63 6b 20 61 6c   may be stack al
0f70: 6c 6f 63 61 74 65 64 2e 20 49 6e 74 65 72 6e 61  located. Interna
0f80: 6c 6c 79 20 69 74 20 6e 65 65 64 73 20 6c 65 73  lly it needs les
0f90: 73 20 74 68 61 6e 20 31 6b 62 20 6f 66 20 64 79  s than 1kb of dy
0fa0: 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 66 6f 72  namic memory for
0fb0: 20 74 68 65 20 63 6f 72 65 2c 20 77 69 74 68 20   the core, with 
0fc0: 74 68 65 20 63 61 76 65 61 74 20 74 68 61 74 20  the caveat that 
0fd0: 28 6f 70 74 69 6f 6e 61 6c 29 20 61 75 74 6f 2d  (optional) auto-
0fe0: 69 6e 74 65 72 6e 69 6e 67 20 6f 66 20 73 74 72  interning of str
0ff0: 69 6e 67 73 20 63 61 6e 20 69 6e 63 72 65 61 73  ings can increas
1000: 65 20 74 68 69 73 20 22 73 69 67 6e 69 66 69 63  e this "signific
1010: 61 6e 74 6c 79 22 20 28 61 6e 79 77 68 65 72 65  antly" (anywhere
1020: 20 66 72 6f 6d 20 2b 32 6b 62 20 74 6f 20 2b 32   from +2kb to +2
1030: 30 6b 62 20 69 6e 20 6d 79 20 74 65 73 74 73 2c  0kb in my tests,
1040: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
1050: 65 20 6e 75 6d 62 65 72 20 61 6e 64 20 68 61 73  e number and has
1060: 68 20 76 61 6c 75 65 73 20 6f 66 20 75 6e 69 71  h values of uniq
1070: 75 65 20 73 74 72 69 6e 67 73 29 2e 0d 0a 20 20  ue strings)...  
1080: 20 2a 20 20 50 72 6f 76 69 64 65 73 20 74 68 65   *  Provides the
1090: 20 3c 65 6d 3e 62 61 73 69 73 3c 2f 65 6d 3e 20   <em>basis</em> 
10a0: 66 6f 72 20 73 63 72 69 70 74 69 6e 67 20 61 70  for scripting ap
10b0: 70 20 62 65 68 61 76 69 6f 75 72 73 2c 20 62 75  p behaviours, bu
10c0: 74 20 3c 65 6d 3e 6e 6f 74 20 61 20 6c 61 6e 67  t <em>not a lang
10d0: 75 61 67 65 3c 2f 65 6d 3e 2e 20 53 65 65 20 74  uage</em>. See t
10e0: 68 65 20 5b 73 32 7c 73 32 20 70 61 67 65 5d 20  he [s2|s2 page] 
10f0: 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74 20  for the current 
1100: 28 61 73 20 6f 66 20 44 65 63 2e 20 32 30 31 34  (as of Dec. 2014
1110: 29 20 73 63 72 69 70 74 69 6e 67 20 6c 61 6e 67  ) scripting lang
1120: 75 61 67 65 2c 20 61 6e 64 20 5b 74 68 31 69 73  uage, and [th1is
1130: 68 5d 20 66 6f 72 20 61 6e 20 6f 6c 64 65 72 20  h] for an older 
1140: 28 6e 6f 77 20 6f 62 73 6f 6c 65 74 65 29 20 6f  (now obsolete) o
1150: 6e 65 2e 0d 0a 20 20 20 2a 20 20 43 61 6e 20 61  ne...   *  Can a
1160: 6c 73 6f 20 62 65 20 75 73 65 64 20 61 73 20 61  lso be used as a
1170: 20 73 6f 72 74 20 6f 66 20 67 61 72 62 61 67 65   sort of garbage
1180: 20 63 6f 6c 6c 65 63 74 6f 72 2c 20 69 6e 64 65   collector, inde
1190: 70 65 6e 64 65 6e 74 20 6f 66 20 61 6e 79 20 73  pendent of any s
11a0: 63 72 69 70 74 69 6e 67 2d 72 65 6c 61 74 65 64  cripting-related
11b0: 20 66 65 61 74 75 72 65 73 2e 20 49 74 20 64 6f   features. It do
11c0: 65 73 20 6e 6f 74 20 3c 65 6d 3e 72 65 71 75 69  es not <em>requi
11d0: 72 65 3c 2f 65 6d 3e 20 61 20 73 63 72 69 70 74  re</em> a script
11e0: 69 6e 67 20 6c 61 6e 67 75 61 67 65 20 74 6f 20  ing language to 
11f0: 62 65 20 75 73 65 66 75 6c 2c 20 74 68 6f 75 67  be useful, thoug
1200: 68 20 74 68 61 74 20 69 73 20 74 68 65 20 70 72  h that is the pr
1210: 69 6d 61 72 79 20 74 61 72 67 65 74 20 63 6c 69  imary target cli
1220: 65 6e 74 20 74 79 70 65 2e 0d 0a 20 20 20 2a 20  ent type...   * 
1230: 20 41 6c 6c 6f 77 73 20 6f 6e 65 20 74 6f 20 72   Allows one to r
1240: 65 70 6c 61 63 65 20 74 68 65 20 6d 65 6d 6f 72  eplace the memor
1250: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 69 74 20  y allocator (it 
1260: 6d 75 73 74 20 62 65 20 72 65 61 6c 6c 6f 63 2d  must be realloc-
1270: 63 61 70 61 62 6c 65 29 2e 0d 0a 20 20 20 2a 20  capable)...   * 
1280: 20 55 73 65 73 20 43 2b 2b 2d 6c 69 6b 65 20 73   Uses C++-like s
1290: 63 6f 70 69 6e 67 20 61 6e 64 20 66 69 6e 61 6c  coping and final
12a0: 69 7a 61 74 69 6f 6e 2e 20 46 69 6e 61 6c 69 7a  ization. Finaliz
12b0: 65 72 73 20 61 72 65 20 3c 65 6d 3e 61 6c 77 61  ers are <em>alwa
12c0: 79 73 3c 2f 65 6d 3e 20 63 61 6c 6c 65 64 2c 20  ys</em> called, 
12d0: 70 72 6f 76 69 64 65 64 20 74 68 65 20 6c 69 62  provided the lib
12e0: 72 61 72 79 20 69 73 20 75 73 65 64 20 70 72 6f  rary is used pro
12f0: 70 65 72 6c 79 2c 20 62 75 74 20 64 65 73 74 72  perly, but destr
1300: 75 63 74 69 6f 6e 20 6f 72 64 65 72 20 69 73 20  uction order is 
1310: 75 6e 73 70 65 63 69 66 69 65 64 2e 0d 0a 20 20  unspecified...  
1320: 20 2a 20 20 50 72 6f 76 69 64 65 73 20 73 65 76   *  Provides sev
1330: 65 72 61 6c 20 45 43 4d 41 53 63 72 69 70 74 2d  eral ECMAScript-
1340: 6c 69 6b 65 20 74 79 70 65 73 20 61 6e 64 20 61  like types and a
1350: 20 66 65 77 20 63 75 73 74 6f 6d 20 74 79 70 65   few custom type
1360: 73 3a 20 69 6e 74 65 67 65 72 73 20 28 31 36 2d  s: integers (16-
1370: 2c 20 33 32 2d 2c 20 6f 72 20 36 34 2d 62 69 74  , 32-, or 64-bit
1380: 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 62  , depending on b
1390: 75 69 6c 64 20 6f 70 74 69 6f 6e 73 29 2c 20 64  uild options), d
13a0: 6f 75 62 6c 65 73 2c 20 62 6f 6f 6c 65 61 6e 73  oubles, booleans
13b0: 2c 20 6e 75 6c 6c 2c 20 75 6e 64 65 66 69 6e 65  , null, undefine
13c0: 64 2c 20 61 72 72 61 79 73 2c 20 6f 62 6a 65 63  d, arrays, objec
13d0: 74 73 2c 20 66 75 6e 63 74 69 6f 6e 73 2c 20 65  ts, functions, e
13e0: 78 63 65 70 74 69 6f 6e 73 2c 20 6d 65 6d 6f 72  xceptions, memor
13f0: 79 20 62 75 66 66 65 72 73 2c 20 68 61 73 68 20  y buffers, hash 
1400: 74 61 62 6c 65 73 2c 20 61 6e 64 20 22 6e 61 74  tables, and "nat
1410: 69 76 65 73 22 20 28 61 20 67 65 6e 65 72 69 63  ives" (a generic
1420: 20 77 72 61 70 70 65 72 20 66 6f 72 20 62 69 6e   wrapper for bin
1430: 64 69 6e 67 20 63 6c 69 65 6e 74 2d 73 70 65 63  ding client-spec
1440: 69 66 69 63 20 74 79 70 65 73 29 2e 20 4e 6f 6e  ific types). Non
1450: 2d 63 6f 6e 74 61 69 6e 65 72 20 76 61 6c 75 65  -container value
1460: 73 20 28 65 2e 67 2e 20 6e 75 6d 62 65 72 73 20  s (e.g. numbers 
1470: 61 6e 64 20 73 74 72 69 6e 67 73 29 20 61 72 65  and strings) are
1480: 20 61 6c 77 61 79 73 20 69 6d 6d 75 74 61 62 6c   always immutabl
1490: 65 2e 20 46 75 6e 63 74 69 6f 6e 73 20 61 72 65  e. Functions are
14a0: 20 66 69 72 73 74 2d 63 6c 61 73 73 20 6f 62 6a   first-class obj
14b0: 65 63 74 2d 74 79 70 65 20 76 61 6c 75 65 73 2e  ect-type values.
14c0: 0d 0a 20 20 20 2a 20 20 41 6c 6c 20 76 61 6c 75  ..   *  All valu
14d0: 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 72  es are passed ar
14e0: 6f 75 6e 64 20 22 62 79 20 72 65 66 65 72 65 6e  ound "by referen
14f0: 63 65 22 20 28 77 65 6c 6c 2c 20 70 6f 69 6e 74  ce" (well, point
1500: 65 72 29 2c 20 75 73 69 6e 67 20 61 20 63 6f 6d  er), using a com
1510: 62 69 6e 61 74 69 6f 6e 20 6f 66 20 72 65 66 65  bination of refe
1520: 72 65 6e 63 65 20 63 6f 75 6e 74 69 6e 67 20 61  rence counting a
1530: 6e 64 20 73 63 6f 70 65 2d 6c 65 76 65 6c 20 74  nd scope-level t
1540: 72 61 63 6b 69 6e 67 20 74 6f 20 6d 61 6e 61 67  racking to manag
1550: 65 20 74 68 65 69 72 20 6c 69 66 65 74 69 6d 65  e their lifetime
1560: 73 2e 0d 0a 20 20 20 2a 20 20 43 6f 6e 74 61 69  s...   *  Contai
1570: 6e 65 72 20 76 61 6c 75 65 73 20 28 61 72 72 61  ner values (arra
1580: 79 73 2c 20 6f 62 6a 65 63 74 73 29 20 63 61 6e  ys, objects) can
1590: 20 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20   participate in 
15a0: 67 72 61 70 68 73 2f 63 79 63 6c 65 73 20 77 69  graphs/cycles wi
15b0: 74 68 6f 75 74 20 69 6e 74 72 6f 64 75 63 69 6e  thout introducin
15c0: 67 20 6c 65 61 6b 73 2e 20 4d 61 6b 69 6e 67 20  g leaks. Making 
15d0: 75 73 65 20 6f 66 20 74 68 69 73 20 72 65 71 75  use of this requ
15e0: 69 72 65 73 20 73 74 72 69 63 74 20 63 6f 68 65  ires strict cohe
15f0: 72 65 6e 63 65 20 74 6f 20 74 68 65 20 41 50 49  rence to the API
1600: 27 73 20 6d 65 6d 6f 72 79 2f 6f 77 6e 65 72 73  's memory/owners
1610: 68 69 70 20 72 75 6c 65 73 2c 20 62 75 74 20 69  hip rules, but i
1620: 73 20 70 72 65 74 74 79 20 65 61 73 79 20 74 6f  s pretty easy to
1630: 20 64 6f 2e 0d 0a 20 20 20 2a 20 20 43 61 6e 20   do...   *  Can 
1640: 6f 70 74 69 6f 6e 61 6c 6c 79 20 61 75 74 6f 6d  optionally autom
1650: 61 74 69 63 61 6c 6c 79 20 69 6e 74 65 72 6e 61  atically interna
1660: 6c 69 7a 65 20 73 74 72 69 6e 67 20 76 61 6c 75  lize string valu
1670: 65 73 2c 20 73 75 63 68 20 74 68 61 74 20 61 6c  es, such that al
1680: 6c 20 73 74 72 69 6e 67 73 20 63 72 65 61 74 65  l strings create
1690: 64 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  d with the same 
16a0: 62 79 74 65 73 20 61 72 65 20 61 75 74 6f 6d 61  bytes are automa
16b0: 74 69 63 61 6c 6c 79 20 73 68 61 72 65 64 20 61  tically shared a
16c0: 6e 64 20 63 6c 65 61 6e 65 64 20 75 70 20 75 73  nd cleaned up us
16d0: 69 6e 67 20 74 68 65 20 72 65 66 65 72 65 6e 63  ing the referenc
16e0: 65 2d 63 6f 75 6e 74 69 6e 67 20 6d 65 63 68 61  e-counting mecha
16f0: 6e 69 73 6d 2e 20 54 68 69 73 20 73 75 70 70 6f  nism. This suppo
1700: 72 74 20 68 61 73 20 61 20 6d 65 6d 6f 72 79 20  rt has a memory 
1710: 63 6f 73 74 20 28 61 20 63 6f 75 70 6c 65 20 6b  cost (a couple k
1720: 62 20 70 65 72 20 70 61 67 65 20 69 6e 20 74 68  b per page in th
1730: 65 20 69 6e 74 65 72 6e 69 6e 67 20 74 61 62 6c  e interning tabl
1740: 65 2c 20 77 69 74 68 20 31 20 70 61 67 65 20 70  e, with 1 page p
1750: 65 72 20 73 74 72 69 6e 67 20 68 61 73 68 20 63  er string hash c
1760: 6f 6c 6c 69 73 69 6f 6e 20 64 65 70 74 68 29 20  ollision depth) 
1770: 62 75 74 20 68 61 73 20 61 6d 6f 72 74 69 7a 65  but has amortize
1780: 64 20 4f 28 31 29 20 73 70 65 65 64 20 61 6e 64  d O(1) speed and
1790: 20 63 61 6e 20 73 61 76 65 20 74 6f 6e 73 20 28   can save tons (
17a0: 61 73 20 69 6e 20 6d 61 6e 79 20 6d 65 67 61 62  as in many megab
17b0: 79 74 65 73 29 20 6f 66 20 6d 65 6d 6f 72 79 20  ytes) of memory 
17c0: 77 68 65 6e 20 72 65 2d 75 73 69 6e 67 20 74 68  when re-using th
17d0: 65 20 73 61 6d 65 20 73 74 72 69 6e 67 73 20 6d  e same strings m
17e0: 61 6e 79 20 74 69 6d 65 73 20 28 65 2e 67 2e 20  any times (e.g. 
17f0: 61 73 20 70 72 6f 70 65 72 74 79 20 6b 65 79 73  as property keys
1800: 20 6f 72 20 69 64 65 6e 74 69 66 69 65 72 73 20   or identifiers 
1810: 69 6e 20 61 20 6c 6f 6f 70 29 2e 20 49 74 73 20  in a loop). Its 
1820: 75 73 65 66 75 6c 6e 65 73 73 20 61 6e 64 20 63  usefulness and c
1830: 6f 73 74 20 76 61 72 69 65 73 20 67 72 65 61 74  ost varies great
1840: 6c 79 20 61 63 72 6f 73 73 20 73 63 72 69 70 74  ly across script
1850: 73 2c 20 62 75 74 20 69 6e 20 61 6c 6c 20 63 61  s, but in all ca
1860: 73 65 73 20 69 74 20 73 70 65 65 64 73 20 75 70  ses it speeds up
1870: 20 6f 70 65 72 61 74 69 6f 6e 73 20 6c 69 6b 65   operations like
1880: 20 73 74 72 69 6e 67 2d 75 73 69 6e 67 20 6c 6f   string-using lo
1890: 6f 70 73 20 28 62 79 20 72 6f 75 67 68 6c 79 20  ops (by roughly 
18a0: 32 78 20 69 6e 20 6d 6f 73 74 20 6d 79 20 74 65  2x in most my te
18b0: 73 74 73 29 2e 0d 0a 20 20 20 2a 20 20 4f 70 74  sts)...   *  Opt
18c0: 69 6f 6e 61 6c 6c 79 20 73 75 70 70 6f 72 74 73  ionally supports
18d0: 20 6d 65 6d 6f 72 79 20 63 61 70 70 69 6e 67 20   memory capping 
18e0: 62 61 73 65 64 20 6f 6e 20 76 61 72 69 6f 75 73  based on various
18f0: 20 63 72 69 74 65 72 69 61 3a 20 6d 61 78 20 61   criteria: max a
1900: 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2c 20  llocation size, 
1910: 74 6f 74 61 6c 2f 63 6f 6e 63 75 72 72 65 6e 74  total/concurrent
1920: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 63 6f 75 6e   allocation coun
1930: 74 2c 20 6f 72 20 74 6f 74 61 6c 2f 63 6f 6e 63  t, or total/conc
1940: 75 72 72 65 6e 74 20 62 79 74 65 73 20 61 6c 6c  urrent bytes all
1950: 6f 63 61 74 65 64 2e 20 57 68 65 6e 20 65 6e 61  ocated. When ena
1960: 62 6c 65 64 2c 20 61 6c 6c 20 61 6c 6c 6f 63 61  bled, all alloca
1970: 74 69 6f 6e 73 20 63 6f 73 74 20 3c 74 74 3e 73  tions cost <tt>s
1980: 69 7a 65 6f 66 28 76 6f 69 64 2a 29 3c 2f 74 74  izeof(void*)</tt
1990: 3e 20 6d 6f 72 65 20 62 79 74 65 73 20 62 75 74  > more bytes but
19a0: 20 74 68 69 73 20 61 6c 6c 6f 77 73 20 63 77 61   this allows cwa
19b0: 6c 20 74 6f 20 74 72 61 63 6b 20 61 6c 6c 20 6d  l to track all m
19c0: 65 6d 6f 72 79 20 77 69 74 68 20 62 79 74 65 20  emory with byte 
19d0: 70 72 65 63 69 73 69 6f 6e 2c 20 77 68 69 63 68  precision, which
19e0: 20 61 6c 6c 6f 77 73 20 6f 6e 65 20 6f 66 20 69   allows one of i
19f0: 74 73 20 72 65 63 79 63 6c 65 72 73 20 74 6f 20  ts recyclers to 
1a00: 77 6f 72 6b 20 62 65 74 74 65 72 2e 0d 0a 20 20  work better...  
1a10: 20 2a 20 20 54 68 65 20 73 6f 75 72 63 65 20 74   *  The source t
1a20: 72 65 65 20 69 6e 63 6c 75 64 65 73 20 5b 73 32  ree includes [s2
1a30: 5d 20 61 6e 64 20 5b 74 68 31 69 73 68 5d 20 62  ] and [th1ish] b
1a40: 69 6e 64 69 6e 67 73 20 74 6f 20 73 65 76 65 72  indings to sever
1a50: 61 6c 20 33 72 64 2d 70 61 72 74 79 20 6c 69 62  al 3rd-party lib
1a60: 72 61 72 69 65 73 2c 20 73 6f 20 74 68 65 72 65  raries, so there
1a70: 20 61 72 65 20 70 6c 65 6e 74 69 66 75 6c 20 65   are plentiful e
1a80: 78 61 6d 70 6c 65 73 20 6f 66 20 68 6f 77 20 74  xamples of how t
1a90: 6f 20 75 73 65 20 69 74 2e 0d 0a 0d 0a 0d 0a 50  o use it.......P
1aa0: 72 69 6d 61 72 79 20 6d 69 73 66 65 61 74 75 72  rimary misfeatur
1ab0: 65 73 3a 0d 0a 20 20 20 2a 20 20 45 61 63 68 20  es:..   *  Each 
1ac0: 65 6e 67 69 6e 65 20 69 6e 73 74 61 6e 63 65 20  engine instance 
1ad0: 69 73 20 3c 65 6d 3e 73 74 72 69 63 74 6c 79 3c  is <em>strictly<
1ae0: 2f 65 6d 3e 20 73 69 6e 67 6c 65 2d 74 68 72 65  /em> single-thre
1af0: 61 64 65 64 2e 20 55 73 65 20 62 79 20 6d 75 6c  aded. Use by mul
1b00: 74 69 70 6c 65 20 74 68 72 65 61 64 73 20 3c 65  tiple threads <e
1b10: 6d 3e 77 69 6c 6c 3c 2f 65 6d 3e 20 63 6f 72 72  m>will</em> corr
1b20: 75 70 74 20 69 74 73 20 73 74 61 74 65 2e 20 0d  upt its state. .
1b30: 0a 20 20 20 2a 20 20 53 69 6d 69 6c 61 72 6c 79  .   *  Similarly
1b40: 2c 20 65 61 63 68 20 65 6e 67 69 6e 65 20 69 6e  , each engine in
1b50: 73 74 61 6e 63 65 20 69 73 20 75 6e 61 77 61 72  stance is unawar
1b60: 65 20 6f 66 20 61 6e 79 20 6f 74 68 65 72 20 65  e of any other e
1b70: 6e 67 69 6e 65 73 2e 20 3c 65 6d 3e 4e 6f 3c 2f  ngines. <em>No</
1b80: 65 6d 3e 20 76 61 6c 75 65 73 20 63 72 65 61 74  em> values creat
1b90: 65 64 20 62 79 20 6f 6e 65 20 65 6e 67 69 6e 65  ed by one engine
1ba0: 20 6d 75 73 74 20 3c 65 6d 3e 65 76 65 72 3c 2f   must <em>ever</
1bb0: 65 6d 3e 20 62 65 20 6d 61 64 65 20 76 69 73 69  em> be made visi
1bc0: 62 6c 65 20 74 6f 20 61 6e 6f 74 68 65 72 20 65  ble to another e
1bd0: 6e 67 69 6e 65 20 28 76 69 61 20 70 61 73 73 69  ngine (via passi
1be0: 6e 67 20 74 68 65 6d 20 74 6f 20 74 68 65 20 41  ng them to the A
1bf0: 50 49 73 20 77 69 74 68 20 61 20 64 69 66 66 65  PIs with a diffe
1c00: 72 65 6e 74 20 65 6e 67 69 6e 65 20 69 6e 73 74  rent engine inst
1c10: 61 6e 63 65 29 20 6f 72 20 63 6f 72 72 75 70 74  ance) or corrupt
1c20: 69 6f 6e 20 6f 66 20 65 61 63 68 20 65 6e 67 69  ion of each engi
1c30: 6e 65 27 73 20 73 74 61 74 65 20 77 69 6c 6c 20  ne's state will 
1c40: 65 6e 73 75 65 20 76 69 61 20 63 72 6f 73 73 2d  ensue via cross-
1c50: 77 69 72 69 6e 67 20 6f 66 20 74 68 65 20 6d 65  wiring of the me
1c60: 6d 6f 72 79 27 73 20 6f 77 6e 65 72 73 68 69 70  mory's ownership
1c70: 2e 20 41 6e 79 20 63 6f 6d 6d 75 6e 69 63 61 74  . Any communicat
1c80: 69 6f 6e 20 62 65 74 77 65 65 6e 20 74 77 6f 20  ion between two 
1c90: 65 6e 67 69 6e 65 20 69 6e 73 74 61 6e 63 65 73  engine instances
1ca0: 20 6d 75 73 74 20 62 65 20 69 6d 70 6c 65 6d 65   must be impleme
1cb0: 6e 74 65 64 20 75 73 69 6e 67 20 69 6e 74 65 72  nted using inter
1cc0: 6d 65 64 69 61 72 79 20 6d 65 6d 6f 72 79 2f 63  mediary memory/c
1cd0: 68 61 6e 6e 65 6c 73 20 6e 6f 74 20 6d 61 6e 61  hannels not mana
1ce0: 67 65 64 20 62 79 20 65 69 74 68 65 72 20 65 6e  ged by either en
1cf0: 67 69 6e 65 2c 20 65 2e 67 2e 20 75 73 69 6e 67  gine, e.g. using
1d00: 20 4a 53 4f 4e 20 64 61 74 61 20 76 69 61 20 73   JSON data via s
1d10: 6f 6d 65 20 73 6f 72 74 20 6f 66 20 6d 65 73 73  ome sort of mess
1d20: 61 67 65 20 71 75 65 75 65 20 6f 72 20 72 61 77  age queue or raw
1d30: 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 6d   memory buffer m
1d40: 61 6e 61 67 65 64 20 6f 75 74 73 69 64 65 20 6f  anaged outside o
1d50: 66 20 63 77 61 6c 2e 0d 0a 20 20 20 2a 20 20 56  f cwal...   *  V
1d60: 61 6c 75 65 73 20 63 72 65 61 74 65 64 20 76 69  alues created vi
1d70: 61 20 63 77 61 6c 20 28 65 2e 67 2e 20 6e 75 6d  a cwal (e.g. num
1d80: 62 65 72 73 20 61 6e 64 20 73 74 72 69 6e 67 73  bers and strings
1d90: 29 20 3c 65 6d 3e 64 6f 3c 2f 65 6d 3e 20 63 6f  ) <em>do</em> co
1da0: 73 74 20 6e 6f 74 61 62 6c 79 20 6d 6f 72 65 20  st notably more 
1db0: 74 68 61 6e 20 74 68 65 69 72 20 72 61 77 20 6e  than their raw n
1dc0: 61 74 69 76 65 20 65 71 75 69 76 61 6c 65 6e 74  ative equivalent
1dd0: 73 2c 20 3c 65 6d 3e 65 73 70 65 63 69 61 6c 6c  s, <em>especiall
1de0: 79 3c 2f 65 6d 3e 20 6f 6e 20 36 34 2d 62 69 74  y</em> on 64-bit
1df0: 20 28 77 68 65 72 65 20 70 6f 69 6e 74 65 72 73   (where pointers
1e00: 20 63 6f 73 74 20 74 77 69 63 65 20 61 73 20 6d   cost twice as m
1e10: 75 63 68 20 28 61 6e 64 20 77 65 20 75 73 65 20  uch (and we use 
1e20: 3c 65 6d 3e 6c 6f 74 73 3c 2f 65 6d 3e 20 6f 66  <em>lots</em> of
1e30: 20 70 6f 69 6e 74 65 72 73 29 29 2e 20 48 61 6c   pointers)). Hal
1e40: 66 20 6f 66 20 74 68 61 74 20 77 65 69 67 68 74  f of that weight
1e50: 20 69 73 20 72 65 6c 61 74 65 64 20 74 6f 20 6f   is related to o
1e60: 77 6e 65 72 73 68 69 70 2f 67 61 72 62 61 67 65  wnership/garbage
1e70: 20 63 6f 6c 6c 65 63 74 69 6f 6e 2c 20 73 6f 20   collection, so 
1e80: 74 68 65 20 63 6f 73 74 20 69 73 20 73 68 61 72  the cost is shar
1e90: 65 64 20 61 6d 6f 6e 67 73 74 20 74 68 65 20 66  ed amongst the f
1ea0: 72 61 6d 65 77 6f 72 6b 27 73 20 76 61 72 69 6f  ramework's vario
1eb0: 75 73 20 70 69 65 63 65 73 20 28 61 6e 64 20 77  us pieces (and w
1ec0: 6f 75 6c 64 20 62 65 20 70 61 69 64 20 65 6c 73  ould be paid els
1ed0: 65 77 68 65 72 65 20 69 66 20 6e 6f 74 20 64 69  ewhere if not di
1ee0: 72 65 63 74 6c 79 20 69 6e 20 65 61 63 68 20 76  rectly in each v
1ef0: 61 6c 75 65 29 2e 20 54 68 61 74 20 73 61 69 64  alue). That said
1f00: 2c 20 69 74 73 20 72 65 63 79 63 6c 69 6e 67 20  , its recycling 
1f10: 6d 65 63 68 61 6e 69 73 6d 20 74 65 6e 64 73 20  mechanism tends 
1f20: 74 6f 20 6d 61 6b 65 20 74 68 65 6d 20 65 78 63  to make them exc
1f30: 65 70 74 69 6f 6e 61 6c 6c 79 20 63 68 65 61 70  eptionally cheap
1f40: 20 28 69 6e 20 74 68 65 20 61 67 67 72 65 67 61   (in the aggrega
1f50: 74 65 29 20 69 6e 20 6c 6f 6e 67 65 72 2d 72 75  te) in longer-ru
1f60: 6e 6e 69 6e 67 20 73 63 72 69 70 74 73 20 28 75  nning scripts (u
1f70: 6e 64 65 72 20 31 20 62 79 74 65 20 70 65 72 20  nder 1 byte per 
1f80: 76 61 6c 75 65 20 69 6e 73 74 61 6e 63 65 20 28  value instance (
1f90: 61 67 67 72 65 67 61 74 65 64 29 20 69 6e 20 6d  aggregated) in m
1fa0: 61 6e 79 20 63 61 73 65 73 20 66 6f 72 20 6e 75  any cases for nu
1fb0: 6d 65 72 69 63 20 74 79 70 65 73 2c 20 61 6e 64  meric types, and
1fc0: 20 75 6e 64 65 72 20 34 20 62 79 74 65 73 20 70   under 4 bytes p
1fd0: 65 72 20 73 74 72 69 6e 67 20 6f 72 20 68 69 67  er string or hig
1fe0: 68 65 72 2d 6c 65 76 65 6c 20 63 6f 6e 73 74 72  her-level constr
1ff0: 75 63 74 20 69 73 20 6e 6f 74 20 75 6e 63 6f 6d  uct is not uncom
2000: 6d 6f 6e 29 2e 0d 0a 20 20 2a 20 20 54 68 69 73  mon)...  *  This
2010: 20 65 6e 67 69 6e 65 20 69 73 20 69 6e 74 65 6e   engine is inten
2020: 64 65 64 20 74 6f 20 73 74 61 79 20 73 69 6d 70  ded to stay simp
2030: 6c 65 20 61 6e 64 20 6d 65 6d 6f 72 79 2d 6c 69  le and memory-li
2040: 67 68 74 2c 20 61 6e 64 20 74 68 65 72 65 20 61  ght, and there a
2050: 72 65 20 6e 6f 20 70 6c 61 6e 73 20 61 74 20 61  re no plans at a
2060: 6c 6c 20 74 6f 20 64 65 76 65 6c 6f 70 20 61 6e  ll to develop an
2070: 79 20 61 64 76 61 6e 63 65 64 20 66 65 61 74 75  y advanced featu
2080: 72 65 73 2e 20 4d 79 20 72 6f 75 67 68 20 74 61  res. My rough ta
2090: 72 67 65 74 20 67 6f 61 6c 20 66 6f 72 20 6d 65  rget goal for me
20a0: 6d 6f 72 79 20 75 73 65 20 69 73 20 61 72 6f 75  mory use is arou
20b0: 6e 64 20 32 2d 33 6b 62 20 66 6f 72 20 33 32 2d  nd 2-3kb for 32-
20c0: 62 69 74 20 62 75 69 6c 64 73 20 28 69 74 27 73  bit builds (it's
20d0: 20 63 75 72 72 65 6e 74 6c 79 20 66 61 72 20 6c   currently far l
20e0: 65 73 73 21 29 2c 20 6e 6f 74 20 69 6e 63 6c 75  ess!), not inclu
20f0: 64 69 6e 67 20 70 75 72 65 6c 79 20 6f 70 74 69  ding purely opti
2100: 6f 6e 61 6c 20 66 65 61 74 75 72 65 73 20 28 65  onal features (e
2110: 2e 67 2e 20 73 74 72 69 6e 67 20 69 6e 74 65 72  .g. string inter
2120: 6e 69 6e 67 29 20 61 6e 64 20 6d 65 6d 6f 72 79  ning) and memory
2130: 20 74 68 65 20 63 6c 69 65 6e 74 20 61 6c 6c 6f   the client allo
2140: 63 61 74 65 73 2e 20 43 75 72 72 65 6e 74 6c 79  cates. Currently
2150: 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 74 20 77   the only part w
2160: 68 69 63 68 20 75 73 65 73 20 73 69 67 6e 69 66  hich uses signif
2170: 69 63 61 6e 74 20 6d 65 6d 6f 72 79 20 6f 75 74  icant memory out
2180: 20 6f 66 20 74 68 65 20 62 6f 78 20 69 73 20 74   of the box is t
2190: 68 65 20 73 74 72 69 6e 67 2d 69 6e 74 65 72 6e  he string-intern
21a0: 69 6e 67 20 74 61 62 6c 65 20 28 63 75 72 72 65  ing table (curre
21b0: 6e 74 6c 79 20 61 62 6f 75 74 20 33 6b 62 2f 70  ntly about 3kb/p
21c0: 61 67 65 2c 20 77 69 74 68 20 70 61 67 65 73 20  age, with pages 
21d0: 62 65 69 6e 67 20 61 64 64 65 64 20 61 73 20 6e  being added as n
21e0: 65 77 6c 79 2d 69 6e 74 65 72 6e 65 64 20 73 74  ewly-interned st
21f0: 72 69 6e 67 73 20 68 61 76 65 20 68 61 73 68 20  rings have hash 
2200: 63 6f 6c 6c 69 73 69 6f 6e 73 29 2e 20 54 68 61  collisions). Tha
2210: 74 20 70 61 72 74 20 69 73 20 6f 66 66 20 62 79  t part is off by
2220: 20 64 65 66 61 75 6c 74 20 61 6e 64 20 63 61 6e   default and can
2230: 20 62 65 20 65 6e 61 62 6c 65 64 2f 64 69 73 61   be enabled/disa
2240: 62 6c 65 64 20 61 74 20 72 75 6e 74 69 6d 65 2e  bled at runtime.
2250: 0d 0a 20 20 2a 20 20 63 77 61 6c 20 6b 6e 6f 77  ..  *  cwal know
2260: 69 6e 67 6c 79 20 73 61 63 72 69 66 69 63 65 73  ingly sacrifices
2270: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 69 6e 20   performance in 
2280: 70 6c 61 63 65 73 20 66 6f 72 20 64 65 74 65 72  places for deter
2290: 6d 69 6e 69 73 74 69 63 20 64 65 73 74 72 75 63  ministic destruc
22a0: 74 69 6f 6e 20 62 65 68 61 76 69 6f 75 72 2e 20  tion behaviour. 
22b0: 53 6f 6d 65 20 6f 66 20 69 74 73 20 61 6c 67 6f  Some of its algo
22c0: 72 69 74 68 6d 73 20 28 69 6e 20 70 61 72 74 69  rithms (in parti
22d0: 63 75 6c 61 72 20 63 6f 6e 74 61 69 6e 65 72 20  cular container 
22e0: 63 6c 65 61 6e 75 70 29 20 77 69 6c 6c 20 28 70  cleanup) will (p
22f0: 6f 73 73 69 62 6c 79 29 20 73 6c 6f 77 20 64 6f  ossibly) slow do
2300: 77 6e 20 77 68 65 6e 20 64 65 61 6c 69 6e 67 20  wn when dealing 
2310: 77 69 74 68 20 68 75 6e 64 72 65 64 73 2d 20 6f  with hundreds- o
2320: 72 20 74 68 6f 75 73 61 6e 64 73 2d 20 6f 66 20  r thousands- of 
2330: 76 61 6c 75 65 73 20 70 65 72 20 73 63 6f 70 65  values per scope
2340: 20 69 66 20 74 68 6f 73 65 20 76 61 6c 75 65 73   if those values
2350: 20 66 6f 72 6d 20 63 6f 6d 70 6c 65 78 20 63 79   form complex cy
2360: 63 6c 65 73 2e 20 28 49 74 20 75 73 65 73 20 61  cles. (It uses a
2370: 20 22 73 6c 6f 77 20 62 75 74 20 73 75 72 65 22   "slow but sure"
2380: 20 6d 65 74 68 6f 64 20 66 6f 72 20 63 6c 65 61   method for clea
2390: 6e 69 6e 67 20 75 70 20 63 79 63 6c 65 73 2e 29  ning up cycles.)
23a0: 20 4f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 77   Optimizations w
23b0: 69 6c 6c 20 62 65 20 6d 61 64 65 20 77 68 65 72  ill be made wher
23c0: 65 20 66 65 61 73 69 62 6c 65 20 61 73 20 65 78  e feasible as ex
23d0: 70 65 72 69 65 6e 63 65 20 72 65 76 65 61 6c 73  perience reveals
23e0: 20 77 68 61 74 20 74 68 65 79 20 73 68 6f 75 6c   what they shoul
23f0: 64 20 62 65 2e 20 54 68 61 74 20 73 61 69 64 2c  d be. That said,
2400: 20 69 74 73 20 63 6f 72 65 2d 6d 6f 73 74 20 61   its core-most a
2410: 6c 67 6f 72 69 74 68 6d 73 20 61 72 65 20 61 6c  lgorithms are al
2420: 6c 20 4f 28 31 29 20 77 68 65 72 65 20 70 6f 73  l O(1) where pos
2430: 73 69 62 6c 65 2c 20 61 6e 64 20 73 6f 6d 65 20  sible, and some 
2440: 6f 74 68 65 72 73 20 68 61 76 65 20 61 20 73 6d  others have a sm
2450: 61 6c 6c 20 4f 28 4e 29 20 6f 72 20 73 69 6d 69  all O(N) or simi
2460: 6c 61 72 6c 79 20 66 61 73 74 20 63 6f 6d 70 75  larly fast compu
2470: 74 61 74 69 6f 6e 61 6c 20 63 6f 6d 70 6c 65 78  tational complex
2480: 69 74 79 2e 0d 0a 20 20 2a 20 20 52 65 66 65 72  ity...  *  Refer
2490: 65 6e 63 65 20 63 6f 75 6e 74 69 6e 67 20 69 6e  ence counting in
24a0: 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 20 77 69 74   conjunction wit
24b0: 68 20 63 79 63 6c 65 73 20 69 73 20 6f 66 20 63  h cycles is of c
24c0: 6f 75 72 73 65 20 68 69 73 74 6f 72 69 63 61 6c  ourse historical
24d0: 6c 79 20 70 72 6f 62 6c 65 6d 61 74 69 63 2c 20  ly problematic, 
24e0: 61 6e 64 20 69 6e 74 72 6f 64 75 63 65 73 20 61  and introduces a
24f0: 6c 6c 20 73 6f 72 74 73 20 6f 66 20 77 72 69 6e  ll sorts of wrin
2500: 6b 6c 65 73 2e 20 54 68 65 20 68 79 62 72 69 64  kles. The hybrid
2510: 20 72 65 66 63 6f 75 6e 74 2f 73 63 6f 70 65 2d   refcount/scope-
2520: 74 72 61 63 6b 69 6e 67 20 6f 77 6e 65 72 73 68  tracking ownersh
2530: 69 70 20 6d 65 63 68 61 6e 69 73 6d 20 68 61 6e  ip mechanism han
2540: 64 6c 65 73 20 63 79 63 6c 65 73 20 71 75 69 74  dles cycles quit
2550: 65 20 77 65 6c 6c 2e 20 54 68 72 6f 75 67 68 6f  e well. Througho
2560: 75 74 20 74 68 65 20 64 65 76 65 6c 6f 70 6d 65  ut the developme
2570: 6e 74 20 6f 66 20 5b 74 68 31 69 73 68 5d 20 61  nt of [th1ish] a
2580: 6e 64 20 5b 73 32 5d 2c 20 63 77 61 6c 27 73 20  nd [s2], cwal's 
2590: 6f 76 65 72 61 6c 6c 20 6d 65 63 68 61 6e 69 73  overall mechanis
25a0: 6d 20 68 61 73 20 62 65 65 6e 20 70 72 6f 76 65  m has been prove
25b0: 6e 20 74 6f 20 62 65 20 20 6d 65 6d 6f 72 79 2d  n to be  memory-
25c0: 66 72 75 67 61 6c 20 61 6e 64 20 72 65 6c 69 61  frugal and relia
25d0: 62 6c 65 2c 20 70 72 6f 76 69 64 65 64 20 69 74  ble, provided it
25e0: 20 69 73 20 75 73 65 64 20 70 72 6f 70 65 72 6c   is used properl
25f0: 79 2e 20 49 74 73 20 47 43 20 6d 65 63 68 61 6e  y. Its GC mechan
2600: 69 73 6d 20 64 6f 65 73 20 68 61 76 65 20 61 20  ism does have a 
2610: 63 6f 75 70 6c 65 20 22 64 65 61 74 68 20 74 72  couple "death tr
2620: 61 70 22 20 63 61 73 65 73 20 77 68 69 63 68 20  ap" cases which 
2630: 63 6c 69 65 6e 74 73 20 73 68 6f 75 6c 64 20 61  clients should a
2640: 76 6f 69 64 20 74 6f 20 6b 65 65 70 20 6d 65 6d  void to keep mem
2650: 6f 72 79 20 63 6f 73 74 73 20 64 6f 77 6e 2c 20  ory costs down, 
2660: 62 75 74 20 69 6e 20 70 72 61 63 74 69 63 65 20  but in practice 
2670: 69 74 20 70 65 72 66 6f 72 6d 73 20 72 65 6d 61  it performs rema
2680: 72 6b 61 62 6c 79 20 77 65 6c 6c 2e 20 28 49 6e  rkably well. (In
2690: 20 70 72 61 63 74 69 63 65 2c 20 76 69 61 20 5b   practice, via [
26a0: 73 32 5d 20 61 6e 64 20 5b 74 68 31 69 73 68 5d  s2] and [th1ish]
26b0: 2c 20 73 75 63 68 20 63 61 73 65 73 20 64 6f 6e  , such cases don
26c0: 27 74 20 63 6f 6d 65 20 75 70 2c 20 62 75 74 20  't come up, but 
26d0: 74 68 65 79 20 63 61 6e 20 62 65 20 77 69 6c 6c  they can be will
26e0: 66 75 6c 6c 79 20 63 6f 6e 73 74 72 75 63 74 65  fully constructe
26f0: 64 2e 29 0d 0a 20 20 2a 20 20 44 65 74 65 72 6d  d.)..  *  Determ
2700: 69 6e 69 73 74 69 63 20 66 69 6e 61 6c 69 7a 61  inistic finaliza
2710: 74 69 6f 6e 20 69 73 20 61 20 6b 65 79 20 72 65  tion is a key re
2720: 71 75 69 72 65 6d 65 6e 74 20 66 6f 72 20 6d 65  quirement for me
2730: 2c 20 61 6e 64 20 63 77 61 6c 20 6d 61 6b 65 73  , and cwal makes
2740: 20 73 75 72 65 20 74 68 61 74 20 69 66 20 74 68   sure that if th
2750: 65 20 63 6c 69 65 6e 74 20 75 73 65 73 20 69 74  e client uses it
2760: 20 70 72 6f 70 65 72 6c 79 2c 20 66 69 6e 61 6c   properly, final
2770: 69 7a 61 74 69 6f 6e 20 6d 65 74 68 6f 64 73 20  ization methods 
2780: 3c 65 6d 3e 77 69 6c 6c 3c 2f 65 6d 3e 20 62 65  <em>will</em> be
2790: 20 63 61 6c 6c 65 64 2e 20 49 74 20 63 61 6e 6e   called. It cann
27a0: 6f 74 20 67 75 61 72 61 6e 74 79 20 61 20 22 70  ot guaranty a "p
27b0: 72 6f 70 65 72 22 20 6f 72 64 65 72 20 6f 66 20  roper" order of 
27c0: 74 68 65 20 63 6c 65 61 6e 75 70 2c 20 62 75 74  the cleanup, but
27d0: 20 73 75 63 68 20 63 61 73 65 73 20 77 68 65 72   such cases wher
27e0: 65 20 74 68 65 20 64 65 73 74 72 75 63 74 69 6f  e the destructio
27f0: 6e 20 6f 72 64 65 72 20 63 61 6e 20 6d 61 6b 65  n order can make
2800: 20 61 20 62 69 67 20 64 69 66 66 65 72 65 6e 63   a big differenc
2810: 65 20 61 72 65 20 6c 69 6d 69 74 65 64 20 74 6f  e are limited to
2820: 20 63 6c 69 65 6e 74 2d 77 72 61 70 70 65 64 20   client-wrapped 
2830: 4e 61 74 69 76 65 20 74 79 70 65 73 20 77 68 69  Native types whi
2840: 63 68 20 72 65 66 65 72 65 6e 63 65 20 65 61 63  ch reference eac
2850: 68 20 6f 74 68 65 72 20 28 61 6e 64 20 22 6d 61  h other (and "ma
2860: 6e 75 61 6c 22 20 66 69 6e 61 6c 69 7a 65 72 73  nual" finalizers
2870: 20 63 61 6e 20 62 65 20 61 74 74 61 63 68 65 64   can be attached
2880: 20 74 6f 20 74 68 6f 73 65 29 2e 20 49 6e 20 6d   to those). In m
2890: 79 20 65 78 70 65 72 69 65 6e 63 65 20 77 69 74  y experience wit
28a0: 68 20 6f 74 68 65 72 20 73 63 72 69 70 74 69 6e  h other scriptin
28b0: 67 20 65 6e 67 69 6e 65 73 2c 20 69 6e 20 73 75  g engines, in su
28c0: 63 68 20 63 61 73 65 73 20 63 6c 69 65 6e 74 20  ch cases client 
28d0: 63 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 61 64  code needs to ad
28e0: 64 20 73 61 66 65 67 75 61 72 64 73 20 61 67 61  d safeguards aga
28f0: 69 6e 73 74 20 70 6f 74 65 6e 74 69 61 6c 6c 79  inst potentially
2900: 20 69 6e 63 6f 72 72 65 63 74 20 64 65 73 74 72   incorrect destr
2910: 75 63 74 69 6f 6e 20 6f 72 64 65 72 2e 20 54 68  uction order. Th
2920: 65 20 65 78 61 6d 70 6c 65 20 77 68 69 63 68 20  e example which 
2930: 63 6f 6d 65 73 20 74 6f 20 6d 69 6e 64 20 69 73  comes to mind is
2940: 20 61 20 64 61 74 61 62 61 73 65 20 64 72 69 76   a database driv
2950: 65 72 20 61 6e 64 20 70 72 65 70 61 72 65 64 20  er and prepared 
2960: 73 74 61 74 65 6d 65 6e 74 73 20 69 74 20 63 72  statements it cr
2970: 65 61 74 65 73 20 28 77 68 69 63 68 20 6e 65 65  eates (which nee
2980: 64 20 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65  d to be destroye
2990: 64 20 62 65 66 6f 72 65 20 74 68 65 20 64 72 69  d before the dri
29a0: 76 65 72 20 69 73 29 2e 20 54 68 65 20 5b 63 77  ver is). The [cw
29b0: 61 6c 5f 77 65 61 6b 5f 72 65 66 7c 77 65 61 6b  al_weak_ref|weak
29c0: 20 72 65 66 65 72 65 6e 63 65 5d 20 61 62 73 74   reference] abst
29d0: 72 61 63 74 69 6f 6e 20 63 61 6e 20 62 65 20 6f  raction can be o
29e0: 66 20 73 6f 6d 65 20 61 73 73 69 73 74 61 6e 63  f some assistanc
29f0: 65 20 68 65 72 65 20 62 75 74 20 69 73 20 6e 6f  e here but is no
2a00: 74 20 61 20 6d 61 67 69 63 20 62 75 6c 6c 65 74  t a magic bullet
2a10: 2e 0a 5a 20 65 65 30 62 35 35 36 34 32 61 36 36  ..Z ee0b55642a66
2a20: 61 31 65 34 62 63 65 35 34 36 34 38 66 32 35 32  a1e4bce54648f252
2a30: 38 30 37 31 0a                                   8071.