X-Git-Url: http://plrg.eecs.uci.edu/git/?p=folly.git;a=blobdiff_plain;f=folly%2Fio%2Fasync%2FREADME.md;h=0918b3966cfb9aba582ff9c19d0c657d45b8928f;hp=a6214dbdfd5034d2e364cd9a93e7f5e9f5c8e86a;hb=c1a1a5e6039c13c55597fa942ce1c01ecfe2f6a3;hpb=314c43c4f95dc51f2c97d00216be062eebbd5454;ds=sidebyside

diff --git a/folly/io/async/README.md b/folly/io/async/README.md
index a6214dbd..0918b396 100644
--- a/folly/io/async/README.md
+++ b/folly/io/async/README.md
@@ -293,6 +293,30 @@ type.  It's also pretty easy to forget to add a DestructorGuard in
 code that calls callbacks.  But it is well worth it to avoid queuing
 callbacks, and the improved P99 times as a result.
 
+### DestructorCheck
+
+Often for an object requesting callbacks from other components (timer,
+socket connect, etc.) there is a chance that the requestor will be
+deallocated before it'll receive the callback.  One of the ways to avoid
+dereferencing the deallocated object from callbacks is to derive the
+object from DelayedDestruction, and add a delayed destruction guard
+to the callback context.  In case if keeping the object around until
+all the requested callbacks fire is too expensive, or if the callback
+requestor can't have private destructor (it's allocated on the stack,
+or as a member of a larger object), DestructorCheck can be used.
+DestructorCheck is not affecting object life time. It helps other
+component to detect safely that the tracked object was deallocated.
+
+The object requesting the callback must be derived from DestructorCheck.
+The callback context should contain an instance of
+DestructorCheck::Safety object initialized with a reference to the
+object requesting the callback.  Safety object can be captured by value
+in the callback lambda, or explicitly added to a predefined callback
+context class. Multiple instances of Safety object can be instantiated
+for the same tracked object.  Once the callback is invoked, before
+dereferencing the requester object, callback code should make sure that
+`destroyed()` method for the corresponding Safety object returns false.
+
 ### EventBaseManager
 
 DANGEROUS.