libtap Event Queues Programming Manual

libtap version 2 provides new functions to help you write tests in C/C++ for event driven (asynchronous) code, which can be particularly hard to test.

SYNOPSIS

#include <tap.h>

void * tap_dup(const void * mem, size_t size);
const void * tap_ev_arg(tap_ev ev, const char * name);
void tap_ev_free(tap_ev ev);
void tap_ev_queue_push(tap_ev_queue queue, const char * identifier, unsigned argc, ...);
void tap_ev_push(const char * identifier, unsigned argc, ...);
unsigned tap_ev_queue_count(tap_ev_queue queue, const char * identifier);
unsigned tap_ev_count(const char * identifier);
unsigned tap_ev_queue_length(tap_ev_queue queue);
unsigned tap_ev_length(void);
tap_ev tap_ev_queue_shift(tap_ev_queue queue);
tap_ev tap_ev_shift(void);
void tap_ev_queue_flush(tap_ev_queue queue);
void tap_ev_flush(void);
tap_ev_queue tap_ev_queue_get_default(void);
tap_ev_queue tap_ev_queue_new(void);

INTRODUCTION

The libtap library provides functions for writing unit test programs in C or C++. The API is similar to that of perl's Test::More, a powerful unit test library used extensively to test perl modules. Test programs written using libtap produce output consistent with the Test Anything Protocol. Though not required, a test harness that parses this protocol can run these tests and produce useful reports summarizing their success or failure.

For all function that take const char * format, ... as their last two parameters, format is a printf-like format string, and is followed by one or more arguments that are values to be formatted using that string.

Recording Events

tap_dup is a convenience function that allocates size bytes of memory and copies data from mem to the duplicate. This is useful when an event argument value is ephemeral and will no longer be valid by the time the test program processes it.

tap_ev_push pushes an event onto the default queue. The event has an identifier and a count of arguments argc, followed by zero or more arguments, each specified by a pair of char * key and void * value.

Processing Events

tap_ev_count returns the number of events with the given identifier in the default event queue.

tap_ev_length returns the total number of events in the default event queue.

tap_ev_shift shifts the first event from the head of the default event queue and returns it.

tap_ev_arg gets the value of an argument from event object ev by its name.

tap_ev_free frees the storage used by event ev.

tap_ev_flush remove and free all events from the default event queue.

Multiple Event Queues

Sometimes its helpful to deal with more than one independent stream of events. In that case, there are analogous functions that operate on a queue other than the default queue.

tap_ev_queue_get_default returns the default event queue.

tap_ev_queue_new allocates, constructs, and returns a new event queue.

tap_ev_queue_push pushes an event onto event queue queue. The event has an identifier and a count of arguments argc, followed by zero or more arguments, each specified by a pair of char * key and void * value.

tap_ev_queue_count returns the number of events with the given identifier in event queue queue.

tap_ev_queue_length returns the total number of in event queue queue.

tap_ev_queue_shift shifts the first event from the head of event queue queue and returns it.

tap_ev_queue_flush remove and free all events from event queue queue.

EXAMPLES

libtap event queues are used in many unit tests in the sxe open source project, available from github.com.

HISTORY

libtap event queues were added to allow the event driven code in the sxe project to be more easily tested.

AUTHOR

Jim Belton (my.name@gmail.com)