Cache string values of formats on ast_format_cap() to save processing.

Channel snapshots have string representations of the channel's native formats.
Prior to this change, the format strings were re-created on ever channel snapshot
creation. Since channel native formats rarely change, this was very wasteful.
Now, string representations of formats may optionally be stored on the ast_format_cap
for cases where string representations may be requested frequently. When formats
are altered, the string cache is marked as invalid. When strings are requested, the
cache validity is checked. If the cache is valid, then the cached strings are copied.
If the cache is invalid, then the string cache is rebuilt and copied, and the cache
is marked as being valid again.

Review: https://reviewboard.asterisk.org/r/2879
........

Merged revisions 400356 from http://svn.asterisk.org/svn/asterisk/branches/12


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

1 files changed, 15 insertions, 20 deletions

diff --git a/include/asterisk/format_cap.h b/include/asterisk/format_cap.h
index b34f1d3ca..aa4eb3bfd 100644
--- a/include/asterisk/format_cap.h
+++ b/include/asterisk/format_cap.h
@@ -29,32 +29,27 @@
 /*! Capabilities are represented by an opaque structure statically defined in format_capability.c */
 struct ast_format_cap;
 
-/*!
- * \brief Allocate a new ast_format_cap structure.
- *
- * \note Allocation of this object assumes locking
- * is already occuring and that the point of contention
- * is above this capabilities structure.  For example,
- * a tech_pvt object referencing a capabilities structure
- * can use this function as long as it always holds the
- * tech_pvt lock while accessing its capabilities.
- *
- * \retval ast_format_cap object on success.
- * \retval NULL on failure.
- */
-struct ast_format_cap *ast_format_cap_alloc_nolock(void);
+enum ast_format_cap_flags {
+	/*!
+	 * The ast_format_cap will be allocated with no lock.
+	 * Useful if there is a separate lock used to protect the structure
+	 */
+	AST_FORMAT_CAP_FLAG_NOLOCK = (1 << 0),
+	/*!
+	 * String representations of the formats are cached on the structure.
+	 * Useful if string representation is frequently requested of the structure.
+	 */
+	AST_FORMAT_CAP_FLAG_CACHE_STRINGS = (1 << 1),
+};
 
 /*!
- * \brief Allocate a new ast_format_cap structure with locking
- *
- * \note If no other form of locking is taking place, use this function.
- * This function makes most sense for globally accessible capabilities structures
- * that have no other means of locking.
+ * \brief Allocate a new ast_format_cap structure
  *
+ * \param flags Modifiers of struct behavior.
  * \retval ast_format_cap object on success.
  * \retval NULL on failure.
  */
-struct ast_format_cap *ast_format_cap_alloc(void);
+struct ast_format_cap *ast_format_cap_alloc(enum ast_format_cap_flags flags);
 
 /*!
  * \brief Destroy an ast_format_cap structure.