stasis: Use an implementation specific channel snapshot cache.

Channels no longer use the Stasis cache for channel snapshots. Instead
they are stored in a hash table in stasis_channels which reduces the
number of Stasis messages created and allows better storage.

As a result the following APIs are no longer available since the stasis
cache is no longer used:
ast_channel_topic_cached()
ast_channel_topic_all_cached()

The ast_channel_cache_all() and ast_channel_cache_by_name() functions
now return an ao2_container of ast_channel_snapshots rather than
a container of stasis_messages therefore you can't (and don't need
to) call stasis_cache functions on it.

The ast_channel_topic_all() function now returns a normal topic not
a cached one so you can't use stasis cache functions on it either.

The ast_channel_snapshot_type() stasis message now has the
ast_channel_snapshot_update structure as it's data. It contains the
last snapshot and the new one.

ast_channel_snapshot_get_latest() still returns the latest snapshot.

The latest snapshot is now stored on the channel itself to eliminate
cache hits when Stasis messages that have the snapshot as a payload
are created.

ASTERISK-28102

Change-Id: I9334febff60a82d7c39703e49059fa3a68825786

include/asterisk/channel.h

@@ -147,6 +147,15 @@ extern "C" {
  */
 #define AST_MAX_PUBLIC_UNIQUEID 149
 
+/*!
+ * The number of buckets to store channels or channel information
+ */
+#ifdef LOW_MEMORY
+#define AST_NUM_CHANNEL_BUCKETS 61
+#else
+#define AST_NUM_CHANNEL_BUCKETS 1567
+#endif
+
 /*!
  * Maximum size of an internal Asterisk channel unique ID.
  *
@@ -2649,6 +2658,17 @@ void ast_channel_internal_swap_uniqueid_and_linkedid(struct ast_channel *a, stru
  */
 void ast_channel_internal_swap_topics(struct ast_channel *a, struct ast_channel *b);
 
+/*!
+ * \brief Swap snapshots beteween two channels
+ * \param a First channel
+ * \param b Second channel
+ * \return void
+ *
+ * \note
+ * This is used in masquerade to exchange snapshots
+ */
+void ast_channel_internal_swap_snapshots(struct ast_channel *a, struct ast_channel *b);
+
 /*!
  * \brief Set uniqueid and linkedid string value only (not time)
  * \param chan The channel to set the uniqueid to
@@ -4236,6 +4256,8 @@ enum ast_channel_adsicpe ast_channel_adsicpe(const struct ast_channel *chan);
 void ast_channel_adsicpe_set(struct ast_channel *chan, enum ast_channel_adsicpe value);
 enum ast_channel_state ast_channel_state(const struct ast_channel *chan);
 ast_callid ast_channel_callid(const struct ast_channel *chan);
+struct ast_channel_snapshot *ast_channel_snapshot(const struct ast_channel *chan);
+void ast_channel_snapshot_set(struct ast_channel *chan, struct ast_channel_snapshot *snapshot);
 
 /*!
  * \pre chan is locked
@@ -4561,21 +4583,6 @@ struct varshead *ast_channel_get_vars(struct ast_channel *chan);
  */
 struct stasis_topic *ast_channel_topic(struct ast_channel *chan);
 
-/*!
- * \since 12
- * \brief A topic which publishes the events for a particular channel.
- *
- * \ref ast_channel_snapshot messages are replaced with \ref stasis_cache_update
- *
- * If the given \a chan is \c NULL, ast_channel_topic_all_cached() is returned.
- *
- * \param chan Channel, or \c NULL.
- *
- * \retval Topic for channel's events.
- * \retval ast_channel_topic_all() if \a chan is \c NULL.
- */
-struct stasis_topic *ast_channel_topic_cached(struct ast_channel *chan);
-
 /*!
  * \brief Get the bridge associated with a channel
  * \since 12.0.0

include/asterisk/stasis_channels.h

@@ -75,6 +75,23 @@ struct ast_channel_snapshot {
 	struct varshead *ari_vars;              /*!< Variables to be appended to ARI events */
 };
 
+/*!
+ * \since 17
+ * \brief Structure representing a change of snapshot of channel state.
+ *
+ * While not enforced programmatically, this object is shared across multiple
+ * threads, and should be treated as an immutable object.
+ *
+ * \note This structure will not have a transition of an old snapshot with no
+ * new snapshot to indicate that a channel has gone away. A new snapshot will
+ * always exist and a channel going away can be determined by checking for the
+ * AST_FLAG_DEAD flag on the new snapshot.
+ */
+struct ast_channel_snapshot_update {
+	struct ast_channel_snapshot *old_snapshot; /*!< The old channel snapshot */
+	struct ast_channel_snapshot *new_snapshot; /*!< The new channel snapshot */
+};
+
 /*!
  * \since 12
  * \brief Blob of data associated with a channel.
@@ -94,7 +111,7 @@ struct ast_channel_blob {
  */
 struct ast_multi_channel_blob;
 
-struct stasis_cp_all *ast_channel_cache_all(void);
+struct ao2_container *ast_channel_cache_all(void);
 
 /*!
  * \since 12
@@ -103,36 +120,19 @@ struct stasis_cp_all *ast_channel_cache_all(void);
  */
 struct stasis_topic *ast_channel_topic_all(void);
 
-/*!
- * \since 12
- * \brief A caching topic which caches \ref ast_channel_snapshot messages from
- * ast_channel_events_all(void).
- *
- * \retval Topic for all channel events.
- */
-struct stasis_topic *ast_channel_topic_all_cached(void);
-
-/*!
- * \since 12
- * \brief Primary channel cache, indexed by Uniqueid.
- *
- * \retval Cache of \ref ast_channel_snapshot.
- */
-struct stasis_cache *ast_channel_cache(void);
-
 /*!
  * \since 12
  * \brief Secondary channel cache, indexed by name.
  *
  * \retval Cache of \ref ast_channel_snapshot.
  */
-struct stasis_cache *ast_channel_cache_by_name(void);
+struct ao2_container *ast_channel_cache_by_name(void);
 
 /*!
  * \since 12
- * \brief Message type for \ref ast_channel_snapshot.
+ * \brief Message type for \ref ast_channel_snapshot_update.
  *
- * \retval Message type for \ref ast_channel_snapshot.
+ * \retval Message type for \ref ast_channel_snapshot_update.
  */
 struct stasis_message_type *ast_channel_snapshot_type(void);
 
@@ -175,6 +175,18 @@ struct ast_channel_snapshot *ast_channel_snapshot_get_latest(const char *uniquei
  */
 struct ast_channel_snapshot *ast_channel_snapshot_get_latest_by_name(const char *name);
 
+/*!
+ * \since 17
+ * \brief Send the final channel snapshot for a channel, thus removing it from cache
+ *
+ * \pre chan is locked
+ *
+ * \param chan The channel to send the final channel snapshot for
+ *
+ * \note This will also remove the cached snapshot from the channel itself
+ */
+void ast_channel_publish_final_snapshot(struct ast_channel *chan);
+
 /*!
  * \since 12
  * \brief Creates a \ref ast_channel_blob message.
@@ -303,6 +315,8 @@ void ast_multi_channel_blob_add_channel(struct ast_multi_channel_blob *obj,
  * \param type Type of stasis message.
  * \param blob The blob being published. (NULL if no blob)
  *
+ * \note This will use the current snapshot on the channel and will not generate a new one.
+ *
  * \return Nothing
  */
 void ast_channel_publish_blob(struct ast_channel *chan, struct stasis_message_type *type,
@@ -557,17 +571,6 @@ void ast_channel_publish_dial_forward(struct ast_channel *caller,
 		const char *dialstatus,
 		const char *forward);
 
-/*!
- * \since 12
- * \brief Publish in the \ref ast_channel_topic a \ref ast_channel_snapshot
- * message indicating a change in channel state
- *
- * \pre chan is locked
- *
- * \param chan The channel whose state has changed
- */
-void ast_publish_channel_state(struct ast_channel *chan);
-
 /*! @} */
 
 /*!