[svn-commits] dlee: branch dlee/stasis-cache-split r394233 - /team/dlee/stasis-cache-split/...

[SVN commits to the Digium repositories]

Author: dlee
Date: Fri Jul 12 16:08:16 2013
New Revision: 394233

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

Modified:
    team/dlee/stasis-cache-split/include/asterisk/stasis.h
    team/dlee/stasis-cache-split/include/asterisk/stasis_endpoints.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=394233&r1=394232&r2=394233
==============================================================================
--- team/dlee/stasis-cache-split/include/asterisk/stasis.h (original)
+++ team/dlee/stasis-cache-split/include/asterisk/stasis.h Fri Jul 12 16:08:16 2013
@@ -94,10 +94,17 @@
  * in the system, and it's desirable to query that state from the cache without
  * locking the original object. It's also desirable for subscribers of the
  * caching topic to receive messages that have both the old cache value and the
- * new value being put into the cache. For this, we have
- * stasis_caching_topic_create(), providing it with the topic which publishes
- * the messages that you wish to cache, and a function that can identify
- * cacheable messages.
+ * new value being put into the cache. For this, we have stasis_cache_create()
+ * and stasis_caching_topic_create(), providing them with the topic which
+ * publishes the messages that you wish to cache, and a function that can
+ * 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
+ * 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
@@ -110,6 +117,9 @@
  * call stasis_caching_unsubscribe(). Due to cyclic references, the \ref
  * stasis_caching_topic will not be freed until after it has been unsubscribed,
  * and all other ao2_ref()'s have been cleaned up.
+ *
+ * The \ref stasis_cache object is a normal AO2 managed object, which can be
+ * release with ao2_cleanup().
  *
  * \par stasis_subscriber
  *

Modified: team/dlee/stasis-cache-split/include/asterisk/stasis_endpoints.h
URL: http://svnview.digium.com/svn/asterisk/team/dlee/stasis-cache-split/include/asterisk/stasis_endpoints.h?view=diff&rev=394233&r1=394232&r2=394233
==============================================================================
--- team/dlee/stasis-cache-split/include/asterisk/stasis_endpoints.h (original)
+++ team/dlee/stasis-cache-split/include/asterisk/stasis_endpoints.h Fri Jul 12 16:08:16 2013
@@ -137,8 +137,6 @@
 /*!
  * \brief Returns the topic for a specific endpoint.
  *
- * This is AO2 managed, so ao2_cleanup when done.
- *
  * \param endpoint The endpoint.
  * \return The topic for the given endpoint.
  * \return ast_endpoint_topic_all() if endpoint is \c NULL.
@@ -152,8 +150,6 @@
  * \ref ast_endpoint_snapshot messages are replaced with
  * \ref stasis_cache_update
  *
- * This is AO2 managed, so ao2_cleanup when done.
- *
  * \param endpoint The endpoint.
  * \return The topic for the given endpoint.
  * \return ast_endpoint_topic_all() if endpoint is \c NULL.
@@ -163,6 +159,7 @@
 
 /*!
  * \internal
+ * \brief Cache and global topics for endpoints.
  * \since 12
  */
 struct stasis_cache_all *ast_endpoint_cache_all(void);