Merged revisions 337974 via svnmerge from

https://origsvn.digium.com/svn/asterisk/branches/10

................
  r337974 | rmudgett | 2011-09-26 14:35:23 -0500 (Mon, 26 Sep 2011) | 37 lines
  
  Merged revisions 337973 via svnmerge from 
  https://origsvn.digium.com/svn/asterisk/branches/1.8
  
  ........
    r337973 | rmudgett | 2011-09-26 14:30:39 -0500 (Mon, 26 Sep 2011) | 30 lines
    
    Fix deadlock when using dummy channels.
    
    Dummy channels created by ast_dummy_channel_alloc() should be destoyed by
    ast_channel_unref().  Using ast_channel_release() needlessly grabs the
    channel container lock and can cause a deadlock as a result.
    
    * Analyzed use of ast_dummy_channel_alloc() and made use
    ast_channel_unref() when done with the dummy channel.  (Primary reason for
    the reported deadlock.)
    
    * Made app_dial.c:dial_exec_full() not call ast_call() holding any channel
    locks.  Chan_local could not perform deadlock avoidance correctly.
    (Potential deadlock exposed by this issue.  Secondary reason for the
    reported deadlock since the held lock was part of the deadlock chain.)
    
    * Fixed some uses of ast_dummy_channel_alloc() not checking the returned
    channel pointer for failure.
    
    * Fixed some potential chan=NULL pointer usage in func_odbc.c.  Protected
    by testing the bogus_chan value.
    
    * Fixed needlessly clearing a 1024 char auto array when setting the first
    char to zero is enough in manager.c:action_getvar().
    
    (closes issue ASTERISK-18613)
    Reported by: Thomas Arimont
    Patches:
          jira_asterisk_18613_v1.8.patch (license #5621) patch uploaded by rmudgett
    Tested by: Thomas Arimont
  ........
................


git-svn-id: https://origsvn.digium.com/svn/asterisk/trunk@337975 65c4cc65-6c06-0410-ace0-fbb531ad65f3

2 files changed, 29 insertions, 3 deletions

diff --git a/include/asterisk/cel.h b/include/asterisk/cel.h
index 226a6cf24..b388ffd9b 100644
--- a/include/asterisk/cel.h
+++ b/include/asterisk/cel.h
@@ -190,8 +190,11 @@ void ast_cel_check_retire_linkedid(struct ast_channel *chan);
 /*!
  * \brief Create a fake channel from data in a CEL event
  *
- * This function creates a fake channel containing the serialized channel data 
- * in the given cel event.  It must be released with ast_channel_release.
+ * \note
+ * This function creates a fake channel containing the
+ * serialized channel data in the given cel event.  It should be
+ * released with ast_channel_unref() but could be released with
+ * ast_channel_release().
  *
  * \param event the CEL event
  *
diff --git a/include/asterisk/channel.h b/include/asterisk/channel.h
index 44f0a20f3..4d25f66e6 100644
--- a/include/asterisk/channel.h
+++ b/include/asterisk/channel.h
@@ -1134,6 +1134,7 @@ struct ast_channel * attribute_malloc __attribute__((format(printf, 13, 14)))
 	__ast_channel_alloc(needqueue, state, cid_num, cid_name, acctcode, exten, context, linkedid, amaflag, \
 			    __FILE__, __LINE__, __FUNCTION__, __VA_ARGS__)
 
+#if defined(REF_DEBUG) || defined(__AST_DEBUG_MALLOC)
 /*!
  * \brief Create a fake channel structure
  *
@@ -1143,11 +1144,32 @@ struct ast_channel * attribute_malloc __attribute__((format(printf, 13, 14)))
  * \note This function should ONLY be used to create a fake channel
  *       that can then be populated with data for use in variable
  *       substitution when a real channel does not exist.
+ *
+ * \note The created dummy channel should be destroyed by
+ * ast_channel_unref().  Using ast_channel_release() needlessly
+ * grabs the channel container lock and can cause a deadlock as
+ * a result.  Also grabbing the channel container lock reduces
+ * system performance.
  */
-#if defined(REF_DEBUG) || defined(__AST_DEBUG_MALLOC)
 #define ast_dummy_channel_alloc()	__ast_dummy_channel_alloc(__FILE__, __LINE__, __PRETTY_FUNCTION__)
 struct ast_channel *__ast_dummy_channel_alloc(const char *file, int line, const char *function);
 #else
+/*!
+ * \brief Create a fake channel structure
+ *
+ * \retval NULL failure
+ * \retval non-NULL successfully allocated channel
+ *
+ * \note This function should ONLY be used to create a fake channel
+ *       that can then be populated with data for use in variable
+ *       substitution when a real channel does not exist.
+ *
+ * \note The created dummy channel should be destroyed by
+ * ast_channel_unref().  Using ast_channel_release() needlessly
+ * grabs the channel container lock and can cause a deadlock as
+ * a result.  Also grabbing the channel container lock reduces
+ * system performance.
+ */
 struct ast_channel *ast_dummy_channel_alloc(void);
 #endif
 
@@ -1593,6 +1615,7 @@ int __ast_answer(struct ast_channel *chan, unsigned int delay, int cdr_answer);
 
 /*!
  * \brief Make a call
+ * \note Absolutely _NO_ channel locks should be held before calling this function.
  * \param chan which channel to make the call on
  * \param addr destination of the call
  * \param timeout time to wait on for connect