WAND Trace processing  4.0.5
libtrace_parallel.h File Reference

Header file containing definitions for structures and functions related to the parallel framework. More...

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

Go to the source code of this file.

Data Structures

union  libtrace_generic_t
 A collection of types for convenience used in place of a simple void* to allow any type of data to be stored and passed around easily. More...
 
struct  libtrace_message_t
 Structure describing a message that can be sent to a libtrace thread. More...
 
struct  libtrace_result_t
 Structure holding information about a result. More...
 
struct  libtrace_info_t
 
struct  libtrace_combine
 The methods we use to combine the results from multiple processing threads into a single output. More...
 

Typedefs

typedef struct libtrace_result_t libtrace_result_t
 
typedef struct libtrace_message_t libtrace_message_t
 Structure describing a message that can be sent to a libtrace thread. More...
 
typedef struct libtrace_info_t libtrace_info_t
 
typedef struct libtrace_combine libtrace_combine_t
 
typedef uint64_t(* fn_hasher )(const libtrace_packet_t *packet, void *data)
 The definition for a hasher function, allowing matching packets to be directed to the correct thread for processing. More...
 
typedef void *(* fn_cb_starting )(libtrace_t *libtrace, libtrace_thread_t *t, void *global)
 The starting callback for a processing or reporting thread. More...
 
typedef void(* fn_cb_dataless )(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls)
 A callback function for any message that does not require any specific data, e.g. More...
 
typedef void(* fn_cb_first_packet )(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, libtrace_thread_t *sender)
 A callback function for a first packet message seen by a processing thread. More...
 
typedef void(* fn_cb_tick )(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, uint64_t order)
 A callback function for handling a tick message within a processing thread. More...
 
typedef libtrace_packet_t *(* fn_cb_packet )(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, libtrace_packet_t *packet)
 A callback function triggered when a processing thread receives a packet. More...
 
typedef void(* fn_cb_result )(libtrace_t *libtrace, libtrace_thread_t *sender, void *global, void *tls, libtrace_result_t *result)
 Callback for handling a result message. More...
 
typedef void(* fn_cb_usermessage )(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, int mesg, libtrace_generic_t data, libtrace_thread_t *sender)
 Callback for handling any user-defined message types. More...
 

Enumerations

enum  libtrace_messages {
  MESSAGE_PACKET, MESSAGE_RESULT, MESSAGE_STARTING, MESSAGE_STOPPING,
  MESSAGE_RESUMING, MESSAGE_PAUSING, MESSAGE_DO_PAUSE, MESSAGE_DO_STOP,
  MESSAGE_FIRST_PACKET, MESSAGE_POST_REPORTER, MESSAGE_TICK_INTERVAL, MESSAGE_TICK_COUNT,
  MESSAGE_USER = 1000
}
 The libtrace_messages enum All libtrace messages are defined and documented here. More...
 
enum  hasher_types { HASHER_BALANCE, HASHER_BIDIRECTIONAL, HASHER_UNIDIRECTIONAL, HASHER_CUSTOM }
 The hasher types that are available to libtrace applications. More...
 
enum  result_types { RESULT_PACKET, RESULT_TICK_INTERVAL, RESULT_TICK_COUNT, RESULT_USER = 1000 }
 Types of results. More...
 

Functions

 ct_assert (sizeof(libtrace_generic_t)==8)
 
DLLEXPORT int trace_pstart (libtrace_t *libtrace, void *global_blob, libtrace_callback_set_t *per_packet_cbs, libtrace_callback_set_t *reporter_cbs)
 Start or restart an input trace in the parallel libtrace framework. More...
 
DLLEXPORT int trace_set_starting_cb (libtrace_callback_set_t *cbset, fn_cb_starting handler)
 Registers a starting callback against a callback set. More...
 
DLLEXPORT int trace_set_stopping_cb (libtrace_callback_set_t *cbset, fn_cb_dataless handler)
 Registers a stopping callback against a callback set. More...
 
DLLEXPORT int trace_set_resuming_cb (libtrace_callback_set_t *cbset, fn_cb_dataless handler)
 Registers a resuming callback against a callback set. More...
 
DLLEXPORT int trace_set_pausing_cb (libtrace_callback_set_t *cbset, fn_cb_dataless handler)
 Registers a pausing callback against a callback set. More...
 
DLLEXPORT int trace_set_packet_cb (libtrace_callback_set_t *cbset, fn_cb_packet handler)
 Registers a packet callback against a callback set. More...
 
DLLEXPORT int trace_set_first_packet_cb (libtrace_callback_set_t *cbset, fn_cb_first_packet handler)
 Registers a first packet callback against a callback set. More...
 
DLLEXPORT int trace_set_result_cb (libtrace_callback_set_t *cbset, fn_cb_result handler)
 Registers a result callback against a callback set. More...
 
DLLEXPORT int trace_set_tick_count_cb (libtrace_callback_set_t *cbset, fn_cb_tick handler)
 Registers a tick counter callback against a callback set. More...
 
DLLEXPORT int trace_set_tick_interval_cb (libtrace_callback_set_t *cbset, fn_cb_tick handler)
 Registers a tick interval callback against a callback set. More...
 
DLLEXPORT int trace_set_user_message_cb (libtrace_callback_set_t *cbset, fn_cb_usermessage handler)
 Registers a callback for custom user messages against a callback set. More...
 
DLLEXPORT libtrace_callback_set_ttrace_create_callback_set (void)
 Create a callback set that can be used to define callbacks for parallel libtrace threads. More...
 
DLLEXPORT void trace_destroy_callback_set (libtrace_callback_set_t *cbset)
 Destroys a callback set, freeing up any resources it was using. More...
 
DLLEXPORT int trace_ppause (libtrace_t *libtrace)
 Pauses a trace previously started with trace_pstart() More...
 
DLLEXPORT int trace_pstop (libtrace_t *libtrace)
 Stops a parallel trace, causing all threads to exit as if an EOF has occurred. More...
 
DLLEXPORT void trace_join (libtrace_t *trace)
 Waits for a trace to finish and all threads to join. More...
 
DLLEXPORT void trace_publish_result (libtrace_t *libtrace, libtrace_thread_t *t, uint64_t key, libtrace_generic_t value, int type)
 Publish a result to the reporter thread (via the combiner) More...
 
DLLEXPORT bool trace_has_dedicated_hasher (libtrace_t *libtrace)
 Check if a dedicated hasher thread is being used. More...
 
DLLEXPORT bool trace_has_reporter (libtrace_t *libtrace)
 Checks if a trace is using a reporter thread. More...
 
DLLEXPORT int trace_post_reporter (libtrace_t *libtrace)
 Post a message to the reporter thread requesting that it check for more results. More...
 
DLLEXPORT int libtrace_thread_get_message_count (libtrace_t *libtrace, libtrace_thread_t *t)
 Check the number of messages waiting in a thread's message queue. More...
 
DLLEXPORT int libtrace_thread_get_message (libtrace_t *libtrace, libtrace_thread_t *t, libtrace_message_t *message)
 Read a message from a thread in a blocking fashion. More...
 
DLLEXPORT int libtrace_thread_try_get_message (libtrace_t *libtrace, libtrace_thread_t *t, libtrace_message_t *message)
 Read a message from a thread in a non-blocking fashion. More...
 
DLLEXPORT int trace_message_reporter (libtrace_t *libtrace, libtrace_message_t *message)
 Send a message to the reporter thread. More...
 
DLLEXPORT int trace_message_perpkts (libtrace_t *libtrace, libtrace_message_t *message)
 Send a message to all processing threads. More...
 
DLLEXPORT int trace_message_thread (libtrace_t *libtrace, libtrace_thread_t *t, libtrace_message_t *message)
 Send a message to a specific thread. More...
 
DLLEXPORT bool trace_has_finished (libtrace_t *libtrace)
 Checks if a parallel trace has finished reading packets. More...
 
DLLEXPORT bool trace_is_parallel (libtrace_t *libtrace)
 Check if libtrace is directly reading from multiple queues from within the capture format (such as a NICs hardware queues). More...
 
DLLEXPORT uint64_t trace_packet_get_order (libtrace_packet_t *packet)
 Returns either the sequence number or erf timestamp of a packet. More...
 
DLLEXPORT uint64_t trace_packet_get_hash (libtrace_packet_t *packet)
 Returns the hash of a packet. More...
 
DLLEXPORT void trace_packet_set_order (libtrace_packet_t *packet, uint64_t order)
 Sets the order of a packet. More...
 
DLLEXPORT void trace_packet_set_hash (libtrace_packet_t *packet, uint64_t hash)
 Sets the hash of a packet. More...
 
DLLEXPORT int trace_get_first_packet (libtrace_t *libtrace, libtrace_thread_t *t, const libtrace_packet_t **packet, const struct timeval **tv)
 Returns the first packet read by a processing thread since the source trace was last started or restarted. More...
 
DLLEXPORT void libtrace_make_packet_safe (libtrace_packet_t *pkt)
 Makes a packet safe, preventing the packet from becoming invalid after a pausing a trace. More...
 
DLLEXPORT void libtrace_make_result_safe (libtrace_result_t *res)
 Makes a result safe, preventing the result from becoming invalid after pausing a trace. More...
 
DLLEXPORT void trace_free_packet (libtrace_t *libtrace, libtrace_packet_t *packet)
 In a parallel trace, free a packet back to libtrace. More...
 
DLLEXPORT void trace_increment_packet_refcount (libtrace_packet_t *packet)
 Increments the internal reference counter for a packet. More...
 
DLLEXPORT void trace_decrement_packet_refcount (libtrace_packet_t *packet)
 Decrements the internal reference counter for a packet. More...
 
DLLEXPORT libtrace_info_ttrace_get_information (libtrace_t *libtrace)
 Provides some basic information about a trace based on its input format. More...
 
DLLEXPORT int trace_set_configuration (libtrace_t *trace, const char *str)
 Sets the configuration of a trace based upon a comma separated list of key value pairs. More...
 
DLLEXPORT int trace_set_configuration_file (libtrace_t *trace, FILE *file)
 Sets configuration from a file. More...
 
DLLEXPORT int trace_get_perpkt_threads (libtrace_t *t)
 Returns the number of processing threads that have been created for a given trace. More...
 
DLLEXPORT int trace_get_perpkt_thread_id (libtrace_thread_t *thread)
 Returns the internal unique ID for a packet processing thread. More...
 
DLLEXPORT void trace_set_combiner (libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config)
 Sets a combiner function for an input trace. More...
 
Parallel Configuration

These methods provide a way to configure the parallel libtrace library.

Many of these options are typically unneeded by most applications as they control tuning aspects of the library and are more useful to the end user.

To allow the end user to change this configuration libtrace will search for three environment variables and apply them to the configuration in the following order. Such that the first has the lowest priority.

  1. LIBTRACE_CONF, The global environment configuration
  2. LIBTRACE_CONF_<FORMAT>, Applied to a given format
  3. LIBTRACE_CONF_<FORMAT_URI>, Applied the specified trace

E.g.

  • int:eth0 would match LIBTRACE_CONF, LIBTRACE_CONF_INT, LIBTRACE_CONF_INT_ETH0
  • dag:/dev/dag0,0 would match LIBTRACE_CONF, LIBTRACE_CONF_DAG, LIBTRACE_CONF_DAG__DEV_DAG0_0
  • test.erf would match LIBTRACE_CONF, LIBTRACE_CONF_ERF, LIBTRACE_CONF_ERF_TEST_ERF
Note
All environment variables names MUST only contain [A-Z], [0-9] and [_] (underscore). Any characters outside of this range should be capitalised if possible or replaced with an underscore.
DLLEXPORT int trace_set_perpkt_threads (libtrace_t *trace, int nb)
 Set the maximum number of perpkt threads to use in a trace. More...
 
DLLEXPORT int trace_set_tick_interval (libtrace_t *trace, size_t millisec)
 Set the interval between tick messages in milliseconds. More...
 
DLLEXPORT int trace_set_tick_count (libtrace_t *trace, size_t count)
 Set the number of packets to be read between tick messages. More...
 
DLLEXPORT int trace_set_tracetime (libtrace_t *trace, bool tracetime)
 Delays packets so they are played back in trace-time rather than as fast as possible (real-time). More...
 
DLLEXPORT int trace_set_cache_size (libtrace_t *trace, size_t size)
 Sets the maximum size of the freelist used to store empty packets and their memory buffers. More...
 
DLLEXPORT int trace_set_thread_cache_size (libtrace_t *trace, size_t size)
 This sets the maximum size of the freelist cache owned by each thread used to provide faster access to empty packets than the main shared pool. More...
 
DLLEXPORT int trace_set_fixed_count (libtrace_t *trace, bool fixed)
 Determines whether a trace is allowed to create additional packets beyond the cache size. More...
 
DLLEXPORT int trace_set_burst_size (libtrace_t *trace, size_t size)
 The number of packets to batch together for processing internally by libtrace. More...
 
DLLEXPORT int trace_set_hasher_queue_size (libtrace_t *trace, size_t size)
 Sets the maximum size of the buffer used between the single hasher thread and the packet processing thread. More...
 
DLLEXPORT int trace_set_hasher_polling (libtrace_t *trace, bool polling)
 Enables or disables polling of the hasher queue. More...
 
DLLEXPORT int trace_set_reporter_polling (libtrace_t *trace, bool polling)
 Enables or disables polling of the reporter result queue. More...
 
DLLEXPORT int trace_set_reporter_thold (libtrace_t *trace, size_t thold)
 Set the number of results that are required in the result queue before a MESSAGE_POST_REPORTER is sent to the reporter so that it can read the results. More...
 
DLLEXPORT int trace_set_debug_state (libtrace_t *trace, bool debug_state)
 Enable or disable debug output for parallel libtrace. More...
 
DLLEXPORT int trace_set_hasher (libtrace_t *trace, enum hasher_types type, fn_hasher hasher, void *data)
 Set the hasher function for a parallel trace. More...
 

Variables

const libtrace_combine_t combiner_unordered
 Takes unordered (or ordered) input and produces unordered output. More...
 
const libtrace_combine_t combiner_ordered
 Takes ordered input and produces ordered output. More...
 
const libtrace_combine_t combiner_sorted
 Like classic Google Map/Reduce, the results are sorted in ascending order based on their key. More...
 

Detailed Description

Header file containing definitions for structures and functions related to the parallel framework.

Author
Richard Sanger
Version
4.0.0

The parallel libtrace framework is a replacement to the libtrace framework that allows packet processing workload to be spread over multiple threads. It can also take advantage of native parallelism in the packet capture source.

Typedef Documentation

typedef void(* fn_cb_dataless)(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls)

A callback function for any message that does not require any specific data, e.g.

stopping, pausing, or resuming callbacks.

Parameters
libtraceThe parallel trace.
tThe thread that is running.
globalThe global storage.
tlsThe thread local storage.
typedef void(* fn_cb_first_packet)(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, libtrace_thread_t *sender)

A callback function for a first packet message seen by a processing thread.

Parameters
libtraceThe parallel trace.
tThe thread that is running.
globalThe global storage.
tlsThe thread local storage.
senderThe thread that saw the first packet.
typedef libtrace_packet_t*(* fn_cb_packet)(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, libtrace_packet_t *packet)

A callback function triggered when a processing thread receives a packet.

Parameters
libtraceThe parallel trace.
tThe thread that is running
globalThe global storage.
tlsThe thread local storage.
packetThe packet to be processed.
Returns
either the packet itself if it is not being published as a result or NULL otherwise. If returning NULL, it is the user's responsibility to ensure the packet is freed when the reporter thread is finished with it.
typedef void(* fn_cb_result)(libtrace_t *libtrace, libtrace_thread_t *sender, void *global, void *tls, libtrace_result_t *result)

Callback for handling a result message.

Should only be required by the reporter thread.

Parameters
libtraceThe parallel trace.
senderThe thread that generated this result.
globalThe global storage.
tlsThe thread local storage.
resultThe result associated with the message.
typedef void*(* fn_cb_starting)(libtrace_t *libtrace, libtrace_thread_t *t, void *global)

The starting callback for a processing or reporting thread.

Use this callback to allocate and initialise any thread-local storage that you would like to be available in other callbacks.

Parameters
libtraceThe parallel trace.
tThe thread that has just started.
globalThe global storage for the trace.
Returns
The returned value is stored against the thread's local storage. This is typically passed as the 'tls' argument to other callbacks.
typedef void(* fn_cb_tick)(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, uint64_t order)

A callback function for handling a tick message within a processing thread.

Parameters
libtraceThe parallel trace.
tThe thread that is running.
globalThe global storage.
tlsThe thread local storage.
uint64_tThe value of the tick; either a timestamp or packet count depending on the type of tick.
typedef void(* fn_cb_usermessage)(libtrace_t *libtrace, libtrace_thread_t *t, void *global, void *tls, int mesg, libtrace_generic_t data, libtrace_thread_t *sender)

Callback for handling any user-defined message types.

This will handle any messages with a type >= MESSAGE_USER.

Parameters
libtraceThe parallel trace.
tThe thread.
globalThe global storage.
tlsThe thread local storage.
mesgThe code identifying the message type.
dataThe data associated with the message.
typedef uint64_t(* fn_hasher)(const libtrace_packet_t *packet, void *data)

The definition for a hasher function, allowing matching packets to be directed to the correct thread for processing.

Parameters
packetThe packet to be hashed.
dataA void pointer which can contain additional information, such as configuration for the hasher function.
Returns
The id of the thread that should receive this packet.

Structure describing a message that can be sent to a libtrace thread.

Enumeration Type Documentation

The hasher types that are available to libtrace applications.

These can be selected using trace_set_hasher().

Enumerator
HASHER_BALANCE 

Balance load across per-packet threads as best as possible, i.e the program does not care which thread sees a given packet.

This will be implemented using a hash or round robin, depending on the format and libtrace configuration.

HASHER_BIDIRECTIONAL 

Use a hash which is bi-directional for TCP and UDP flows, such that packets with the same 5-tuple are sent to the same processing thread.

All non TCP/UDP packets will be sent to the same thread.

Note
it is possible that UDP packets may not be spread across processing threads, depending upon the format support. In this case they would be directed to a single thread.
HASHER_UNIDIRECTIONAL 

Use a hash which is uni-directional across TCP and UDP flows, such that the opposing directions of the same 5-tuple may end up on different processing threads.

Otherwise this is identical to HASHER_BIDIRECTIONAL.

HASHER_CUSTOM 

This value indicates that the hasher is a custom user-defined function.

The libtrace_messages enum All libtrace messages are defined and documented here.

Some messages can be sent to control the internal behaviour of the library while others are used to trigger the user-defined callback functions. If a user wishes to send their own custom messages, they should use numbers greater than MESSAGE_USER (1000).

Note
Some messages are for internal use only
Enumerator
MESSAGE_PACKET 

A libtrace packet is ready, this will trigger the packet callback for the processing threads.

MESSAGE_RESULT 

A libtrace result is ready, this will trigger the result callback for the reporter thread.

MESSAGE_STARTING 

This message is sent to each thread when it first starts and will trigger the starting callback for the processing and reporter threads.

A starting message is sent when trace_pstart is called for the first time on a trace.

MESSAGE_STOPPING 

This message is sent to each thread when the thread ends and will trigger the stopping callback for the processing and reporter threads.

MESSAGE_RESUMING 

This message is sent to each thread when the thread transitions from a paused state to a running state.

It will trigger the resuming callback for the processing and reporter threads.

A resuming message is sent whenever trace_pstart is called on a trace (including the first time the trace is started).

MESSAGE_PAUSING 

This message is sent to each thread when the thread transitions into a paused state from a running state.

It will trigger the pausing callback for the processing and reporter threads.

A pausing message is sent whenever trace_ppause is called on a trace. It will also be sent when a trace is stopped, as all traces are implicitly paused before they stop.

MESSAGE_DO_PAUSE 

An internal message for forcing another thread to pause.

Do not use this in user-defined callbacks!

MESSAGE_DO_STOP 

An internal message for forcing another thread to stop.

Do not use this in user-defined callbacks!

MESSAGE_FIRST_PACKET 

This message is sent to each processing thread as soon as the first packet has been seen by any of the processing threads.

This will trigger the first_packet callback for the processing threads, allowing the threads to perform any initialisation required based on the properties of the first packet (e.g. the timestamp).

Threads should use trace_get_first_packet() to access the packet that triggered this message.

Note
Upon pausing and restarting a trace, this message will be sent again when the first new packet is encountered.
MESSAGE_POST_REPORTER 

An internal message for notifying the reporter thread that more results are available.

Do not use this in user-defined callbacks – call trace_post_reporter() instead.

MESSAGE_TICK_INTERVAL 

Sent to per-packet threads periodically after the configured time interval has passed.

This is sent out-of-band with respect to packets and as a result can appear after a packet with an later time-stamp, or before one with an earlier time-stamp.

Parameters
datadata.uint64 holds the system time-stamp in the erf format
sendershould be ignoredThis message is sent to the processing threads periodically, after the configured time interval has passed. This message will trigger the tick_interval callback function for the processing threads.

This message is sent out-of-band relative to packet messages and therefore can appear after a packet with a later timestamp or before a packet with an earlier timestamp.

MESSAGE_TICK_COUNT 

Sent to per-packet threads once the configured number of packets are read from a trace.

This are sent in-band with respect to packets such that all threads will see it between the same packets.

Parameters
datadata.uint64 holds the number of packets seen so far across all threads
senderSet to the current per-packet threadThis message is sent to the processing threads periodically, after the configured number of packets have been read from the input trace. This message will trigger the tick_count callback function for the processing threads.

This message is sent in-band relative to packet messages and will always appear in the right place relative to the other packets observed by the thread.

MESSAGE_USER 

All message codes at or above this value represent custom user-defined messages and will trigger the usermessage callback for the processing threads.

Types of results.

Custom result types users should be defined as RESULT_USER(1000) or greater.

Enumerator
RESULT_PACKET 

The result contains a pointer to a libtrace_packet_t.

This packet should be freed using trace_free_packet() once the result is processed by the reporter thread.

The key for a RESULT_PACKET is the packet order (see trace_get_packet_order() for more about ordering).

RESULT_TICK_INTERVAL 

The result is a tick timestamp.

The key is an ERF timestamp.

RESULT_TICK_COUNT 

The result is a tick counter.

The key is the sequence number of the tick, relative to the packets read so far.

RESULT_USER 

Any user-defined result codes should be at or above this value.

Function Documentation

DLLEXPORT void libtrace_make_packet_safe ( libtrace_packet_t pkt)

Makes a packet safe, preventing the packet from becoming invalid after a pausing a trace.

Parameters
[in,out]pktThe packet to make safe

This copies a packet in such a way that it will be able to survive a pause. However this will not allow the packet to be used after the format is destroyed.

References libtrace_packet_t::buf_control, trace_copy_packet(), TRACE_CTRL_PACKET, and trace_fin_packet().

Referenced by libtrace_make_result_safe().

DLLEXPORT void libtrace_make_result_safe ( libtrace_result_t res)

Makes a result safe, preventing the result from becoming invalid after pausing a trace.

Parameters
[in,out]resThe result to make safe.

This ensures the internal content of a result is safe to survive a pause. Note that this is only an issue if the result contains a packet. See libtrace_make_packet_safe().

Makes a result safe, preventing the result from becoming invalid after pausing a trace.

This will call libtrace_make_packet_safe if the result is a packet.

References libtrace_make_packet_safe(), RESULT_PACKET, libtrace_result_t::type, and libtrace_result_t::value.

DLLEXPORT int libtrace_thread_get_message ( libtrace_t libtrace,
libtrace_thread_t t,
libtrace_message_t message 
)

Read a message from a thread in a blocking fashion.

Parameters
[in]libtraceThe input trace
[in]tThe thread to check, if NULL the current thread will be used.
[out]messageA pointer to a libtrace_message_t structure which will be filled with the retrieved message.
Returns
The number of messages remaining otherwise -1 upon error.
Note
For best performance it is recommended to supply the thread argument even if it is the current thread.
DLLEXPORT int libtrace_thread_get_message_count ( libtrace_t libtrace,
libtrace_thread_t t 
)

Check the number of messages waiting in a thread's message queue.

Parameters
[in]libtraceThe input trace
[in]tThe thread to check; if NULL the current thread will be used.
Returns
packets in the queue otherwise -1 upon error.
Note
For best performance it is recommended to supply the thread argument even if it is the current thread.
DLLEXPORT int libtrace_thread_try_get_message ( libtrace_t libtrace,
libtrace_thread_t t,
libtrace_message_t message 
)

Read a message from a thread in a non-blocking fashion.

Parameters
[in]libtraceThe input trace
[in]tThe thread to check, if NULL the current thread will be used.
[out]messageA pointer to a libtrace_message_t structure which will be filled with the retrieved message.
Returns
0 if successful otherwise -1 upon error or if no message were available.
Note
For best performance it is recommended to supply the thread argument even if it is the current thread.
DLLEXPORT libtrace_callback_set_t* trace_create_callback_set ( void  )

Create a callback set that can be used to define callbacks for parallel libtrace threads.

Returns
A pointer to a freshly allocated callback set.

Referenced by trace_pstart().

DLLEXPORT void trace_decrement_packet_refcount ( libtrace_packet_t packet)

Decrements the internal reference counter for a packet.

Parameters
packetThe packet opaque pointer

If the reference counter goes below one, trace_fin_packet() will be called on the packet.

You may wish to use this function (and its incrementing counterpart) in situations where you are retaining multiple references to a packet outside of the core packet processing function. This will ensure that the packet is not released until there are no more outstanding references to the packet anywhere in your program.

References libtrace_packet_t::ref_lock, libtrace_packet_t::refcount, libtrace_packet_t::trace, and trace_free_packet().

DLLEXPORT void trace_destroy_callback_set ( libtrace_callback_set_t cbset)

Destroys a callback set, freeing up any resources it was using.

Parameters
cbsetThe callback set to be destroyed.

Referenced by trace_destroy().

DLLEXPORT void trace_free_packet ( libtrace_t libtrace,
libtrace_packet_t packet 
)

In a parallel trace, free a packet back to libtrace.

Parameters
[in]libtraceA parallel input trace
[in]packetThe packet to be released back to libtrace

The packet should not be used after calling this function.

Note
Don't use this inside a packet callback function – just return the packet instead, as this will be faster.
All packets should be free'd before a trace is destroyed.

References libtrace_t::packet_freelist, and trace_fin_packet().

Referenced by trace_decrement_packet_refcount().

DLLEXPORT int trace_get_first_packet ( libtrace_t libtrace,
libtrace_thread_t t,
const libtrace_packet_t **  packet,
const struct timeval **  tv 
)

Returns the first packet read by a processing thread since the source trace was last started or restarted.

Parameters
[in]libtracethe parallel input trace.
[in]tEither a per packet thread or NULL to retrieve the earliest packet across all per packet threads.
[out]packetA pointer to the requested packet. [Optional]
[out]tvThe system time-stamp when the packet was received. [Optional]
Returns
1 if we are confident this is the first packet. Otherwise 0 if this is a best guess (this is only possible int the case t=NULL) in which case we recommend trying again at a later time. -1 is returned if an error occurs, such as when this function is supplied an invalid thread.

The packet and timeval returned by this function is shared by all threads and remain valid until MESSAGE_PAUSING is received.

References ASSERT_RET.

DLLEXPORT libtrace_info_t* trace_get_information ( libtrace_t libtrace)

Provides some basic information about a trace based on its input format.

Parameters
libtraceThe trace that is being inquired about.
Returns
a libtrace_info_t structure that contains information about the trace format, i.e. is it live or not, how many threads it supports.

See trace_is_parallel(), trace_get_perpkt_threads().

References libtrace_t::format, and libtrace_format_t::info.

DLLEXPORT int trace_get_perpkt_thread_id ( libtrace_thread_t thread)

Returns the internal unique ID for a packet processing thread.

Parameters
threadThe thread being queried.
Returns
The ID number of the thread or -1 if the thread is not a processing thread or is otherwise invalid.
DLLEXPORT int trace_get_perpkt_threads ( libtrace_t t)

Returns the number of processing threads that have been created for a given trace.

Parameters
tA parallel trace.
Returns
The number of processing threads owned by that trace.

Returns the number of processing threads that have been created for a given trace.

TODO what if the trace is not running yet, or has finished??

libtrace_perpkt_thread_nb

Parameters
tThe trace
Returns
DLLEXPORT bool trace_has_dedicated_hasher ( libtrace_t libtrace)

Check if a dedicated hasher thread is being used.

Parameters
[in]libtraceThe parallel input trace
Returns
true if the trace has dedicated hasher thread otherwise false.

This should only be called after the trace has been started with trace_pstart().

Referenced by trace_get_thread_statistics(), trace_join(), trace_ppause(), trace_pstart(), and trace_pstop().

DLLEXPORT bool trace_has_finished ( libtrace_t libtrace)

Checks if a parallel trace has finished reading packets.

Returns
true if the trace has finished reading packets (even if all results have not yet been processed). Otherwise false.
Note
This returns true even if all results have not yet been processed by the reporter thread.

References libtrace_t::state.

DLLEXPORT bool trace_has_reporter ( libtrace_t libtrace)

Checks if a trace is using a reporter thread.

Parameters
[in]libtraceThe parallel input trace
Returns
True if the trace is using a reporter otherwise false

References libtrace_t::state.

Referenced by trace_join(), trace_message_reporter(), and trace_ppause().

DLLEXPORT void trace_increment_packet_refcount ( libtrace_packet_t packet)

Increments the internal reference counter for a packet.

Parameters
packetThe packet opaque pointer

You may wish to use this function (and its decrementing counterpart) in situations where you are retaining multiple references to a packet outside of the core packet processing function. This will ensure that the packet is not released until there are no more outstanding references to the packet anywhere in your program.

References libtrace_packet_t::ref_lock, and libtrace_packet_t::refcount.

DLLEXPORT bool trace_is_parallel ( libtrace_t libtrace)

Check if libtrace is directly reading from multiple queues from within the capture format (such as a NICs hardware queues).

A trace is considered to be parallel if the input format for the trace allows the packets to be read in a natively parallel fashion, i.e. packets can be read using multiple pipelines. If this function returns false, the packets are instead being read from a single input source and then distributed amongst the processing threads.

Factors that may cause this function to return false despite the format normally supporting native parallel reads include: the choice of hasher function, the number of threads choosen (such as 1 or more than the trace supports) or another error when trying to start the parallel format.

If called before the trace is started, i.e. before trace_pstart(), this function returns an indication whether the trace has the possiblity to support native parallel reads. After trace_pstart() is called this should be checked again to confirm that this has happened.

Returns
true if the trace is parallel or false if the library is splitting the trace into multiple threads.

References libtrace_t::pread, and libtrace_t::state.

Referenced by trace_ppause().

DLLEXPORT void trace_join ( libtrace_t trace)

Waits for a trace to finish and all threads to join.

Parameters
traceThe parallel trace

Waits for a trace to finish, whether this be due to an error occurring, an EOF or trace_pstop.

References ASSERT_RET, libtrace_message_t::code, MESSAGE_DO_STOP, trace_destroy_packet(), trace_has_dedicated_hasher(), trace_has_reporter(), and trace_message_thread().

DLLEXPORT int trace_message_perpkts ( libtrace_t libtrace,
libtrace_message_t message 
)

Send a message to all processing threads.

Parameters
[in]libtraceThe parallel trace
[in]messageThe message to be sent. If the sender field is NULL, libtrace will attempt to fill this in. It is faster to assign this if it is known.
Returns
0 if successful. Otherwise, a negative number is returned that indicates the number of processing threads that the message was not sent to (i.e. -1 means one thread could not be sent the message).

References libtrace_message_t::sender.

Referenced by store_first_packet(), and trace_pstop().

DLLEXPORT int trace_message_reporter ( libtrace_t libtrace,
libtrace_message_t message 
)

Send a message to the reporter thread.

Parameters
[in]libtraceThe parallel trace
[in]messageThe message to be sent. If the sender field is NULL, libtrace will attempt to fill this in. It is faster to assign this if it is known.
Returns
-1 upon error indicating the message has not been sent. Otherwise, will return the number of messages the reporter has not yet read.

References trace_has_reporter(), and trace_message_thread().

Referenced by store_first_packet(), and trace_post_reporter().

DLLEXPORT int trace_message_thread ( libtrace_t libtrace,
libtrace_thread_t t,
libtrace_message_t message 
)

Send a message to a specific thread.

Parameters
[in]libtraceThe parallel trace
[in]tThe thread to message
[in]messageThe message to be sent. If the sender field is NULL, libtrace will attempt to fill this in. It is faster to assign this if it is known.
Returns
-1 upon error indicating the message has not been sent. Otherwise, will return the number of messages the recipient has not yet read.

References libtrace_message_t::sender.

Referenced by trace_join(), trace_message_reporter(), trace_ppause(), and trace_pstop().

DLLEXPORT uint64_t trace_packet_get_hash ( libtrace_packet_t packet)

Returns the hash of a packet.

Parameters
[in]packet
Returns
A 64-bit hash
Note
This function will only work in situations where a custom hash is being used. You can use trace_has_dedicated_hasher() to check if this is the case.

References libtrace_packet_t::hash.

DLLEXPORT uint64_t trace_packet_get_order ( libtrace_packet_t packet)

Returns either the sequence number or erf timestamp of a packet.

Parameters
[in]packet
Returns
A 64bit sequence number or erf timestamp.

The returned value can be used to compare the relative ordering of packets. Formats that are not natively parallel will typically return a sequence number. Natively parallel formats will return a timestamp.

References libtrace_packet_t::order.

DLLEXPORT void trace_packet_set_hash ( libtrace_packet_t packet,
uint64_t  hash 
)

Sets the hash of a packet.

Parameters
[in]packet
[in]hashthe new hash

Once a packet reaches the processing thread, the libtrace library has little use for this field and as such this can essentially be used for any storage that the user requires.

References libtrace_packet_t::hash.

DLLEXPORT void trace_packet_set_order ( libtrace_packet_t packet,
uint64_t  order 
)

Sets the order of a packet.

Parameters
[in]packet
[in]orderthe new order of a packet
Note
Many combiners rely on this value, so please ensure that changing this conforms to the expectations of the combiner.

Generally speaking, you probably shouldn't be changing the order of packets!

References libtrace_packet_t::order.

Referenced by trace_read_packet().

DLLEXPORT int trace_post_reporter ( libtrace_t libtrace)

Post a message to the reporter thread requesting that it check for more results.

Parameters
[in]Theparallel input trace
Returns
-1 upon error indicating the message has not been sent otherwise a backlog indicator (the number of messages the reporter has not yet read).

References libtrace_message_t::code, MESSAGE_POST_REPORTER, and trace_message_reporter().

DLLEXPORT int trace_pstart ( libtrace_t libtrace,
void *  global_blob,
libtrace_callback_set_t per_packet_cbs,
libtrace_callback_set_t reporter_cbs 
)

Start or restart an input trace in the parallel libtrace framework.

Parameters
libtraceThe input trace to start
global_blobGlobal data related to this trace. This may be NULL if no global data is required.
per_packet_cbsA set of user supplied functions to be called in response to messages that are observed by the processing threads.
reporter_cbsA set of user supplied functions to be called in response to messages being seen by the reporter thread. Optional if NULL, the reporter thread will not be started.
Returns
0 on success, otherwise -1 to indicate an error has occurred

This can also be used to restart an existing parallel trace, that has previously been paused using trace_ppause(). In this case global_blob, per_packet_cbs and reporter_cbs will only be updated if they are non-null. Otherwise their previous values will be maintained.

References ASSERT_RET, libtrace_t::format, libtrace_t::global_blob, libtrace_format_t::info, libtrace_combine::initialise, libtrace_t::libtrace_lock, libtrace_info_t::live, libtrace_t::packet_freelist, libtrace_format_t::pause_input, libtrace_t::perpkt_thread_states, libtrace_format_t::ppause_input, libtrace_t::pread, libtrace_format_t::pstart_input, snprintf(), libtrace_format_t::start_input, libtrace_t::startcount, libtrace_t::started, libtrace_t::state, trace_create_callback_set(), trace_create_packet(), trace_destroy_packet(), TRACE_ERR_BAD_STATE, TRACE_ERR_INIT_FAILED, trace_has_dedicated_hasher(), trace_is_err(), and trace_set_err().

DLLEXPORT int trace_pstop ( libtrace_t libtrace)

Stops a parallel trace, causing all threads to exit as if an EOF has occurred.

This replaces trace_interrupt(), allowing a specified trace to be stopped.

Parameters
libtraceThe parallel trace to be stopped
Returns
0 on success, otherwise -1 to indicate an error has occurred

Ideally, this should only be called by the main thread (i.e. from a signal handler) but it can be called from within a reporter thread reasonably safely.

Stops a parallel trace, causing all threads to exit as if an EOF has occurred.

  1. Calls ppause
  2. Sends a message asking for threads to finish
  3. Releases threads which will pause

References libtrace_message_t::code, MESSAGE_DO_STOP, trace_has_dedicated_hasher(), trace_message_perpkts(), trace_message_thread(), and trace_ppause().

DLLEXPORT void trace_publish_result ( libtrace_t libtrace,
libtrace_thread_t t,
uint64_t  key,
libtrace_generic_t  value,
int  type 
)

Publish a result to the reporter thread (via the combiner)

Parameters
[in]libtraceThe parallel input trace
[in]tThe current per-packet thread
[in]keyThe key of the result (used for sorting by the combiner)
[in]valueThe value of the result
[in]typeThe type of result (see result_types)

Publish a result to the reporter thread (via the combiner)

from a perpkt handler

References libtrace_result_t::key, libtrace_combine::publish, libtrace_result_t::type, and libtrace_result_t::value.

DLLEXPORT int trace_set_burst_size ( libtrace_t trace,
size_t  size 
)

The number of packets to batch together for processing internally by libtrace.

Parameters
traceA parallel input trace
sizeThe total number of packets to batch together. Set to the default, 0, to autoconfigure this value.
Returns
0 if successful otherwise -1

Internally libtrace will attempt to read up to this number of packets from a format at a time. Typically, values of 10 will get good performance and increasing beyond that will should little difference.

Note
We still pass a single packet at a time to the packet callback function.
DLLEXPORT int trace_set_cache_size ( libtrace_t trace,
size_t  size 
)

Sets the maximum size of the freelist used to store empty packets and their memory buffers.

Parameters
traceA parallel input trace
sizeThe number of empty packets to cache in memory. Set to the default, 0, to autoconfigure this value.
Returns
0 if successful otherwise -1

Internally libtrace maintains a buffer of packet structures which includes a cache per thread and a shared main pool. This option configures the size of the main pool. If an application is not passing packets through to the reporter thread, i.e. the packet callback always returns the packet, then the main pool is not used.

Note
Setting this too low could cause performance issues or a deadlock. An unblockable warning will be printed.
See also
trace_set_thread_cache_size(), trace_set_fixed_count()
DLLEXPORT void trace_set_combiner ( libtrace_t trace,
const libtrace_combine_t combiner,
libtrace_generic_t  config 
)

Sets a combiner function for an input trace.

Parameters
traceThe input trace
combinerThe combiner to use
configConfiguration information. Dependent upon the combiner.

Sets a combiner against a trace, this should only be called on a non-started or paused trace. By default, combiner_unordered will be used if this function is not called before starting the trace.

References libtrace_combine::configuration.

DLLEXPORT int trace_set_configuration ( libtrace_t trace,
const char *  str 
)

Sets the configuration of a trace based upon a comma separated list of key value pairs.

Parameters
traceA parallel trace which is not running or destroyed.
strA comma separated list of key=value pairs: e.g. "burst_size=20,perpkt_threads=2,fixed_count=true"
Returns
0 if successful otherwise -1. If bad options are passed we will print the error to stderr but still return successful.

List of keys:

Booleans can be set as 0/1 or false/true.

Note
a environment variable interface is provided by default to users via LIBTRACE_CONF, see Parallel Configuration for more information.
This interface is provided to allow a user to quickly configure an application using a single API call. A nicer programatic method for configuration would be to use the appropriate trace_set_*() function for each option.

Referenced by trace_set_configuration_file().

DLLEXPORT int trace_set_configuration_file ( libtrace_t trace,
FILE *  file 
)

Sets configuration from a file.

This reads every line from the file and interprets each line with trace_set_configuration().

Parameters
traceA parallel trace which is not running or destroyed
fileA file pointer which we read each line from
Returns
0 if successful otherwise -1. If bad options are passed we will print the error to stderr but still return successful.
Note
We do not close the file pointer upon completion

References trace_set_configuration().

DLLEXPORT int trace_set_debug_state ( libtrace_t trace,
bool  debug_state 
)

Enable or disable debug output for parallel libtrace.

If enabled, libtrace will print a line to standard error for every state change observed by both the trace as a whole and by each thread.

You really shouldn't need to enable this....

Parameters
traceA parallel input trace
debug_stateIf true debug is printed. Defaults false.
Returns
0 if successful otherwise -1.
DLLEXPORT int trace_set_first_packet_cb ( libtrace_callback_set_t cbset,
fn_cb_first_packet  handler 
)

Registers a first packet callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe first packet callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_fixed_count ( libtrace_t trace,
bool  fixed 
)

Determines whether a trace is allowed to create additional packets beyond the cache size.

If set to true, libtrace will cease reading packets once the cache is used up until the other threads release some packets back to the cache.

If set to false (the default), libtrace will use malloc and free to create additional packets when the cache is exhausted. This will be slower than getting a packet from the cache and will eventually run the machine out of memory if packets are allocated faster than they are released.

Parameters
traceA parallel input trace
fixedIf true the total number of packets is limited, otherwise it is not. Defaults to false.
Returns
0 if successful otherwise -1
See also
trace_set_thread_cache_size(), trace_set_cache_size()
DLLEXPORT int trace_set_hasher ( libtrace_t trace,
enum hasher_types  type,
fn_hasher  hasher,
void *  data 
)

Set the hasher function for a parallel trace.

Parameters
[in]traceThe parallel trace to apply the hasher to
[in]typeThe type of hashing to apply, see enum hasher_types
[in]hasherA hasher function to use [Optional]
[in]dataData passed to the hasher function [Optional]
Returns
0 if successful otherwise -1 on error

The hasher function in a parallel trace can be used to control which processing thread will receive each packet.

See hasher_types for a list of hashers supported natively by libtrace.

HASHER_BALANCE is the default and will dispatch packets as fast as possible to all threads arbitrarily.

HASHER_CUSTOM will force the libtrace to use the user defined function. In this case, the hasher parameter must be supplied.

With other defined hasher types libtrace will try to push the hashing into the capture format wherever possible. In this case, the hasher parameter is optional; if a hasher is provided then it will be preferred over the libtrace implementation.

Note
When supplying a hasher function it should be thread-safe so it can be run in parallel by libtrace. Ideally this should rely upon no state, other than some form of seed value supplied in data.

References libtrace_format_t::config_input, libtrace_t::format, libtrace_t::hasher, HASHER_BALANCE, HASHER_BIDIRECTIONAL, HASHER_CUSTOM, libtrace_t::hasher_type, HASHER_UNIDIRECTIONAL, and TRACE_OPTION_HASHER.

Referenced by trace_config().

DLLEXPORT int trace_set_hasher_polling ( libtrace_t trace,
bool  polling 
)

Enables or disables polling of the hasher queue.

If enabled, the processing threads will poll on the hasher queue, yielding if no data is available.

If disabled, the processing threads will block on a condition variable if there is no data available from the hasher.

Parameters
traceA parallel input trace
pollingIf true the hasher will poll waiting for data, otherwise it will use a condition variable. Defaults to false.

We note polling is likely to waste many CPU cycles and could even decrease performance.

Returns
0 if successful otherwise -1
DLLEXPORT int trace_set_hasher_queue_size ( libtrace_t trace,
size_t  size 
)

Sets the maximum size of the buffer used between the single hasher thread and the packet processing thread.

Setting this to less than recommend could cause a deadlock for an input trace that manages its own packets. A unblockable warning message will be printed to stderr in this case.

DLLEXPORT int trace_set_packet_cb ( libtrace_callback_set_t cbset,
fn_cb_packet  handler 
)

Registers a packet callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe packet callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_pausing_cb ( libtrace_callback_set_t cbset,
fn_cb_dataless  handler 
)

Registers a pausing callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe pausing callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_perpkt_threads ( libtrace_t trace,
int  nb 
)

Set the maximum number of perpkt threads to use in a trace.

Only valid on a new trace, that has not be started. Once started the number of threads cannot be changed without destroying the trace.

Parameters
[in]traceThe parallel input trace
[in]nbThe number of threads to use. If set to 0, libtrace will try to auto-detect how many threads it can use.
Returns
0 if successful otherwise -1

References libtrace_t::state.

DLLEXPORT int trace_set_reporter_polling ( libtrace_t trace,
bool  polling 
)

Enables or disables polling of the reporter result queue.

If enabled, the reporter thread will continuously poll for results. If disabled, the reporter will only check for results if it receives a MESSAGE_POST_REPORTER.

Parameters
traceA parallel input trace
pollingIf true the reporter will poll waiting for data, otherwise it will wait for a MESSAGE_POST_REPORTER. Defaults to false.
Returns
0 if successful otherwise -1

We note polling is likely to waste many CPU cycles and could even decrease performance.

Note
This setting could be ignored by some reporters.
DLLEXPORT int trace_set_reporter_thold ( libtrace_t trace,
size_t  thold 
)

Set the number of results that are required in the result queue before a MESSAGE_POST_REPORTER is sent to the reporter so that it can read the results.

Set this to 1 to ensure if you require your results to reach the reporter as soon as possible.

Parameters
traceA parallel input trace
tholdThe threshold on the number of results to enqueue before notifying the reporter thread to read them.
Returns
0 if successful otherwise -1
Note
This setting is generally ignored if the reporter is polling. However, some combiner functions might ignore the polling behaviour and still require this to be set.
See also
trace_publish_result(), trace_post_reporter()
DLLEXPORT int trace_set_result_cb ( libtrace_callback_set_t cbset,
fn_cb_result  handler 
)

Registers a result callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe result callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_resuming_cb ( libtrace_callback_set_t cbset,
fn_cb_dataless  handler 
)

Registers a resuming callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe resuming callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_starting_cb ( libtrace_callback_set_t cbset,
fn_cb_starting  handler 
)

Registers a starting callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe starting callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_stopping_cb ( libtrace_callback_set_t cbset,
fn_cb_dataless  handler 
)

Registers a stopping callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe stopping callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_thread_cache_size ( libtrace_t trace,
size_t  size 
)

This sets the maximum size of the freelist cache owned by each thread used to provide faster access to empty packets than the main shared pool.

Parameters
traceA parallel input trace
sizeThe number of empty packets to cache in memory. Set to the default, 0, to autoconfigure this value.
Returns
0 if successful otherwise -1
See also
trace_set_cache_size(), trace_set_fixed_count()
DLLEXPORT int trace_set_tick_count ( libtrace_t trace,
size_t  count 
)

Set the number of packets to be read between tick messages.

Parameters
[in]traceThe parallel input trace
[in]countThe tick count. If 0 this is disabled [default].
Returns
0 if successful otherwise -1

When enabled, MESSAGE_TICK_COUNT will be sent to all processing threads after every 'count' packets have been read from the trace. This allows results to be published even in cases where new packets are not being directed to a processing thread, while still maintaining order etc.

See also
MESSAGE_TICK_COUNT, trace_set_tick_interval()
DLLEXPORT int trace_set_tick_count_cb ( libtrace_callback_set_t cbset,
fn_cb_tick  handler 
)

Registers a tick counter callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe tick callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_tick_interval ( libtrace_t trace,
size_t  millisec 
)

Set the interval between tick messages in milliseconds.

Parameters
[in]traceThe parallel input trace
[in]millisecThe interval in milliseconds. If 0 this is disabled [default].
Returns
0 if successful, otherwise -1.

When enabled, MESSAGE_TICK_INTERVAL will be sent every tick interval to all processing threads. This allows results to be published even in cases where new packets are not being directed to a processing thread, while still maintaining order etc.

See also
MESSAGE_TICK_INTERVAL, trace_set_tick_count()
DLLEXPORT int trace_set_tick_interval_cb ( libtrace_callback_set_t cbset,
fn_cb_tick  handler 
)

Registers a tick interval callback against a callback set.

Parameters
cbsetThe callback set.
handlerThe tick callback function.
Returns
0 if successful, -1 otherwise.
DLLEXPORT int trace_set_tracetime ( libtrace_t trace,
bool  tracetime 
)

Delays packets so they are played back in trace-time rather than as fast as possible (real-time).

Parameters
traceA parallel input trace
tracetimeIf true packets are released with time spacing that matches the original trace. Otherwise packets are read as fast as possible.
Returns
0 if successful otherwise -1
DLLEXPORT int trace_set_user_message_cb ( libtrace_callback_set_t cbset,
fn_cb_usermessage  handler 
)

Registers a callback for custom user messages against a callback set.

Parameters
cbsetThe callback set.
handlerThe user message callback function.
Returns
0 if successful, -1 otherwise.

Variable Documentation

const libtrace_combine_t combiner_ordered

Takes ordered input and produces ordered output.

Each processing thread must produce results that are strictly ordered for this combiner to work correctly.

For example, a thread may publish a series of results with the keys (in order) of 1,4,10,11,15,20 as the keys are all in order. It must not publish the results in the order 1,4,11,10,15,20 – 10 comes after 11, which is out-of-order.

const libtrace_combine_t combiner_sorted

Like classic Google Map/Reduce, the results are sorted in ascending order based on their key.

The sorting is only done when the trace finishes and all results are stored internally until then.

This only works with a very limited number of results, otherwise libtrace will just run out of memory and crash. You should always use combiner_ordered if you can.

const libtrace_combine_t combiner_unordered

Takes unordered (or ordered) input and produces unordered output.

This is the fastest combiner but makes no attempt to ensure you get results in a particular order.