libcwal  Artifact Content

Artifact 49d2c638bea6edefca16fed7c6ad7a45ebc55293:

Wiki page [CwalBestPractices] by stephan 2016-01-14 08:34:05.
D 2016-01-14T08:34:05.070
L CwalBestPractices
U stephan
W 1682
<h1>cwal Best Practices</h1>

Since its inception, <em>lots</em> has happened in cwal. Its API has mutated, its conventions
changed, and various best/worst practices have been discovered. This page covers a bit of the 
latter: best/worst practices.

<h2>Best Practices Summary</h2>

In no particular order...
   *  Build cwal in debug mode. This enables tons of assertions which can catch certain misuses long
   before they trigger downstream undefined behaviour.

   *  Always use <tt>cwal_value_ref()</tt>. While it is technically legal to not specifically acquire
   references to new Values, practice has shown that failing to acquire references can potentially be
   dangerous (in that downstream calls might pull such a Value out from under the client). This is
   seemingly a no-brainer, but th1ish and s2 make heavy use of "temp" (no-ref-count) vars because their
   "eval" engines would otherwise have a difficult time figuring out when to deref.

   *  Allocate cwal_engine and cwal_scope on the stack. The APIs allow for these to be dynamically allocated,
   but it's never necessary to do so for scopes, and only rarely necessary for cwal_engine instances.

   *  Always test new code with all recycling options <em>disabled</em>. The reason is simple: the recycler
   can hide (from valgrind) invalid access to memory which is in one of the recyclers, because such access
   is technically legal (in that the memory still belongs to cwal) while being semantically illegal (in that the
   client should not be accessing it). Be sure to run all new code through valgrind with recycling on and off
   to catch the widest variety of misuse.

Z ab0899c7cf5634f3cf5437c719ccd9e5