[svn-commits] dlee: branch dlee/stasis-cache-split r393886 - /team/dlee/stasis-cache-split/...
SVN commits to the Digium repositories
svn-commits at lists.digium.com
Tue Jul 9 11:32:08 CDT 2013
Author: dlee
Date: Tue Jul 9 11:32:07 2013
New Revision: 393886
URL: http://svnview.digium.com/svn/asterisk?view=rev&rev=393886
Log:
Core API changes
Added:
team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h (with props)
Modified:
team/dlee/stasis-cache-split/include/asterisk/stasis.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=393886&r1=393885&r2=393886
==============================================================================
--- team/dlee/stasis-cache-split/include/asterisk/stasis.h (original)
+++ team/dlee/stasis-cache-split/include/asterisk/stasis.h Tue Jul 9 11:32:07 2013
@@ -514,6 +514,8 @@
/*! @} */
+/*! @{ */
+
/*!
* \brief Pool for topic aggregation
*/
@@ -575,22 +577,17 @@
/*! @{ */
/*!
+ * \brief A message cache, for use with \ref stasis_caching_topic.
+ * \since 12
+ */
+struct stasis_cache;
+
+/*!
* \brief A topic wrapper, which caches certain messages.
* \since 12
*/
struct stasis_caching_topic;
-/*!
- * \brief A message which instructs the caching topic to remove an entry from its cache.
- *
- * \param message Message representative of the cache entry that should be cleared.
- * This will become the data held in the stasis_cache_clear message.
- *
- * \return Message which, when sent to the \a topic, will clear the item from the cache.
- * \return \c NULL on error.
- * \since 12
- */
-struct stasis_message *stasis_cache_clear_create(struct stasis_message *message);
/*!
* \brief Callback extract a unique identity from a snapshot message.
@@ -604,6 +601,21 @@
* \since 12
*/
typedef const char *(*snapshot_get_id)(struct stasis_message *message);
+
+/*!
+ * \brief Create a cache.
+ *
+ * This is the backend store for a \ref stasis_caching_topic. The cache is
+ * thread safe, allowing concurrent reads and writes.
+ *
+ * The returned object is AO2 managed, so ao2_cleanup() when you're done.
+ *
+ * \param id_fn Callback to extract the id from a snapshot message.
+ * \return New cache indexed by \a id_fn.
+ * \return \c NULL on error
+ * \since 12
+ */
+struct stasis_cache *stasis_cache_create(snapshot_get_id id_fn);
/*!
* \brief Create a topic which monitors and caches messages from another topic.
@@ -614,12 +626,30 @@
* the original snapshot message and the new message.
*
* \param original_topic Topic publishing snapshot messages.
- * \param id_fn Callback to extract the id from a snapshot message.
+ * \param cache Backend cache in which to keep snapshots.
* \return New topic which changes snapshot messages to stasis_cache_update()
* messages, and forwards all other messages from the original topic.
- * \since 12
- */
-struct stasis_caching_topic *stasis_caching_topic_create(struct stasis_topic *original_topic, snapshot_get_id id_fn);
+ * \return \c NULL on error
+ * \since 12
+ */
+struct stasis_caching_topic *stasis_caching_topic_create(
+ struct stasis_topic *original_topic, struct stasis_cache *cache);
+
+/*!
+ * \brief Add a secondary cache to a caching topic.
+ *
+ * The secondary cache should identify objects by a different field than the
+ * primary cache. This is useful when snapshots may have multiple unique
+ * identifiers (such as \ref ast_channel's uniqueid and name), and may be looked
+ * up by either.
+ *
+ * \param caching_topic Topic to which to add the secondary cache.
+ * \param cache Secondary cache to add to the topic.
+ * \return 0 on success.
+ * \return -1 on error.
+ */
+int stasis_caching_topic_add_secondary_cache(
+ struct stasis_caching_topic *caching_topic, struct stasis_cache *cache);
/*!
* \brief Unsubscribes a caching topic from its upstream topic.
@@ -651,53 +681,70 @@
/*!
* \brief Returns the topic of cached events from a caching topics.
* \param caching_topic The caching topic.
- * \return The topic that publishes cache update events, along with passthrough events
- * from the underlying topic.
+ * \return The topic that publishes cache update events, along with passthrough
+ * events from the underlying topic.
* \return \c NULL if \a caching_topic is \c NULL.
* \since 12
*/
-struct stasis_topic *stasis_caching_get_topic(struct stasis_caching_topic *caching_topic);
+struct stasis_topic *stasis_caching_get_topic(
+ struct stasis_caching_topic *caching_topic);
+
+/*!
+ * \brief A message which instructs the caching topic to remove an entry from
+ * its cache.
+ *
+ * \param message Message representative of the cache entry that should be
+ * cleared. This will become the data held in the
+ * stasis_cache_clear message.
+ *
+ * \return Message which, when sent to a \ref stasis_caching_topic, will clear
+ * the item from the cache.
+ * \return \c NULL on error.
+ * \since 12
+ */
+struct stasis_message *stasis_cache_clear_create(struct stasis_message *message);
/*!
* \brief Retrieve an item from the cache.
*
* The returned item is AO2 managed, so ao2_cleanup() when you're done with it.
*
- * \param caching_topic The topic returned from stasis_caching_topic_create().
+ * \param cache The cache to query.
* \param type Type of message to retrieve.
* \param id Identity of the snapshot to retrieve.
* \return Message from the cache.
* \return \c NULL if message is not found.
* \since 12
*/
-#define stasis_cache_get(caching_topic, type, id) stasis_cache_get_extended(caching_topic, type, id, 0)
+#define stasis_cache_get(cache, type, id) \
+ stasis_cache_get_extended(cache, type, id, 0)
/*!
* \brief Retrieve an item from the cache.
- * \param caching_topic The topic returned from stasis_caching_topic_create().
+ * \param cache The cache to query.
* \param type Type of message to retrieve.
* \param id Identity of the snapshot to retrieve.
- * \param guaranteed If set to 1 it is guaranteed that any pending messages have been processed.
+ * \param guaranteed If set to 1 it is guaranteed that any pending messages
+ * have been processed.
* \return Message from the cache. The cache still owns the message, so
* ao2_ref() if you want to keep it.
* \return \c NULL if message is not found.
* \since 12
*/
-struct stasis_message *stasis_cache_get_extended(struct stasis_caching_topic *caching_topic,
- struct stasis_message_type *type,
- const char *id,
- unsigned int guaranteed);
+struct stasis_message *stasis_cache_get_extended(
+ struct stasis_cache *cache, struct stasis_message_type *type,
+ const char *id, unsigned int guaranteed);
/*!
* \brief Dump cached items to a subscription
- * \param caching_topic The topic returned from stasis_caching_topic_create().
+ * \param cache The cache to query.
* \param type Type of message to dump (any type if \c NULL).
* \return ao2_container containing all matches (must be unreffed by caller)
* \return \c NULL on allocation error
* \since 12
*/
-struct ao2_container *stasis_cache_dump(struct stasis_caching_topic *caching_topic,
- struct stasis_message_type *type);
+struct ao2_container *stasis_cache_dump(struct stasis_cache *cache,
+ struct stasis_message_type *type);
/*! @} */
Added: 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=auto&rev=393886
==============================================================================
--- team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h (added)
+++ team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h Tue Jul 9 11:32:07 2013
@@ -1,0 +1,112 @@
+/*
+ * Asterisk -- An open source telephony toolkit.
+ *
+ * Copyright (C) 2013, Digium, Inc.
+ *
+ * David M. Lee, II <dlee at digium.com>
+ *
+ * See http://www.asterisk.org for more information about
+ * the Asterisk project. Please do not directly contact
+ * any of the maintainers of this project for assistance;
+ * the project provides a web site, mailing lists and IRC
+ * channels for your use.
+ *
+ * This program is free software, distributed under the terms of
+ * the GNU General Public License Version 2. See the LICENSE file
+ * at the top of the source tree.
+ */
+
+#ifndef _ASTERISK_STASIS_CACHE_PATTERN_H
+#define _ASTERISK_STASIS_CACHE_PATTERN_H
+
+/*! \file
+ *
+ * \brief Caching pattern for \ref stasis topics.
+ *
+ * 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.
+ *
+ * This pattern creates an 'all' side (\ref stasis_cache_all) which contains the
+ * shared cache and aggregator topics.
+ *
+ * For individual topics, there's the 'one' side, which creates the individual
+ * topic and caching topics, along with all the necessary forwarding
+ * subscriptions.
+ */
+
+#include "asterisk/stasis.h"
+
+/*!
+ * \brief The 'all' side of the cache pattern. These are typically built as
+ * global objects for specific modules.
+ */
+struct stasis_cache_all;
+
+/*!
+ * \brief Create an all instance of the cache pattern.
+ *
+ * This object is AO2 managed, so dispose of it with ao2_cleanup().
+ *
+ * \param name Base name of the topics.
+ * \param id_fn Identity function for the cache.
+ * \return All side instance.
+ * \return \c NULL on error.
+ */
+struct stasis_cache_all *stasis_cache_all_create(const char *name,
+ snapshot_get_id id_fn);
+
+/*!
+ * \brief Get the aggregator topic.
+ */
+struct stasis_topic *stasis_cache_all_topic(struct stasis_cache_all *all);
+
+/*!
+ * \brief Get the caching topic.
+ */
+struct stasis_topic *stasis_cache_all_topic_cached(
+ struct stasis_cache_all *all);
+
+/*!
+ * \brief Get the cache.
+ */
+struct stasis_cache *stasis_cache_all_cache(struct stasis_cache_all *all);
+
+/*!
+ * \brief The 'one' side of the cache pattern. These are built per-instance for
+ * some corresponding object, and must be explicitly disposed of using
+ * stasis_cache_one_unsubscribe().
+ */
+struct stasis_cache_one;
+
+/*!
+ * \brief Create the 'one' side of the cache pattern.
+ *
+ * \param all All side which aggregates this topic.
+ * \return One side instance
+ */
+struct stasis_cache_one *stasis_cache_one_create(struct stasis_cache_all *all);
+
+/*!
+ * \brief Call to cancel forwarding of toward the cache aggregator.
+ *
+ * \param one One side of the cache pattern.
+ */
+void stasis_cache_one_unsubscribe(struct stasis_cache_one *one);
+
+/*!
+ * \brief Get the base topic for this instance.
+ *
+ * \param one One side of the cache pattern.
+ */
+struct stasis_topic *stasis_cache_one_topic(struct stasis_cache_one *one);
+
+/*!
+ * \brief Get the caching topic for this instance.
+ *
+ * \param one One side of the cache pattern.
+ */
+struct stasis_topic *stasis_cache_one_topic_cached(
+ struct stasis_cache_one *one);
+
+#endif /* _ASTERISK_STASIS_CACHE_PATTERN_H */
Propchange: team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h
------------------------------------------------------------------------------
svn:keywords = Author Date Id Revision
Propchange: team/dlee/stasis-cache-split/include/asterisk/stasis_cache_pattern.h
------------------------------------------------------------------------------
svn:mime-type = text/plain
More information about the svn-commits
mailing list