- * changes in a significant way. If called twice on the same key, then
- * the last TTL takes precedence.
+ * changes in a significant way. This deletes the key and starts a hold-off
+ * period where the key cannot be written to for a few seconds (HOLDOFF_TTL).
+ * This is done to avoid the following race condition:
+ * a) Some DB data changes and delete() is called on a corresponding key
+ * b) A request refills the key with a stale value from a lagged DB
+ * c) The stale value is stuck there until the key is expired/evicted
+ *
+ * This is implemented by storing a special "tombstone" value at the cache
+ * key that this class recognizes; get() calls will return false for the key
+ * and any set() calls will refuse to replace tombstone values at the key.
+ * For this to always avoid writing stale values, the following must hold:
+ * a) Replication lag is bounded to being less than HOLDOFF_TTL; or
+ * b) If lag is higher, the DB will have gone into read-only mode already
+ *
+ * If called twice on the same key, then the last hold-off TTL takes
+ * precedence. For idempotence, the $ttl should not vary for different
+ * delete() calls on the same key. Also note that lowering $ttl reduces
+ * the effective range of the 'lockTSE' parameter to getWithSetCallback().