stasis_state.h File Reference

Stasis State API. More...

#include "asterisk/stasis.h"

Include dependency graph for stasis_state.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	stasis_state_observer
	Managed stasis state event interface. More...

Typedefs
typedef int(*	on_stasis_state) (const char *id, struct stasis_message *msg, void *user_data)
	The delegate called for each managed state. More...

Functions
int	stasis_state_add_observer (struct stasis_state_manager *manager, struct stasis_state_observer *observer)
	Add an observer to receive managed state related events. More...
struct stasis_state_publisher *	stasis_state_add_publisher (struct stasis_state_manager *manager, const char *id)
	Add a publisher to the managed state for the given id. More...
struct stasis_state_subscriber *	stasis_state_add_subscriber (struct stasis_state_manager *manager, const char *id)
	Add a subscriber to the managed stasis state for the given id. More...
struct stasis_topic *	stasis_state_all_topic (struct stasis_state_manager *manager)
	Retrieve the manager's topic (the topic that all state topics get forwarded to) More...
void	stasis_state_callback_all (struct stasis_state_manager *manager, on_stasis_state handler, void *data)
	For each managed state call the given handler. More...
void	stasis_state_callback_subscribed (struct stasis_state_manager *manager, on_stasis_state handler, void *data)
	For each managed, and explicitly subscribed state call the given handler. More...
struct stasis_state_manager *	stasis_state_manager_create (const char *topic_name)
	Create a stasis state manager. More...
void	stasis_state_publish (struct stasis_state_publisher *pub, struct stasis_message *msg)
	Publish to a managed state (topic) using a publisher. More...
void	stasis_state_publish_by_id (struct stasis_state_manager *manager, const char *id, const struct ast_eid *eid, struct stasis_message *msg)
	Publish to a managed named by id topic, and add an implicit subscriber. More...
const char *	stasis_state_publisher_id (const struct stasis_state_publisher *pub)
	Retrieve the publisher's underlying state's unique id. More...
struct stasis_topic *	stasis_state_publisher_topic (struct stasis_state_publisher *pub)
	Retrieve the publisher's topic. More...
void	stasis_state_remove_observer (struct stasis_state_manager *manager, struct stasis_state_observer *observer)
	Remove an observer (will no longer receive managed state related events). More...
void	stasis_state_remove_publish_by_id (struct stasis_state_manager *manager, const char *id, const struct ast_eid *eid, struct stasis_message *msg)
	Publish to a managed named by id topic, and remove an implicit publisher. More...
struct stasis_state_subscriber *	stasis_state_subscribe_pool (struct stasis_state_manager *manager, const char *id, stasis_subscription_cb callback, void *data)
	Add a subscriber, and subscribe to its underlying stasis topic. More...
void *	stasis_state_subscriber_data (struct stasis_state_subscriber *sub)
	Retrieve the last known state stasis message payload for the subscriber. More...
const char *	stasis_state_subscriber_id (const struct stasis_state_subscriber *sub)
	Retrieve the underlying subscribed to state's unique id. More...
struct stasis_subscription *	stasis_state_subscriber_subscription (struct stasis_state_subscriber *sub)
	Retrieve the stasis topic subscription if available. More...
struct stasis_topic *	stasis_state_subscriber_topic (struct stasis_state_subscriber *sub)
	Retrieve the subscriber's topic. More...
struct stasis_topic *	stasis_state_topic (struct stasis_state_manager *manager, const char *id)
	Retrieve a managed topic creating one if not currently managed. More...
void *	stasis_state_unsubscribe (struct stasis_state_subscriber *sub)
	Unsubscribe from the stasis topic and stasis state. More...
void *	stasis_state_unsubscribe_and_join (struct stasis_state_subscriber *sub)
	Unsubscribe from the stasis topic, block until the final message is received, and then unsubscribe from stasis state. More...

Detailed Description

Stasis State API.

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:

• stasis_state_manager
• stasis_state_subscriber
• stasis_state_publisher
• stasis_state_observer

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 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.

stasis_state_subscriber

As mentioned, 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 (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.

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 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 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 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 ast_eid. However, a final call to 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).

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.

Definition in file stasis_state.h.

Typedef Documentation

on_stasis_state

typedef int(* on_stasis_state) (const char *id, struct stasis_message *msg, void *user_data)

The delegate called for each managed state.

Parameters

id	The unique id of a managed state object
msg	The last published message on the state, or NULL
user_data	Data object the user passed into the manager callback

Return values

0	to continue traversing
CMP_STOP	(2) to stop traversing

Since

13.28.0

16.5.0

Definition at line 521 of file stasis_state.h.

Function Documentation

stasis_state_add_observer()

int stasis_state_add_observer	(	struct stasis_state_manager *	manager,
		struct stasis_state_observer *	observer
	)

Add an observer to receive managed state related events.

Parameters

manager	The state manager
observer	The observer handling events

Return values

0	if successfully registered
-1	on failure

Since

13.28.0

16.5.0

Definition at line 688 of file stasis_state.c.

References AST_VECTOR_APPEND, AST_VECTOR_RW_UNLOCK, and AST_VECTOR_RW_WRLOCK.

Referenced by ast_mwi_add_observer(), and subscriptions_create().

{
   int res;

   AST_VECTOR_RW_WRLOCK(&manager->observers);
   res = AST_VECTOR_APPEND(&manager->observers, observer);
   AST_VECTOR_RW_UNLOCK(&manager->observers);

   return res;
}

stasis_state_add_publisher()

struct stasis_state_publisher* stasis_state_add_publisher	(	struct stasis_state_manager *	manager,
		const char *	id
	)

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.

Parameters

manager	The manager object
id	The unique id of a managed state

Return values

A	stasis state publisher
NULL	if an error occurred

Since

13.28.0

16.5.0

Definition at line 531 of file stasis_state.c.

References stasis_state_manager::all_topic, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_ref, ast_log, LOG_ERROR, NULL, publisher_dtor(), stasis_topic_name(), stasis_state_publisher::state, and state_find_or_add.

Referenced by ast_mwi_add_publisher(), and publishers_create().

{
   struct stasis_state_publisher *pub = ao2_alloc_options(
      sizeof(*pub), publisher_dtor, AO2_ALLOC_OPT_LOCK_NOLOCK);

   if (!pub) {
      ast_log(LOG_ERROR, "Unable to create publisher to %s/%s\n",
         stasis_topic_name(manager->all_topic), id);
      return NULL;
   }

   pub->state = state_find_or_add(manager, NULL, id);
   if (!pub->state) {
      ao2_ref(pub, -1);
      return NULL;
   }

   return pub;
}

stasis_state_add_subscriber()

struct stasis_state_subscriber* stasis_state_add_subscriber	(	struct stasis_state_manager *	manager,
		const char *	id
	)

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.

Parameters

manager	The manager object
id	The unique id of a managed state

Return values

A	stasis state subscriber
NULL	if an error occurred

Since

13.28.0

16.5.0

Definition at line 412 of file stasis_state.c.

References stasis_state_manager::all_topic, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_lock, ao2_ref, ao2_unlock, ast_log, AST_VECTOR_GET, AST_VECTOR_RW_RDLOCK, AST_VECTOR_RW_UNLOCK, AST_VECTOR_SIZE, LOG_ERROR, NULL, stasis_state::num_subscribers, stasis_topic_name(), stasis_state_subscriber::state, state_find_or_add, sub, and subscriber_dtor().

Referenced by ast_mwi_add_subscriber(), and stasis_state_subscribe_pool().

{
   size_t i;
   struct stasis_state_subscriber *sub = ao2_alloc_options(
      sizeof(*sub), subscriber_dtor, AO2_ALLOC_OPT_LOCK_NOLOCK);

   if (!sub) {
      ast_log(LOG_ERROR, "Unable to create subscriber to %s/%s\n",
         stasis_topic_name(manager->all_topic), id);
      return NULL;
   }

   sub->state = state_find_or_add(manager, NULL, id);
   if (!sub->state) {
      ao2_ref(sub, -1);
      return NULL;
   }

   ao2_lock(sub->state);
   ++sub->state->num_subscribers;
   ao2_unlock(sub->state);

   AST_VECTOR_RW_RDLOCK(&manager->observers);
   for (i = 0; i < AST_VECTOR_SIZE(&manager->observers); ++i) {
      if (AST_VECTOR_GET(&manager->observers, i)->on_subscribe) {
         AST_VECTOR_GET(&manager->observers, i)->on_subscribe(id, sub);
      }
   }
   AST_VECTOR_RW_UNLOCK(&manager->observers);

   return sub;
}

stasis_state_all_topic()

struct stasis_topic* stasis_state_all_topic

(

struct stasis_state_manager *

manager

)

Retrieve the manager's topic (the topic that all state topics get forwarded to)

Parameters

manager

The manager object

Return values

The	manager's topic.

Since

13.28.0

16.5.0

Definition at line 364 of file stasis_state.c.

References stasis_state_manager::all_topic.

Referenced by ast_mwi_topic_all().

{
   return manager->all_topic;
}

stasis_state_callback_all()

void stasis_state_callback_all	(	struct stasis_state_manager *	manager,
		on_stasis_state	handler,
		void *	data
	)

For each managed state call the given handler.

Parameters

manager	The state manager
handler	The handler to call for each managed state
data	User to data to pass on to the handler

Since

13.28.0

16.5.0

Definition at line 740 of file stasis_state.c.

References ao2_callback_data, ast_assert, handle_stasis_state_proxy(), NULL, OBJ_MULTIPLE, OBJ_NODATA, and stasis_state_manager::states.

Referenced by ast_mwi_state_callback_all(), and publish().

{
   ast_assert(handler != NULL);

   ao2_callback_data(manager->states, OBJ_MULTIPLE | OBJ_NODATA,
      handle_stasis_state_proxy, handler, data);
}

stasis_state_callback_subscribed()

void stasis_state_callback_subscribed	(	struct stasis_state_manager *	manager,
		on_stasis_state	handler,
		void *	data
	)

For each managed, and explicitly subscribed state call the given handler.

Parameters

manager	The state manager
handler	The handler to call for each managed state
data	User to data to pass on to the handler

Since

13.28.0

16.5.0

Definition at line 763 of file stasis_state.c.

References ao2_callback_data, ast_assert, handle_stasis_state_subscribed(), NULL, OBJ_MULTIPLE, OBJ_NODATA, and stasis_state_manager::states.

Referenced by ast_mwi_state_callback_subscribed().

{
   ast_assert(handler != NULL);

   ao2_callback_data(manager->states, OBJ_MULTIPLE | OBJ_NODATA,
      handle_stasis_state_subscribed, handler, data);
}

stasis_state_manager_create()

struct stasis_state_manager* stasis_state_manager_create

(

const char *

topic_name

)

Create a stasis state manager.

Note

The state manager is an ao2_object. When done simply decrement its reference for object cleanup.

Parameters

topic_name

The name of the topic to create that all state topics get forwarded to

Return values

A	stasis state manager
NULL	if an error occurred

Since

13.28.0

16.5.0

Definition at line 324 of file stasis_state.c.

References stasis_state_manager::all_topic, AO2_ALLOC_OPT_LOCK_MUTEX, AO2_ALLOC_OPT_LOCK_NOLOCK, ao2_alloc_options, ao2_container_alloc_hash, ao2_container_register(), ao2_ref, ast_alloca, AST_VECTOR_RW_INIT, stasis_state_proxy::manager, NULL, stasis_topic_create(), stasis_topic_name(), STATE_BUCKETS, state_manager_dtor(), and stasis_state_manager::states.

Referenced by AST_TEST_DEFINE(), and mwi_init().

{
   struct stasis_state_manager *manager;

   manager = ao2_alloc_options(sizeof(*manager), state_manager_dtor,
      AO2_ALLOC_OPT_LOCK_NOLOCK);
   if (!manager) {
      return NULL;
   }

   manager->states = ao2_container_alloc_hash(AO2_ALLOC_OPT_LOCK_MUTEX, 0,
      STATE_BUCKETS, stasis_state_proxy_hash_fn, NULL, stasis_state_proxy_cmp_fn);
   if (!manager->states) {
      ao2_ref(manager, -1);
      return NULL;
   }

   manager->all_topic = stasis_topic_create(topic_name);
   if (!manager->all_topic) {
      ao2_ref(manager, -1);
      return NULL;
   }

   if (AST_VECTOR_RW_INIT(&manager->observers, 2) != 0) {
      ao2_ref(manager, -1);
      return NULL;
   }

#ifdef AO2_DEBUG
   {
      char *container_name =
         ast_alloca(strlen(stasis_topic_name(manager->all_topic)) + strlen("-manager") + 1);
      sprintf(container_name, "%s-manager", stasis_topic_name(manager->all_topic));
      ao2_container_register(container_name, manager->states, state_prnt_obj);
   }
#endif

   return manager;
}

stasis_state_publish()

void stasis_state_publish	(	struct stasis_state_publisher *	pub,
		struct stasis_message *	msg
	)

Publish to a managed state (topic) using a publisher.

Parameters

pub	The publisher to use to publish the message
msg	The message to publish

Since

13.28.0

16.5.0

Definition at line 562 of file stasis_state.c.

References ao2_lock, ao2_replace, ao2_unlock, stasis_state::msg, stasis_publish(), stasis_state_publisher::state, and stasis_state::topic.

Referenced by ast_mwi_publish(), and explicit_publish_cb().

{
   ao2_lock(pub->state);
   ao2_replace(pub->state->msg, msg);
   ao2_unlock(pub->state);

   stasis_publish(pub->state->topic, msg);
}

stasis_state_publish_by_id()

void stasis_state_publish_by_id	(	struct stasis_state_manager *	manager,
		const char *	id,
		const struct ast_eid *	eid,
		struct stasis_message *	msg
	)

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.

Parameters

manager	The state manager
id	A state's unique id
eid	The unique system id
msg	The message to publish

Since

13.28.0

16.5.0

Definition at line 638 of file stasis_state.c.

References ao2_lock, ao2_ref, ao2_replace, ao2_unlock, stasis_state::msg, NULL, stasis_publish(), state, state_find_or_add, state_find_or_add_eid(), and stasis_state::topic.

Referenced by ast_mwi_publish_by_mailbox(), and implicit_publish_cb().

{
   struct stasis_state *state;

   state = state_find_or_add(manager, NULL, id);
   if (!state) {
      return;
   }

   ao2_lock(state);
   state_find_or_add_eid(state, eid);
   ao2_replace(state->msg, msg);
   ao2_unlock(state);

   stasis_publish(state->topic, msg);

   ao2_ref(state, -1);
}

stasis_state_publisher_id()

const char* stasis_state_publisher_id

(

const struct stasis_state_publisher *

pub

)

Retrieve the publisher's underlying state's unique id.

Parameters

pub	A stasis state publisher

Return values

The	managed state's id

Since

13.28.0

16.5.0

Definition at line 552 of file stasis_state.c.

References stasis_state_publisher::state.

Referenced by ast_mwi_publish(), and explicit_publish_cb().

{
   return pub->state->id;
}

stasis_state_publisher_topic()

struct stasis_topic* stasis_state_publisher_topic

(

struct stasis_state_publisher *

pub

)

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.

Parameters

pub	A stasis state publisher

Return values

The	publisher's topic

Since

13.28.0

16.5.0

Definition at line 557 of file stasis_state.c.

References stasis_state_publisher::state, and stasis_state::topic.

{
   return pub->state->topic;
}

stasis_state_remove_observer()

void stasis_state_remove_observer	(	struct stasis_state_manager *	manager,
		struct stasis_state_observer *	observer
	)

Remove an observer (will no longer receive managed state related events).

Parameters

manager	The state manager
observer	The observer being removed

Since

13.28.0

16.5.0

Definition at line 700 of file stasis_state.c.

References AST_VECTOR_ELEM_CLEANUP_NOOP, AST_VECTOR_REMOVE_ELEM_UNORDERED, AST_VECTOR_RW_UNLOCK, and AST_VECTOR_RW_WRLOCK.

Referenced by ast_mwi_remove_observer(), and subscriptions_destroy().

{
   AST_VECTOR_RW_WRLOCK(&manager->observers);
   AST_VECTOR_REMOVE_ELEM_UNORDERED(&manager->observers, observer, AST_VECTOR_ELEM_CLEANUP_NOOP);
   AST_VECTOR_RW_UNLOCK(&manager->observers);
}

stasis_state_remove_publish_by_id()

void stasis_state_remove_publish_by_id	(	struct stasis_state_manager *	manager,
		const char *	id,
		const struct ast_eid *	eid,
		struct stasis_message *	msg
	)

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.

Parameters

manager	The state manager
id	A state's unique id
eid	The unique system id
msg	The message to publish (can be NULL)

Since

13.28.0

16.5.0

Definition at line 658 of file stasis_state.c.

References ao2_lock, ao2_ref, ao2_unlock, ao2_weakproxy_find, ast_debug, OBJ_SEARCH_KEY, stasis_publish(), state_find_and_remove_eid(), stasis_state_manager::states, and stasis_state::topic.

Referenced by ast_delete_mwi_state_full(), and publishers_destroy().

{
   struct stasis_state *state = ao2_weakproxy_find(manager->states, id, OBJ_SEARCH_KEY, "");

   if (!state) {
      /*
       * In most circumstances state should already exist here. However, if there is no
       * state then it can mean one of a few things:
       *
       * 1. This function was called prior to an implicit publish for the same given
       *    manager, and id.
       * 2. This function was called more than once for the same manager, and id.
       * 3. There is ref count problem with the explicit subscribers, and publishers.
       */
      ast_debug(5, "Attempted to remove state for id '%s', but state not found\n", id);
      return;
   }

   if (msg) {
      stasis_publish(state->topic, msg);
   }

   ao2_lock(state);
   state_find_and_remove_eid(state, eid);
   ao2_unlock(state);

   ao2_ref(state, -1);
}

stasis_state_subscribe_pool()

struct stasis_state_subscriber* stasis_state_subscribe_pool	(	struct stasis_state_manager *	manager,
		const char *	id,
		stasis_subscription_cb	callback,
		void *	data
	)

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.

Parameters

manager	The manager object
id	The unique id of a managed state
callback	The stasis subscription callback
data	A user data object passed to the stasis subscription

Return values

A	stasis state subscriber
NULL	if an error occurred

Since

13.28.0

16.5.0

Definition at line 446 of file stasis_state.c.

References ao2_ref, ast_debug, NULL, stasis_state_add_subscriber(), stasis_state_subscriber::stasis_sub, stasis_subscribe_pool, stasis_topic_name(), stasis_state_subscriber::state, sub, and stasis_state::topic.

Referenced by ast_mwi_subscribe_pool(), and subscriptions_create().

{
   struct stasis_topic *topic;
   struct stasis_state_subscriber *sub = stasis_state_add_subscriber(manager, id);

   if (!sub) {
      return NULL;
   }

   topic = sub->state->topic;
   ast_debug(3, "Creating stasis state subscription to id '%s'. Topic: '%s':%p %d\n",
      id, stasis_topic_name(topic), topic, (int)ao2_ref(topic, 0));

   sub->stasis_sub = stasis_subscribe_pool(topic, callback, data);

   if (!sub->stasis_sub) {
      ao2_ref(sub, -1);
      return NULL;
   }

   return sub;
}

stasis_state_subscriber_data()

void* stasis_state_subscriber_data

(

struct stasis_state_subscriber *

sub

)

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

Parameters

sub	A stasis state subscriber

Return values

The	subscriber's state message data
NULL	if no data has been published yet

Since

13.28.0

16.5.0

Definition at line 497 of file stasis_state.c.

References ao2_bump, ao2_lock, ao2_unlock, stasis_state::msg, stasis_message_data(), and stasis_state_subscriber::state.

Referenced by ast_mwi_subscriber_data(), and handle_validate().

{
   void *res;

   /*
    * The data's reference needs to be bumped before returning so it doesn't disappear
    * for the caller. Lock state, so the underlying message data is not replaced while
    * retrieving.
    */
   ao2_lock(sub->state);
   res = ao2_bump(stasis_message_data(sub->state->msg));
   ao2_unlock(sub->state);

   return res;
}

stasis_state_subscriber_id()

const char* stasis_state_subscriber_id

(

const struct stasis_state_subscriber *

sub

)

Retrieve the underlying subscribed to state's unique id.

Parameters

sub	A stasis state subscriber

Return values

The	managed state's id

Since

13.28.0

16.5.0

Definition at line 487 of file stasis_state.c.

References stasis_state_subscriber::state.

Referenced by ast_mwi_subscriber_data().

{
   return sub->state->id;
}

stasis_state_subscriber_subscription()

struct stasis_subscription* stasis_state_subscriber_subscription

(

struct stasis_state_subscriber *

sub

)

Retrieve the stasis topic subscription if available.

Parameters

sub	A stasis state subscriber

Return values

The	subscriber's stasis subscription
NULL	if no subscription available

Since

13.28.0

16.5.0

Definition at line 513 of file stasis_state.c.

References stasis_state_subscriber::stasis_sub.

Referenced by ast_mwi_subscriber_subscription().

{
   return sub->stasis_sub;
}

stasis_state_subscriber_topic()

struct stasis_topic* stasis_state_subscriber_topic

(

struct stasis_state_subscriber *

sub

)

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.

Parameters

sub	A stasis state subscriber

Return values

The	subscriber's topic

Since

13.28.0

16.5.0

Definition at line 492 of file stasis_state.c.

References stasis_state_subscriber::state, and stasis_state::topic.

Referenced by ast_mwi_subscriber_topic().

{
   return sub->state->topic;
}

stasis_state_topic()

struct stasis_topic* stasis_state_topic	(	struct stasis_state_manager *	manager,
		const char *	id
	)

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.

Parameters

manager	The manager object
id	The unique id of/for the topic

Return values

A	managed stasis topic.
NULL	if an error occurred

Since

13.28.0

16.5.0

Definition at line 369 of file stasis_state.c.

References ao2_ref, NULL, state, state_find_or_add, and stasis_state::topic.

Referenced by ast_mwi_topic().

{
   struct stasis_topic *topic;
   struct stasis_state *state;

   state = state_find_or_add(manager, NULL, id);
   if (!state) {
      return NULL;
   }

   topic = state->topic;
   ao2_ref(state, -1);
   return topic;
}

stasis_state_unsubscribe()

void* stasis_state_unsubscribe

(

struct stasis_state_subscriber *

sub

)

Unsubscribe from the stasis topic and stasis state.

Parameters

sub	A stasis state subscriber

Return values

NULL

Since

13.28.0

16.5.0

Definition at line 470 of file stasis_state.c.

References ao2_ref, NULL, stasis_state_subscriber::stasis_sub, and stasis_unsubscribe().

Referenced by ast_mwi_unsubscribe().

{
   sub->stasis_sub = stasis_unsubscribe(sub->stasis_sub);
   ao2_ref(sub, -1);
   return NULL;
}

stasis_state_unsubscribe_and_join()

void* stasis_state_unsubscribe_and_join

(

struct stasis_state_subscriber *

sub

)

Unsubscribe from the stasis topic, block until the final message is received, and then unsubscribe from stasis state.

Parameters

sub	A stasis state subscriber

Return values

NULL

Since

13.28.0

16.5.0

Definition at line 477 of file stasis_state.c.

References ao2_ref, NULL, stasis_state_subscriber::stasis_sub, and stasis_unsubscribe_and_join().

Referenced by ast_mwi_unsubscribe_and_join(), and subscriptions_destroy().

{
   if (sub) {
      sub->stasis_sub = stasis_unsubscribe_and_join(sub->stasis_sub);
      ao2_ref(sub, -1);
   }

   return NULL;
}