libcwal  CwalBestPractices

cwal Best Practices

Since its inception, lots 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.

Best Practices Summary

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 cwal_value_ref(). 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 disabled. 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.