Asterisk - The Open Source Telephony Project GIT-master-ff80666
Functions
stasis_internal.h File Reference

Internal Stasis APIs. More...

#include "asterisk/stasis.h"
Include dependency graph for stasis_internal.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions

struct stasis_subscriptioninternal_stasis_subscribe (struct stasis_topic *topic, stasis_subscription_cb callback, void *data, int needs_mailbox, int use_thread_pool, const char *file, int lineno, const char *func)
 Create a subscription. More...
 

Detailed Description

Internal Stasis APIs.

This header file is used to define functions that are shared between files that make up Stasis Message Bus API. Functions declared here should not be used by any module outside of Stasis.

If you find yourself needing to call one of these functions directly, something has probably gone horribly wrong.

Author
Matt Jordan mjord.nosp@m.an@d.nosp@m.igium.nosp@m..com

Definition in file stasis_internal.h.

Function Documentation

◆ internal_stasis_subscribe()

struct stasis_subscription * internal_stasis_subscribe ( struct stasis_topic topic,
stasis_subscription_cb  callback,
void *  data,
int  needs_mailbox,
int  use_thread_pool,
const char *  file,
int  lineno,
const char *  func 
)

Create a subscription.

In addition to being AO2 managed memory (requiring an ao2_cleanup() to free up this reference), the subscription must be explicitly unsubscribed from its topic using stasis_unsubscribe().

The invocations of the callback are serialized, but may not always occur on the same thread. The invocation order of different subscriptions is unspecified.

Note: modules outside of Stasis should use stasis_subscribe.

Parameters
topicTopic to subscribe to.
callbackCallback function for subscription messages.
dataData to be passed to the callback, in addition to the message.
needs_mailboxDetermines whether or not the subscription requires a mailbox. Subscriptions with mailboxes will be delivered on some non-publisher thread; subscriptions without mailboxes will be delivered on the publisher thread.
use_thread_poolUse the thread pool for the subscription. This is only relevant if needs_mailbox is non-zero.
file,lineno,func
Returns
New stasis_subscription object.
Return values
NULLon error.
Since
12

Definition at line 923 of file stasis.c.

932{
933 struct stasis_subscription *sub;
934 int ret;
935
936 if (!topic) {
937 return NULL;
938 }
939
940 /* The ao2 lock is used for join_cond. */
942 if (!sub) {
943 return NULL;
944 }
945
946#ifdef AST_DEVMODE
948 sub->statistics = stasis_subscription_statistics_create(sub, needs_mailbox, use_taskpool, file, lineno, func);
949 if (ret < 0 || !sub->statistics) {
950 ao2_ref(sub, -1);
951 return NULL;
952 }
953#else
955 if (ret < 0) {
956 ao2_ref(sub, -1);
957 return NULL;
958 }
959#endif
960
961 if (needs_mailbox) {
962 char tps_name[AST_TASKPROCESSOR_MAX_NAME + 1];
963
964 /* Create name with seq number appended. */
965 ast_taskprocessor_build_name(tps_name, sizeof(tps_name), "stasis/%c:%s",
966 use_taskpool ? 'p' : 'm',
968
969 /*
970 * With a small number of subscribers, a thread-per-sub is
971 * acceptable. For a large number of subscribers, a thread
972 * pool should be used.
973 */
974 if (use_taskpool) {
975 sub->mailbox = ast_taskpool_serializer(tps_name, taskpool);
976 } else {
977 sub->mailbox = ast_taskprocessor_get(tps_name, TPS_REF_DEFAULT);
978 }
979 if (!sub->mailbox) {
980 ao2_ref(sub, -1);
981
982 return NULL;
983 }
985 /* Taskprocessor has a reference */
986 ao2_ref(sub, +1);
987 }
988
989 ao2_ref(topic, +1);
990 sub->topic = topic;
991 sub->callback = callback;
992 sub->data = data;
993 ast_cond_init(&sub->join_cond, NULL);
995 AST_VECTOR_INIT(&sub->accepted_message_types, 0);
996 sub->accepted_formatters = STASIS_SUBSCRIPTION_FORMATTER_NONE;
997
998 if (topic_add_subscription(topic, sub) != 0) {
999 ao2_ref(sub, -1);
1000 ao2_ref(topic, -1);
1001
1002 return NULL;
1003 }
1005
1006 return sub;
1007}
#define ast_asprintf(ret, fmt,...)
A wrapper for asprintf()
Definition: astmm.h:267
#define ao2_ref(o, delta)
Reference/unreference an object and return the old refcount.
Definition: astobj2.h:459
#define ao2_t_alloc(data_size, destructor_fn, debug_msg)
Definition: astobj2.h:407
static struct ast_channel * callback(struct ast_channelstorage_instance *driver, ao2_callback_data_fn *cb_fn, void *arg, void *data, int ao2_flags)
#define ast_cond_init(cond, attr)
Definition: lock.h:208
int ast_atomic_fetchadd_int(volatile int *p, int v)
Atomically add v to *p and return the previous value of *p.
Definition: lock.h:764
struct stasis_forward * sub
Definition: res_corosync.c:240
#define NULL
Definition: resample.c:96
const char * stasis_topic_name(const struct stasis_topic *topic)
Return the name of a topic.
Definition: stasis.c:694
static int topic_add_subscription(struct stasis_topic *topic, struct stasis_subscription *sub)
Add a subscriber to a topic.
Definition: stasis.c:1268
static void subscription_dtor(void *obj)
Definition: stasis.c:781
static struct ast_taskpool * taskpool
Definition: stasis.c:374
static void send_subscription_subscribe(struct stasis_topic *topic, struct stasis_subscription *sub)
Definition: stasis.c:1715
@ STASIS_SUBSCRIPTION_FILTER_NONE
Definition: stasis.h:295
@ STASIS_SUBSCRIPTION_FORMATTER_NONE
Definition: stasis.h:309
struct stasis_topic * topic
Definition: stasis.c:751
int subscriber_id
Definition: stasis.c:450
struct ast_taskprocessor * ast_taskpool_serializer(const char *name, struct ast_taskpool *pool)
Serialized execution of tasks within a ast_taskpool.
Definition: taskpool.c:819
struct ast_taskprocessor * ast_taskprocessor_get(const char *name, enum ast_tps_options create)
Get a reference to a taskprocessor with the specified name and create the taskprocessor if necessary.
void ast_taskprocessor_set_local(struct ast_taskprocessor *tps, void *local_data)
Sets the local data associated with a taskprocessor.
@ TPS_REF_DEFAULT
return a reference to a taskprocessor, create one if it does not exist
Definition: taskprocessor.h:76
void ast_taskprocessor_build_name(char *buf, unsigned int size, const char *format,...)
Build a taskprocessor name with a sequence number on the end.
#define AST_TASKPROCESSOR_MAX_NAME
Suggested maximum taskprocessor name length (less null terminator).
Definition: taskprocessor.h:61
static void statistics(void)
Definition: utils/frame.c:287
#define AST_VECTOR_INIT(vec, size)
Initialize a vector.
Definition: vector.h:124

References ao2_ref, ao2_t_alloc, ast_asprintf, ast_atomic_fetchadd_int(), ast_cond_init, ast_taskpool_serializer(), ast_taskprocessor_build_name(), ast_taskprocessor_get(), AST_TASKPROCESSOR_MAX_NAME, ast_taskprocessor_set_local(), AST_VECTOR_INIT, callback(), stasis_subscription::data, make_ari_stubs::file, NULL, send_subscription_subscribe(), STASIS_SUBSCRIPTION_FILTER_NONE, STASIS_SUBSCRIPTION_FORMATTER_NONE, stasis_topic_name(), statistics(), sub, stasis_topic::subscriber_id, subscription_dtor(), taskpool, stasis_subscription::topic, topic_add_subscription(), and TPS_REF_DEFAULT.

Referenced by __stasis_subscribe(), __stasis_subscribe_pool(), and stasis_caching_topic_create().