[asterisk-commits] dlee: branch dlee/stasis-cache-split r394261 - /team/dlee/stasis-cache-split/...

[SVN commits to the Asterisk project]

Author: dlee
Date: Fri Jul 12 17:31:51 2013
New Revision: 394261

URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=394261
Log:
Doc fixes

Modified:
    team/dlee/stasis-cache-split/include/asterisk/stasis.h
    team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h

Modified: team/dlee/stasis-cache-split/include/asterisk/stasis.h
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-cache-split/include/asterisk/stasis.h?view=diff&rev=394261&r1=394260&r2=394261
==============================================================================
--- team/dlee/stasis-cache-split/include/asterisk/stasis.h (original)
+++ team/dlee/stasis-cache-split/include/asterisk/stasis.h Fri Jul 12 17:31:51 2013
@@ -100,14 +100,18 @@
  * identify cacheable messages.
  *
  * The \ref stasis_cache is designed so that it may be shared amongst several
- * \ref stasis_caching_topics. This allows you to have individual caching
+ * \ref stasis_caching_topic objects. This allows you to have individual caching
  * topics per-object (i.e. so you can subscribe to updates for a single object),
  * and still have a single cache to query for the state of all objects. While a
  * cache may be shared amongst different message types, such a usage is probably
  * not a good idea.
  *
- * The returned \ref stasis_caching_topic provides a topic that forwards
- * non-cacheable messages unchanged. A cacheable message is wrapped in a \ref
+ * The \ref stasis_cache can only be written to by \ref stasis_caching_topics.
+ * It's a thread safe container, so freely use the stasis_cache_get() and
+ * stasis_cache_dump() to query the cache.
+ *
+ * The \ref stasis_caching_topic provides a topic that forwards non-cacheable
+ * messages unchanged. A cacheable message is wrapped in a \ref
  * stasis_cache_update message which provides the old snapshot (or \c NULL if
  * this is a new cache entry), and the new snapshot (or \c NULL if the entry was
  * removed from the cache). A stasis_cache_clear_create() message must be sent

Modified: team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h?view=diff&rev=394261&r1=394260&r2=394261
==============================================================================
--- team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h (original)
+++ team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h Fri Jul 12 17:31:51 2013
@@ -25,14 +25,18 @@
  *
  * A typical pattern for Stasis objects is to have individual objects, which
  * have their own topic and caching topic. These individual topics feed a
- * upstream collector topics.
+ * upstream aggregate topics, and a shared cache.
  *
- * This pattern creates an 'all' side (\ref stasis_cp_all) which contains the
- * shared cache and aggregator topics.
+ * The \ref stasis_cp_all object contains the aggregate topics and shared cache.
+ * This is built with the base name for the topics, and the identity function to
+ * identify messages in the cache.
  *
- * For individual topics, there's the 'one' side, which creates the individual
- * topic and caching topics, along with all the necessary forwarding
- * subscriptions.
+ * The \ref stasis_cp_single object contains the \ref stasis_topic for a single
+ * instance, and the corresponding \ref stasis_caching_topic.
+ *
+ * Since the \ref stasis_cp_single object has subscriptions for forwarding
+ * and caching, it must be disposed of using stasis_cp_single_unsubscribe()
+ * instead of simply ao2_cleanup().
  */
 
 #include "asterisk/stasis.h"
@@ -57,18 +61,41 @@
 	snapshot_get_id id_fn);
 
 /*!
- * \brief Get the aggregator topic.
+ * \brief Get the aggregate topic.
+ *
+ * This topic aggregates all messages published to corresponding
+ * stasis_cp_single_topic() topics.
+ *
+ * \param all All side caching pattern object.
+ * \return The aggregate topic.
+ * \return \c NULL if \a all is \c NULL
  */
 struct stasis_topic *stasis_cp_all_topic(struct stasis_cp_all *all);
 
 /*!
  * \brief Get the caching topic.
+ *
+ * This topic aggregates all messages from the corresponding
+ * stasis_cp_single_topic_cached() topics.
+ *
+ * Note that one normally only subscribes to the caching topic, since data
+ * is fed to it from its upstream topic.
+ *
+ * \param all All side caching pattern object.
+ * \return The aggregate caching topic.
+ * \return \c NULL if \a all is \c NULL
  */
 struct stasis_topic *stasis_cp_all_topic_cached(
 	struct stasis_cp_all *all);
 
 /*!
  * \brief Get the cache.
+ *
+ * This is the shared cache for all corresponding \ref stasis_cp_single objects.
+ *
+ * \param all All side caching pattern object.
+ * \return The cache.
+ * \return \c NULL if \a all is \c NULL
  */
 struct stasis_cache *stasis_cp_all_cache(struct stasis_cp_all *all);
 
@@ -82,7 +109,9 @@
 /*!
  * \brief Create the 'one' side of the cache pattern.
  *
- * \param all All side which aggregates this topic.
+ * Dispose of using stasis_cp_single_unsubscribe().
+ *
+ * \param all Corresponding all side.
  * \param name Base name for the topics.
  * \return One side instance
  */
@@ -90,23 +119,30 @@
 	const char *name);
 
 /*!
- * \brief Call to cancel forwarding of toward the cache aggregator.
+ * \brief Stops caching and forwarding messages.
  *
  * \param one One side of the cache pattern.
  */
 void stasis_cp_single_unsubscribe(struct stasis_cp_single *one);
 
 /*!
- * \brief Get the base topic for this instance.
+ * \brief Get the topic for this instance.
  *
  * \param one One side of the cache pattern.
+ * \return The main topic.
+ * \return \c NULL if \a one is \c NULL
  */
 struct stasis_topic *stasis_cp_single_topic(struct stasis_cp_single *one);
 
 /*!
  * \brief Get the caching topic for this instance.
  *
+ * Note that one normally only subscribes to the caching topic, since data
+ * is fed to it from its upstream topic.
+ *
  * \param one One side of the cache pattern.
+ * \return The caching topic.
+ * \return \c NULL if \a one is \c NULL
  */
 struct stasis_topic *stasis_cp_single_topic_cached(
 	struct stasis_cp_single *one);