[asterisk-commits] dlee: branch dlee/clean-shutdown r388727 - /team/dlee/clean-shutdown/include/...

[SVN commits to the Asterisk project]

Author: dlee
Date: Tue May 14 15:45:53 2013
New Revision: 388727

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=388727
Log:
Document the shutdown options

Modified:
    team/dlee/clean-shutdown/include/asterisk/stasis.h

Modified: team/dlee/clean-shutdown/include/asterisk/stasis.h
URL: http://svnview.digium.com/svn/asterisk/team/dlee/clean-shutdown/include/asterisk/stasis.h?view=diff&rev=388727&r1=388726&r2=388727
==============================================================================
--- team/dlee/clean-shutdown/include/asterisk/stasis.h (original)
+++ team/dlee/clean-shutdown/include/asterisk/stasis.h Tue May 14 15:45:53 2013
@@ -124,6 +124,34 @@
  * stasis_subscription. Due to cyclic references, the \ref
  * stasis_subscription will not be freed until after it has been unsubscribed,
  * and all other ao2_ref()'s have been cleaned up.
+ *
+ * \par Shutdown
+ *
+ * Subscriptions have two options for unsubscribing, depending upon the context
+ * in which you need to unsubscribe.
+ *
+ * If your subscription is owned by a module, and your must unsubscribe from the
+ * module_unload() function, then you'll want to use the
+ * stasis_unsubscribe_and_join() function. This will block until the final
+ * message has been received on the subscription. Otherwise, there's the danger
+ * of invoking the callback function after it has been unloaded.
+ *
+ * If your subscription is owned by an object, then your object should have an
+ * explicit shutdown() function, which calls stasis_unsubscribe(). In your
+ * subscription handler, when the stasis_subscription_final_message() has been
+ * received, decrement the refcount on your object. In your object's destructor,
+ * you may assert that stasis_subscription_is_done() to validate that the
+ * subscription's callback will no longer be invoked.
+ *
+ * \b Note: You may be tempted to simply call stasis_unsubscribe_and_join() from
+ * an object's destructor. While code that does this may work most of the time,
+ * it's got one big downside. There's a general assumption that object
+ * destruction is non-blocking. If you block the destruction waiting for the
+ * subscription to complete, there's the danger that the subscription may
+ * process a message which will bump the refcount up by one. Then it does
+ * whatever it does, decrements the refcount, which then procedes to re-destroy
+ * the object. Now you've got hard to reproduce bugs that only show up under
+ * certain loads.
  */
 
 #include "asterisk/utils.h"