libcwal  Hex Artifact Content

Artifact 49d2c638bea6edefca16fed7c6ad7a45ebc55293:

Wiki page [CwalBestPractices] by stephan 2016-01-14 08:34:05.
0000: 44 20 32 30 31 36 2d 30 31 2d 31 34 54 30 38 3a  D 2016-01-14T08:
0010: 33 34 3a 30 35 2e 30 37 30 0a 4c 20 43 77 61 6c  34:05.070.L Cwal
0020: 42 65 73 74 50 72 61 63 74 69 63 65 73 0a 55 20  BestPractices.U 
0030: 73 74 65 70 68 61 6e 0a 57 20 31 36 38 32 0a 3c  stephan.W 1682.<
0040: 68 31 3e 63 77 61 6c 20 42 65 73 74 20 50 72 61  h1>cwal Best Pra
0050: 63 74 69 63 65 73 3c 2f 68 31 3e 0d 0a 0d 0a 53  ctices</h1>....S
0060: 69 6e 63 65 20 69 74 73 20 69 6e 63 65 70 74 69  ince its incepti
0070: 6f 6e 2c 20 3c 65 6d 3e 6c 6f 74 73 3c 2f 65 6d  on, <em>lots</em
0080: 3e 20 68 61 73 20 68 61 70 70 65 6e 65 64 20 69  > has happened i
0090: 6e 20 63 77 61 6c 2e 20 49 74 73 20 41 50 49 20  n cwal. Its API 
00a0: 68 61 73 20 6d 75 74 61 74 65 64 2c 20 69 74 73  has mutated, its
00b0: 20 63 6f 6e 76 65 6e 74 69 6f 6e 73 0d 0a 63 68   conventions..ch
00c0: 61 6e 67 65 64 2c 20 61 6e 64 20 76 61 72 69 6f  anged, and vario
00d0: 75 73 20 62 65 73 74 2f 77 6f 72 73 74 20 70 72  us best/worst pr
00e0: 61 63 74 69 63 65 73 20 68 61 76 65 20 62 65 65  actices have bee
00f0: 6e 20 64 69 73 63 6f 76 65 72 65 64 2e 20 54 68  n discovered. Th
0100: 69 73 20 70 61 67 65 20 63 6f 76 65 72 73 20 61  is page covers a
0110: 20 62 69 74 20 6f 66 20 74 68 65 20 0d 0a 6c 61   bit of the ..la
0120: 74 74 65 72 3a 20 62 65 73 74 2f 77 6f 72 73 74  tter: best/worst
0130: 20 70 72 61 63 74 69 63 65 73 2e 0d 0a 0d 0a 3c   practices.....<
0140: 68 32 3e 42 65 73 74 20 50 72 61 63 74 69 63 65  h2>Best Practice
0150: 73 20 53 75 6d 6d 61 72 79 3c 2f 68 32 3e 0d 0a  s Summary</h2>..
0160: 0d 0a 49 6e 20 6e 6f 20 70 61 72 74 69 63 75 6c  ..In no particul
0170: 61 72 20 6f 72 64 65 72 2e 2e 2e 0d 0a 20 20 20  ar order.....   
0180: 0d 0a 20 20 20 2a 20 20 42 75 69 6c 64 20 63 77  ..   *  Build cw
0190: 61 6c 20 69 6e 20 64 65 62 75 67 20 6d 6f 64 65  al in debug mode
01a0: 2e 20 54 68 69 73 20 65 6e 61 62 6c 65 73 20 74  . This enables t
01b0: 6f 6e 73 20 6f 66 20 61 73 73 65 72 74 69 6f 6e  ons of assertion
01c0: 73 20 77 68 69 63 68 20 63 61 6e 20 63 61 74 63  s which can catc
01d0: 68 20 63 65 72 74 61 69 6e 20 6d 69 73 75 73 65  h certain misuse
01e0: 73 20 6c 6f 6e 67 0d 0a 20 20 20 62 65 66 6f 72  s long..   befor
01f0: 65 20 74 68 65 79 20 74 72 69 67 67 65 72 20 64  e they trigger d
0200: 6f 77 6e 73 74 72 65 61 6d 20 75 6e 64 65 66 69  ownstream undefi
0210: 6e 65 64 20 62 65 68 61 76 69 6f 75 72 2e 0d 0a  ned behaviour...
0220: 0d 0a 20 20 20 2a 20 20 41 6c 77 61 79 73 20 75  ..   *  Always u
0230: 73 65 20 3c 74 74 3e 63 77 61 6c 5f 76 61 6c 75  se <tt>cwal_valu
0240: 65 5f 72 65 66 28 29 3c 2f 74 74 3e 2e 20 57 68  e_ref()</tt>. Wh
0250: 69 6c 65 20 69 74 20 69 73 20 74 65 63 68 6e 69  ile it is techni
0260: 63 61 6c 6c 79 20 6c 65 67 61 6c 20 74 6f 20 6e  cally legal to n
0270: 6f 74 20 73 70 65 63 69 66 69 63 61 6c 6c 79 20  ot specifically 
0280: 61 63 71 75 69 72 65 0d 0a 20 20 20 72 65 66 65  acquire..   refe
0290: 72 65 6e 63 65 73 20 74 6f 20 6e 65 77 20 56 61  rences to new Va
02a0: 6c 75 65 73 2c 20 70 72 61 63 74 69 63 65 20 68  lues, practice h
02b0: 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 66 61  as shown that fa
02c0: 69 6c 69 6e 67 20 74 6f 20 61 63 71 75 69 72 65  iling to acquire
02d0: 20 72 65 66 65 72 65 6e 63 65 73 20 63 61 6e 20   references can 
02e0: 70 6f 74 65 6e 74 69 61 6c 6c 79 20 62 65 0d 0a  potentially be..
02f0: 20 20 20 64 61 6e 67 65 72 6f 75 73 20 28 69 6e     dangerous (in
0300: 20 74 68 61 74 20 64 6f 77 6e 73 74 72 65 61 6d   that downstream
0310: 20 63 61 6c 6c 73 20 6d 69 67 68 74 20 70 75 6c   calls might pul
0320: 6c 20 73 75 63 68 20 61 20 56 61 6c 75 65 20 6f  l such a Value o
0330: 75 74 20 66 72 6f 6d 20 75 6e 64 65 72 20 74 68  ut from under th
0340: 65 20 63 6c 69 65 6e 74 29 2e 20 54 68 69 73 20  e client). This 
0350: 69 73 0d 0a 20 20 20 73 65 65 6d 69 6e 67 6c 79  is..   seemingly
0360: 20 61 20 6e 6f 2d 62 72 61 69 6e 65 72 2c 20 62   a no-brainer, b
0370: 75 74 20 74 68 31 69 73 68 20 61 6e 64 20 73 32  ut th1ish and s2
0380: 20 6d 61 6b 65 20 68 65 61 76 79 20 75 73 65 20   make heavy use 
0390: 6f 66 20 22 74 65 6d 70 22 20 28 6e 6f 2d 72 65  of "temp" (no-re
03a0: 66 2d 63 6f 75 6e 74 29 20 76 61 72 73 20 62 65  f-count) vars be
03b0: 63 61 75 73 65 20 74 68 65 69 72 0d 0a 20 20 20  cause their..   
03c0: 22 65 76 61 6c 22 20 65 6e 67 69 6e 65 73 20 77  "eval" engines w
03d0: 6f 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 68  ould otherwise h
03e0: 61 76 65 20 61 20 64 69 66 66 69 63 75 6c 74 20  ave a difficult 
03f0: 74 69 6d 65 20 66 69 67 75 72 69 6e 67 20 6f 75  time figuring ou
0400: 74 20 77 68 65 6e 20 74 6f 20 64 65 72 65 66 2e  t when to deref.
0410: 0d 0a 0d 0a 20 20 20 2a 20 20 41 6c 6c 6f 63 61  ....   *  Alloca
0420: 74 65 20 63 77 61 6c 5f 65 6e 67 69 6e 65 20 61  te cwal_engine a
0430: 6e 64 20 63 77 61 6c 5f 73 63 6f 70 65 20 6f 6e  nd cwal_scope on
0440: 20 74 68 65 20 73 74 61 63 6b 2e 20 54 68 65 20   the stack. The 
0450: 41 50 49 73 20 61 6c 6c 6f 77 20 66 6f 72 20 74  APIs allow for t
0460: 68 65 73 65 20 74 6f 20 62 65 20 64 79 6e 61 6d  hese to be dynam
0470: 69 63 61 6c 6c 79 20 61 6c 6c 6f 63 61 74 65 64  ically allocated
0480: 2c 0d 0a 20 20 20 62 75 74 20 69 74 27 73 20 6e  ,..   but it's n
0490: 65 76 65 72 20 6e 65 63 65 73 73 61 72 79 20 74  ever necessary t
04a0: 6f 20 64 6f 20 73 6f 20 66 6f 72 20 73 63 6f 70  o do so for scop
04b0: 65 73 2c 20 61 6e 64 20 6f 6e 6c 79 20 72 61 72  es, and only rar
04c0: 65 6c 79 20 6e 65 63 65 73 73 61 72 79 20 66 6f  ely necessary fo
04d0: 72 20 63 77 61 6c 5f 65 6e 67 69 6e 65 20 69 6e  r cwal_engine in
04e0: 73 74 61 6e 63 65 73 2e 0d 0a 0d 0a 20 20 20 2a  stances.....   *
04f0: 20 20 41 6c 77 61 79 73 20 74 65 73 74 20 6e 65    Always test ne
0500: 77 20 63 6f 64 65 20 77 69 74 68 20 61 6c 6c 20  w code with all 
0510: 72 65 63 79 63 6c 69 6e 67 20 6f 70 74 69 6f 6e  recycling option
0520: 73 20 3c 65 6d 3e 64 69 73 61 62 6c 65 64 3c 2f  s <em>disabled</
0530: 65 6d 3e 2e 20 54 68 65 20 72 65 61 73 6f 6e 20  em>. The reason 
0540: 69 73 20 73 69 6d 70 6c 65 3a 20 74 68 65 20 72  is simple: the r
0550: 65 63 79 63 6c 65 72 0d 0a 20 20 20 63 61 6e 20  ecycler..   can 
0560: 68 69 64 65 20 28 66 72 6f 6d 20 76 61 6c 67 72  hide (from valgr
0570: 69 6e 64 29 20 69 6e 76 61 6c 69 64 20 61 63 63  ind) invalid acc
0580: 65 73 73 20 74 6f 20 6d 65 6d 6f 72 79 20 77 68  ess to memory wh
0590: 69 63 68 20 69 73 20 69 6e 20 6f 6e 65 20 6f 66  ich is in one of
05a0: 20 74 68 65 20 72 65 63 79 63 6c 65 72 73 2c 20   the recyclers, 
05b0: 62 65 63 61 75 73 65 20 73 75 63 68 20 61 63 63  because such acc
05c0: 65 73 73 0d 0a 20 20 20 69 73 20 74 65 63 68 6e  ess..   is techn
05d0: 69 63 61 6c 6c 79 20 6c 65 67 61 6c 20 28 69 6e  ically legal (in
05e0: 20 74 68 61 74 20 74 68 65 20 6d 65 6d 6f 72 79   that the memory
05f0: 20 73 74 69 6c 6c 20 62 65 6c 6f 6e 67 73 20 74   still belongs t
0600: 6f 20 63 77 61 6c 29 20 77 68 69 6c 65 20 62 65  o cwal) while be
0610: 69 6e 67 20 73 65 6d 61 6e 74 69 63 61 6c 6c 79  ing semantically
0620: 20 69 6c 6c 65 67 61 6c 20 28 69 6e 20 74 68 61   illegal (in tha
0630: 74 20 74 68 65 0d 0a 20 20 20 63 6c 69 65 6e 74  t the..   client
0640: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 61   should not be a
0650: 63 63 65 73 73 69 6e 67 20 69 74 29 2e 20 42 65  ccessing it). Be
0660: 20 73 75 72 65 20 74 6f 20 72 75 6e 20 61 6c 6c   sure to run all
0670: 20 6e 65 77 20 63 6f 64 65 20 74 68 72 6f 75 67   new code throug
0680: 68 20 76 61 6c 67 72 69 6e 64 20 77 69 74 68 20  h valgrind with 
0690: 72 65 63 79 63 6c 69 6e 67 20 6f 6e 20 61 6e 64  recycling on and
06a0: 20 6f 66 66 0d 0a 20 20 20 74 6f 20 63 61 74 63   off..   to catc
06b0: 68 20 74 68 65 20 77 69 64 65 73 74 20 76 61 72  h the widest var
06c0: 69 65 74 79 20 6f 66 20 6d 69 73 75 73 65 2e 0d  iety of misuse..
06d0: 0a 0a 5a 20 61 62 30 38 39 39 63 37 63 66 35 36  ..Z ab0899c7cf56
06e0: 33 34 66 33 63 66 35 34 33 37 63 37 31 39 63 63  34f3cf5437c719cc
06f0: 64 39 65 35 0a                                   d9e5.