stasis_test.h File Reference

Test infrastructure for dealing with Stasis. More...

#include "asterisk/lock.h"
#include "asterisk/stasis.h"

Include dependency graph for stasis_test.h:

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

Go to the source code of this file.

Data Structures
struct	stasis_message_sink
	Structure that collects messages from a topic. More...

Macros
#define	STASIS_SINK_DEFAULT_WAIT   5000

Typedefs
typedef int(*	stasis_wait_cb) (struct stasis_message *msg, const void *data)

Functions
stasis_subscription_cb	stasis_message_sink_cb (void)
	Topic callback to receive messages. More...
struct stasis_message_sink *	stasis_message_sink_create (void)
	Create a message sink. More...
int	stasis_message_sink_should_stay (struct stasis_message_sink *sink, int num_messages, int timeout_millis)
	Ensures that no new messages are received. More...
int	stasis_message_sink_wait_for (struct stasis_message_sink *sink, int start, stasis_wait_cb cmp_cb, const void *data, int timeout_millis)
	Wait for a message that matches the given criteria. More...
int	stasis_message_sink_wait_for_count (struct stasis_message_sink *sink, int num_messages, int timeout_millis)
	Wait for a sink's num_messages field to reach a certain level. More...
struct stasis_message *	stasis_test_message_create (void)
	Creates a test message. More...
struct stasis_message_type *	stasis_test_message_type (void)
	Gets the type of messages created by stasis_test_message_create(). More...

Detailed Description

Test infrastructure for dealing with Stasis.

Author

David M. Lee, II dlee@.nosp@m.digi.nosp@m.um.co.nosp@m.m

This file contains some helpful utilities for testing Stasis related topics and messages. The stasis_message_sink is something you can subscribe to a topic which will receive all of the messages from the topic. This messages are accumulated in its messages field.

There are a set of wait functions (stasis_message_sink_wait_for_count(), stasis_message_sink_wait_for(), etc.) which will block waiting for conditions to be met in the stasis_message_sink.

Definition in file stasis_test.h.

Macro Definition Documentation

STASIS_SINK_DEFAULT_WAIT

#define STASIS_SINK_DEFAULT_WAIT   5000

Definition at line 41 of file stasis_test.h.

Typedef Documentation

stasis_wait_cb

typedef int(* stasis_wait_cb) (struct stasis_message *msg, const void *data)

Definition at line 95 of file stasis_test.h.

Function Documentation

stasis_message_sink_cb()

stasis_subscription_cb stasis_message_sink_cb

(

void

)

Topic callback to receive messages.

We return a function pointer instead of simply exposing the function because of the vagaries of dlopen(), RTLD_LAZY, and function pointers. See the comment on the implementation for details why.

Returns

Function pointer to stasis_message_sink's message handling function

Definition at line 143 of file res_stasis_test.c.

{
    return message_sink_cb;
}

References message_sink_cb().

Referenced by AST_TEST_DEFINE().

stasis_message_sink_create()

struct stasis_message_sink * stasis_message_sink_create

(

void

)

Create a message sink.

This is an AO2 managed object, which you ao2_cleanup() when done. The destructor waits for an unsubscribe message to be received, to ensure the object isn't disposed of before the topic is finished.

Definition at line 79 of file res_stasis_test.c.

{
    RAII_VAR(struct stasis_message_sink *, sink, NULL, ao2_cleanup);
 
    sink = ao2_alloc(sizeof(*sink), stasis_message_sink_dtor);
    if (!sink) {
        return NULL;
    }
    ast_mutex_init(&sink->lock);
    ast_cond_init(&sink->cond, NULL);
    sink->max_messages = 4;
    sink->messages =
        ast_malloc(sizeof(*sink->messages) * sink->max_messages);
    if (!sink->messages) {
        return NULL;
    }
    ao2_ref(sink, +1);
    return sink;
}

References ao2_alloc, ao2_cleanup, ao2_ref, ast_cond_init, ast_malloc, ast_mutex_init, NULL, RAII_VAR, and stasis_message_sink_dtor().

Referenced by AST_TEST_DEFINE().

stasis_message_sink_should_stay()

int stasis_message_sink_should_stay	(	struct stasis_message_sink *	sink,
		int	num_messages,
		int	timeout_millis
	)

Ensures that no new messages are received.

The optional timeout prevents complete deadlock in a test.

Parameters

sink	Sink to wait on.
num_messages	expecte sink->num_messages.
timeout_millis	Number of milliseconds to wait for.

Returns

Actual sink->num_messages value at return. If this is < num_messages, then the timeout expired.

Definition at line 170 of file res_stasis_test.c.

{
    struct timespec deadline = make_deadline(timeout_millis);
 
    SCOPED_MUTEX(lock, &sink->lock);
    while (sink->num_messages == num_messages) {
        int r = ast_cond_timedwait(&sink->cond, &sink->lock, &deadline);
 
        if (r == ETIMEDOUT) {
            break;
        }
        if (r != 0) {
            ast_log(LOG_ERROR, "Unexpected condition error: %s\n",
                strerror(r));
            break;
        }
    }
    return sink->num_messages;
}

References ast_cond_timedwait, ast_log, stasis_message_sink::cond, lock, stasis_message_sink::lock, LOG_ERROR, make_deadline(), stasis_message_sink::num_messages, and SCOPED_MUTEX.

stasis_message_sink_wait_for()

int stasis_message_sink_wait_for	(	struct stasis_message_sink *	sink,
		int	start,
		stasis_wait_cb	cmp_cb,
		const void *	data,
		int	timeout_millis
	)

Wait for a message that matches the given criteria.

Parameters

sink	Sink to wait on.
start	Index of message to start with.
cmp_cb	comparison function. This returns true (non-zero) on match and false (zero) on match.
data
timeout_millis	Number of milliseconds to wait.

Returns

Index of the matching message.

Negative for no match.

Definition at line 191 of file res_stasis_test.c.

{
    struct timespec deadline = make_deadline(timeout_millis);
 
    SCOPED_MUTEX(lock, &sink->lock);
 
    /* wait for the start */
    while (sink->num_messages < start + 1) {
        int r = ast_cond_timedwait(&sink->cond, &sink->lock, &deadline);
 
        if (r == ETIMEDOUT) {
            /* Timed out waiting for the start */
            return -1;
        }
        if (r != 0) {
            ast_log(LOG_ERROR, "Unexpected condition error: %s\n",
                strerror(r));
            return -2;
        }
    }
 
 
    while (!cmp_cb(sink->messages[start], data)) {
        ++start;
 
        while (sink->num_messages < start + 1) {
            int r = ast_cond_timedwait(&sink->cond,
                &sink->lock, &deadline);
 
            if (r == ETIMEDOUT) {
                return -1;
            }
            if (r != 0) {
                ast_log(LOG_ERROR,
                    "Unexpected condition error: %s\n",
                    strerror(r));
                return -2;
            }
        }
    }
 
    return start;
}

References ast_cond_timedwait, ast_log, stasis_message_sink::cond, lock, stasis_message_sink::lock, LOG_ERROR, make_deadline(), stasis_message_sink::messages, stasis_message_sink::num_messages, and SCOPED_MUTEX.

Referenced by AST_TEST_DEFINE().

stasis_message_sink_wait_for_count()

int stasis_message_sink_wait_for_count	(	struct stasis_message_sink *	sink,
		int	num_messages,
		int	timeout_millis
	)

Wait for a sink's num_messages field to reach a certain level.

The optional timeout prevents complete deadlock in a test.

Parameters

sink	Sink to wait on.
num_messages	sink->num_messages value to wait for.
timeout_millis	Number of milliseconds to wait. -1 to wait forever.

Returns

Actual sink->num_messages value at return. If this is < num_messages, then the timeout expired.

Definition at line 149 of file res_stasis_test.c.

{
    struct timespec deadline = make_deadline(timeout_millis);
 
    SCOPED_MUTEX(lock, &sink->lock);
    while (sink->num_messages < num_messages) {
        int r = ast_cond_timedwait(&sink->cond, &sink->lock, &deadline);
 
        if (r == ETIMEDOUT) {
            break;
        }
        if (r != 0) {
            ast_log(LOG_ERROR, "Unexpected condition error: %s\n",
                strerror(r));
            break;
        }
    }
    return sink->num_messages;
}

References ast_cond_timedwait, ast_log, stasis_message_sink::cond, lock, stasis_message_sink::lock, LOG_ERROR, make_deadline(), stasis_message_sink::num_messages, and SCOPED_MUTEX.

Referenced by AST_TEST_DEFINE().