<p>Friendly Automation <strong>merged</strong> this change.</p><p><a href="https://gerrit.asterisk.org/c/asterisk/+/11462">View Change</a></p><div style="white-space:pre-wrap">Approvals:
Joshua Colp: Looks good to me, but someone else must approve
George Joseph: Looks good to me, approved
Friendly Automation: Approved for Submit
</div><pre style="font-family: monospace,monospace; white-space: pre-wrap;">stasis_state: Add new stasis_state module<br><br>This new module describes an API that can be thought of as a combination of<br>stasis topic pools, and caching. Except, hopefully done in a more efficient<br>and less memory "leaky" manner.<br><br>The API defines methods, and data structures for managing, and tracking<br>published message state through stasis. By adding a subscriber or publisher,<br>consumers can more easily track the lifetime of the contained state. For<br>instance, when no more publishers and/or subscribers have need of the topic,<br>and associated state its data is removed from the managed container.<br><br>* stasis_state_manager *<br><br>The manager stores and well, manages state data. Each state is an association<br>of a unique stasis topic, and the last known published stasis message on that<br>topic. There is only ever one managed state object per topic. For each topic<br>all messages are forwarded to an "all" topic also maintained by the manager.<br><br>* stasis_state_subscriber *<br><br>Topic and state can be created, or referenced within the manager by adding a<br>stasis_state_subscriber. When adding a subscriber if no state currently exists<br>new managed state is immediately created. If managed state already exists then<br>a new subscriber is created referencing that state. The managed state is<br>guaranteed to live throughout the subscriber's lifetime. State is only removed<br>from the manager when no other entities require it.<br><br>* stasis_state_publisher *<br><br>Topic and state can be created, or referenced within the manager by also adding<br>a stasis_state_publisher. When adding a publisher if no state currently exists<br>new managed state is created. If managed state already exists then a new<br>publisher is created referencing that state. The managed state is guaranteed to<br>live throughout the publisher's lifetime. State is only removed from the<br>manager when no other entities require it.<br><br>* stasis_state_observer *<br><br>Some modules may wish to watch for, and react to managed state events. By<br>registering a state observer, and implementing handlers for the desired<br>callbacks those modules can do so.<br><br>* other *<br><br>Callbacks also exist that allow consumers to iterate over all, or some of the<br>managed state.<br><br>ASTERISK-28442<br><br>Change-Id: I7a4a06685a96e511da9f5bd23f9601642d7bd8e5<br>---<br>A include/asterisk/stasis_state.h<br>A main/stasis_state.c<br>A tests/test_stasis_state.c<br>3 files changed, 1,806 insertions(+), 0 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/include/asterisk/stasis_state.h b/include/asterisk/stasis_state.h</span><br><span>new file mode 100644</span><br><span>index 0000000..a1d3625</span><br><span>--- /dev/null</span><br><span>+++ b/include/asterisk/stasis_state.h</span><br><span>@@ -0,0 +1,549 @@</span><br><span style="color: hsl(120, 100%, 40%);">+/*</span><br><span style="color: hsl(120, 100%, 40%);">+ * Asterisk -- An open source telephony toolkit.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Copyright (C) 2019, Sangoma Technologies Corporation</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Kevin Harwell <kharwell@digium.com></span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * See http://www.asterisk.org for more information about</span><br><span style="color: hsl(120, 100%, 40%);">+ * the Asterisk project. Please do not directly contact</span><br><span style="color: hsl(120, 100%, 40%);">+ * any of the maintainers of this project for assistance;</span><br><span style="color: hsl(120, 100%, 40%);">+ * the project provides a web site, mailing lists and IRC</span><br><span style="color: hsl(120, 100%, 40%);">+ * channels for your use.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This program is free software, distributed under the terms of</span><br><span style="color: hsl(120, 100%, 40%);">+ * the GNU General Public License Version 2. See the LICENSE file</span><br><span style="color: hsl(120, 100%, 40%);">+ * at the top of the source tree.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#ifndef _STASIS_STATE_H</span><br><span style="color: hsl(120, 100%, 40%);">+#define _STASIS_STATE_H</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! \file</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Stasis State API.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \par Intro</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This module defines the data structures, and handling of "state" for topics within</span><br><span style="color: hsl(120, 100%, 40%);">+ * stasis. State is defined as the last stasis message, and its contained message data,</span><br><span style="color: hsl(120, 100%, 40%);">+ * published on a given topic.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Concepts to know:</span><br><span style="color: hsl(120, 100%, 40%);">+ * - \ref stasis_state_manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * - \ref stasis_state_subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ * - \ref stasis_state_publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ * - \ref stasis_state_observer</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \par stasis_state_manager</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * The manager stores and well, manages state data. Each state is an association of</span><br><span style="color: hsl(120, 100%, 40%);">+ * a unique stasis topic, and the last known published stasis message on that topic.</span><br><span style="color: hsl(120, 100%, 40%);">+ * There is only ever one managed state object per topic. For each topic all messages</span><br><span style="color: hsl(120, 100%, 40%);">+ * are forwarded to an "all" topic also maintained by the manager. This allows</span><br><span style="color: hsl(120, 100%, 40%);">+ * subscriptions to all managed topics, and their state. Managed state is created in</span><br><span style="color: hsl(120, 100%, 40%);">+ * one of several ways:</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Adding an explicit subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ * Adding an explicit publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ * Adding an implicit publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ * Retrieving a stasis state topic from the manager via the \ref stasis_state_topic</span><br><span style="color: hsl(120, 100%, 40%);">+ * function prior to doing one of the above (DO NOT DO THIS).</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * More on the first three options later (see relevant section descriptions below). The</span><br><span style="color: hsl(120, 100%, 40%);">+ * last option, creation through retrieving a topic is not only NOT recommended, but</span><br><span style="color: hsl(120, 100%, 40%);">+ * should NOT even BE DONE. Doing so will inevitably result in a memory leak. Why then</span><br><span style="color: hsl(120, 100%, 40%);">+ * is this even allowed? The short answer is backwards compatibility. The slightly longer</span><br><span style="color: hsl(120, 100%, 40%);">+ * answer is at the time of this module's creation that's how things were historically</span><br><span style="color: hsl(120, 100%, 40%);">+ * done using a combination of stasis topic management spread throughout various other</span><br><span style="color: hsl(120, 100%, 40%);">+ * modules, and stasis caching. And yes it did cause a memory leak.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Preferably, any new code wishing to track topics and states should do so by adding</span><br><span style="color: hsl(120, 100%, 40%);">+ * either an explicit subscriber and/or publisher.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \par stasis_state_subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * As mentioned, topic and state can be created, or referenced within the manager by adding</span><br><span style="color: hsl(120, 100%, 40%);">+ * a \ref stasis_state_subscriber. When adding a subscriber if no state currently exists</span><br><span style="color: hsl(120, 100%, 40%);">+ * new managed state is immediately created. If managed state already exists then a new</span><br><span style="color: hsl(120, 100%, 40%);">+ * subscriber is created referencing that state. The managed state is guaranteed to live</span><br><span style="color: hsl(120, 100%, 40%);">+ * throughout the subscriber's lifetime. State is only removed from the manager when no</span><br><span style="color: hsl(120, 100%, 40%);">+ * other entities require it (no more subscribers, or publishers).</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Subscribers are ao2 objects. Therefore there is no explicit cleanup required aside from</span><br><span style="color: hsl(120, 100%, 40%);">+ * dereferencing the subscriber object using normal ao2 dereferencing methods.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \par stasis_state_publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * There are two ways of tracking publishers: explicitly and implicitly.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Topic and state can be created, or referenced within the manager by also explicitly adding</span><br><span style="color: hsl(120, 100%, 40%);">+ * a \ref stasis_state_publisher. When adding a publisher if no state currently exists new</span><br><span style="color: hsl(120, 100%, 40%);">+ * managed state is created. If managed state already exists then a new publisher is created</span><br><span style="color: hsl(120, 100%, 40%);">+ * referencing that state. The managed state is guaranteed to live throughout the publisher's</span><br><span style="color: hsl(120, 100%, 40%);">+ * lifetime. State is only removed from the manager when no other entities require it (no more</span><br><span style="color: hsl(120, 100%, 40%);">+ * publishers, or subscribers).</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Explicit publishers are ao2 objects. Therefore there is no cleanup required aside from</span><br><span style="color: hsl(120, 100%, 40%);">+ * dereferencing the publisher object using normal ao2 dereferencing methods.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * When adding an explicit publisher, messages should be published using the \ref</span><br><span style="color: hsl(120, 100%, 40%);">+ * stasis_state_publish function. This not only skips a lookup, but doesn't add an implicit</span><br><span style="color: hsl(120, 100%, 40%);">+ * publisher. They are not necessarily mutually exclusive it's just that the two ways exist</span><br><span style="color: hsl(120, 100%, 40%);">+ * to solve two different problems.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * For example (using an explicit publisher):</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * // Add an explicit publisher to topic/state "8675309" within</span><br><span style="color: hsl(120, 100%, 40%);">+ * // a given manager context</span><br><span style="color: hsl(120, 100%, 40%);">+ * pub = stasis_state_add_publisher(manager, "8675309");</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * // Publish a stasis message to the topic/state</span><br><span style="color: hsl(120, 100%, 40%);">+ * stasis_state_publish(pub, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * // Publish another a stasis message to the topic/state</span><br><span style="color: hsl(120, 100%, 40%);">+ * stasis_state_publish(pub, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * // Done with the publisher release the reference</span><br><span style="color: hsl(120, 100%, 40%);">+ * ao2_ref(pub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * An implicit publisher can also be created by calling \ref stasis_state_publish_by_id. Calling</span><br><span style="color: hsl(120, 100%, 40%);">+ * this function not only publishes the message within stasis (creating managed state if needed)</span><br><span style="color: hsl(120, 100%, 40%);">+ * it also sets up internal tracking of the publishing module using an \ref ast_eid. However, a</span><br><span style="color: hsl(120, 100%, 40%);">+ * final call to \ref stasis_state_remove_publish_by_id must be done in order to remove the eid</span><br><span style="color: hsl(120, 100%, 40%);">+ * reference, which will subsequently allow the underlying managed state to be eventually deleted.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * For example (using an implicit publisher):</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * // Publish a stasis message to topic/state 8675309 within a</span><br><span style="color: hsl(120, 100%, 40%);">+ * // given manager context and use the system's default eid</span><br><span style="color: hsl(120, 100%, 40%);">+ * stasis_state_publish_by_id(manager, "8675309", NULL, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * // Do some stuff and then publish again</span><br><span style="color: hsl(120, 100%, 40%);">+ * stasis_state_publish_by_id(manager, "8675309", NULL, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * // Done with all our publishing, so post a final clearing</span><br><span style="color: hsl(120, 100%, 40%);">+ * // message and remove the implicit publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ * stasis_state_remove_publish_by_id(manager, "8675309", NULL, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Explicit publisher/publishing is preferred. However, implicit publishing is allowed for those</span><br><span style="color: hsl(120, 100%, 40%);">+ * situations where it makes more sense to do so, but has been implemented mostly for backwards</span><br><span style="color: hsl(120, 100%, 40%);">+ * compatibility with some modules (using implicit publishing required less initial code changes</span><br><span style="color: hsl(120, 100%, 40%);">+ * to some legacy subsystems).</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \par stasis_state_observer</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Some modules may wish to watch for, and react to managed state events. By registering a state</span><br><span style="color: hsl(120, 100%, 40%);">+ * observer, and implementing handlers for the desired callbacks those modules can do so.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk/stasis.h"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct ast_eid;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Manages a collection of stasis states.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Maintains data related to stasis state. Managed state is an association of a unique stasis</span><br><span style="color: hsl(120, 100%, 40%);">+ * topic (named by a given unique id), and the last known published message.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_manager;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Create a stasis state manager.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note The state manager is an ao2_object. When done simply decrement its reference</span><br><span style="color: hsl(120, 100%, 40%);">+ * for object cleanup.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param topic_name The name of the topic to create that all state topics</span><br><span style="color: hsl(120, 100%, 40%);">+ * get forwarded to</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval A stasis state manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if an error occurred</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_manager *stasis_state_manager_create(const char *topic_name);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve the manager's topic (the topic that all state topics get forwarded to)</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The manager object</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval The manager's topic.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_all_topic(struct stasis_state_manager *manager);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve a managed topic creating one if not currently managed.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * WARNING This function should not be called before adding a publisher or subscriber or</span><br><span style="color: hsl(120, 100%, 40%);">+ * it will cause a memory leak within the stasis state manager. This function is here in</span><br><span style="color: hsl(120, 100%, 40%);">+ * order to allow for compatibility with how things used to work.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Also much like the similar functionality from before it returns the stasis topic, but</span><br><span style="color: hsl(120, 100%, 40%);">+ * does not bump its reference.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The manager object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id of/for the topic</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval A managed stasis topic.</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if an error occurred</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_topic(struct stasis_state_manager *manager, const char *id);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * A subscriber to a particular stasis state. As such it holds a reference to the</span><br><span style="color: hsl(120, 100%, 40%);">+ * underlying stasis state, so that managed state is guaranteed to exist for the</span><br><span style="color: hsl(120, 100%, 40%);">+ * lifetime of the subscriber.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_subscriber;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Add a subscriber to the managed stasis state for the given id</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Adds a subscriber to a managed state based on id. If managed state does not already</span><br><span style="color: hsl(120, 100%, 40%);">+ * exists for the given id then new managed state is created. Otherwise the existing</span><br><span style="color: hsl(120, 100%, 40%);">+ * state is subscribed to.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The manager object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id of a managed state</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if an error occurred</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_subscriber *stasis_state_add_subscriber(</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager, const char *id);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Add a subscriber, and subscribe to its underlying stasis topic.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Adds a subscriber to a managed state based on id. If managed state does not already</span><br><span style="color: hsl(120, 100%, 40%);">+ * exists for the given id then new managed state is created. Otherwise the existing</span><br><span style="color: hsl(120, 100%, 40%);">+ * state is subscribed to. If the state is successfully subscribed to then a stasis</span><br><span style="color: hsl(120, 100%, 40%);">+ * subscription is subsequently created as well.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The manager object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id of a managed state</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param callback The stasis subscription callback</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param data A user data object passed to the stasis subscription</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if an error occurred</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_subscriber *stasis_state_subscribe_pool(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ const char *id, stasis_subscription_cb callback, void *data);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Unsubscribe from the stasis topic and stasis state.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void *stasis_state_unsubscribe(struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Unsubscribe from the stasis topic, block until the final message</span><br><span style="color: hsl(120, 100%, 40%);">+ * is received, and then unsubscribe from stasis state.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void *stasis_state_unsubscribe_and_join(struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve the underlying subscribed to state's unique id</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval The managed state's id</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+const char *stasis_state_subscriber_id(const struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve the subscriber's topic</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note Returned topic's reference count is NOT incremented. However, the topic is</span><br><span style="color: hsl(120, 100%, 40%);">+ * guaranteed to live for the lifetime of the subscriber.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval The subscriber's topic</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_subscriber_topic(struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve the last known state stasis message payload for the subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * If a stasis message has been published to this state, this function returns</span><br><span style="color: hsl(120, 100%, 40%);">+ * that message's payload object. If no stasis message has been published on the</span><br><span style="color: hsl(120, 100%, 40%);">+ * state, or the message's payload does not exist then NULL is returned.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note Returned data's reference count is incremented</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval The subscriber's state message data</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if no data has been published yet</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void *stasis_state_subscriber_data(struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve the stasis topic subscription if available.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub A stasis state subscriber</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval The subscriber's stasis subscription</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if no subscription available</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_subscription *stasis_state_subscriber_subscription(</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief A stasis state publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * A publisher to a particular stasis state and topic. As such it holds a reference to</span><br><span style="color: hsl(120, 100%, 40%);">+ * the underlying stasis state, so that managed state is guaranteed to exist for the</span><br><span style="color: hsl(120, 100%, 40%);">+ * lifetime of the publisher.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_publisher;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Add a publisher to the managed state for the given id</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Adds a publisher to a managed state based on id. If managed state does not already</span><br><span style="color: hsl(120, 100%, 40%);">+ * exists for the given id then new managed state is created. Otherwise the existing</span><br><span style="color: hsl(120, 100%, 40%);">+ * state is used.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The manager object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id of a managed state</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval A stasis state publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval NULL if an error occurred</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_publisher *stasis_state_add_publisher(</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager, const char *id);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve the publisher's underlying state's unique id</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param pub A stasis state publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval The managed state's id</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+const char *stasis_state_publisher_id(const struct stasis_state_publisher *pub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve the publisher's topic</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note Returned topic's reference count is NOT incremented. However, the topic is</span><br><span style="color: hsl(120, 100%, 40%);">+ * guaranteed to live for the lifetime of the publisher.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param pub A stasis state publisher</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval The publisher's topic</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_publisher_topic(struct stasis_state_publisher *pub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Publish to a managed state (topic) using a publisher.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param pub The publisher to use to publish the message</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param msg The message to publish</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_publish(struct stasis_state_publisher *pub, struct stasis_message *msg);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Publish to a managed named by id topic, and add an implicit subscriber.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note It is recommended when adding new publisher functionality within a module</span><br><span style="color: hsl(120, 100%, 40%);">+ * to create and use an explicit publisher instead of using this method.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This creates an implicit publisher keyed off the eid. This ability was mainly</span><br><span style="color: hsl(120, 100%, 40%);">+ * implemented in order to maintain compatibility with already established code.</span><br><span style="color: hsl(120, 100%, 40%);">+ * Allowing the creation of an implicit publisher made is so less changes were</span><br><span style="color: hsl(120, 100%, 40%);">+ * required when stasis state module was initially added.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * There should only ever be one publisher for a specifically named managed topic</span><br><span style="color: hsl(120, 100%, 40%);">+ * within the system. This being the case we can use the eid to implicitly track</span><br><span style="color: hsl(120, 100%, 40%);">+ * the publisher. However once publishing is no longer needed for a topic a call</span><br><span style="color: hsl(120, 100%, 40%);">+ * to stasis_state_remove_publish_by_id is required in order to remove the implicit</span><br><span style="color: hsl(120, 100%, 40%);">+ * publisher. Thus allowing for its eventual destruction. Without the call to remove</span><br><span style="color: hsl(120, 100%, 40%);">+ * a memory leak will occur.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The state manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id A state's unique id</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param eid The unique system id</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param msg The message to publish</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_publish_by_id(struct stasis_state_manager *manager, const char *id,</span><br><span style="color: hsl(120, 100%, 40%);">+ const struct ast_eid *eid, struct stasis_message *msg);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Publish to a managed named by id topic, and remove an implicit publisher.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This function should be called after calling stasis_state_publish_by_id at least once</span><br><span style="color: hsl(120, 100%, 40%);">+ * for the same manager, id, and eid. If the given stasis message is NULL then the implicit</span><br><span style="color: hsl(120, 100%, 40%);">+ * publisher is removed, but no last message is published.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * See note and description on stasis_state_publish_by_id for more details about if, and</span><br><span style="color: hsl(120, 100%, 40%);">+ * when this function should be used.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The state manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id A state's unique id</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param eid The unique system id</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param msg The message to publish (can be NULL)</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_remove_publish_by_id(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ const char *id, const struct ast_eid *eid, struct stasis_message *msg);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! \brief Managed stasis state event interface */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_observer {</span><br><span style="color: hsl(120, 100%, 40%);">+ /*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Raised when any managed state is being subscribed.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id of the managed state</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub The subscriber subscribed</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ void (*on_subscribe)(const char *id, struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Raised when any managed state is being unsubscribed.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id of the managed state</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param sub The subscriber to unsubscribe</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ void (*on_unsubscribe)(const char *id, struct stasis_state_subscriber *sub);</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Add an observer to receive managed state related events.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The state manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param observer The observer handling events</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval 0 if successfully registered</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval -1 on failure</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+int stasis_state_add_observer(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_observer *observer);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Remove an observer (will no longer receive managed state related events).</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The state manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param observer The observer being removed</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_remove_observer(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_observer *observer);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief The delegate called for each managed state.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id of a managed state object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param msg The last published message on the state, or NULL</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param user_data Data object the user passed into the manager callback</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval 0 to continue traversing</span><br><span style="color: hsl(120, 100%, 40%);">+ * \retval CMP_STOP (2) to stop traversing</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+typedef int (*on_stasis_state)(const char *id, struct stasis_message *msg, void *user_data);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief For each managed state call the given handler.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The state manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param handler The handler to call for each managed state</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param data User to data to pass on to the handler</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_callback_all(struct stasis_state_manager *manager, on_stasis_state handler,</span><br><span style="color: hsl(120, 100%, 40%);">+ void *data);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief For each managed, and explicitly subscribed state call the given handler.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The state manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param handler The handler to call for each managed state</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param data User to data to pass on to the handler</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 13.28.0</span><br><span style="color: hsl(120, 100%, 40%);">+ * \since 16.5.0</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_callback_subscribed(struct stasis_state_manager *manager, on_stasis_state handler,</span><br><span style="color: hsl(120, 100%, 40%);">+ void *data);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#endif /* _STASIS_STATE_H */</span><br><span>diff --git a/main/stasis_state.c b/main/stasis_state.c</span><br><span>new file mode 100644</span><br><span>index 0000000..2a9afcb</span><br><span>--- /dev/null</span><br><span>+++ b/main/stasis_state.c</span><br><span>@@ -0,0 +1,791 @@</span><br><span style="color: hsl(120, 100%, 40%);">+/*</span><br><span style="color: hsl(120, 100%, 40%);">+ * Asterisk -- An open source telephony toolkit.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Copyright (C) 2019, Sangoma Technologies Corporation</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Kevin Harwell <kharwell@digium.com></span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * See http://www.asterisk.org for more information about</span><br><span style="color: hsl(120, 100%, 40%);">+ * the Asterisk project. Please do not directly contact</span><br><span style="color: hsl(120, 100%, 40%);">+ * any of the maintainers of this project for assistance;</span><br><span style="color: hsl(120, 100%, 40%);">+ * the project provides a web site, mailing lists and IRC</span><br><span style="color: hsl(120, 100%, 40%);">+ * channels for your use.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This program is free software, distributed under the terms of</span><br><span style="color: hsl(120, 100%, 40%);">+ * the GNU General Public License Version 2. See the LICENSE file</span><br><span style="color: hsl(120, 100%, 40%);">+ * at the top of the source tree.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*** MODULEINFO</span><br><span style="color: hsl(120, 100%, 40%);">+ <support_level>core</support_level></span><br><span style="color: hsl(120, 100%, 40%);">+ ***/</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk.h"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk/stasis_state.h"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Associates a stasis topic to its last known published message</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This object's lifetime is tracked by the number of publishers and subscribers to it.</span><br><span style="color: hsl(120, 100%, 40%);">+ * Once all publishers and subscribers have been removed this object is removed from the</span><br><span style="color: hsl(120, 100%, 40%);">+ * manager's collection and destroyed. While a single object type (namely this one) could</span><br><span style="color: hsl(120, 100%, 40%);">+ * be utilized for both publishers, and subscribers this implementation purposely keeps</span><br><span style="color: hsl(120, 100%, 40%);">+ * them separated. This was done to maintain readability, make debugging easier, and allow</span><br><span style="color: hsl(120, 100%, 40%);">+ * for better logging and future enhancements.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state {</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The number of state subscribers */</span><br><span style="color: hsl(120, 100%, 40%);">+ unsigned int num_subscribers;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The manager that owns and handles this state */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! Forwarding information, i.e. this topic to manager's topic */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_forward *forward;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The managed topic */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_topic *topic;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The actual state data */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_message *msg;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * A container of eids. It's assumed that there is only a single publisher per</span><br><span style="color: hsl(120, 100%, 40%);">+ * eid per topic. Thus the publisher is tracked by the system's eid.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR(, struct ast_eid) eids;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! A unique id for this state object. */</span><br><span style="color: hsl(120, 100%, 40%);">+ char id[0];</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+AO2_STRING_FIELD_HASH_FN(stasis_state, id);</span><br><span style="color: hsl(120, 100%, 40%);">+AO2_STRING_FIELD_CMP_FN(stasis_state, id);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! The number of buckets to use for managed states */</span><br><span style="color: hsl(120, 100%, 40%);">+#define STATE_BUCKETS 57</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_manager {</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! Holds all state objects handled by this manager */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct ao2_container *states;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The manager's topic. All state topics are forward to this one */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_topic *all_topic;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! A collection of manager event handlers */</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW(, struct stasis_state_observer *) observers;</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Retrieve a state's topic name without the manager topic.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * State topics have names that consist of the manager's topic name</span><br><span style="color: hsl(120, 100%, 40%);">+ * combined with a unique id separated by a slash. For instance:</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * manager topic's name/unique id</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This method retrieves the unique id part from the state's topic name.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager_topic The manager's topic</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param state_topic A state topic</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return The state's topic unique id</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static const char *state_id_by_topic(struct stasis_topic *manager_topic,</span><br><span style="color: hsl(120, 100%, 40%);">+ const struct stasis_topic *state_topic)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ const char *id;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* This topic should always belong to the manager */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_assert(ast_begins_with(stasis_topic_name(manager_topic),</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_topic_name(state_topic)));</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ id = strchr(stasis_topic_name(state_topic), '/');</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* The state's unique id should always exist */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_assert(id != NULL && (id + 1) != NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return (id + 1);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static void state_dtor(void *obj)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state = obj;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state->forward = stasis_forward_cancel(state->forward);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_cleanup(state->topic);</span><br><span style="color: hsl(120, 100%, 40%);">+ state->topic = NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_cleanup(state->msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ state->msg = NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_cleanup(state->manager);</span><br><span style="color: hsl(120, 100%, 40%);">+ state->manager = NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* All eids should have been removed */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_assert(AST_VECTOR_SIZE(&state->eids) == 0);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_FREE(&state->eids);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Allocate a stasis state object.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Create and initialize a state structure. It's required that either a state</span><br><span style="color: hsl(120, 100%, 40%);">+ * topic, or an id is specified. If a state topic is not given then one will be</span><br><span style="color: hsl(120, 100%, 40%);">+ * created using the given id.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The owning manager</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param state_topic A state topic to be managed</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id for the state</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return A stasis_state object or NULL</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return NULL on error</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static struct stasis_state *state_alloc(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_topic *state_topic, const char *id)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state_topic) {</span><br><span style="color: hsl(120, 100%, 40%);">+ char *name;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* If not given a state topic, then an id is required */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_assert(id != NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * To provide further detail and to ensure that the topic is unique within the</span><br><span style="color: hsl(120, 100%, 40%);">+ * scope of the system we prefix it with the manager's topic name, which should</span><br><span style="color: hsl(120, 100%, 40%);">+ * itself already be unique.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ if (ast_asprintf(&name, "%s/%s", stasis_topic_name(manager->all_topic), id) < 0) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to create state topic name '%s/%s'\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_topic_name(manager->all_topic), id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state_topic = stasis_topic_create(name);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state_topic) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to create state topic '%s'\n", name);</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_free(name);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_free(name);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!id) {</span><br><span style="color: hsl(120, 100%, 40%);">+ /* If not given an id, then a state topic is required */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_assert(state_topic != NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* Get the id we'll key off of from the state topic */</span><br><span style="color: hsl(120, 100%, 40%);">+ id = state_id_by_topic(manager->all_topic, state_topic);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * Since the state topic could have been passed in, go ahead and bump its reference.</span><br><span style="color: hsl(120, 100%, 40%);">+ * By doing this here first, it allows us to consistently decrease the reference on</span><br><span style="color: hsl(120, 100%, 40%);">+ * state allocation error.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state_topic, +1);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state = ao2_alloc(sizeof(*state) + strlen(id) + 1, state_dtor);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to allocate state '%s' in manager '%s'\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ id, stasis_topic_name(manager->all_topic));</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state_topic, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ strcpy(state->id, id); /* Safe */</span><br><span style="color: hsl(120, 100%, 40%);">+ state->topic = state_topic; /* ref already bumped above */</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state->forward = stasis_forward_all(state->topic, manager->all_topic);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state->forward) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to add state '%s' forward in manager '%s'\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ id, stasis_topic_name(manager->all_topic));</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (AST_VECTOR_INIT(&state->eids, 2)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to initialize eids for state '%s' in manager '%s'\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ id, stasis_topic_name(manager->all_topic));</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state->manager = ao2_bump(manager);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return state;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Create a state object, and add it to the manager.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note Locking on the states container is specifically not done here, thus</span><br><span style="color: hsl(120, 100%, 40%);">+ * appropriate locks should be applied prior to this function being called.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The manager to be added to</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param state_topic A state topic to be managed (if NULL id is required)</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id for the state (if NULL state_topic is required)</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return The added state object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return NULL on error</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static struct stasis_state *state_add(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_topic *state_topic, const char *id)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state = state_alloc(manager, state_topic, id);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!ao2_link_flags(manager->states, state, OBJ_NOLOCK)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to add state '%s' to manager '%s'\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ state->id ? state->id : "", stasis_topic_name(manager->all_topic));</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return state;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Find a state by id, or create one if not found and add it to the manager.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note Locking on the states container is specifically not done here, thus</span><br><span style="color: hsl(120, 100%, 40%);">+ * appropriate locks should be applied prior to this function being called.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param manager The manager to be added to</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param state_topic A state topic to be managed (if NULL id is required)</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param id The unique id for the state (if NULL state_topic is required)</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return The added state object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \return NULL on error</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static struct stasis_state *state_find_or_add(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_topic *state_topic, const char *id)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (ast_strlen_zero(id)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ id = state_id_by_topic(manager->all_topic, state_topic);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state = ao2_find(manager->states, id, OBJ_SEARCH_KEY | OBJ_NOLOCK);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return state ? state : state_add(manager, state_topic, id);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static void state_manager_dtor(void *obj)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager = obj;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#ifdef AO2_DEBUG</span><br><span style="color: hsl(120, 100%, 40%);">+ {</span><br><span style="color: hsl(120, 100%, 40%);">+ char *container_name =</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_alloca(strlen(stasis_topic_name(manager->all_topic)) + strlen("-manager") + 1);</span><br><span style="color: hsl(120, 100%, 40%);">+ sprintf(container_name, "%s-manager", stasis_topic_name(manager->all_topic));</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_container_unregister(container_name);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+#endif</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_cleanup(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ manager->states = NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_cleanup(manager->all_topic);</span><br><span style="color: hsl(120, 100%, 40%);">+ manager->all_topic = NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_FREE(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#ifdef AO2_DEBUG</span><br><span style="color: hsl(120, 100%, 40%);">+static void state_prnt_obj(void *v_obj, void *where, ao2_prnt_fn *prnt)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state = v_obj;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ prnt(where, "%s", stasis_topic_name(state->topic));</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+#endif</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_manager *stasis_state_manager_create(const char *topic_name)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ manager = ao2_alloc_options(sizeof(*manager), state_manager_dtor,</span><br><span style="color: hsl(120, 100%, 40%);">+ AO2_ALLOC_OPT_LOCK_NOLOCK);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!manager) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ manager->states = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0,</span><br><span style="color: hsl(120, 100%, 40%);">+ STATE_BUCKETS, stasis_state_hash_fn, NULL, stasis_state_cmp_fn);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!manager->states) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(manager, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ manager->all_topic = stasis_topic_create(topic_name);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!manager->all_topic) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(manager, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (AST_VECTOR_RW_INIT(&manager->observers, 2) != 0) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(manager, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#ifdef AO2_DEBUG</span><br><span style="color: hsl(120, 100%, 40%);">+ {</span><br><span style="color: hsl(120, 100%, 40%);">+ char *container_name =</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_alloca(strlen(stasis_topic_name(manager->all_topic)) + strlen("-manager") + 1);</span><br><span style="color: hsl(120, 100%, 40%);">+ sprintf(container_name, "%s-manager", stasis_topic_name(manager->all_topic));</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_container_register(container_name, manager->states, state_prnt_obj);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+#endif</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return manager;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_all_topic(struct stasis_state_manager *manager)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return manager->all_topic;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_topic(struct stasis_state_manager *manager, const char *id)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_topic *topic;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ state = state_find_or_add(manager, NULL, id);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ topic = state->topic;</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return topic;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Remove a state from the stasis manager</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * State should only be removed from the manager under the following conditions:</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * There are no more subscribers to it</span><br><span style="color: hsl(120, 100%, 40%);">+ * There are no more explicit publishers publishing to it</span><br><span style="color: hsl(120, 100%, 40%);">+ * There are no more implicit publishers publishing to it</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Subscribers and explicit publishers hold a reference to the state object itself, so</span><br><span style="color: hsl(120, 100%, 40%);">+ * once a state's reference count drops to 2 (1 for the manager, 1 passed in) then we</span><br><span style="color: hsl(120, 100%, 40%);">+ * know there are no more subscribers or explicit publishers. Implicit publishers are</span><br><span style="color: hsl(120, 100%, 40%);">+ * tracked by eids, so once that container is empty no more implicit publishers exist</span><br><span style="color: hsl(120, 100%, 40%);">+ * for the state either. Only then can a state be removed.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param state The state to remove</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static void state_remove(struct stasis_state *state)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * The manager's state container also needs to be locked here prior to checking</span><br><span style="color: hsl(120, 100%, 40%);">+ * the state's reference count, and potentially removing since we don't want its</span><br><span style="color: hsl(120, 100%, 40%);">+ * count to possibly increase between the check and unlinking.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(state->manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * If there are only 2 references left then it's the one owned by the manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ * and the one passed in to this function. However, before removing it from the</span><br><span style="color: hsl(120, 100%, 40%);">+ * manager we need to also check that no eid is associated with the given state.</span><br><span style="color: hsl(120, 100%, 40%);">+ * If an eid still remains then this means that an implicit publisher is still</span><br><span style="color: hsl(120, 100%, 40%);">+ * publishing to this state.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ if (ao2_ref(state, 0) == 2 && AST_VECTOR_SIZE(&state->eids) == 0) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlink_flags(state->manager->states, state, 0);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(state->manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* Now it's safe to remove the reference that is held on the given state */</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_subscriber {</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The stasis state subscribed to */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state;</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The stasis subscription. */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_subscription *stasis_sub;</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static void subscriber_dtor(void *obj)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_subscriber *sub = obj;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager = sub->state->manager;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_RDLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < AST_VECTOR_SIZE(&manager->observers); ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ if (AST_VECTOR_GET(&manager->observers, i)->on_unsubscribe) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_GET(&manager->observers, i)->on_unsubscribe(sub->state->id, sub);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_UNLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(sub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+ --sub->state->num_subscribers;</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(sub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state_remove(sub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_subscriber *stasis_state_add_subscriber(</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager, const char *id)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_subscriber *sub = ao2_alloc_options(</span><br><span style="color: hsl(120, 100%, 40%);">+ sizeof(*sub), subscriber_dtor, AO2_ALLOC_OPT_LOCK_NOLOCK);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!sub) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to create subscriber to %s/%s\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_topic_name(manager->all_topic), id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ sub->state = state_find_or_add(manager, NULL, id);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!sub->state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(sub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(sub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+ ++sub->state->num_subscribers;</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(sub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_RDLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < AST_VECTOR_SIZE(&manager->observers); ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ if (AST_VECTOR_GET(&manager->observers, i)->on_subscribe) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_GET(&manager->observers, i)->on_subscribe(id, sub);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_UNLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return sub;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_subscriber *stasis_state_subscribe_pool(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ const char *id, stasis_subscription_cb callback, void *data)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_topic *topic;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_subscriber *sub = stasis_state_add_subscriber(manager, id);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!sub) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ topic = sub->state->topic;</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_debug(3, "Creating stasis state subscription to id '%s'. Topic: '%s':%p %d\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ id, stasis_topic_name(topic), topic, (int)ao2_ref(topic, 0));</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ sub->stasis_sub = stasis_subscribe_pool(topic, callback, data);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!sub->stasis_sub) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(sub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return sub;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void *stasis_state_unsubscribe(struct stasis_state_subscriber *sub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ sub->stasis_sub = stasis_unsubscribe(sub->stasis_sub);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(sub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void *stasis_state_unsubscribe_and_join(struct stasis_state_subscriber *sub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ sub->stasis_sub = stasis_unsubscribe_and_join(sub->stasis_sub);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(sub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+const char *stasis_state_subscriber_id(const struct stasis_state_subscriber *sub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return sub->state->id;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_subscriber_topic(struct stasis_state_subscriber *sub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return sub->state->topic;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void *stasis_state_subscriber_data(struct stasis_state_subscriber *sub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ void *res;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * The data's reference needs to be bumped before returning so it doesn't disappear</span><br><span style="color: hsl(120, 100%, 40%);">+ * for the caller. Lock state, so the underlying message data is not replaced while</span><br><span style="color: hsl(120, 100%, 40%);">+ * retrieving.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(sub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+ res = ao2_bump(stasis_message_data(sub->state->msg));</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(sub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return res;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_subscription *stasis_state_subscriber_subscription(</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_subscriber *sub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return sub->stasis_sub;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_publisher {</span><br><span style="color: hsl(120, 100%, 40%);">+ /*! The stasis state to publish to */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state;</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static void publisher_dtor(void *obj)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_publisher *pub = obj;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state_remove(pub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_publisher *stasis_state_add_publisher(</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_manager *manager, const char *id)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_publisher *pub = ao2_alloc_options(</span><br><span style="color: hsl(120, 100%, 40%);">+ sizeof(*pub), publisher_dtor, AO2_ALLOC_OPT_LOCK_NOLOCK);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!pub) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to create publisher to %s/%s\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_topic_name(manager->all_topic), id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ pub->state = state_find_or_add(manager, NULL, id);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!pub->state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(pub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return pub;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+const char *stasis_state_publisher_id(const struct stasis_state_publisher *pub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return pub->state->id;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_topic *stasis_state_publisher_topic(struct stasis_state_publisher *pub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ return pub->state->topic;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_publish(struct stasis_state_publisher *pub, struct stasis_message *msg)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(pub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_replace(pub->state->msg, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(pub->state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_publish(pub->state->topic, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Find, or add the given eid to the state object</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Publishers can be tracked implicitly using eids. This allows us to add, and subsequently</span><br><span style="color: hsl(120, 100%, 40%);">+ * remove state objects from the managed states container in a deterministic way. Using the</span><br><span style="color: hsl(120, 100%, 40%);">+ * eids in this way is possible because it's guaranteed that there will only ever be a single</span><br><span style="color: hsl(120, 100%, 40%);">+ * publisher for a uniquely named topic (topics tracked by this module) on a system.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note The vector does not use locking. Instead we use the state object for that, so it</span><br><span style="color: hsl(120, 100%, 40%);">+ * needs to be locked prior to calling this method.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param state The state object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param eid The system id to add to the state object</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static void state_find_or_add_eid(struct stasis_state *state, const struct ast_eid *eid)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!eid) {</span><br><span style="color: hsl(120, 100%, 40%);">+ eid = &ast_eid_default;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < AST_VECTOR_SIZE(&state->eids); ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!ast_eid_cmp(AST_VECTOR_GET_ADDR(&state->eids, i), eid)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (i == AST_VECTOR_SIZE(&state->eids)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_APPEND(&state->eids, *eid);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * \internal</span><br><span style="color: hsl(120, 100%, 40%);">+ * \brief Find, and remove the given eid from the state object</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Used to remove an eid from an implicit publisher.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \note The vector does not use locking. Instead we use the state object for that, so it</span><br><span style="color: hsl(120, 100%, 40%);">+ * needs to be locked prior to calling this method.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param state The state object</span><br><span style="color: hsl(120, 100%, 40%);">+ * \param eid The system id to remove from the state object</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static void state_find_and_remove_eid(struct stasis_state *state, const struct ast_eid *eid)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!eid) {</span><br><span style="color: hsl(120, 100%, 40%);">+ eid = &ast_eid_default;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < AST_VECTOR_SIZE(&state->eids); ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!ast_eid_cmp(AST_VECTOR_GET_ADDR(&state->eids, i), eid)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_REMOVE_UNORDERED(&state->eids, i);</span><br><span style="color: hsl(120, 100%, 40%);">+ return;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_publish_by_id(struct stasis_state_manager *manager, const char *id,</span><br><span style="color: hsl(120, 100%, 40%);">+ const struct ast_eid *eid, struct stasis_message *msg)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+ state = state_find_or_add(manager, NULL, id);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(manager->states);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+ state_find_or_add_eid(state, eid);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_replace(state->msg, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_publish(state->topic, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(state, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_remove_publish_by_id(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ const char *id, const struct ast_eid *eid, struct stasis_message *msg)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state = ao2_find(manager->states, id, OBJ_SEARCH_KEY);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!state) {</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * In most circumstances state should already exist here. However, if there is no</span><br><span style="color: hsl(120, 100%, 40%);">+ * state then it can mean one of a few things:</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * 1. This function was called prior to an implicit publish for the same given</span><br><span style="color: hsl(120, 100%, 40%);">+ * manager, and id.</span><br><span style="color: hsl(120, 100%, 40%);">+ * 2. This function was called more than once for the same manager, and id.</span><br><span style="color: hsl(120, 100%, 40%);">+ * 3. There is ref count problem with the explicit subscribers, and publishers.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_debug(5, "Attempted to remove state for id '%s', but state not found\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (msg) {</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_publish(state->topic, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+ state_find_and_remove_eid(state, eid);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ state_remove(state);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+int stasis_state_add_observer(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_observer *observer)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ int res;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_WRLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+ res = AST_VECTOR_APPEND(&manager->observers, observer);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_UNLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return res;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_remove_observer(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_observer *observer)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_WRLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_REMOVE_ELEM_UNORDERED(&manager->observers, observer, AST_VECTOR_ELEM_CLEANUP_NOOP);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_RW_UNLOCK(&manager->observers);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int handle_stasis_state(void *obj, void *arg, void *data, int flags)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state = obj;</span><br><span style="color: hsl(120, 100%, 40%);">+ on_stasis_state handler = arg;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_message *msg;</span><br><span style="color: hsl(120, 100%, 40%);">+ int res;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * State needs to be locked here while we retrieve and bump the reference on its message</span><br><span style="color: hsl(120, 100%, 40%);">+ * object. Doing so guarantees the message object will live throughout its handling.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_lock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+ msg = ao2_bump(state->msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_unlock(state);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ res = handler(state->id, msg, data);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_cleanup(msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ return res;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_callback_all(struct stasis_state_manager *manager, on_stasis_state handler,</span><br><span style="color: hsl(120, 100%, 40%);">+ void *data)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_assert(handler != NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_callback_data(manager->states, OBJ_MULTIPLE | OBJ_NODATA,</span><br><span style="color: hsl(120, 100%, 40%);">+ handle_stasis_state, handler, data);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int handle_stasis_state_subscribed(void *obj, void *arg, void *data, int flags)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state *state = obj;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (state->num_subscribers) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return handle_stasis_state(obj, arg, data, flags);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+void stasis_state_callback_subscribed(struct stasis_state_manager *manager, on_stasis_state handler,</span><br><span style="color: hsl(120, 100%, 40%);">+ void *data)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_assert(handler != NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_callback_data(manager->states, OBJ_MULTIPLE | OBJ_NODATA,</span><br><span style="color: hsl(120, 100%, 40%);">+ handle_stasis_state_subscribed, handler, data);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span>diff --git a/tests/test_stasis_state.c b/tests/test_stasis_state.c</span><br><span>new file mode 100644</span><br><span>index 0000000..3ad450d</span><br><span>--- /dev/null</span><br><span>+++ b/tests/test_stasis_state.c</span><br><span>@@ -0,0 +1,466 @@</span><br><span style="color: hsl(120, 100%, 40%);">+/*</span><br><span style="color: hsl(120, 100%, 40%);">+ * Asterisk -- An open source telephony toolkit.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Copyright (C) 2019, Sangoma Technologies Corporation</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * Kevin Harwell <kharwell@digium.com></span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * See http://www.asterisk.org for more information about</span><br><span style="color: hsl(120, 100%, 40%);">+ * the Asterisk project. Please do not directly contact</span><br><span style="color: hsl(120, 100%, 40%);">+ * any of the maintainers of this project for assistance;</span><br><span style="color: hsl(120, 100%, 40%);">+ * the project provides a web site, mailing lists and IRC</span><br><span style="color: hsl(120, 100%, 40%);">+ * channels for your use.</span><br><span style="color: hsl(120, 100%, 40%);">+ *</span><br><span style="color: hsl(120, 100%, 40%);">+ * This program is free software, distributed under the terms of</span><br><span style="color: hsl(120, 100%, 40%);">+ * the GNU General Public License Version 2. See the LICENSE file</span><br><span style="color: hsl(120, 100%, 40%);">+ * at the top of the source tree.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*** MODULEINFO</span><br><span style="color: hsl(120, 100%, 40%);">+ <depend>TEST_FRAMEWORK</depend></span><br><span style="color: hsl(120, 100%, 40%);">+ <support_level>core</support_level></span><br><span style="color: hsl(120, 100%, 40%);">+ ***/</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk.h"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk/astobj2.h"</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk/conversions.h"</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk/module.h"</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk/stasis_state.h"</span><br><span style="color: hsl(120, 100%, 40%);">+#include "asterisk/test.h"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#define test_category "/stasis/core/state/"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#define TOPIC_COUNT 500</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+#define MANAGER_TOPIC "foo"</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_message_type *foo_type(void);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! foo stasis message type */</span><br><span style="color: hsl(120, 100%, 40%);">+STASIS_MESSAGE_TYPE_DEFN(foo_type);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! foo_type data */</span><br><span style="color: hsl(120, 100%, 40%);">+struct foo_data {</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t bar;</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+AST_VECTOR(subscriptions, struct stasis_state_subscriber *);</span><br><span style="color: hsl(120, 100%, 40%);">+AST_VECTOR(publishers, struct stasis_state_publisher *);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*!</span><br><span style="color: hsl(120, 100%, 40%);">+ * For testing purposes each subscribed state's id is a number. This value is</span><br><span style="color: hsl(120, 100%, 40%);">+ * the summation of all id's.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+static size_t sum_total;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! Test variable that tracks the running total of state ids */</span><br><span style="color: hsl(120, 100%, 40%);">+static size_t running_total;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+/*! This value is set to check if state data is NULL before publishing */</span><br><span style="color: hsl(120, 100%, 40%);">+static int expect_null;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int validate_data(const char *id, struct foo_data *foo)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t num;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (ast_str_to_umax(id, &num)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to convert the state's id '%s' to numeric\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total += num;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!foo) {</span><br><span style="color: hsl(120, 100%, 40%);">+ if (expect_null) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Expected state data for '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (expect_null) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Expected NULL state data for '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (foo->bar != num) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unexpected state data for '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static void handle_validate(const char *id, struct stasis_state_subscriber *sub)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct foo_data *foo = stasis_state_subscriber_data(sub);</span><br><span style="color: hsl(120, 100%, 40%);">+ validate_data(id, foo);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_cleanup(foo);</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+struct stasis_state_observer foo_observer = {</span><br><span style="color: hsl(120, 100%, 40%);">+ .on_subscribe = handle_validate,</span><br><span style="color: hsl(120, 100%, 40%);">+ .on_unsubscribe = handle_validate</span><br><span style="color: hsl(120, 100%, 40%);">+};</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static void foo_type_cb(void *data, struct stasis_subscription *sub, struct stasis_message *message)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ /* No op since we are not really testing stasis topic handling here */</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int subscriptions_destroy(struct stasis_state_manager *manager, struct subscriptions *subs)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total = expect_null = 0;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_CALLBACK_VOID(subs, stasis_state_unsubscribe_and_join);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_FREE(subs);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_state_remove_observer(manager, &foo_observer);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (running_total != sum_total) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to destroy all subscriptions: running=%zu, sum=%zu\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total, sum_total);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int subscriptions_create(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct subscriptions *subs)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (stasis_state_add_observer(manager, &foo_observer) ||</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_INIT(subs, TOPIC_COUNT)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ sum_total = running_total = 0;</span><br><span style="color: hsl(120, 100%, 40%);">+ expect_null = 1;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < TOPIC_COUNT; ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_subscriber *sub;</span><br><span style="color: hsl(120, 100%, 40%);">+ char id[32];</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (snprintf(id, 10, "%zu", i) == -1) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to convert subscriber id to string\n");</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ sub = stasis_state_subscribe_pool(manager, id, foo_type_cb, NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!sub) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to create a state subscriber for id '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(sub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (AST_VECTOR_APPEND(subs, sub)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to add to foo_sub to vector for id '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(sub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ sum_total += i;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (i != TOPIC_COUNT || running_total != sum_total) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to create all subscriptions: running=%zu, sum=%zu\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total, sum_total);</span><br><span style="color: hsl(120, 100%, 40%);">+ subscriptions_destroy(manager, subs);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int publishers_destroy(struct stasis_state_manager *manager, struct publishers *pubs)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (pubs) {</span><br><span style="color: hsl(120, 100%, 40%);">+ /* Remove explicit publishers */</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_CALLBACK_VOID(pubs, ao2_cleanup);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_VECTOR_FREE(pubs);</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < TOPIC_COUNT; ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ char id[32];</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* Remove implicit publishers */</span><br><span style="color: hsl(120, 100%, 40%);">+ if (snprintf(id, 10, "%zu", i) == -1) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to convert publisher id to string\n");</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_state_remove_publish_by_id(manager, id, NULL, NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int publishers_create(struct stasis_state_manager *manager,</span><br><span style="color: hsl(120, 100%, 40%);">+ struct publishers *pubs)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (AST_VECTOR_INIT(pubs, TOPIC_COUNT)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < TOPIC_COUNT; ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_publisher *pub;</span><br><span style="color: hsl(120, 100%, 40%);">+ char id[32];</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (snprintf(id, 10, "%zu", i) == -1) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to convert publisher id to string\n");</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* Create the state publisher */</span><br><span style="color: hsl(120, 100%, 40%);">+ pub = stasis_state_add_publisher(manager, id);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!pub) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to create a state publisher for id '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (AST_VECTOR_APPEND(pubs, pub)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to add to publisher to vector for id '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(pub, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (i != TOPIC_COUNT) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to create all publishers: count=%zu\n", i);</span><br><span style="color: hsl(120, 100%, 40%);">+ publishers_destroy(manager, pubs);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static struct stasis_message *create_foo_type_message(const char *id)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_message *msg;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct foo_data *foo;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ foo = ao2_alloc(sizeof(*foo), NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!foo) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to allocate foo data for '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (ast_str_to_umax(id, &foo->bar)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to convert the state's id '%s' to numeric\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(foo, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ msg = stasis_message_create_full(foo_type(), foo, NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!msg) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed to create stasis message for '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(foo, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+ return msg;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int implicit_publish_cb(const char *id, struct stasis_message *msg, void *user_data)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ /* For each state object create and publish new state data */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct foo_data *foo = stasis_message_data(msg);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (validate_data(id, foo)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return CMP_STOP;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ msg = create_foo_type_message(id);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!msg) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return CMP_STOP;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* Now publish it on the managed state object */</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_state_publish_by_id(user_data, id, NULL, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(msg, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int explicit_publish_cb(const char *id, struct stasis_message *msg, void *user_data)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ /* For each state object create and publish new state data */</span><br><span style="color: hsl(120, 100%, 40%);">+ struct publishers *pubs = user_data;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct stasis_state_publisher *pub = NULL;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct foo_data *foo = stasis_message_data(msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ size_t i;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (validate_data(id, foo)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return CMP_STOP;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ msg = create_foo_type_message(id);</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!msg) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return CMP_STOP;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ for (i = 0; i < AST_VECTOR_SIZE(pubs); ++i) {</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!strcmp(stasis_state_publisher_id(AST_VECTOR_GET(pubs, i)), id)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ pub = AST_VECTOR_GET(pubs, i);</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (!pub) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Unable to locate publisher for id '%s'\n", id);</span><br><span style="color: hsl(120, 100%, 40%);">+ return CMP_STOP;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_state_publish(pub, msg);</span><br><span style="color: hsl(120, 100%, 40%);">+ ao2_ref(msg, -1);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int publish(struct stasis_state_manager *manager, on_stasis_state cb,</span><br><span style="color: hsl(120, 100%, 40%);">+ void *user_data)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ /* First time there is no state data */</span><br><span style="color: hsl(120, 100%, 40%);">+ expect_null = 1;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total = 0;</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_state_callback_all(manager, cb, user_data);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (running_total != sum_total) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed manager_callback (1): running=%zu, sum=%zu\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total, sum_total);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /* Second time check valid state data exists */</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total = expect_null = 0;</span><br><span style="color: hsl(120, 100%, 40%);">+ stasis_state_callback_all(manager, cb, user_data);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ if (running_total != sum_total) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Failed manager_callback (2): running=%zu, sum=%zu\n",</span><br><span style="color: hsl(120, 100%, 40%);">+ running_total, sum_total);</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+AST_TEST_DEFINE(implicit_publish)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ RAII_VAR(struct stasis_state_manager *, manager, NULL, ao2_cleanup);</span><br><span style="color: hsl(120, 100%, 40%);">+ struct subscriptions subs;</span><br><span style="color: hsl(120, 100%, 40%);">+ int rc = AST_TEST_PASS;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ switch (cmd) {</span><br><span style="color: hsl(120, 100%, 40%);">+ case TEST_INIT:</span><br><span style="color: hsl(120, 100%, 40%);">+ info->name = __func__;</span><br><span style="color: hsl(120, 100%, 40%);">+ info->category = test_category;</span><br><span style="color: hsl(120, 100%, 40%);">+ info->summary = "Test implicit publishing of stasis state";</span><br><span style="color: hsl(120, 100%, 40%);">+ info->description = info->summary;</span><br><span style="color: hsl(120, 100%, 40%);">+ return AST_TEST_NOT_RUN;</span><br><span style="color: hsl(120, 100%, 40%);">+ case TEST_EXECUTE:</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ manager = stasis_state_manager_create(MANAGER_TOPIC);</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_test_validate(test, manager != NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_test_validate(test, !subscriptions_create(manager, &subs));</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_test_validate_cleanup(test, !publish(manager, implicit_publish_cb, manager),</span><br><span style="color: hsl(120, 100%, 40%);">+ rc, cleanup);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+cleanup:</span><br><span style="color: hsl(120, 100%, 40%);">+ if (subscriptions_destroy(manager, &subs) || publishers_destroy(manager, NULL)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return AST_TEST_FAIL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * State subscriptions add a ref a state. The state in turn adds a ref</span><br><span style="color: hsl(120, 100%, 40%);">+ * to the manager. So if more than one ref is held on the manager before</span><br><span style="color: hsl(120, 100%, 40%);">+ * exiting, there is a ref leak some place.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ if (ao2_ref(manager, 0) != 1) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Memory leak - Too many references held on manager\n");</span><br><span style="color: hsl(120, 100%, 40%);">+ return AST_TEST_FAIL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return rc;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+AST_TEST_DEFINE(explicit_publish)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ RAII_VAR(struct stasis_state_manager *, manager, NULL, ao2_cleanup);</span><br><span style="color: hsl(120, 100%, 40%);">+ struct subscriptions subs;</span><br><span style="color: hsl(120, 100%, 40%);">+ struct publishers pubs;</span><br><span style="color: hsl(120, 100%, 40%);">+ int rc = AST_TEST_PASS;</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ switch (cmd) {</span><br><span style="color: hsl(120, 100%, 40%);">+ case TEST_INIT:</span><br><span style="color: hsl(120, 100%, 40%);">+ info->name = __func__;</span><br><span style="color: hsl(120, 100%, 40%);">+ info->category = test_category;</span><br><span style="color: hsl(120, 100%, 40%);">+ info->summary = "Test explicit publishing of stasis state";</span><br><span style="color: hsl(120, 100%, 40%);">+ info->description = info->summary;</span><br><span style="color: hsl(120, 100%, 40%);">+ return AST_TEST_NOT_RUN;</span><br><span style="color: hsl(120, 100%, 40%);">+ case TEST_EXECUTE:</span><br><span style="color: hsl(120, 100%, 40%);">+ break;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ manager = stasis_state_manager_create(MANAGER_TOPIC);</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_test_validate(test, manager != NULL);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_test_validate(test, !subscriptions_create(manager, &subs));</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_test_validate_cleanup(test, !publishers_create(manager, &pubs), rc, cleanup);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_test_validate_cleanup(test, !publish(manager, explicit_publish_cb, &pubs),</span><br><span style="color: hsl(120, 100%, 40%);">+ rc, cleanup);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+cleanup:</span><br><span style="color: hsl(120, 100%, 40%);">+ if (subscriptions_destroy(manager, &subs) || publishers_destroy(manager, &pubs)) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return AST_TEST_FAIL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ /*</span><br><span style="color: hsl(120, 100%, 40%);">+ * State subscriptions add a ref a state. The state in turn adds a ref</span><br><span style="color: hsl(120, 100%, 40%);">+ * to the manager. So if more than one ref is held on the manager before</span><br><span style="color: hsl(120, 100%, 40%);">+ * exiting, there is a ref leak some place.</span><br><span style="color: hsl(120, 100%, 40%);">+ */</span><br><span style="color: hsl(120, 100%, 40%);">+ if (ao2_ref(manager, 0) != 1) {</span><br><span style="color: hsl(120, 100%, 40%);">+ ast_log(LOG_ERROR, "Memory leak - Too many references held on manager\n");</span><br><span style="color: hsl(120, 100%, 40%);">+ return AST_TEST_FAIL;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return rc;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int unload_module(void)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_TEST_UNREGISTER(implicit_publish);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_TEST_UNREGISTER(explicit_publish);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ STASIS_MESSAGE_TYPE_CLEANUP(foo_type);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return 0;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+static int load_module(void)</span><br><span style="color: hsl(120, 100%, 40%);">+{</span><br><span style="color: hsl(120, 100%, 40%);">+ if (STASIS_MESSAGE_TYPE_INIT(foo_type) != 0) {</span><br><span style="color: hsl(120, 100%, 40%);">+ return -1;</span><br><span style="color: hsl(120, 100%, 40%);">+ }</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_TEST_REGISTER(implicit_publish);</span><br><span style="color: hsl(120, 100%, 40%);">+ AST_TEST_REGISTER(explicit_publish);</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+ return AST_MODULE_LOAD_SUCCESS;</span><br><span style="color: hsl(120, 100%, 40%);">+}</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+AST_MODULE_INFO_STANDARD(ASTERISK_GPL_KEY, "Stasis state testing");</span><br><span></span><br></pre><p>To view, visit <a href="https://gerrit.asterisk.org/c/asterisk/+/11462">change 11462</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://gerrit.asterisk.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://gerrit.asterisk.org/c/asterisk/+/11462"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: asterisk </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-Change-Id: I7a4a06685a96e511da9f5bd23f9601642d7bd8e5 </div>
<div style="display:none"> Gerrit-Change-Number: 11462 </div>
<div style="display:none"> Gerrit-PatchSet: 4 </div>
<div style="display:none"> Gerrit-Owner: Kevin Harwell <kharwell@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Benjamin Keith Ford <bford@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Friendly Automation </div>
<div style="display:none"> Gerrit-Reviewer: George Joseph <gjoseph@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Joshua Colp <jcolp@digium.com> </div>
<div style="display:none"> Gerrit-Reviewer: Kevin Harwell <kharwell@digium.com> </div>
<div style="display:none"> Gerrit-MessageType: merged </div>