Some documentation updates in lazy

Summary: Per discussion after commit on the previous diff.

Test Plan: Compiled.

Reviewed By: tjackson@fb.com

FB internal diff: D821985

diff --git a/folly/Lazy.h b/folly/Lazy.h
index 2b18ea7b84b36fdb9588c96a87d0f949a8bf6009..fd3e51036b549d4d369c3a2967ec28851bffbabc 100644 (file)
--- a/folly/Lazy.h
+++ b/folly/Lazy.h
@@ -35,8 +35,8 @@ namespace folly {
  * The value is created using folly::lazy, usually with a lambda, and
  * its value is requested using operator().
  *
- * Note that the value is not safe for current accesses by multiple
- * threads, even if you declare it const.
+ * Note that the value is not safe for concurrent accesses by multiple
+ * threads, even if you declare it const.  See note below.
  *
  *
  * Example Usage:
@@ -70,6 +70,16 @@ namespace folly {
  *      value unnecessarily.  Sharing with mutable lazies would also
  *      leave them with non-value semantics despite looking
  *      value-like.
+ *
+ *    - Not thread safe for const accesses.  Many use cases for lazy
+ *      values are local variables on the stack, where multiple
+ *      threads shouldn't even be able to reach the value.  It still
+ *      is useful to indicate/check that the value doesn't change with
+ *      const, particularly when it is captured by a large family of
+ *      lambdas.  Adding internal synchronization seems like it would
+ *      pessimize the most common use case in favor of less likely use
+ *      cases.
+ *
  */
 
 //////////////////////////////////////////////////////////////////////