libcwal  Hex Artifact Content

Artifact 769b61dd3abcfad304d1f86c6da0f82807157fe7:

Wiki page [HowTo] by stephan 2016-01-12 20:21:35.
0000: 44 20 32 30 31 36 2d 30 31 2d 31 32 54 32 30 3a  D 2016-01-12T20:
0010: 32 31 3a 33 35 2e 35 33 31 0a 4c 20 48 6f 77 54  21:35.531.L HowT
0020: 6f 0a 50 20 65 63 65 65 34 39 34 32 65 62 34 31  o.P ecee4942eb41
0030: 63 36 61 38 63 61 36 37 37 38 63 36 31 63 61 63  c6a8ca6778c61cac
0040: 65 32 34 35 35 61 36 64 61 35 39 37 0a 55 20 73  e2455a6da597.U s
0050: 74 65 70 68 61 6e 0a 57 20 31 33 30 39 33 0a 3c  tephan.W 13093.<
0060: 68 31 3e 55 73 69 6e 67 20 74 68 65 20 63 77 61  h1>Using the cwa
0070: 6c 20 43 20 41 50 49 3c 2f 68 31 3e 0d 0a 0d 0a  l C API</h1>....
0080: 54 68 69 73 20 70 61 67 65 20 70 72 6f 76 69 64  This page provid
0090: 65 73 20 61 20 62 72 69 65 66 20 68 6f 77 2d 74  es a brief how-t
00a0: 6f 20 66 6f 72 20 63 77 61 6c 27 73 20 43 20 41  o for cwal's C A
00b0: 50 49 2e 0d 0a 0d 0a 3c 68 32 3e 48 65 61 64 65  PI.....<h2>Heade
00c0: 72 73 3c 2f 68 32 3e 0d 0a 0d 0a 3c 6e 6f 77 69  rs</h2>....<nowi
00d0: 6b 69 3e 3c 70 72 65 3e 0d 0a 23 69 6e 63 6c 75  ki><pre>..#inclu
00e0: 64 65 20 22 77 68 2f 63 77 61 6c 2f 63 77 61 6c  de "wh/cwal/cwal
00f0: 2e 68 22 0d 0a 2f 2a 20 6f 72 2c 20 69 66 20 75  .h"../* or, if u
0100: 73 69 6e 67 20 74 68 65 20 61 6d 61 6c 67 61 6d  sing the amalgam
0110: 61 74 69 6f 6e 20 62 75 69 6c 64 3a 20 2a 2f 0d  ation build: */.
0120: 0a 23 69 6e 63 6c 75 64 65 20 22 63 77 61 6c 5f  .#include "cwal_
0130: 61 6d 61 6c 67 61 6d 61 74 69 6f 6e 2e 68 22 0d  amalgamation.h".
0140: 0a 3c 2f 70 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e  .</pre></nowiki>
0150: 0d 0a 0d 0a 3c 68 32 3e 49 6e 69 74 69 61 6c 69  ....<h2>Initiali
0160: 7a 69 6e 67 20 61 6e 64 20 43 6c 65 61 6e 69 6e  zing and Cleanin
0170: 67 20 55 70 3c 2f 68 32 3e 0d 0a 0d 0a 54 68 65  g Up</h2>....The
0180: 20 66 69 72 73 74 20 74 68 69 6e 67 20 77 65 20   first thing we 
0190: 6e 65 65 64 20 69 73 20 61 6e 20 22 65 6e 67 69  need is an "engi
01a0: 6e 65 22 20 69 6e 73 74 61 6e 63 65 2c 20 77 68  ne" instance, wh
01b0: 69 63 68 20 6d 61 6e 61 67 65 73 20 73 63 6f 70  ich manages scop
01c0: 69 6e 67 20 61 6e 64 20 6d 65 6d 6f 72 79 20 66  ing and memory f
01d0: 6f 72 20 75 73 2e 20 41 6e 20 65 6e 67 69 6e 65  or us. An engine
01e0: 20 69 6e 73 74 61 6e 63 65 20 72 65 71 75 69 72   instance requir
01f0: 65 73 20 61 20 73 6f 2d 63 61 6c 6c 65 64 20 22  es a so-called "
0200: 76 74 61 62 22 2c 20 77 68 69 63 68 20 69 73 20  vtab", which is 
0210: 61 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20  a collection of 
0220: 22 76 69 72 74 75 61 6c 22 20 66 75 6e 63 74 69  "virtual" functi
0230: 6f 6e 73 20 77 68 69 63 68 20 63 6c 69 65 6e 74  ons which client
0240: 73 20 63 61 6e 20 70 72 6f 76 69 64 65 20 74 6f  s can provide to
0250: 20 63 75 73 74 6f 6d 69 7a 65 20 63 65 72 74 61   customize certa
0260: 69 6e 20 62 65 68 61 76 69 6f 75 72 73 20 6f 66  in behaviours of
0270: 20 74 68 65 20 65 6e 67 69 6e 65 2e 20 46 6f 72   the engine. For
0280: 20 65 78 61 6d 70 6c 65 2c 20 74 68 65 20 76 74   example, the vt
0290: 61 62 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ab defines the m
02a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
02b0: 61 6e 64 20 61 20 67 65 6e 65 72 69 63 20 6f 75  and a generic ou
02c0: 74 70 75 74 20 6d 65 63 68 61 6e 69 73 6d 20 73  tput mechanism s
02d0: 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
02e0: 62 79 20 73 63 72 69 70 74 69 6e 67 20 69 6d 70  by scripting imp
02f0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e 0d 0a 0d  lementations....
0300: 0a 48 65 72 65 20 69 73 20 61 6e 20 65 78 61 6d  .Here is an exam
0310: 70 6c 65 20 6f 66 20 73 65 74 74 69 6e 67 20 75  ple of setting u
0320: 70 20 61 6e 20 65 6e 67 69 6e 65 20 28 73 65 65  p an engine (see
0330: 20 5b 2f 66 69 6e 66 6f 3f 6e 61 6d 65 3d 74 65   [/finfo?name=te
0340: 73 74 2e 63 7c 74 65 73 74 2e 63 5d 20 66 6f 72  st.c|test.c] for
0350: 20 74 68 65 20 66 75 6c 6c 20 69 6d 70 6c 65 6d   the full implem
0360: 65 6e 74 61 74 69 6f 6e 29 3a 0d 0a 0d 0a 0d 0a  entation):......
0370: 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a 20  <nowiki><pre>.. 
0380: 20 20 20 63 77 61 6c 5f 65 6e 67 69 6e 65 5f 76     cwal_engine_v
0390: 74 61 62 20 76 74 61 62 20 3d 20 63 77 61 6c 5f  tab vtab = cwal_
03a0: 65 6e 67 69 6e 65 5f 76 74 61 62 5f 62 61 73 69  engine_vtab_basi
03b0: 63 3b 0d 0a 20 20 20 20 63 77 61 6c 5f 65 6e 67  c;..    cwal_eng
03c0: 69 6e 65 20 45 20 3d 20 63 77 61 6c 5f 65 6e 67  ine E = cwal_eng
03d0: 69 6e 65 5f 65 6d 70 74 79 0d 0a 20 20 20 20 20  ine_empty..     
03e0: 20 20 20 2f 2f 20 4d 41 4b 45 20 53 55 52 45 20     // MAKE SURE 
03f0: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 20 73 74  to initialize st
0400: 61 63 6b 2d 61 6c 6c 6f 63 61 74 65 64 20 69 6e  ack-allocated in
0410: 73 74 61 6e 63 65 73 20 74 68 69 73 20 77 61 79  stances this way
0420: 21 21 21 21 0d 0a 20 20 20 20 20 20 20 20 3b 0d  !!!!..        ;.
0430: 0a 20 20 20 20 63 77 61 6c 5f 65 6e 67 69 6e 65  .    cwal_engine
0440: 20 2a 20 65 20 3d 20 2f 2f 20 64 65 6d 6f 6e 73   * e = // demons
0450: 74 72 61 74 65 20 75 73 69 6e 67 20 61 20 73 74  trate using a st
0460: 61 63 6b 2d 20 76 73 20 68 65 61 70 2d 62 61 73  ack- vs heap-bas
0470: 65 64 20 65 6e 67 69 6e 65 2e 0d 0a 20 20 20 20  ed engine...    
0480: 20 20 20 20 31 20 3f 20 26 45 20 3a 20 4e 55 4c      1 ? &E : NUL
0490: 4c 3b 0d 0a 20 20 20 20 69 6e 74 20 72 63 3b 0d  L;..    int rc;.
04a0: 0a 0d 0a 20 20 20 20 2f 2f 20 53 65 74 20 75 70  ...    // Set up
04b0: 20 6f 75 72 20 22 76 69 72 74 75 61 6c 22 20 66   our "virtual" f
04c0: 75 6e 63 74 69 6f 6e 73 3a 0d 0a 0d 0a 20 20 20  unctions:....   
04d0: 20 2f 2f 20 63 77 61 6c 5f 6f 75 74 70 75 74 28   // cwal_output(
04e0: 29 20 73 65 6e 64 73 20 69 74 73 20 6f 75 74 70  ) sends its outp
04f0: 75 74 20 74 6f 2e 2e 2e 0d 0a 20 20 20 20 76 74  ut to.....    vt
0500: 61 62 2e 6f 75 74 70 75 74 65 72 2e 6f 75 74 70  ab.outputer.outp
0510: 75 74 20 3d 20 63 77 61 6c 5f 6f 75 74 70 75 74  ut = cwal_output
0520: 5f 66 5f 46 49 4c 45 3b 0d 0a 20 20 20 20 76 74  _f_FILE;..    vt
0530: 61 62 2e 6f 75 74 70 75 74 65 72 2e 73 74 61 74  ab.outputer.stat
0540: 65 2e 64 61 74 61 20 3d 20 73 74 64 6f 75 74 3b  e.data = stdout;
0550: 0d 0a 0d 0a 20 20 20 20 2f 2f 20 54 72 61 63 69  ....    // Traci
0560: 6e 67 20 6f 75 74 70 75 74 20 28 69 66 20 65 6e  ng output (if en
0570: 61 62 6c 65 64 29 20 67 6f 65 73 20 68 65 72 65  abled) goes here
0580: 3a 0d 0a 20 20 20 20 76 74 61 62 2e 74 72 61 63  :..    vtab.trac
0590: 65 72 20 3d 20 63 77 61 6c 5f 65 6e 67 69 6e 65  er = cwal_engine
05a0: 5f 74 72 61 63 65 72 5f 46 49 4c 45 3b 0d 0a 20  _tracer_FILE;.. 
05b0: 20 20 20 76 74 61 62 2e 74 72 61 63 65 72 2e 73     vtab.tracer.s
05c0: 74 61 74 65 20 3d 20 73 74 64 6f 75 74 3b 0d 0a  tate = stdout;..
05d0: 0d 0a 20 20 20 20 2f 2f 20 4f 75 72 20 61 70 70  ..    // Our app
05e0: 2d 6c 6f 63 61 6c 20 69 6e 69 74 69 61 6c 69 7a  -local initializ
05f0: 61 74 69 6f 6e 20 68 6f 6f 6b 3a 0d 0a 20 20 20  ation hook:..   
0600: 20 76 74 61 62 2e 68 6f 6f 6b 2e 6f 6e 5f 69 6e   vtab.hook.on_in
0610: 69 74 20 3d 20 65 5f 69 6e 69 74 5f 65 6e 67 69  it = e_init_engi
0620: 6e 65 3b 0d 0a 20 20 20 20 76 74 61 62 2e 68 6f  ne;..    vtab.ho
0630: 6f 6b 2e 69 6e 69 74 5f 73 74 61 74 65 20 3d 20  ok.init_state = 
0640: 65 3b 0d 0a 0d 0a 20 20 20 20 2f 2f 20 4e 6f 77  e;....    // Now
0650: 20 69 6e 69 74 69 61 6c 69 7a 65 20 65 20 77 69   initialize e wi
0660: 74 68 20 6f 75 72 20 76 74 61 62 3a 0d 0a 20 20  th our vtab:..  
0670: 20 20 72 63 20 3d 20 63 77 61 6c 5f 65 6e 67 69    rc = cwal_engi
0680: 6e 65 5f 69 6e 69 74 28 20 26 65 2c 20 26 76 74  ne_init( &e, &vt
0690: 61 62 20 29 0d 0a 20 20 20 20 20 20 2f 2f 20 79  ab )..      // y
06a0: 65 73 2c 20 65 27 73 20 61 64 64 72 65 73 73 20  es, e's address 
06b0: 20 5e 5e 21 20 53 65 65 20 74 68 65 20 41 50 49   ^^! See the API
06c0: 20 64 6f 63 73 20 66 6f 72 20 77 68 79 2e 0d 0a   docs for why...
06d0: 20 20 20 20 20 20 3b 0d 0a 20 20 20 20 69 66 28        ;..    if(
06e0: 72 63 29 20 7b 20 2e 2e 2e 65 72 72 6f 72 2e 2e  rc) { ...error..
06f0: 2e 20 7d 0d 0a 20 20 20 20 65 6c 73 65 20 7b 20  . }..    else { 
0700: 2e 2e 2e 75 73 65 20 65 2e 2e 2e 20 7d 0d 0a 0d  ...use e... }...
0710: 0a 20 20 20 20 2f 2f 20 45 76 65 6e 74 75 61 6c  .    // Eventual
0720: 6c 79 20 63 6c 65 61 6e 20 75 70 20 28 72 65 67  ly clean up (reg
0730: 61 72 64 6c 65 73 73 20 6f 66 20 73 75 63 63 65  ardless of succe
0740: 73 73 20 6f 72 20 66 61 69 6c 75 72 65 29 3a 0d  ss or failure):.
0750: 0a 20 20 20 20 63 77 61 6c 5f 65 6e 67 69 6e 65  .    cwal_engine
0760: 5f 64 65 73 74 72 6f 79 28 65 29 3b 0d 0a 3c 2f  _destroy(e);..</
0770: 70 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d  pre></nowiki>...
0780: 0a 0d 0a 3c 68 32 3e 43 72 65 61 74 69 6e 67 20  ...<h2>Creating 
0790: 61 6e 64 20 46 72 65 65 69 6e 67 20 56 61 6c 75  and Freeing Valu
07a0: 65 73 3c 2f 68 32 3e 0d 0a 0d 0a 43 6f 6e 73 69  es</h2>....Consi
07b0: 64 65 72 20 74 68 69 73 20 63 6f 64 65 3a 0d 0a  der this code:..
07c0: 0d 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d  ..<nowiki><pre>.
07d0: 0a 69 6e 74 20 72 63 20 3d 20 63 77 61 6c 5f 73  .int rc = cwal_s
07e0: 63 6f 70 65 5f 70 75 73 68 28 20 65 2c 20 4e 55  cope_push( e, NU
07f0: 4c 4c 20 29 3b 0d 0a 69 66 28 72 63 29 20 7b 0d  LL );..if(rc) {.
0800: 0a 20 20 20 20 2f 2f 20 53 65 72 69 6f 75 73 20  .    // Serious 
0810: 65 72 72 6f 72 21 0d 0a 20 20 20 20 2f 2f 20 57  error!..    // W
0820: 69 6c 6c 20 6f 6e 6c 79 20 66 61 69 6c 20 69 66  ill only fail if
0830: 20 21 65 2c 20 61 6e 20 4f 4f 4d 20 63 6f 6e 64   !e, an OOM cond
0840: 69 74 69 6f 6e 2c 20 6f 72 20 70 65 72 68 61 70  ition, or perhap
0850: 73 20 6d 65 6d 6f 72 79 0d 0a 20 20 20 20 2f 2f  s memory..    //
0860: 20 63 6f 72 72 75 70 74 69 6f 6e 20 6f 72 20 73   corruption or s
0870: 6f 6d 65 20 73 75 63 68 0d 0a 7d 65 6c 73 65 7b  ome such..}else{
0880: 0d 0a 20 2f 2f 20 75 73 65 20 65 2c 20 74 68 65  .. // use e, the
0890: 6e 2e 2e 2e 20 0d 0a 20 63 77 61 6c 5f 73 63 6f  n... .. cwal_sco
08a0: 70 65 5f 70 6f 70 28 20 65 20 29 3b 20 2f 2f 20  pe_pop( e ); // 
08b0: 4d 55 53 54 20 62 65 20 63 61 6c 6c 65 64 20 66  MUST be called f
08c0: 6f 72 20 65 61 63 68 20 5f 73 75 63 63 65 73 73  or each _success
08d0: 66 75 6c 5f 20 70 75 73 68 28 29 0d 0a 7d 0d 0a  ful_ push()..}..
08e0: 0d 0a 2f 2f 20 73 69 64 65 62 61 72 3a 20 74 68  ..// sidebar: th
08f0: 65 72 65 20 61 72 65 20 61 20 63 6f 75 70 6c 65  ere are a couple
0900: 20 6f 74 68 65 72 20 6f 70 74 69 6f 6e 73 20 66   other options f
0910: 6f 72 20 70 75 73 68 69 6e 67 20 73 63 6f 70 65  or pushing scope
0920: 73 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  s, depending on 
0930: 68 6f 77 0d 0a 2f 2f 20 6f 6e 65 20 77 61 6e 74  how..// one want
0940: 73 20 74 6f 20 6d 61 6e 61 67 65 20 74 68 65 20  s to manage the 
0950: 6d 65 6d 6f 72 79 20 6f 66 20 74 68 65 20 73 63  memory of the sc
0960: 6f 70 65 20 6f 62 6a 65 63 74 20 28 65 2e 67 2e  ope object (e.g.
0970: 20 69 74 20 6d 61 79 20 62 65 20 73 74 61 63 6b   it may be stack
0980: 2d 61 6c 6c 6f 63 61 74 65 64 29 2e 0d 0a 3c 2f  -allocated)...</
0990: 70 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d  pre></nowiki>...
09a0: 0a 42 65 74 77 65 65 6e 20 74 68 65 20 70 75 73  .Between the pus
09b0: 68 2f 70 6f 70 20 63 61 6c 6c 73 2c 20 61 6c 6c  h/pop calls, all
09c0: 20 6e 65 77 20 76 61 6c 75 65 73 20 61 72 65 20   new values are 
09d0: 69 6e 69 74 69 61 6c 6c 79 20 6f 77 6e 65 64 20  initially owned 
09e0: 62 79 20 74 68 65 20 70 75 73 68 65 64 20 73 63  by the pushed sc
09f0: 6f 70 65 20 61 6e 64 20 77 69 6c 6c 20 62 65 20  ope and will be 
0a00: 63 6c 65 61 6e 65 64 20 75 70 20 62 65 66 6f 72  cleaned up befor
0a10: 65 20 3c 74 74 3e 63 77 61 6c 5f 73 63 6f 70 65  e <tt>cwal_scope
0a20: 5f 70 6f 70 28 29 3c 2f 74 74 3e 20 72 65 74 75  _pop()</tt> retu
0a30: 72 6e 73 2e 20 54 68 65 20 6c 69 62 72 61 72 79  rns. The library
0a40: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 72 61 63   internally trac
0a50: 6b 73 20 74 68 65 20 3c 65 6d 3e 6f 6c 64 65 73  ks the <em>oldes
0a60: 74 3c 2f 65 6d 3e 20 73 63 6f 70 65 20 77 68 69  t</em> scope whi
0a70: 63 68 20 65 76 65 72 20 22 63 6c 61 69 6d 73 22  ch ever "claims"
0a80: 20 61 20 76 61 6c 75 65 2c 20 73 75 63 68 20 74   a value, such t
0a90: 68 61 74 20 61 20 76 61 6c 75 65 20 77 69 6c 6c  hat a value will
0aa0: 20 28 67 65 6e 65 72 61 6c 6c 79 29 20 61 6c 77   (generally) alw
0ab0: 61 79 73 20 62 65 20 74 72 61 63 6b 65 64 20 62  ays be tracked b
0ac0: 79 20 65 78 61 63 74 6c 79 20 6f 6e 65 20 73 63  y exactly one sc
0ad0: 6f 70 65 2e 20 54 68 65 72 65 20 61 72 65 20 62  ope. There are b
0ae0: 72 69 65 66 20 70 65 72 69 6f 64 73 20 69 6e 20  rief periods in 
0af0: 61 20 76 61 6c 75 65 27 73 20 6c 69 66 65 74 69  a value's lifeti
0b00: 6d 65 20 77 68 65 72 65 20 69 74 20 68 61 73 20  me where it has 
0b10: 6e 6f 20 73 63 6f 70 65 20 6f 72 20 70 6f 69 6e  no scope or poin
0b20: 74 73 20 74 6f 20 61 20 68 69 67 68 65 72 2d 6c  ts to a higher-l
0b30: 65 76 65 6c 20 73 63 6f 70 65 20 74 68 61 6e 20  evel scope than 
0b40: 69 74 20 73 68 6f 75 6c 64 2c 20 62 75 74 20 74  it should, but t
0b50: 68 65 20 6c 69 62 72 61 72 79 20 61 63 63 6f 75  he library accou
0b60: 6e 74 73 20 66 6f 72 20 74 68 65 73 65 2c 20 63  nts for these, c
0b70: 6f 72 72 65 63 74 69 6e 67 20 74 68 65 6d 20 69  orrecting them i
0b80: 66 20 6e 65 65 64 65 64 2e 0d 0a 0d 0a 57 68 65  f needed.....Whe
0b90: 6e 20 61 20 76 61 6c 75 65 20 69 73 20 69 6e 73  n a value is ins
0ba0: 65 72 74 65 64 20 69 6e 74 6f 20 61 20 63 6f 6e  erted into a con
0bb0: 74 61 69 6e 65 72 20 76 61 6c 75 65 20 28 61 6e  tainer value (an
0bc0: 20 41 72 72 61 79 20 6f 72 20 4f 62 6a 65 63 74   Array or Object
0bd0: 29 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 20  ) the container 
0be0: 65 6e 73 75 72 65 73 20 74 68 61 74 20 74 68 65  ensures that the
0bf0: 20 76 61 6c 75 65 20 69 73 20 6d 61 6e 61 67 65   value is manage
0c00: 64 20 62 79 20 28 6f 72 20 74 72 61 6e 73 66 65  d by (or transfe
0c10: 72 72 65 64 20 74 6f 29 20 61 20 73 63 6f 70 65  rred to) a scope
0c20: 20 77 68 69 63 68 20 20 69 73 20 61 74 20 74 68   which  is at th
0c30: 65 20 63 6f 6e 74 61 69 6e 65 72 27 73 20 6c 65  e container's le
0c40: 76 65 6c 20 6f 72 20 6c 6f 77 65 72 2e 20 54 68  vel or lower. Th
0c50: 69 73 20 65 66 66 65 63 74 69 76 65 6c 79 20 65  is effectively e
0c60: 6e 73 75 72 65 73 20 74 68 61 74 20 76 61 6c 75  nsures that valu
0c70: 65 73 20 6c 69 76 65 20 61 73 20 6c 6f 6e 67 20  es live as long 
0c80: 61 73 20 61 6c 6c 20 6f 66 20 74 68 65 69 72 20  as all of their 
0c90: 72 65 66 65 72 65 6e 63 65 73 20 61 6e 64 20 67  references and g
0ca0: 69 76 65 73 20 75 73 20 61 20 73 6f 6c 69 64 20  ives us a solid 
0cb0: 73 65 74 20 6f 66 20 72 75 6c 65 73 20 77 68 69  set of rules whi
0cc0: 63 68 20 77 65 20 63 61 6e 20 75 73 65 20 66 6f  ch we can use fo
0cd0: 72 20 70 72 6f 70 65 72 20 63 6c 65 61 6e 75 70  r proper cleanup
0ce0: 20 6f 66 20 73 63 6f 70 65 73 20 69 6e 20 74 68   of scopes in th
0cf0: 65 20 66 61 63 65 20 6f 66 20 63 79 63 6c 65 73  e face of cycles
0d00: 2e 0d 0a 0d 0a 56 61 6c 75 65 73 20 61 72 65 20  .....Values are 
0d10: 61 6c 77 61 79 73 20 63 72 65 61 74 65 64 20 77  always created w
0d20: 69 74 68 69 6e 20 74 68 65 20 63 6f 6e 74 65 78  ithin the contex
0d30: 74 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  t of the current
0d40: 6c 79 2d 61 63 74 69 76 65 20 63 77 61 6c 20 73  ly-active cwal s
0d50: 63 6f 70 65 20 28 74 68 65 20 74 6f 70 20 73 63  cope (the top sc
0d60: 6f 70 65 20 6f 6e 20 74 68 65 20 73 74 61 63 6b  ope on the stack
0d70: 29 2e 20 54 68 65 72 65 20 61 72 65 20 61 20 6e  ). There are a n
0d80: 75 6d 62 65 72 20 6f 66 20 66 61 63 74 6f 72 79  umber of factory
0d90: 20 66 75 6e 63 74 69 6f 6e 73 20 77 68 69 63 68   functions which
0da0: 20 63 72 65 61 74 65 20 76 61 6c 75 65 73 2c 20   create values, 
0db0: 61 73 20 64 65 6d 6f 6e 73 74 72 61 74 65 64 20  as demonstrated 
0dc0: 68 65 72 65 3a 0d 0a 0d 0a 3c 6e 6f 77 69 6b 69  here:....<nowiki
0dd0: 3e 3c 70 72 65 3e 0d 0a 63 77 61 6c 5f 76 61 6c  ><pre>..cwal_val
0de0: 75 65 20 2a 20 76 49 6e 74 20 3d 20 63 77 61 6c  ue * vInt = cwal
0df0: 5f 6e 65 77 5f 69 6e 74 65 67 65 72 28 20 65 2c  _new_integer( e,
0e00: 20 34 32 20 29 3b 0d 0a 63 77 61 6c 5f 76 61 6c   42 );..cwal_val
0e10: 75 65 20 2a 20 76 42 6f 6f 6c 20 3d 20 63 77 61  ue * vBool = cwa
0e20: 6c 5f 6e 65 77 5f 62 6f 6f 6c 28 31 29 3b 20 2f  l_new_bool(1); /
0e30: 2f 63 77 61 6c 5f 76 61 6c 75 65 5f 74 72 75 65  /cwal_value_true
0e40: 28 29 2f 63 77 61 6c 5f 76 61 6c 75 65 5f 66 61  ()/cwal_value_fa
0e50: 6c 73 65 28 29 0d 0a 63 77 61 6c 5f 76 61 6c 75  lse()..cwal_valu
0e60: 65 20 2a 20 76 44 62 6c 20 3d 20 63 77 61 6c 5f  e * vDbl = cwal_
0e70: 6e 65 77 5f 64 6f 75 62 6c 65 28 20 65 2c 20 32  new_double( e, 2
0e80: 34 2e 34 32 20 29 3b 0d 0a 63 77 61 6c 5f 76 61  4.42 );..cwal_va
0e90: 6c 75 65 20 2a 20 76 4e 75 6c 6c 20 3d 20 63 77  lue * vNull = cw
0ea0: 61 6c 5f 76 61 6c 75 65 5f 6e 75 6c 6c 28 29 3b  al_value_null();
0eb0: 0d 0a 63 77 61 6c 5f 76 61 6c 75 65 20 2a 20 76  ..cwal_value * v
0ec0: 75 6e 64 65 66 20 3d 20 63 77 61 6c 5f 76 61 6c  undef = cwal_val
0ed0: 75 65 5f 75 6e 64 65 66 69 6e 65 64 28 29 3b 0d  ue_undefined();.
0ee0: 0a 63 77 61 6c 5f 73 74 72 69 6e 67 20 2a 20 73  .cwal_string * s
0ef0: 74 72 20 3d 20 63 77 61 6c 5f 6e 65 77 5f 73 74  tr = cwal_new_st
0f00: 72 69 6e 67 28 20 65 2c 20 22 48 69 21 22 2c 20  ring( e, "Hi!", 
0f10: 33 20 29 3b 0d 0a 63 77 61 6c 5f 76 61 6c 75 65  3 );..cwal_value
0f20: 20 2a 20 76 53 74 72 20 3d 20 63 77 61 6c 5f 73   * vStr = cwal_s
0f30: 74 72 69 6e 67 5f 76 61 6c 75 65 28 73 74 72 29  tring_value(str)
0f40: 3b 0d 0a 61 73 73 65 72 74 28 20 63 77 61 6c 5f  ;..assert( cwal_
0f50: 76 61 6c 75 65 5f 67 65 74 5f 73 74 72 69 6e 67  value_get_string
0f60: 28 76 53 74 72 29 20 3d 3d 20 73 74 72 20 29 3b  (vStr) == str );
0f70: 0d 0a 63 77 61 6c 5f 6f 62 6a 65 63 74 20 2a 20  ..cwal_object * 
0f80: 6f 62 6a 20 3d 20 63 77 61 6c 5f 6e 65 77 5f 6f  obj = cwal_new_o
0f90: 62 6a 65 63 74 28 65 29 3b 0d 0a 63 77 61 6c 5f  bject(e);..cwal_
0fa0: 61 72 72 61 79 20 2a 20 61 72 20 3d 20 63 77 61  array * ar = cwa
0fb0: 6c 5f 6e 65 77 5f 61 72 72 61 79 28 65 29 3b 0d  l_new_array(e);.
0fc0: 0a 2f 2f 20 54 68 65 72 65 20 61 72 65 20 61 20  .// There are a 
0fd0: 66 65 77 20 6f 74 68 65 72 73 20 61 73 20 77 65  few others as we
0fe0: 6c 6c 2e 0d 0a 3c 2f 70 72 65 3e 3c 2f 6e 6f 77  ll...</pre></now
0ff0: 69 6b 69 3e 0d 0a 0d 0a 45 61 63 68 20 6f 66 20  iki>....Each of 
1000: 74 68 6f 73 65 20 76 61 6c 75 65 73 20 69 73 20  those values is 
1010: 69 6e 69 74 69 61 6c 6c 79 20 6d 61 6e 61 67 65  initially manage
1020: 64 20 62 79 20 74 68 65 20 63 75 72 72 65 6e 74  d by the current
1030: 20 73 63 6f 70 65 2c 20 61 73 20 64 65 73 63 72   scope, as descr
1040: 69 62 65 64 20 61 62 6f 76 65 2c 20 61 6e 64 20  ibed above, and 
1050: 74 68 65 20 63 6c 69 65 6e 74 20 64 6f 65 73 20  the client does 
1060: 6e 6f 74 20 6e 65 65 64 20 74 6f 20 65 78 70 6c  not need to expl
1070: 69 63 69 74 6c 79 20 72 65 6c 65 61 73 65 20 74  icitly release t
1080: 68 65 6d 20 28 69 74 20 63 61 6e 20 62 65 20 64  hem (it can be d
1090: 6f 6e 65 2c 20 74 68 6f 75 67 68 29 2e 0d 0a 0d  one, though)....
10a0: 0a 41 6c 6c 20 6e 6f 6e 2d 63 6f 6e 74 61 69 6e  .All non-contain
10b0: 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 3c 65  er values are <e
10c0: 6d 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 65 6d 3e  m>immutable</em>
10d0: 20 2d 20 74 68 65 69 72 20 75 6e 64 65 72 6c 79   - their underly
10e0: 69 6e 67 20 22 6e 61 74 69 76 65 22 20 76 61 6c  ing "native" val
10f0: 75 65 20 63 61 6e 6e 6f 74 20 62 65 20 6d 6f 64  ue cannot be mod
1100: 69 66 69 65 64 20 77 69 74 68 6f 75 74 20 64 65  ified without de
1110: 73 74 72 6f 79 69 6e 67 2f 72 65 63 72 65 61 74  stroying/recreat
1120: 69 6e 67 20 74 68 65 6d 20 28 74 68 69 73 20 69  ing them (this i
1130: 73 20 6e 6f 74 20 61 73 20 65 78 70 65 6e 73 69  s not as expensi
1140: 76 65 20 61 73 20 69 74 20 73 6f 75 6e 64 73 20  ve as it sounds 
1150: 64 75 65 20 74 6f 20 72 65 66 63 6f 75 6e 74 69  due to refcounti
1160: 6e 67 20 61 6e 64 20 6d 65 6d 6f 72 79 20 72 65  ng and memory re
1170: 63 79 63 6c 69 6e 67 29 2e 20 54 68 65 20 63 6f  cycling). The co
1180: 6e 74 61 69 6e 65 72 20 74 79 70 65 73 20 61 72  ntainer types ar
1190: 65 20 6f 66 20 63 6f 75 72 73 65 20 6d 75 74 61  e of course muta
11a0: 62 6c 65 20 28 6f 72 20 74 68 65 79 20 77 6f 75  ble (or they wou
11b0: 6c 64 20 62 65 20 70 72 65 74 74 79 20 75 73 65  ld be pretty use
11c0: 6c 65 73 73 29 2e 20 53 74 72 69 6e 67 73 20 61  less). Strings a
11d0: 72 65 20 69 6d 6d 75 74 61 62 6c 65 2c 20 61 6e  re immutable, an
11e0: 64 20 63 61 6e 6e 6f 74 20 62 65 20 6d 61 64 65  d cannot be made
11f0: 20 6f 74 68 65 72 77 69 73 65 20 77 69 74 68 6f   otherwise witho
1200: 75 74 20 73 61 63 72 69 66 69 63 69 6e 67 20 61  ut sacrificing a
1210: 74 20 6c 65 61 73 74 20 74 77 6f 20 3c 74 74 3e  t least two <tt>
1220: 6d 61 6c 6c 6f 63 28 29 3c 2f 74 74 3e 2d 72 65  malloc()</tt>-re
1230: 64 75 63 74 69 6f 6e 20 6f 70 74 69 6d 69 7a 61  duction optimiza
1240: 74 69 6f 6e 73 20 77 68 69 63 68 20 72 65 6c 79  tions which rely
1250: 20 6f 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   on the current 
1260: 73 74 72 69 6e 67 2d 61 6c 6c 6f 63 61 74 69 6f  string-allocatio
1270: 6e 20 6d 65 63 68 61 6e 69 73 6d 2e 0d 0a 0d 0a  n mechanism.....
1280: 57 68 65 6e 20 76 61 6c 75 65 73 20 61 72 65 20  When values are 
1290: 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 20 61 6e  inserted into an
12a0: 64 20 72 65 6d 6f 76 65 64 20 66 72 6f 6d 20 63  d removed from c
12b0: 6f 6e 74 61 69 6e 65 72 73 2c 20 74 68 65 69 72  ontainers, their
12c0: 20 72 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74   reference count
12d0: 73 20 61 72 65 20 6d 61 6e 61 67 65 64 20 74 6f  s are managed to
12e0: 20 65 6e 73 75 72 65 20 74 68 61 74 20 61 20 76   ensure that a v
12f0: 61 6c 75 65 20 63 61 6e 20 73 75 72 76 69 76 65  alue can survive
1300: 20 6c 6f 6e 67 65 72 20 74 68 61 6e 20 69 74 73   longer than its
1310: 20 73 63 6f 70 65 20 61 6e 64 20 67 65 74 20 63   scope and get c
1320: 6c 65 61 6e 65 64 20 75 70 20 77 68 65 6e 20 74  leaned up when t
1330: 68 65 20 6c 61 73 74 20 72 65 66 65 72 65 6e 63  he last referenc
1340: 65 20 69 73 20 72 65 6c 65 61 73 65 64 2e 20 49  e is released. I
1350: 66 20 61 20 63 6f 6e 74 61 69 6e 65 72 20 68 6f  f a container ho
1360: 6c 64 69 6e 67 20 69 74 20 67 65 74 73 20 6d 6f  lding it gets mo
1370: 76 65 64 20 74 6f 20 61 20 68 69 67 68 65 72 2d  ved to a higher-
1380: 6c 65 76 65 6c 20 28 6f 6c 64 65 72 29 20 73 63  level (older) sc
1390: 6f 70 65 20 2c 20 69 74 20 67 65 74 73 20 75 70  ope , it gets up
13a0: 2d 73 63 6f 70 65 64 2c 20 74 6f 6f 2c 20 69 66  -scoped, too, if
13b0: 20 6e 65 65 64 65 64 2e 0d 0a 0d 0a 43 6c 69 65   needed.....Clie
13c0: 6e 74 73 2c 20 69 66 20 74 68 65 79 20 77 61 6e  nts, if they wan
13d0: 74 20 74 6f 20 6b 65 65 70 20 76 61 6c 75 65 73  t to keep values
13e0: 20 61 6c 69 76 65 2c 20 6d 61 6e 61 67 65 20 6c   alive, manage l
13f0: 69 66 65 74 69 6d 65 73 20 75 73 69 6e 67 20 61  ifetimes using a
1400: 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20   combination of 
1410: 72 65 66 63 6f 75 6e 74 73 20 61 6e 64 20 73 63  refcounts and sc
1420: 6f 70 65 20 6f 77 6e 65 72 73 68 69 70 2e 20 4c  ope ownership. L
1430: 65 74 27 73 20 73 75 66 66 69 63 65 20 77 69 74  et's suffice wit
1440: 68 20 74 68 69 73 20 73 69 6d 70 6c 69 66 69 65  h this simplifie
1450: 64 20 64 65 73 63 72 69 70 74 69 6f 6e 20 28 77  d description (w
1460: 68 69 63 68 20 69 73 20 61 63 63 75 72 61 74 65  hich is accurate
1470: 20 62 75 74 20 69 73 20 6e 6f 74 20 74 68 65 20   but is not the 
1480: 77 68 6f 6c 65 20 74 72 75 74 68 29 2e 2e 2e 0d  whole truth)....
1490: 0a 0d 0a 41 20 63 6c 69 65 6e 74 20 6d 61 79 20  ...A client may 
14a0: 6f 62 74 61 69 6e 20 61 20 72 65 66 65 72 65 6e  obtain a referen
14b0: 63 65 20 66 6f 72 20 68 69 6d 73 65 6c 66 20 62  ce for himself b
14c0: 79 20 63 61 6c 6c 69 6e 67 20 3c 74 74 3e 63 77  y calling <tt>cw
14d0: 61 6c 5f 76 61 6c 75 65 5f 72 65 66 28 29 3c 2f  al_value_ref()</
14e0: 74 74 3e 2e 20 46 6f 72 20 65 61 63 68 20 74 69  tt>. For each ti
14f0: 6d 65 20 61 20 76 61 6c 75 65 20 69 73 20 70 61  me a value is pa
1500: 73 73 65 64 20 74 6f 20 74 68 61 74 2c 20 69 74  ssed to that, it
1510: 20 3c 65 6d 3e 6d 75 73 74 3c 2f 65 6d 3e 20 62   <em>must</em> b
1520: 65 20 70 61 73 73 65 64 20 74 6f 20 3c 74 74 3e  e passed to <tt>
1530: 63 77 61 6c 5f 76 61 6c 75 65 5f 75 6e 72 65 66  cwal_value_unref
1540: 28 29 3c 2f 74 74 3e 2e 20 54 68 69 6e 6b 20 6f  ()</tt>. Think o
1550: 66 20 3c 74 74 3e 63 77 61 6c 5f 76 61 6c 75 65  f <tt>cwal_value
1560: 5f 72 65 66 28 29 3c 2f 74 74 3e 20 61 73 20 72  _ref()</tt> as r
1570: 65 73 6f 75 72 63 65 20 61 63 71 75 69 73 69 74  esource acquisit
1580: 69 6f 6e 20 61 6e 64 20 3c 74 74 3e 63 77 61 6c  ion and <tt>cwal
1590: 5f 76 61 6c 75 65 5f 75 6e 72 65 66 28 29 3c 2f  _value_unref()</
15a0: 74 74 3e 20 61 73 20 74 68 65 20 72 65 6c 65 61  tt> as the relea
15b0: 73 65 20 6f 66 20 74 68 61 74 20 72 65 73 6f 75  se of that resou
15c0: 72 63 65 2e 20 55 6e 72 65 66 27 69 6e 67 20 6d  rce. Unref'ing m
15d0: 69 67 68 74 20 6f 72 20 6d 69 67 68 74 20 6e 6f  ight or might no
15e0: 74 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 66 72  t immediately fr
15f0: 65 65 20 74 68 65 20 76 61 6c 75 65 2c 20 62 75  ee the value, bu
1600: 74 20 74 68 65 20 63 6c 69 65 6e 74 20 6d 75 73  t the client mus
1610: 74 20 74 72 65 61 74 20 69 74 20 61 73 20 69 66  t treat it as if
1620: 20 69 74 20 77 65 72 65 20 73 65 6d 61 6e 74 69   it were semanti
1630: 63 61 6c 6c 79 20 66 72 65 65 64 2c 20 61 6e 64  cally freed, and
1640: 20 6e 6f 74 20 72 65 66 65 72 20 74 6f 20 74 68   not refer to th
1650: 65 20 70 6f 69 6e 74 65 72 20 61 67 61 69 6e 2e  e pointer again.
1660: 20 28 57 68 69 6c 65 2c 20 69 6e 20 66 61 63 74   (While, in fact
1670: 2c 20 69 74 20 3c 65 6d 3e 6d 69 67 68 74 3c 2f  , it <em>might</
1680: 65 6d 3e 20 62 65 20 76 61 6c 69 64 20 66 6f 72  em> be valid for
1690: 20 73 6f 6d 65 20 74 69 6d 65 20 64 75 65 20 74   some time due t
16a0: 6f 20 72 65 63 79 63 6c 69 6e 67 20 61 6e 64 20  o recycling and 
16b0: 73 75 63 68 2c 20 61 63 63 65 73 73 69 6e 67 20  such, accessing 
16c0: 69 74 20 69 6e 76 6f 6b 65 73 20 55 6e 64 65 66  it invokes Undef
16d0: 69 6e 65 64 20 42 65 68 61 76 69 6f 75 72 2e 29  ined Behaviour.)
16e0: 20 49 66 20 61 20 63 6c 69 65 6e 74 20 66 61 69   If a client fai
16f0: 6c 73 20 74 6f 20 63 61 6c 6c 20 75 6e 72 65 66  ls to call unref
1700: 2c 20 74 68 65 20 6f 77 6e 69 6e 67 20 73 63 6f  , the owning sco
1710: 70 65 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  pe will eventual
1720: 6c 79 20 72 65 61 70 20 74 68 65 20 76 61 6c 75  ly reap the valu
1730: 65 20 28 61 6c 6c 20 72 65 66 65 72 65 6e 63 65  e (all reference
1740: 73 20 74 6f 20 69 74 2c 20 6d 69 6e 75 73 20 61  s to it, minus a
1750: 6e 79 20 63 6c 65 61 6e 65 64 20 75 70 20 62 79  ny cleaned up by
1760: 20 63 6f 6e 74 61 69 6e 65 72 73 20 69 6e 20 74   containers in t
1770: 68 65 20 73 61 6d 65 20 73 63 6f 70 65 29 2e 20  he same scope). 
1780: 69 2e 65 2e 20 69 74 20 77 69 6c 6c 20 62 65 20  i.e. it will be 
1790: 63 6c 65 61 6e 65 64 20 75 70 20 65 76 65 6e 74  cleaned up event
17a0: 75 61 6c 6c 79 2c 20 62 75 74 20 69 74 20 72 65  ually, but it re
17b0: 70 72 65 73 65 6e 74 73 20 61 20 76 69 72 74 75  presents a virtu
17c0: 61 6c 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 20 61  al memory leak a
17d0: 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 72 65  s long as the re
17e0: 66 65 72 65 6e 63 69 6e 67 20 73 63 6f 70 65 20  ferencing scope 
17f0: 69 73 20 61 6c 69 76 65 29 2e 0d 0a 0d 0a 3c 68  is alive).....<h
1800: 32 3e 57 6f 72 6b 69 6e 67 20 77 69 74 68 20 56  2>Working with V
1810: 61 6c 75 65 73 3c 2f 68 32 3e 0d 0a 0d 0a 54 68  alues</h2>....Th
1820: 65 20 63 77 61 6c 20 76 61 6c 75 65 20 74 79 70  e cwal value typ
1830: 65 73 20 6d 61 70 20 6e 61 74 75 72 61 6c 6c 79  es map naturally
1840: 20 74 6f 20 63 6f 6d 6d 6f 6e 6c 79 2d 75 73 65   to commonly-use
1850: 64 20 76 61 6c 75 65 20 74 79 70 65 73 2e 20 41  d value types. A
1860: 6e 20 6f 76 65 72 76 69 65 77 20 6f 66 20 74 68  n overview of th
1870: 65 20 74 79 70 65 73 3a 0d 0a 0d 0a 20 20 20 2a  e types:....   *
1880: 20 20 49 6e 74 65 67 65 72 73 2c 20 64 6f 75 62    Integers, doub
1890: 6c 65 73 2c 20 62 6f 6f 6c 65 61 6e 73 2e 0d 0a  les, booleans...
18a0: 20 20 20 2a 20 20 54 68 65 20 73 70 65 63 69 61     *  The specia
18b0: 6c 2d 63 61 73 65 20 22 6e 75 6c 6c 22 20 61 6e  l-case "null" an
18c0: 64 20 22 75 6e 64 65 66 69 6e 65 64 22 20 76 61  d "undefined" va
18d0: 6c 75 65 73 2e 0d 0a 20 20 20 2a 20 20 53 74 72  lues...   *  Str
18e0: 69 6e 67 73 3a 20 74 68 65 20 6c 69 62 72 61 72  ings: the librar
18f0: 79 20 64 6f 65 73 20 6e 6f 74 20 61 73 73 75 6d  y does not assum
1900: 65 20 61 20 73 70 65 63 69 66 69 63 20 65 6e 63  e a specific enc
1910: 6f 64 69 6e 67 2c 20 77 69 74 68 20 74 68 65 20  oding, with the 
1920: 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20 74  exception that t
1930: 68 65 20 63 77 61 6c 2d 74 6f 2d 6a 73 6f 6e 20  he cwal-to-json 
1940: 75 74 69 6c 69 74 79 20 63 6f 64 65 20 61 73 73  utility code ass
1950: 75 6d 65 73 20 55 54 46 38 2e 20 4d 69 6e 6f 72  umes UTF8. Minor
1960: 20 62 75 67 3a 20 63 75 72 72 65 6e 74 6c 79 20   bug: currently 
1970: 63 61 6e 6e 6f 74 20 77 6f 72 6b 20 77 69 74 68  cannot work with
1980: 20 55 54 46 31 36 20 62 65 63 61 75 73 65 20 69   UTF16 because i
1990: 74 20 61 73 73 75 6d 65 73 20 30 20 69 73 20 74  t assumes 0 is t
19a0: 68 65 20 65 6e 64 2d 6f 66 2d 73 74 72 69 6e 67  he end-of-string
19b0: 20 62 79 74 65 2e 20 55 54 46 38 20 73 68 6f 75   byte. UTF8 shou
19c0: 6c 64 20 62 65 20 66 69 6e 65 2e 0d 0a 20 20 20  ld be fine...   
19d0: 2a 20 20 41 72 72 61 79 73 20 70 72 6f 76 69 64  *  Arrays provid
19e0: 65 20 67 65 6e 65 72 69 63 20 6c 69 73 74 20 73  e generic list s
19f0: 75 70 70 6f 72 74 2e 20 54 68 65 79 20 63 61 6e  upport. They can
1a00: 20 61 6c 73 6f 20 68 6f 6c 64 20 70 72 6f 70 65   also hold prope
1a10: 72 74 69 65 73 20 6c 69 6b 65 2e 2e 2e 0d 0a 20  rties like..... 
1a20: 20 20 2a 20 20 4f 62 6a 65 63 74 73 20 70 72 6f    *  Objects pro
1a30: 76 69 64 65 20 6d 61 70 2d 6c 69 6b 65 20 73 75  vide map-like su
1a40: 70 70 6f 72 74 2c 20 77 69 74 68 20 74 68 65 20  pport, with the 
1a50: 63 61 76 65 61 74 20 74 68 61 74 20 74 68 65 79  caveat that they
1a60: 20 63 75 72 72 65 6e 74 6c 79 20 68 61 76 65 20   currently have 
1a70: 4f 28 4e 29 20 73 65 61 72 63 68 20 74 69 6d 65  O(N) search time
1a80: 20 62 65 63 61 75 73 65 20 74 68 65 20 73 63 6f   because the sco
1a90: 70 69 6e 67 20 72 75 6c 65 73 20 6f 72 69 67 69  ping rules origi
1aa0: 6e 61 6c 6c 79 20 72 65 71 75 69 72 65 64 20 74  nally required t
1ab0: 68 61 74 20 74 68 65 79 20 62 65 20 6b 65 70 74  hat they be kept
1ac0: 20 69 6e 20 69 6e 73 65 72 74 69 6f 6e 20 6f 72   in insertion or
1ad0: 64 65 72 20 28 74 68 61 74 20 69 73 20 6e 6f 20  der (that is no 
1ae0: 6c 6f 6e 67 65 72 20 74 68 65 20 63 61 73 65 2c  longer the case,
1af0: 20 73 69 6e 63 65 20 77 65 20 63 61 6e 6e 6f 74   since we cannot
1b00: 20 67 75 61 72 61 6e 74 79 20 64 65 73 74 72 75   guaranty destru
1b10: 63 74 69 6f 6e 20 6f 72 64 65 72 20 6f 6e 63 65  ction order once
1b20: 20 61 20 76 61 6c 75 65 20 6c 65 61 76 65 73 20   a value leaves 
1b30: 69 74 73 20 6f 72 69 67 69 6e 61 6c 20 73 63 6f  its original sco
1b40: 70 65 29 2e 20 41 74 20 6f 6e 65 20 70 6f 69 6e  pe). At one poin
1b50: 74 20 68 61 73 68 74 61 62 6c 65 73 20 77 65 72  t hashtables wer
1b60: 65 20 75 73 65 64 20 66 6f 72 20 70 72 6f 70 65  e used for prope
1b70: 72 74 79 20 73 74 6f 72 61 67 65 20 28 77 69 74  rty storage (wit
1b80: 68 20 4f 28 31 29 20 73 65 61 72 63 68 20 73 70  h O(1) search sp
1b90: 65 65 64 29 2c 20 62 75 74 20 74 68 65 20 6d 65  eed), but the me
1ba0: 6d 6f 72 79 20 63 6f 73 74 20 77 61 73 20 64 65  mory cost was de
1bb0: 65 6d 65 64 20 74 6f 6f 20 68 69 67 68 2e 0d 0a  emed too high...
1bc0: 20 20 2a 20 48 61 73 68 20 54 61 62 6c 65 73 20    * Hash Tables 
1bd0: 6f 66 66 65 72 20 66 61 73 74 65 72 20 70 72 6f  offer faster pro
1be0: 70 65 72 74 79 20 73 74 6f 72 61 67 65 20 61 6e  perty storage an
1bf0: 64 20 72 65 74 72 69 65 76 61 6c 2c 20 62 75 74  d retrieval, but
1c00: 20 28 6e 6f 72 6d 61 6c 6c 79 29 20 63 6f 73 74   (normally) cost
1c10: 20 6d 6f 72 65 20 6d 65 6d 6f 72 79 20 74 68 61   more memory tha
1c20: 6e 20 4f 62 6a 65 63 74 73 20 28 74 68 6f 75 67  n Objects (thoug
1c30: 68 20 72 65 63 79 63 6c 69 6e 67 20 69 6d 70 72  h recycling impr
1c40: 6f 76 65 6d 65 6e 74 73 20 69 6e 20 6c 61 74 65  ovements in late
1c50: 20 32 30 31 34 20 72 65 64 75 63 65 64 20 74 68   2014 reduced th
1c60: 61 74 20 67 61 70 20 63 6f 6e 73 69 64 65 72 61  at gap considera
1c70: 62 6c 79 29 2e 0d 0a 20 20 20 2a 20 20 22 4e 61  bly)...   *  "Na
1c80: 74 69 76 65 73 22 20 61 72 65 20 63 6c 69 65 6e  tives" are clien
1c90: 74 2d 73 70 65 63 69 66 69 65 64 20 74 79 70 65  t-specified type
1ca0: 73 20 77 72 61 70 70 65 64 20 62 65 68 69 6e 64  s wrapped behind
1cb0: 20 61 20 63 77 61 6c 20 76 61 6c 75 65 20 68 61   a cwal value ha
1cc0: 6e 64 6c 65 2c 20 61 6c 6c 6f 77 69 6e 67 20 63  ndle, allowing c
1cd0: 6c 69 65 6e 74 73 20 74 6f 20 69 6e 74 65 67 72  lients to integr
1ce0: 61 74 65 20 74 68 65 69 72 20 6f 77 6e 20 74 79  ate their own ty
1cf0: 70 65 73 20 76 69 61 20 63 77 61 6c 27 73 20 76  pes via cwal's v
1d00: 61 6c 75 65 2f 73 63 6f 70 69 6e 67 2f 6c 69 66  alue/scoping/lif
1d10: 65 74 69 6d 65 20 6d 65 63 68 61 6e 69 73 6d 73  etime mechanisms
1d20: 2c 20 69 6e 63 6c 75 64 69 6e 67 20 61 20 66 69  , including a fi
1d30: 6e 61 6c 69 7a 65 72 20 6d 65 74 68 6f 64 20 74  nalizer method t
1d40: 6f 20 63 6c 65 61 6e 20 75 70 20 74 68 65 20 76  o clean up the v
1d50: 61 6c 75 65 20 77 68 65 6e 20 74 68 65 20 65 6e  alue when the en
1d60: 67 69 6e 65 20 69 73 20 64 6f 6e 65 20 77 69 74  gine is done wit
1d70: 68 20 69 74 2e 20 4e 61 74 69 76 65 73 20 74 72  h it. Natives tr
1d80: 61 6e 73 70 61 72 65 6e 74 6c 79 20 74 61 6b 65  ansparently take
1d90: 20 70 61 72 74 20 69 6e 20 72 65 66 65 72 65 6e   part in referen
1da0: 63 65 20 63 6f 75 6e 74 69 6e 67 20 61 6e 64 20  ce counting and 
1db0: 76 69 72 74 75 61 6c 20 65 78 74 65 6e 64 20 74  virtual extend t
1dc0: 68 65 20 4f 62 6a 65 63 74 20 74 79 70 65 2c 20  he Object type, 
1dd0: 73 6f 20 74 68 65 79 20 63 61 6e 20 68 6f 6c 64  so they can hold
1de0: 20 6d 65 6d 62 65 72 20 70 72 6f 70 65 72 74 69   member properti
1df0: 65 73 20 28 61 6e 64 20 74 68 75 73 20 70 61 72  es (and thus par
1e00: 74 69 63 69 70 61 74 65 20 69 6e 20 67 72 61 70  ticipate in grap
1e10: 68 73 29 2e 0d 0a 0d 0a 3c 6e 6f 77 69 6b 69 3e  hs).....<nowiki>
1e20: 3c 70 72 65 3e 0d 0a 2f 2f 20 42 65 20 73 75 72  <pre>..// Be sur
1e30: 65 20 74 6f 20 72 65 61 64 20 74 68 65 20 41 50  e to read the AP
1e40: 49 73 20 74 6f 20 75 6e 64 65 72 73 74 61 6e 64  Is to understand
1e50: 20 77 68 69 63 68 20 63 6f 6e 76 65 72 73 69 6f   which conversio
1e60: 6e 73 20 61 72 65 20 6c 65 67 61 6c 0d 0a 2f 2f  ns are legal..//
1e70: 20 61 6e 64 20 77 68 69 63 68 20 61 72 65 20 6e   and which are n
1e80: 6f 74 21 0d 0a 63 77 61 6c 5f 69 6e 74 20 74 20  ot!..cwal_int t 
1e90: 69 20 3d 20 63 77 61 6c 5f 76 61 6c 75 65 5f 67  i = cwal_value_g
1ea0: 65 74 5f 69 6e 74 65 67 65 72 28 76 29 3b 0d 0a  et_integer(v);..
1eb0: 63 77 61 6c 5f 64 6f 75 62 6c 65 5f 74 20 64 20  cwal_double_t d 
1ec0: 3d 20 63 77 61 6c 5f 76 61 6c 75 65 5f 67 65 74  = cwal_value_get
1ed0: 5f 64 6f 75 62 6c 65 28 76 29 3b 0d 0a 63 77 61  _double(v);..cwa
1ee0: 6c 5f 73 74 72 69 6e 67 20 2a 20 73 74 72 20 3d  l_string * str =
1ef0: 20 63 77 61 6c 5f 76 61 6c 75 65 5f 67 65 74 5f   cwal_value_get_
1f00: 73 74 72 69 6e 67 28 76 29 3b 0d 0a 63 68 61 72  string(v);..char
1f10: 20 63 6f 6e 73 74 20 2a 20 63 73 74 72 20 3d 20   const * cstr = 
1f20: 63 77 61 6c 5f 73 74 72 69 6e 67 5f 63 73 74 72  cwal_string_cstr
1f30: 28 73 74 72 29 3b 0d 0a 63 77 61 6c 5f 73 69 7a  (str);..cwal_siz
1f40: 65 5f 74 20 73 6c 65 6e 20 3d 20 63 77 61 6c 5f  e_t slen = cwal_
1f50: 73 74 72 69 6e 67 5f 6c 65 6e 67 74 68 5f 62 79  string_length_by
1f60: 74 65 73 28 73 74 72 29 3b 0d 0a 0d 0a 69 6e 74  tes(str);....int
1f70: 20 72 63 3b 0d 0a 0d 0a 72 63 20 3d 20 63 77 61   rc;....rc = cwa
1f80: 6c 5f 6f 62 6a 65 63 74 5f 73 65 74 28 65 2c 20  l_object_set(e, 
1f90: 6f 62 6a 2c 20 22 66 6f 6f 22 2c 20 33 2c 20 73  obj, "foo", 3, s
1fa0: 6f 6d 65 56 61 6c 75 65 20 29 3b 20 2f 2f 33 3d  omeValue ); //3=
1fb0: 3d 73 74 72 6c 65 6e 28 22 66 6f 6f 22 29 0d 0a  =strlen("foo")..
1fc0: 61 73 73 65 72 74 28 30 3d 3d 72 63 29 3b 0d 0a  assert(0==rc);..
1fd0: 72 63 20 3d 20 63 77 61 6c 5f 6f 62 6a 65 63 74  rc = cwal_object
1fe0: 5f 73 65 74 5f 73 28 65 2c 20 6f 62 6a 2c 20 73  _set_s(e, obj, s
1ff0: 74 72 2c 20 73 6f 6d 65 56 61 6c 75 65 20 29 3b  tr, someValue );
2000: 0d 0a 61 73 73 65 72 74 28 30 3d 3d 72 63 29 3b  ..assert(0==rc);
2010: 0d 0a 72 63 20 3d 20 63 77 61 6c 5f 61 72 72 61  ..rc = cwal_arra
2020: 79 5f 73 65 74 28 20 65 2c 20 61 72 72 61 79 2c  y_set( e, array,
2030: 20 73 6f 6d 65 56 61 6c 75 65 20 29 3b 0d 0a 61   someValue );..a
2040: 73 73 65 72 74 28 30 3d 3d 72 63 29 3b 0d 0a 2e  ssert(0==rc);...
2050: 2e 2e 0d 0a 3c 2f 70 72 65 3e 3c 2f 6e 6f 77 69  ....</pre></nowi
2060: 6b 69 3e 0d 0a 0d 0a 54 68 65 20 63 6f 6e 74 61  ki>....The conta
2070: 69 6e 65 72 20 41 50 49 73 20 61 72 65 20 6d 69  iner APIs are mi
2080: 73 73 69 6e 67 20 61 20 67 6f 6f 64 20 64 65 61  ssing a good dea
2090: 6c 20 6f 66 20 66 75 6e 63 74 69 6f 6e 61 6c 69  l of functionali
20a0: 74 79 20 62 65 63 61 75 73 65 20 74 68 65 79 20  ty because they 
20b0: 64 65 72 69 76 65 20 66 72 6f 6d 20 61 20 4a 53  derive from a JS
20c0: 4f 4e 20 41 50 49 20 77 68 69 63 68 20 64 69 64  ON API which did
20d0: 6e 27 74 20 6e 65 65 64 20 61 20 66 75 6c 6c 20  n't need a full 
20e0: 73 65 74 20 6f 66 20 75 74 69 6c 69 74 79 20 41  set of utility A
20f0: 50 49 73 2e 20 54 68 65 79 20 77 69 6c 6c 20 62  PIs. They will b
2100: 65 20 66 6c 65 73 68 65 64 20 6f 75 74 20 61 73  e fleshed out as
2110: 20 6e 65 65 64 65 64 2e 20 43 6f 6e 74 61 69 6e   needed. Contain
2120: 65 72 73 20 68 61 76 65 20 74 6f 20 74 61 6b 65  ers have to take
2130: 20 63 61 72 65 20 74 6f 20 6b 65 65 70 20 74 68   care to keep th
2140: 65 20 73 63 6f 70 65 2d 74 72 61 63 6b 69 6e 67  e scope-tracking
2150: 20 6d 65 63 68 61 6e 69 73 6d 20 6f 6e 20 74 72   mechanism on tr
2160: 61 63 6b 20 28 70 72 69 6d 61 72 69 6c 79 20 28  ack (primarily (
2170: 70 6f 73 73 69 62 6c 79 20 6f 6e 6c 79 29 20 66  possibly only) f
2180: 6f 72 20 74 68 65 20 73 61 6b 65 20 6f 66 20 63  or the sake of c
2190: 79 63 6c 65 73 29 2c 20 6d 61 6b 69 6e 67 20 74  ycles), making t
21a0: 68 65 6d 20 73 6c 69 67 68 74 6c 79 20 6d 6f 72  hem slightly mor
21b0: 65 20 74 65 64 69 6f 75 73 20 74 6f 20 69 6d 70  e tedious to imp
21c0: 6c 65 6d 65 6e 74 20 74 68 61 6e 20 74 68 65 79  lement than they
21d0: 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65   would otherwise
21e0: 20 62 65 20 28 62 75 74 20 6e 6f 74 20 6f 76 65   be (but not ove
21f0: 72 6c 79 2d 73 6f 29 2e 0d 0a 0d 0a 3c 68 32 3e  rly-so).....<h2>
2200: 54 72 69 76 69 61 3a 20 48 6f 77 20 44 65 73 74  Trivia: How Dest
2210: 72 75 63 74 69 6f 6e 20 57 6f 72 6b 73 3c 2f 68  ruction Works</h
2220: 32 3e 0d 0a 0d 0a 44 65 73 74 72 75 63 74 69 6f  2>....Destructio
2230: 6e 20 6f 66 20 76 61 6c 75 65 73 20 68 61 70 70  n of values happ
2240: 65 6e 73 20 61 74 20 6f 6e 6c 79 20 6f 6e 65 20  ens at only one 
2250: 74 69 6d 65 3a 20 77 68 65 6e 20 69 74 73 20 72  time: when its r
2260: 65 66 65 72 65 6e 63 65 20 63 6f 75 6e 74 20 64  eference count d
2270: 72 6f 70 73 20 74 6f 20 30 2e 20 54 68 69 73 20  rops to 0. This 
2280: 6e 6f 72 6d 61 6c 6c 79 20 68 61 70 70 65 6e 73  normally happens
2290: 20 77 68 65 6e 20 61 20 73 63 6f 70 65 20 69 73   when a scope is
22a0: 20 70 6f 70 70 65 64 20 61 6e 64 20 69 74 20 63   popped and it c
22b0: 6c 65 61 6e 73 20 75 70 20 61 6e 79 74 68 69 6e  leans up anythin
22c0: 67 20 69 74 20 68 6f 6c 64 73 20 61 20 72 65 66  g it holds a ref
22d0: 65 72 65 6e 63 65 20 74 6f 2c 20 6e 6f 72 6d 61  erence to, norma
22e0: 6c 6c 79 20 69 6e 20 72 65 76 65 72 73 65 20 6f  lly in reverse o
22f0: 66 20 74 68 65 20 6f 72 64 65 72 20 69 74 20 61  f the order it a
2300: 63 71 75 69 72 65 64 20 74 68 65 20 72 65 66 65  cquired the refe
2310: 72 65 6e 63 65 73 20 28 75 6e 6c 65 73 73 20 73  rences (unless s
2320: 63 6f 70 65 2d 6d 69 67 72 61 74 69 6f 6e 20 6f  cope-migration o
2330: 72 20 72 65 66 65 72 65 6e 63 65 20 6d 61 6e 61  r reference mana
2340: 67 65 6d 65 6e 74 20 63 68 61 6e 67 65 73 20 74  gement changes t
2350: 68 69 73 29 2e 20 54 72 79 69 6e 67 20 74 6f 20  his). Trying to 
2360: 63 6c 65 61 6e 20 75 70 20 61 20 73 65 74 20 6f  clean up a set o
2370: 66 20 63 79 63 6c 69 63 20 76 61 6c 75 65 73 20  f cyclic values 
2380: 66 72 6f 6d 20 63 6c 69 65 6e 74 20 63 6f 64 65  from client code
2390: 20 63 61 6e 20 62 65 20 6d 65 73 73 79 2c 20 61   can be messy, a
23a0: 6e 64 20 74 68 69 73 20 69 73 20 62 65 73 74 20  nd this is best 
23b0: 6c 65 66 74 20 74 6f 20 61 20 70 61 72 65 6e 74  left to a parent
23c0: 20 73 63 6f 70 65 2e 20 49 74 20 69 73 20 63 61   scope. It is ca
23d0: 70 61 62 6c 65 20 6f 66 20 77 65 65 64 69 6e 67  pable of weeding
23e0: 20 6f 75 74 20 63 79 63 6c 65 73 20 64 75 72 69   out cycles duri
23f0: 6e 67 20 64 65 73 74 72 75 63 74 69 6f 6e 2e 20  ng destruction. 
2400: 3c 65 6d 3e 48 6f 77 3c 2f 65 6d 3e 20 61 20 69  <em>How</em> a i
2410: 74 20 63 6c 65 61 6e 73 20 75 70 20 69 73 20 69  t cleans up is i
2420: 6d 70 6f 72 74 61 6e 74 20 74 6f 20 75 6e 64 65  mportant to unde
2430: 72 73 74 61 6e 64 20 69 6e 20 6f 72 64 65 72 20  rstand in order 
2440: 74 6f 20 61 76 6f 69 64 20 73 6f 6d 65 20 6f 72  to avoid some or
2450: 70 68 61 6e 69 6e 67 2d 20 61 6e 64 20 6d 69 73  phaning- and mis
2460: 2d 64 65 73 74 72 75 63 74 69 6f 6e 20 70 69 74  -destruction pit
2470: 66 61 6c 6c 73 20 74 68 65 20 41 50 49 20 63 75  falls the API cu
2480: 72 72 65 6e 74 6c 79 20 61 6c 6c 6f 77 73 20 66  rrently allows f
2490: 6f 72 20 28 62 75 74 20 61 69 6d 73 20 74 6f 20  or (but aims to 
24a0: 6d 61 6b 65 20 64 69 66 66 69 63 75 6c 74 20 74  make difficult t
24b0: 6f 20 64 6f 29 2e 0d 0a 0d 0a 54 68 65 20 73 63  o do).....The sc
24c0: 6f 70 65 20 63 6c 65 61 6e 75 70 20 61 6c 67 6f  ope cleanup algo
24d0: 72 69 74 68 6d 20 3c 65 6d 3e 62 61 73 69 63 61  rithm <em>basica
24e0: 6c 6c 79 3c 2f 65 6d 3e 20 6c 6f 6f 6b 73 20 6c  lly</em> looks l
24f0: 69 6b 65 20 74 68 69 73 20 65 78 74 72 65 6d 65  ike this extreme
2500: 6c 79 20 6f 76 65 72 2d 73 69 6d 70 6c 69 66 69  ly over-simplifi
2510: 65 64 20 72 65 6e 64 69 74 69 6f 6e 3a 0d 0a 0d  ed rendition:...
2520: 0a 3c 6e 6f 77 69 6b 69 3e 3c 70 72 65 3e 0d 0a  .<nowiki><pre>..
2530: 2f 2f 20 76 61 6c 75 65 73 20 3d 3d 20 61 20 6c  // values == a l
2540: 69 73 74 20 6f 66 20 76 61 6c 75 65 20 68 61 6e  ist of value han
2550: 64 6c 65 73 0d 0a 77 68 69 6c 65 28 20 76 61 6c  dles..while( val
2560: 75 65 73 2e 6c 65 6e 67 74 68 20 3e 20 30 20 20  ues.length > 0  
2570: 29 20 7b 0d 0a 20 20 66 6f 72 65 61 63 68 28 76  ) {..  foreach(v
2580: 61 6c 75 65 73 20 61 73 20 76 20 5b 69 6e 20 72  alues as v [in r
2590: 65 76 65 72 73 65 20 6f 72 64 65 72 5d 29 20 75  everse order]) u
25a0: 6e 72 65 66 28 76 29 3b 0d 0a 7d 0d 0a 3c 2f 70  nref(v);..}..</p
25b0: 72 65 3e 3c 2f 6e 6f 77 69 6b 69 3e 0d 0a 0d 0a  re></nowiki>....
25c0: 4e 6f 74 65 20 74 68 65 20 6f 75 74 65 72 20 22  Note the outer "
25d0: 77 68 69 6c 65 22 20 6c 6f 6f 70 2e 20 57 68 65  while" loop. Whe
25e0: 6e 20 61 20 76 61 6c 75 65 27 73 20 72 65 66 63  n a value's refc
25f0: 6f 75 6e 74 20 64 72 6f 70 73 20 74 6f 20 30 2c  ount drops to 0,
2600: 20 70 61 72 74 20 6f 66 20 74 68 65 20 63 6c 65   part of the cle
2610: 61 6e 75 70 20 70 72 6f 63 65 73 73 20 69 73 20  anup process is 
2620: 74 6f 20 72 65 6d 6f 76 65 20 69 74 20 66 72 6f  to remove it fro
2630: 6d 20 69 74 73 20 63 6f 6e 74 72 6f 6c 6c 69 6e  m its controllin
2640: 67 20 73 63 6f 70 65 20 28 77 68 69 63 68 20 74  g scope (which t
2650: 68 69 73 20 6c 6f 6f 70 20 61 73 73 65 72 74 73  his loop asserts
2660: 20 69 73 20 74 68 65 20 63 61 73 65 29 2e 20 54   is the case). T
2670: 68 61 74 20 63 68 61 6e 67 65 73 20 74 68 65 20  hat changes the 
2680: 6c 69 73 74 20 77 65 20 61 72 65 20 6c 6f 6f 70  list we are loop
2690: 69 6e 67 20 6f 76 65 72 20 28 74 68 65 20 61 6c  ing over (the al
26a0: 67 6f 20 61 63 63 6f 75 6e 74 73 20 66 6f 72 20  go accounts for 
26b0: 74 68 61 74 2c 20 6f 66 20 63 6f 75 72 73 65 29  that, of course)
26c0: 2e 20 57 68 65 6e 20 77 65 20 61 72 65 20 64 6f  . When we are do
26d0: 6e 65 20 75 6e 72 65 66 27 69 6e 67 20 65 61 63  ne unref'ing eac
26e0: 68 20 65 6e 74 72 79 20 31 20 74 69 6d 65 2c 20  h entry 1 time, 
26f0: 77 65 20 63 68 65 63 6b 20 74 68 65 20 73 69 7a  we check the siz
2700: 65 20 6f 66 20 74 68 65 20 6c 69 73 74 2e 20 49  e of the list. I
2710: 66 20 69 74 20 69 73 20 6e 6f 74 20 65 6d 70 74  f it is not empt
2720: 79 2c 20 77 65 20 64 6f 20 69 74 20 61 67 61 69  y, we do it agai
2730: 6e 2e 20 41 6e 64 20 61 67 61 69 6e 2c 20 61 6e  n. And again, an
2740: 64 20 61 67 61 69 6e 2e 2e 2e 20 54 68 69 73 20  d again... This 
2750: 70 72 6f 63 65 73 73 20 77 65 65 64 73 20 6f 75  process weeds ou
2760: 74 20 61 6e 79 20 63 79 63 6c 65 73 20 6f 6e 65  t any cycles one
2770: 20 73 74 65 70 20 61 74 20 61 20 74 69 6d 65 2e   step at a time.
2780: 20 48 6f 77 65 76 65 72 2c 20 69 74 20 61 6c 73   However, it als
2790: 6f 20 6d 65 61 6e 73 20 74 68 61 74 20 69 66 20  o means that if 
27a0: 61 20 63 6c 69 65 6e 74 20 72 65 66 65 72 65 6e  a client referen
27b0: 63 65 73 20 61 20 76 61 6c 75 65 20 6d 75 6c 74  ces a value mult
27c0: 69 70 6c 65 20 74 69 6d 65 73 20 62 75 74 20 64  iple times but d
27d0: 6f 65 73 20 6e 6f 74 20 75 6e 72 65 66 20 61 6e  oes not unref an
27e0: 20 65 71 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66   equal number of
27f0: 20 74 69 6d 65 73 2c 20 69 74 73 20 63 6f 6e 74   times, its cont
2800: 72 6f 6c 6c 69 6e 67 20 73 63 6f 70 65 20 77 69  rolling scope wi
2810: 6c 6c 20 61 63 74 75 61 6c 6c 79 20 6c 6f 6f 70  ll actually loop
2820: 20 6f 76 65 72 20 61 6c 6c 20 72 65 66 65 72 65   over all refere
2830: 6e 63 65 20 63 6f 75 6e 74 73 20 28 69 6e 63 6c  nce counts (incl
2840: 75 64 69 6e 67 20 74 68 65 20 6f 6e 65 73 20 66  uding the ones f
2850: 72 6f 6d 20 74 68 65 20 63 6c 69 65 6e 74 29 2c  rom the client),
2860: 20 61 73 20 6d 61 6e 79 20 74 69 6d 65 73 20 61   as many times a
2870: 73 20 69 74 20 74 61 6b 65 73 20 74 6f 20 63 6c  s it takes to cl
2880: 65 61 6e 20 69 74 20 75 70 2e 20 54 68 69 73 20  ean it up. This 
2890: 69 73 20 6e 6f 74 20 3c 65 6d 3e 61 63 74 75 61  is not <em>actua
28a0: 6c 6c 79 3c 2f 65 6d 3e 20 61 20 66 65 61 74 75  lly</em> a featu
28b0: 72 65 2c 20 61 6e 64 20 69 74 20 6d 69 67 68 74  re, and it might
28c0: 20 6d 61 6b 65 20 69 6d 70 6c 65 6d 65 6e 74 69   make implementi
28d0: 6e 67 20 63 6c 6f 73 75 72 65 73 20 6d 6f 72 65  ng closures more
28e0: 20 64 69 66 66 69 63 75 6c 74 20 6f 72 20 69 6d   difficult or im
28f0: 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 69 74  possible, but it
2900: 20 74 75 72 6e 73 20 6f 75 74 20 74 6f 20 77 6f   turns out to wo
2910: 72 6b 20 72 61 74 68 65 72 20 77 65 6c 6c 20 77  rk rather well w
2920: 69 74 68 20 74 68 65 20 77 68 6f 6c 65 20 73 74  ith the whole st
2930: 72 69 63 74 2d 73 63 6f 70 69 6e 67 20 6d 6f 64  rict-scoping mod
2940: 65 6c 20 61 73 20 6c 6f 6e 67 20 61 73 20 63 6c  el as long as cl
2950: 69 65 6e 74 73 20 75 6e 64 65 72 73 74 61 6e 64  ients understand
2960: 20 61 6e 64 20 61 70 70 6c 79 20 73 6f 6d 65 20   and apply some 
2970: 72 75 6c 65 73 20 69 66 20 74 68 65 79 20 77 61  rules if they wa
2980: 6e 74 20 74 6f 20 74 61 6b 65 20 72 65 66 65 72  nt to take refer
2990: 65 6e 63 65 2f 6c 69 66 65 74 69 6d 65 20 6d 61  ence/lifetime ma
29a0: 6e 61 67 65 6d 65 6e 74 20 69 6e 74 6f 20 74 68  nagement into th
29b0: 65 69 72 20 6f 77 6e 20 68 61 6e 64 73 20 28 61  eir own hands (a
29c0: 73 20 6f 70 70 6f 73 65 64 20 74 6f 20 6c 65 61  s opposed to lea
29d0: 76 69 6e 67 20 69 74 20 74 6f 20 61 20 73 63 6f  ving it to a sco
29e0: 70 65 29 2e 20 54 68 65 20 72 75 6c 65 73 20 61  pe). The rules a
29f0: 72 65 20 6e 6f 74 20 79 65 74 20 63 6f 6d 70 6c  re not yet compl
2a00: 65 74 65 6c 79 20 64 6f 63 75 6d 65 6e 74 65 64  etely documented
2a10: 20 62 65 63 61 75 73 65 20 74 68 65 20 41 50 49   because the API
2a20: 73 20 66 6f 72 20 74 68 65 73 65 20 70 61 72 74  s for these part
2a30: 73 20 61 72 65 20 73 74 69 6c 6c 20 75 6e 64 65  s are still unde
2a40: 72 20 63 6f 6e 73 69 64 65 72 61 74 69 6f 6e 2e  r consideration.
2a50: 20 53 74 61 79 20 74 75 6e 65 64 2e 2e 2e 0d 0a   Stay tuned.....
2a60: 0d 0a 0d 0a 63 77 61 6c 27 73 20 73 6c 6f 77 65  ....cwal's slowe
2a70: 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 69 73 20  st component is 
2a80: 74 68 65 20 77 69 72 69 6e 67 20 72 65 71 75 69  the wiring requi
2a90: 72 65 64 20 66 6f 72 20 68 61 6e 64 6c 69 6e 67  red for handling
2aa0: 20 70 72 6f 70 65 72 20 63 6c 65 61 6e 75 70 20   proper cleanup 
2ab0: 69 6e 20 74 68 65 20 66 61 63 65 20 6f 66 20 63  in the face of c
2ac0: 79 63 6c 65 73 2c 20 61 6e 64 20 74 68 69 73 20  ycles, and this 
2ad0: 77 69 72 69 6e 67 20 61 66 66 65 63 74 73 20 6f  wiring affects o
2ae0: 74 68 65 72 20 70 6c 61 63 65 73 20 74 68 61 6e  ther places than
2af0: 20 6a 75 73 74 20 74 68 65 20 63 6c 65 61 6e 75   just the cleanu
2b00: 70 20 63 6f 64 65 2e 20 28 41 63 74 75 61 6c 6c  p code. (Actuall
2b10: 79 3a 20 76 61 6c 67 72 69 6e 64 20 73 61 79 73  y: valgrind says
2b20: 20 74 68 61 74 20 3c 74 74 3e 6d 61 6c 6c 6f 63   that <tt>malloc
2b30: 28 29 3c 2f 74 74 3e 20 74 61 6b 65 73 20 66 61  ()</tt> takes fa
2b40: 72 20 6d 6f 72 65 20 74 69 6d 65 20 74 68 61 6e  r more time than
2b50: 20 74 68 65 20 63 6c 65 61 6e 75 70 21 29 20 43   the cleanup!) C
2b60: 6c 65 61 6e 75 70 20 69 73 2c 20 63 6f 6d 70 75  leanup is, compu
2b70: 74 61 74 69 6f 6e 61 6c 6c 79 20 73 70 65 61 6b  tationally speak
2b80: 69 6e 67 2c 20 73 6f 6d 65 77 68 61 74 20 73 6c  ing, somewhat sl
2b90: 6f 77 20 62 65 63 61 75 73 65 20 69 74 20 68 61  ow because it ha
2ba0: 73 20 74 6f 20 74 72 61 76 65 72 73 65 20 63 79  s to traverse cy
2bb0: 63 6c 69 63 20 67 72 61 70 68 73 20 6f 6e 65 20  clic graphs one 
2bc0: 74 69 6d 65 20 70 65 72 20 63 79 63 6c 65 2c 20  time per cycle, 
2bd0: 72 65 64 75 63 69 6e 67 20 74 68 65 20 72 65 66  reducing the ref
2be0: 63 6f 75 6e 74 20 6f 66 20 65 61 63 68 20 69 74  count of each it
2bf0: 65 6d 20 61 6c 6f 6e 67 20 74 68 65 20 77 61 79  em along the way
2c00: 20 6f 6e 63 65 20 70 65 72 20 74 72 61 76 65 72   once per traver
2c10: 73 61 6c 2e 20 28 53 69 64 65 2d 6e 6f 74 65 3a  sal. (Side-note:
2c20: 20 69 74 20 64 6f 65 73 6e 27 74 20 61 63 74 75   it doesn't actu
2c30: 61 6c 6c 79 20 6b 6e 6f 77 20 69 66 20 74 68 65  ally know if the
2c40: 72 65 20 61 72 65 20 63 79 63 6c 65 73 20 62 75  re are cycles bu
2c50: 74 20 73 69 64 65 2d 65 66 66 65 63 74 73 20 74  t side-effects t
2c60: 68 65 20 6f 77 6e 65 72 73 68 69 70 2f 72 65 66  he ownership/ref
2c70: 65 72 65 6e 63 65 20 63 6f 75 6e 74 69 6e 67 20  erence counting 
2c80: 72 75 6c 65 73 20 61 6c 6c 6f 77 20 69 74 20 64  rules allow it d
2c90: 65 64 75 63 65 20 74 68 69 73 20 61 73 20 69 74  educe this as it
2ca0: 20 67 6f 65 73 2e 29 20 46 6f 72 20 6e 6f 6e 2d   goes.) For non-
2cb0: 67 72 61 70 68 73 20 74 68 69 73 20 69 73 20 74  graphs this is t
2cc0: 68 65 20 73 61 6d 65 20 63 6f 73 74 20 61 73 20  he same cost as 
2cd0: 6e 6f 72 6d 61 6c 20 63 6c 65 61 6e 75 70 20 28  normal cleanup (
2ce0: 65 66 66 65 63 74 69 76 65 6c 79 20 4f 28 4e 29  effectively O(N)
2cf0: 2c 20 4e 3d 74 6f 74 61 6c 20 6e 75 6d 62 65 72  , N=total number
2d00: 20 6f 66 20 76 61 6c 75 65 73 29 2c 20 62 75 74   of values), but
2d10: 20 66 6f 72 20 63 79 63 6c 65 73 20 69 74 20 74   for cycles it t
2d20: 75 72 6e 73 20 69 6e 74 6f 20 73 6f 6d 65 20 66  urns into some f
2d30: 75 6e 63 74 69 6f 6e 20 6f 66 20 4f 28 4e 2a 58  unction of O(N*X
2d40: 29 2c 20 77 68 65 72 65 20 58 20 69 73 20 61 20  ), where X is a 
2d50: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
2d60: 6e 75 6d 62 65 72 20 6f 66 20 63 79 63 6c 65 73  number of cycles
2d70: 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
2d80: 63 6c 65 61 6e 75 70 2d 72 75 6e 20 61 6e 64 20  cleanup-run and 
2d90: 4e 20 6d 69 67 68 74 20 6f 72 20 6d 69 67 68 74  N might or might
2da0: 20 64 65 63 72 65 6d 65 6e 74 20 62 79 20 73 6f   decrement by so
2db0: 6d 65 20 6e 75 6d 62 65 72 20 6c 65 73 73 20 74  me number less t
2dc0: 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
2dd0: 4e 20 66 6f 72 20 65 61 63 68 20 69 74 65 72 61  N for each itera
2de0: 74 69 6f 6e 20 6f 76 65 72 20 74 68 65 20 63 6c  tion over the cl
2df0: 65 61 6e 2d 75 70 20 6c 69 73 74 20 28 64 65 70  ean-up list (dep
2e00: 65 6e 64 69 6e 67 20 6f 6e 20 77 68 65 74 68 65  ending on whethe
2e10: 72 20 61 20 67 69 76 65 6e 20 69 74 65 72 61 74  r a given iterat
2e20: 69 6f 6e 20 62 72 65 61 6b 73 20 61 6e 79 20 63  ion breaks any c
2e30: 79 63 6c 65 73 20 6f 72 20 72 65 6d 6f 76 65 73  ycles or removes
2e40: 20 61 6e 79 20 6e 6f 6e 2d 63 79 63 6c 69 63 20   any non-cyclic 
2e50: 69 74 65 6d 73 29 2e 20 4d 79 20 62 72 61 69 6e  items). My brain
2e60: 20 69 73 6e 27 74 20 62 69 67 20 65 6e 6f 75 67   isn't big enoug
2e70: 68 20 74 6f 20 64 6f 20 74 68 65 20 6d 61 74 68  h to do the math
2e80: 2e 20 54 68 69 73 20 69 6e 66 72 61 73 74 72 75  . This infrastru
2e90: 63 74 75 72 65 20 61 6c 73 6f 20 72 65 71 75 69  cture also requi
2ea0: 72 65 73 20 74 72 61 63 6b 69 6e 67 20 6f 66 20  res tracking of 
2eb0: 61 20 70 61 72 65 6e 74 20 73 63 6f 70 65 20 66  a parent scope f
2ec0: 6f 72 20 65 61 63 68 20 76 61 6c 75 65 2c 20 61  or each value, a
2ed0: 6e 64 20 74 68 61 74 20 69 6e 66 72 61 73 74 72  nd that infrastr
2ee0: 75 63 74 75 72 65 20 63 61 6e 20 69 6d 70 61 63  ucture can impac
2ef0: 74 20 74 68 65 20 73 70 65 65 64 20 6f 66 20 6f  t the speed of o
2f00: 70 65 72 61 74 69 6f 6e 73 20 77 68 69 63 68 20  perations which 
2f10: 6d 6f 76 65 20 61 20 76 61 6c 75 65 20 66 72 6f  move a value fro
2f20: 6d 20 6f 6e 65 20 73 63 6f 70 65 20 74 6f 20 61  m one scope to a
2f30: 6e 6f 74 68 65 72 20 28 62 65 63 61 75 73 65 20  nother (because 
2f40: 74 68 65 79 20 6d 69 67 68 74 20 68 61 76 65 20  they might have 
2f50: 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74 20 74  to ensure that t
2f60: 68 65 69 72 20 63 6f 6e 74 61 69 6e 65 64 20 63  heir contained c
2f70: 68 69 6c 64 72 65 6e 20 61 6c 73 6f 20 68 61 76  hildren also hav
2f80: 65 20 74 68 65 20 70 72 6f 70 65 72 20 73 63 6f  e the proper sco
2f90: 70 65 29 2e 0d 0a 0d 0a 48 69 73 74 6f 72 69 63  pe).....Historic
2fa0: 20 6e 6f 74 65 3a 20 63 77 61 6c 20 6f 72 69 67   note: cwal orig
2fb0: 69 6e 61 6c 6c 79 20 75 73 65 64 20 61 72 72 61  inally used arra
2fc0: 79 73 20 74 6f 20 6d 61 6e 61 67 65 20 6f 77 6e  ys to manage own
2fd0: 65 72 73 68 69 70 20 6c 69 73 74 73 2e 20 49 74  ership lists. It
2fe0: 20 77 61 73 20 65 61 73 79 20 74 6f 20 64 6f 20   was easy to do 
2ff0: 62 75 74 20 6c 65 64 20 74 6f 20 73 65 76 65 72  but led to sever
3000: 61 6c 20 63 6f 72 6e 65 72 20 63 61 73 65 73 20  al corner cases 
3010: 77 68 65 72 65 20 61 6e 20 4f 4f 4d 20 65 72 72  where an OOM err
3020: 6f 72 20 63 6f 75 6c 64 20 63 61 75 73 65 20 61  or could cause a
3030: 6e 20 6f 74 68 65 72 77 69 73 65 20 68 61 72 6d  n otherwise harm
3040: 6c 65 73 73 20 6f 70 65 72 61 74 69 6f 6e 20 74  less operation t
3050: 6f 20 6c 65 61 64 20 74 6f 20 75 6e 64 65 66 69  o lead to undefi
3060: 6e 65 64 20 6f 77 6e 65 72 73 68 69 70 20 6f 66  ned ownership of
3070: 20 61 20 76 61 6c 75 65 20 28 69 2e 65 2e 20 70   a value (i.e. p
3080: 6f 74 65 6e 74 69 61 6c 6c 79 20 61 20 6c 65 61  otentially a lea
3090: 6b 29 2e 20 54 68 65 73 65 20 61 72 72 61 79 73  k). These arrays
30a0: 20 69 6e 63 6c 75 64 65 64 20 74 68 65 20 6f 77   included the ow
30b0: 6e 65 72 73 68 69 70 20 6c 69 73 74 20 69 6e 20  nership list in 
30c0: 61 20 73 63 6f 70 65 2c 20 74 68 65 20 72 65 63  a scope, the rec
30d0: 79 63 6c 65 20 62 69 6e 2c 20 61 6e 64 20 74 68  ycle bin, and th
30e0: 65 20 64 65 66 65 72 72 65 64 20 47 43 20 71 75  e deferred GC qu
30f0: 65 75 65 2e 20 41 73 20 61 6e 20 65 78 70 65 72  eue. As an exper
3100: 69 6d 65 6e 74 20 69 20 74 75 72 6e 65 64 20 74  iment i turned t
3110: 68 65 20 56 61 6c 75 65 20 68 61 6e 64 6c 65 73  he Value handles
3120: 20 69 6e 74 6f 20 6c 69 6e 6b 65 64 20 6c 69 73   into linked lis
3130: 74 73 20 6f 66 20 56 61 6c 75 65 20 68 61 6e 64  ts of Value hand
3140: 6c 65 73 20 74 6f 20 73 70 65 65 64 20 75 70 20  les to speed up 
3150: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 73 74  the various list
3160: 2d 72 65 6c 61 74 65 64 20 6f 70 65 72 61 74 69  -related operati
3170: 6f 6e 73 20 28 66 72 6f 6d 20 77 6f 72 73 74 2d  ons (from worst-
3180: 63 61 73 65 20 4f 28 4e 29 20 74 6f 20 67 75 61  case O(N) to gua
3190: 72 61 6e 74 65 65 64 20 4f 28 31 29 20 66 6f 72  ranteed O(1) for
31a0: 20 77 68 61 74 20 77 65 20 64 6f 20 77 69 74 68   what we do with
31b0: 20 74 68 65 6d 29 2e 20 54 68 65 20 73 77 69 74   them). The swit
31c0: 63 68 20 74 6f 20 6c 69 6e 6b 65 64 20 6c 69 73  ch to linked lis
31d0: 74 73 20 63 6f 73 74 73 20 28 70 72 65 64 69 63  ts costs (predic
31e0: 74 61 62 6c 79 29 20 66 65 77 65 72 20 6f 76 65  tably) fewer ove
31f0: 72 61 6c 6c 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  rall allocations
3200: 2c 20 62 75 74 20 61 6c 73 6f 20 64 65 63 72 65  , but also decre
3210: 61 73 65 64 20 74 68 65 20 61 76 65 72 61 67 65  ased the average
3220: 20 56 61 6c 75 65 20 6d 65 6d 6f 72 79 20 63 6f   Value memory co
3230: 73 74 20 62 65 63 61 75 73 65 20 77 65 20 6c 6f  st because we lo
3240: 73 74 20 74 68 65 20 61 72 72 61 79 73 20 62 65  st the arrays be
3250: 69 6e 67 20 68 65 6c 64 20 65 6c 73 65 77 68 65  ing held elsewhe
3260: 72 65 20 28 77 68 69 63 68 20 77 65 72 65 20 68  re (which were h
3270: 6f 6c 64 69 6e 67 20 74 68 65 20 73 61 6d 65 20  olding the same 
3280: 64 61 74 61 20 69 6e 20 61 20 6d 6f 72 65 20 76  data in a more v
3290: 65 72 62 6f 73 65 20 66 6f 72 6d 29 2e 20 49 74  erbose form). It
32a0: 20 61 6c 73 6f 20 72 65 6d 6f 76 65 64 20 73 65   also removed se
32b0: 76 65 72 61 6c 20 70 6f 74 65 6e 74 69 61 6c 20  veral potential 
32c0: 65 72 72 6f 72 20 63 61 73 65 73 20 69 6e 20 4f  error cases in O
32d0: 4f 4d 20 63 6f 6e 64 69 74 69 6f 6e 73 20 66 72  OM conditions fr
32e0: 6f 6d 20 77 68 69 63 68 20 77 65 20 68 61 64 20  om which we had 
32f0: 6e 6f 20 72 65 63 6f 76 65 72 79 20 73 74 72 61  no recovery stra
3300: 74 65 67 79 2e 20 41 6e 64 20 69 74 20 74 75 72  tegy. And it tur
3310: 6e 73 20 6f 75 74 20 74 6f 20 62 65 20 65 61 73  ns out to be eas
3320: 69 65 72 20 74 6f 20 6d 61 6e 61 67 65 20 74 68  ier to manage th
3330: 65 20 76 61 6c 75 65 73 27 20 73 63 6f 70 65 2d  e values' scope-
3340: 6c 65 76 65 6c 20 6f 77 6e 65 72 73 68 69 70 20  level ownership 
3350: 74 68 69 73 20 77 61 79 2c 20 73 6f 20 74 68 61  this way, so tha
3360: 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 77 61 73  t transition was
3370: 20 61 6e 20 6f 76 65 72 61 6c 6c 20 77 69 6e 2d   an overall win-
3380: 77 69 6e 2e 0a 5a 20 35 39 37 30 65 62 62 65 63  win..Z 5970ebbec
3390: 35 37 64 37 33 37 63 37 64 32 35 37 37 65 39 37  57d737c7d2577e97
33a0: 32 32 61 65 64 61 64 0a                          22aedad.