[asterisk-commits] mmichelson: branch mmichelson/chan_fixup r173347 - /team/mmichelson/chan_fixu...

[SVN commits to the Asterisk project]

Author: mmichelson
Date: Tue Feb  3 19:28:11 2009
New Revision: 173347

URL: http://svn.digium.com/svn-view/asterisk?view=rev&rev=173347
Log:
Added doxygen to autochan.h


Modified:
    team/mmichelson/chan_fixup/include/asterisk/autochan.h

Modified: team/mmichelson/chan_fixup/include/asterisk/autochan.h
URL: http://svn.digium.com/svn-view/asterisk/team/mmichelson/chan_fixup/include/asterisk/autochan.h?view=diff&rev=173347&r1=173346&r2=173347
==============================================================================
--- team/mmichelson/chan_fixup/include/asterisk/autochan.h (original)
+++ team/mmichelson/chan_fixup/include/asterisk/autochan.h Tue Feb  3 19:28:11 2009
@@ -31,16 +31,68 @@
 #ifndef _ASTERISK_AUTOCHAN_H
 #define _ASTERISK_AUTOCHAN_H
 
+/*! \par Autochan locking tips
+ * Autochans were developed with the sole purpose
+ * of being used when a masquerade could otherwise
+ * cause a channel pointer to become invalid. Autochans
+ * allow this, but locking is required to be perfectly safe.
+ * The lock inside the autochan is meant to protect the
+ * pointer to the channel inside, not the data the pointer
+ * points to (that job is handled by the channel lock). Whenever
+ * you wish to access the channel inside an autochan, you should
+ * first lock the autochan. This will ensure that the autochan
+ * pointer will not change.
+ *
+ * It may become necessary for you to lock both an autochan and
+ * the channel that it points to. Because autochans were designed
+ * to be used during masquerades, the correct locking order has
+ * been decided for us. One should be sure to lock the channel first,
+ * and then the autochan after. This is because in ast_do_masquerade,
+ * both channels involved are locked and then ast_autochan_new_channel
+ * is called, which needs to lock the autochan. Be sure to adhere to
+ * this lock order to prevent any possible deadlocks
+ */
+
 struct ast_autochan {
 	struct ast_channel *chan;
 	ast_mutex_t lock;
 	AST_LIST_ENTRY(ast_autochan) list;
 };
 
+/* \brief set up a new ast_autochan structure
+ *
+ * Allocates and initializes an ast_autochan, sets the
+ * autochan's chan pointer to point to the chan parameter, and
+ * adds the autochan to the global list of autochans. The newly-
+ * created autochan is returned to the caller.
+ *
+ * \note autochans must be freed using ast_autochan_destroy
+ * \param chan The channel our new autochan will point to
+ * \retval NULL Failure
+ * \retval non-NULL success
+ */
 struct ast_autochan *ast_autochan_setup(struct ast_channel *chan);
 
+/* \brief destroy an ast_autochan structure
+ *
+ * Removes the passed-in autochan from the list of autochans and
+ * frees all memory associated with it.
+ *
+ * \param autochan The autochan that you wish to destroy
+ * \retval void
+ */
 void ast_autochan_destroy(struct ast_autochan *autochan);
 
+/* \brief Switch what channel autochans point to
+ *
+ * Traverses the list of autochans. All autochans which point to
+ * old_chan will be updated to point to new_chan instead. Currently
+ * this is only called from ast_do_masquerade in channel.c
+ *
+ * \param old_chan The channel that autochans may currently point to
+ * \param new_chan The channel that we want to point those autochans to now
+ * \retval void
+ */
 void ast_autochan_new_channel(struct ast_channel *old_chan, struct ast_channel *new_chan);
 
 #define ast_autochan_lock(a) ast_mutex_lock(&a->lock)