mirror of
https://github.com/asterisk/asterisk.git
synced 2025-10-10 14:51:09 +00:00
363bafc29e
This new module describes an API that can be thought of as a combination of stasis topic pools, and caching. Except, hopefully done in a more efficient and less memory "leaky" manner. The API defines methods, and data structures for managing, and tracking published message state through stasis. By adding a subscriber or publisher, consumers can more easily track the lifetime of the contained state. For instance, when no more publishers and/or subscribers have need of the topic, and associated state its data is removed from the managed container. * stasis_state_manager * The manager stores and well, manages state data. Each state is an association of a unique stasis topic, and the last known published stasis message on that topic. There is only ever one managed state object per topic. For each topic all messages are forwarded to an "all" topic also maintained by the manager. * stasis_state_subscriber * Topic and state can be created, or referenced within the manager by adding a stasis_state_subscriber. When adding a subscriber if no state currently exists new managed state is immediately created. If managed state already exists then a new subscriber is created referencing that state. The managed state is guaranteed to live throughout the subscriber's lifetime. State is only removed from the manager when no other entities require it. * stasis_state_publisher * Topic and state can be created, or referenced within the manager by also adding a stasis_state_publisher. When adding a publisher if no state currently exists new managed state is created. If managed state already exists then a new publisher is created referencing that state. The managed state is guaranteed to live throughout the publisher's lifetime. State is only removed from the manager when no other entities require it. * stasis_state_observer * Some modules may wish to watch for, and react to managed state events. By registering a state observer, and implementing handlers for the desired callbacks those modules can do so. * other * Callbacks also exist that allow consumers to iterate over all, or some of the managed state. ASTERISK-28442 Change-Id: I7a4a06685a96e511da9f5bd23f9601642d7bd8e5
550 lines
18 KiB
C
550 lines
18 KiB
C
/*
|
|
* Asterisk -- An open source telephony toolkit.
|
|
*
|
|
* Copyright (C) 2019, Sangoma Technologies Corporation
|
|
*
|
|
* Kevin Harwell <kharwell@digium.com>
|
|
*
|
|
* See http://www.asterisk.org for more information about
|
|
* the Asterisk project. Please do not directly contact
|
|
* any of the maintainers of this project for assistance;
|
|
* the project provides a web site, mailing lists and IRC
|
|
* channels for your use.
|
|
*
|
|
* This program is free software, distributed under the terms of
|
|
* the GNU General Public License Version 2. See the LICENSE file
|
|
* at the top of the source tree.
|
|
*/
|
|
|
|
#ifndef _STASIS_STATE_H
|
|
#define _STASIS_STATE_H
|
|
|
|
/*! \file
|
|
*
|
|
* \brief Stasis State API.
|
|
*
|
|
* \par Intro
|
|
*
|
|
* This module defines the data structures, and handling of "state" for topics within
|
|
* stasis. State is defined as the last stasis message, and its contained message data,
|
|
* published on a given topic.
|
|
*
|
|
* Concepts to know:
|
|
* - \ref stasis_state_manager
|
|
* - \ref stasis_state_subscriber
|
|
* - \ref stasis_state_publisher
|
|
* - \ref stasis_state_observer
|
|
*
|
|
* \par stasis_state_manager
|
|
*
|
|
* The manager stores and well, manages state data. Each state is an association of
|
|
* a unique stasis topic, and the last known published stasis message on that topic.
|
|
* There is only ever one managed state object per topic. For each topic all messages
|
|
* are forwarded to an "all" topic also maintained by the manager. This allows
|
|
* subscriptions to all managed topics, and their state. Managed state is created in
|
|
* one of several ways:
|
|
*
|
|
* Adding an explicit subscriber
|
|
* Adding an explicit publisher
|
|
* Adding an implicit publisher
|
|
* Retrieving a stasis state topic from the manager via the \ref stasis_state_topic
|
|
* function prior to doing one of the above (DO NOT DO THIS).
|
|
*
|
|
* More on the first three options later (see relevant section descriptions below). The
|
|
* last option, creation through retrieving a topic is not only NOT recommended, but
|
|
* should NOT even BE DONE. Doing so will inevitably result in a memory leak. Why then
|
|
* is this even allowed? The short answer is backwards compatibility. The slightly longer
|
|
* answer is at the time of this module's creation that's how things were historically
|
|
* done using a combination of stasis topic management spread throughout various other
|
|
* modules, and stasis caching. And yes it did cause a memory leak.
|
|
*
|
|
* Preferably, any new code wishing to track topics and states should do so by adding
|
|
* either an explicit subscriber and/or publisher.
|
|
*
|
|
* \par stasis_state_subscriber
|
|
*
|
|
* As mentioned, topic and state can be created, or referenced within the manager by adding
|
|
* a \ref stasis_state_subscriber. When adding a subscriber if no state currently exists
|
|
* new managed state is immediately created. If managed state already exists then a new
|
|
* subscriber is created referencing that state. The managed state is guaranteed to live
|
|
* throughout the subscriber's lifetime. State is only removed from the manager when no
|
|
* other entities require it (no more subscribers, or publishers).
|
|
*
|
|
* Subscribers are ao2 objects. Therefore there is no explicit cleanup required aside from
|
|
* dereferencing the subscriber object using normal ao2 dereferencing methods.
|
|
*
|
|
* \par stasis_state_publisher
|
|
*
|
|
* There are two ways of tracking publishers: explicitly and implicitly.
|
|
*
|
|
* Topic and state can be created, or referenced within the manager by also explicitly adding
|
|
* a \ref stasis_state_publisher. When adding a publisher if no state currently exists new
|
|
* managed state is created. If managed state already exists then a new publisher is created
|
|
* referencing that state. The managed state is guaranteed to live throughout the publisher's
|
|
* lifetime. State is only removed from the manager when no other entities require it (no more
|
|
* publishers, or subscribers).
|
|
*
|
|
* Explicit publishers are ao2 objects. Therefore there is no cleanup required aside from
|
|
* dereferencing the publisher object using normal ao2 dereferencing methods.
|
|
*
|
|
* When adding an explicit publisher, messages should be published using the \ref
|
|
* stasis_state_publish function. This not only skips a lookup, but doesn't add an implicit
|
|
* publisher. They are not necessarily mutually exclusive it's just that the two ways exist
|
|
* to solve two different problems.
|
|
*
|
|
* For example (using an explicit publisher):
|
|
*
|
|
* // Add an explicit publisher to topic/state "8675309" within
|
|
* // a given manager context
|
|
* pub = stasis_state_add_publisher(manager, "8675309");
|
|
*
|
|
* // Publish a stasis message to the topic/state
|
|
* stasis_state_publish(pub, msg);
|
|
*
|
|
* // Publish another a stasis message to the topic/state
|
|
* stasis_state_publish(pub, msg);
|
|
*
|
|
* // Done with the publisher release the reference
|
|
* ao2_ref(pub, -1);
|
|
*
|
|
* An implicit publisher can also be created by calling \ref stasis_state_publish_by_id. Calling
|
|
* this function not only publishes the message within stasis (creating managed state if needed)
|
|
* it also sets up internal tracking of the publishing module using an \ref ast_eid. However, a
|
|
* final call to \ref stasis_state_remove_publish_by_id must be done in order to remove the eid
|
|
* reference, which will subsequently allow the underlying managed state to be eventually deleted.
|
|
*
|
|
* For example (using an implicit publisher):
|
|
*
|
|
* // Publish a stasis message to topic/state 8675309 within a
|
|
* // given manager context and use the system's default eid
|
|
* stasis_state_publish_by_id(manager, "8675309", NULL, msg);
|
|
*
|
|
* // Do some stuff and then publish again
|
|
* stasis_state_publish_by_id(manager, "8675309", NULL, msg);
|
|
*
|
|
* // Done with all our publishing, so post a final clearing
|
|
* // message and remove the implicit publisher
|
|
* stasis_state_remove_publish_by_id(manager, "8675309", NULL, msg);
|
|
*
|
|
* Explicit publisher/publishing is preferred. However, implicit publishing is allowed for those
|
|
* situations where it makes more sense to do so, but has been implemented mostly for backwards
|
|
* compatibility with some modules (using implicit publishing required less initial code changes
|
|
* to some legacy subsystems).
|
|
*
|
|
* \par stasis_state_observer
|
|
*
|
|
* Some modules may wish to watch for, and react to managed state events. By registering a state
|
|
* observer, and implementing handlers for the desired callbacks those modules can do so.
|
|
*/
|
|
|
|
#include "asterisk/stasis.h"
|
|
|
|
struct ast_eid;
|
|
|
|
/*!
|
|
* \brief Manages a collection of stasis states.
|
|
*
|
|
* Maintains data related to stasis state. Managed state is an association of a unique stasis
|
|
* topic (named by a given unique id), and the last known published message.
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_state_manager;
|
|
|
|
/*!
|
|
* \brief Create a stasis state manager.
|
|
*
|
|
* \note The state manager is an ao2_object. When done simply decrement its reference
|
|
* for object cleanup.
|
|
*
|
|
* \param topic_name The name of the topic to create that all state topics
|
|
* get forwarded to
|
|
*
|
|
* \retval A stasis state manager
|
|
* \retval NULL if an error occurred
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_state_manager *stasis_state_manager_create(const char *topic_name);
|
|
|
|
/*!
|
|
* \brief Retrieve the manager's topic (the topic that all state topics get forwarded to)
|
|
*
|
|
* \param manager The manager object
|
|
*
|
|
* \retval The manager's topic.
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_topic *stasis_state_all_topic(struct stasis_state_manager *manager);
|
|
|
|
/*!
|
|
* \brief Retrieve a managed topic creating one if not currently managed.
|
|
*
|
|
* WARNING This function should not be called before adding a publisher or subscriber or
|
|
* it will cause a memory leak within the stasis state manager. This function is here in
|
|
* order to allow for compatibility with how things used to work.
|
|
*
|
|
* Also much like the similar functionality from before it returns the stasis topic, but
|
|
* does not bump its reference.
|
|
*
|
|
* \param manager The manager object
|
|
* \param id The unique id of/for the topic
|
|
*
|
|
* \retval A managed stasis topic.
|
|
* \retval NULL if an error occurred
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_topic *stasis_state_topic(struct stasis_state_manager *manager, const char *id);
|
|
|
|
/*!
|
|
* \brief A stasis state subscriber
|
|
*
|
|
* A subscriber to a particular stasis state. As such it holds a reference to the
|
|
* underlying stasis state, so that managed state is guaranteed to exist for the
|
|
* lifetime of the subscriber.
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_state_subscriber;
|
|
|
|
/*!
|
|
* \brief Add a subscriber to the managed stasis state for the given id
|
|
*
|
|
* Adds a subscriber to a managed state based on id. If managed state does not already
|
|
* exists for the given id then new managed state is created. Otherwise the existing
|
|
* state is subscribed to.
|
|
*
|
|
* \param manager The manager object
|
|
* \param id The unique id of a managed state
|
|
*
|
|
* \retval A stasis state subscriber
|
|
* \retval NULL if an error occurred
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_state_subscriber *stasis_state_add_subscriber(
|
|
struct stasis_state_manager *manager, const char *id);
|
|
|
|
/*!
|
|
* \brief Add a subscriber, and subscribe to its underlying stasis topic.
|
|
*
|
|
* Adds a subscriber to a managed state based on id. If managed state does not already
|
|
* exists for the given id then new managed state is created. Otherwise the existing
|
|
* state is subscribed to. If the state is successfully subscribed to then a stasis
|
|
* subscription is subsequently created as well.
|
|
*
|
|
* \param manager The manager object
|
|
* \param id The unique id of a managed state
|
|
* \param callback The stasis subscription callback
|
|
* \param data A user data object passed to the stasis subscription
|
|
*
|
|
* \retval A stasis state subscriber
|
|
* \retval NULL if an error occurred
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_state_subscriber *stasis_state_subscribe_pool(struct stasis_state_manager *manager,
|
|
const char *id, stasis_subscription_cb callback, void *data);
|
|
|
|
/*!
|
|
* \brief Unsubscribe from the stasis topic and stasis state.
|
|
*
|
|
* \param sub A stasis state subscriber
|
|
*
|
|
* \retval NULL
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void *stasis_state_unsubscribe(struct stasis_state_subscriber *sub);
|
|
|
|
/*!
|
|
* \brief Unsubscribe from the stasis topic, block until the final message
|
|
* is received, and then unsubscribe from stasis state.
|
|
*
|
|
* \param sub A stasis state subscriber
|
|
*
|
|
* \retval NULL
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void *stasis_state_unsubscribe_and_join(struct stasis_state_subscriber *sub);
|
|
|
|
/*!
|
|
* \brief Retrieve the underlying subscribed to state's unique id
|
|
*
|
|
* \param sub A stasis state subscriber
|
|
*
|
|
* \retval The managed state's id
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
const char *stasis_state_subscriber_id(const struct stasis_state_subscriber *sub);
|
|
|
|
/*!
|
|
* \brief Retrieve the subscriber's topic
|
|
*
|
|
* \note Returned topic's reference count is NOT incremented. However, the topic is
|
|
* guaranteed to live for the lifetime of the subscriber.
|
|
*
|
|
* \param sub A stasis state subscriber
|
|
*
|
|
* \retval The subscriber's topic
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_topic *stasis_state_subscriber_topic(struct stasis_state_subscriber *sub);
|
|
|
|
/*!
|
|
* \brief Retrieve the last known state stasis message payload for the subscriber
|
|
*
|
|
* If a stasis message has been published to this state, this function returns
|
|
* that message's payload object. If no stasis message has been published on the
|
|
* state, or the message's payload does not exist then NULL is returned.
|
|
*
|
|
* \note Returned data's reference count is incremented
|
|
*
|
|
* \param sub A stasis state subscriber
|
|
*
|
|
* \retval The subscriber's state message data
|
|
* \retval NULL if no data has been published yet
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void *stasis_state_subscriber_data(struct stasis_state_subscriber *sub);
|
|
|
|
/*!
|
|
* \brief Retrieve the stasis topic subscription if available.
|
|
*
|
|
* \param sub A stasis state subscriber
|
|
*
|
|
* \retval The subscriber's stasis subscription
|
|
* \retval NULL if no subscription available
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_subscription *stasis_state_subscriber_subscription(
|
|
struct stasis_state_subscriber *sub);
|
|
|
|
/*!
|
|
* \brief A stasis state publisher
|
|
*
|
|
* A publisher to a particular stasis state and topic. As such it holds a reference to
|
|
* the underlying stasis state, so that managed state is guaranteed to exist for the
|
|
* lifetime of the publisher.
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_state_publisher;
|
|
|
|
/*!
|
|
* \brief Add a publisher to the managed state for the given id
|
|
*
|
|
* Adds a publisher to a managed state based on id. If managed state does not already
|
|
* exists for the given id then new managed state is created. Otherwise the existing
|
|
* state is used.
|
|
*
|
|
* \param manager The manager object
|
|
* \param id The unique id of a managed state
|
|
*
|
|
* \retval A stasis state publisher
|
|
* \retval NULL if an error occurred
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_state_publisher *stasis_state_add_publisher(
|
|
struct stasis_state_manager *manager, const char *id);
|
|
|
|
/*!
|
|
* \brief Retrieve the publisher's underlying state's unique id
|
|
*
|
|
* \param pub A stasis state publisher
|
|
*
|
|
* \retval The managed state's id
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
const char *stasis_state_publisher_id(const struct stasis_state_publisher *pub);
|
|
|
|
/*!
|
|
* \brief Retrieve the publisher's topic
|
|
*
|
|
* \note Returned topic's reference count is NOT incremented. However, the topic is
|
|
* guaranteed to live for the lifetime of the publisher.
|
|
*
|
|
* \param pub A stasis state publisher
|
|
*
|
|
* \retval The publisher's topic
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
struct stasis_topic *stasis_state_publisher_topic(struct stasis_state_publisher *pub);
|
|
|
|
/*!
|
|
* \brief Publish to a managed state (topic) using a publisher.
|
|
*
|
|
* \param pub The publisher to use to publish the message
|
|
* \param msg The message to publish
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void stasis_state_publish(struct stasis_state_publisher *pub, struct stasis_message *msg);
|
|
|
|
/*!
|
|
* \brief Publish to a managed named by id topic, and add an implicit subscriber.
|
|
*
|
|
* \note It is recommended when adding new publisher functionality within a module
|
|
* to create and use an explicit publisher instead of using this method.
|
|
*
|
|
* This creates an implicit publisher keyed off the eid. This ability was mainly
|
|
* implemented in order to maintain compatibility with already established code.
|
|
* Allowing the creation of an implicit publisher made is so less changes were
|
|
* required when stasis state module was initially added.
|
|
*
|
|
* There should only ever be one publisher for a specifically named managed topic
|
|
* within the system. This being the case we can use the eid to implicitly track
|
|
* the publisher. However once publishing is no longer needed for a topic a call
|
|
* to stasis_state_remove_publish_by_id is required in order to remove the implicit
|
|
* publisher. Thus allowing for its eventual destruction. Without the call to remove
|
|
* a memory leak will occur.
|
|
*
|
|
* \param manager The state manager
|
|
* \param id A state's unique id
|
|
* \param eid The unique system id
|
|
* \param msg The message to publish
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void stasis_state_publish_by_id(struct stasis_state_manager *manager, const char *id,
|
|
const struct ast_eid *eid, struct stasis_message *msg);
|
|
|
|
/*!
|
|
* \brief Publish to a managed named by id topic, and remove an implicit publisher.
|
|
*
|
|
* This function should be called after calling stasis_state_publish_by_id at least once
|
|
* for the same manager, id, and eid. If the given stasis message is NULL then the implicit
|
|
* publisher is removed, but no last message is published.
|
|
*
|
|
* See note and description on stasis_state_publish_by_id for more details about if, and
|
|
* when this function should be used.
|
|
*
|
|
* \param manager The state manager
|
|
* \param id A state's unique id
|
|
* \param eid The unique system id
|
|
* \param msg The message to publish (can be NULL)
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void stasis_state_remove_publish_by_id(struct stasis_state_manager *manager,
|
|
const char *id, const struct ast_eid *eid, struct stasis_message *msg);
|
|
|
|
/*! \brief Managed stasis state event interface */
|
|
struct stasis_state_observer {
|
|
/*!
|
|
* \brief Raised when any managed state is being subscribed.
|
|
*
|
|
* \param id The unique id of the managed state
|
|
* \param sub The subscriber subscribed
|
|
*/
|
|
void (*on_subscribe)(const char *id, struct stasis_state_subscriber *sub);
|
|
|
|
/*!
|
|
* \brief Raised when any managed state is being unsubscribed.
|
|
*
|
|
* \param id The unique id of the managed state
|
|
* \param sub The subscriber to unsubscribe
|
|
*/
|
|
void (*on_unsubscribe)(const char *id, struct stasis_state_subscriber *sub);
|
|
};
|
|
|
|
/*!
|
|
* \brief Add an observer to receive managed state related events.
|
|
*
|
|
* \param manager The state manager
|
|
* \param observer The observer handling events
|
|
*
|
|
* \retval 0 if successfully registered
|
|
* \retval -1 on failure
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
int stasis_state_add_observer(struct stasis_state_manager *manager,
|
|
struct stasis_state_observer *observer);
|
|
|
|
/*!
|
|
* \brief Remove an observer (will no longer receive managed state related events).
|
|
*
|
|
* \param manager The state manager
|
|
* \param observer The observer being removed
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void stasis_state_remove_observer(struct stasis_state_manager *manager,
|
|
struct stasis_state_observer *observer);
|
|
|
|
/*!
|
|
* \brief The delegate called for each managed state.
|
|
*
|
|
* \param id The unique id of a managed state object
|
|
* \param msg The last published message on the state, or NULL
|
|
* \param user_data Data object the user passed into the manager callback
|
|
*
|
|
* \retval 0 to continue traversing
|
|
* \retval CMP_STOP (2) to stop traversing
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
typedef int (*on_stasis_state)(const char *id, struct stasis_message *msg, void *user_data);
|
|
|
|
/*!
|
|
* \brief For each managed state call the given handler.
|
|
*
|
|
* \param manager The state manager
|
|
* \param handler The handler to call for each managed state
|
|
* \param data User to data to pass on to the handler
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void stasis_state_callback_all(struct stasis_state_manager *manager, on_stasis_state handler,
|
|
void *data);
|
|
|
|
/*!
|
|
* \brief For each managed, and explicitly subscribed state call the given handler.
|
|
*
|
|
* \param manager The state manager
|
|
* \param handler The handler to call for each managed state
|
|
* \param data User to data to pass on to the handler
|
|
*
|
|
* \since 13.28.0
|
|
* \since 16.5.0
|
|
*/
|
|
void stasis_state_callback_subscribed(struct stasis_state_manager *manager, on_stasis_state handler,
|
|
void *data);
|
|
|
|
#endif /* _STASIS_STATE_H */
|