source: lib/libtrace_parallel.h @ 5478d3d

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 5478d3d was 5478d3d, checked in by Shane Alcock <salcock@…>, 6 years ago

Fix all outstanding warnings

Implemented trace_get_statistics for formats that were missing it, so
we no longer need to use the deprecated trace_get_dropped_packets anywhere
within libtrace.

  • Property mode set to 100644
File size: 47.0 KB
Line 
1/*
2 * This file is part of libtrace
3 *
4 * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
5 * New Zealand.
6 *
7 * Authors: Richard Sanger
8 *
9 * All rights reserved.
10 *
11 * This code has been developed by the University of Waikato WAND
12 * research group. For further information please see http://www.wand.net.nz/
13 *
14 * libtrace is free software; you can redistribute it and/or modify
15 * it under the terms of the GNU General Public License as published by
16 * the Free Software Foundation; either version 2 of the License, or
17 * (at your option) any later version.
18 *
19 * libtrace is distributed in the hope that it will be useful,
20 * but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
22 * GNU General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with libtrace; if not, write to the Free Software
26 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
27 *
28 * $Id$
29 *
30 */
31
32/** @file
33 *
34 * @brief Header file containing definitions for structures and functions
35 * related to the parallel framework
36 *
37 * @author Richard Sanger
38 *
39 * @version $Id$
40 *
41 * The parallel libtrace framework is a replacement to the libtrace framework. XXX TODO MAKE MORE DOCS HERE.
42 */
43
44#ifndef LIBTRACE_PARALLEL_H
45#define LIBTRACE_PARALLEL_H
46
47#include "libtrace.h"
48#include <stdio.h>
49
50#ifdef __cplusplus
51extern "C" {
52#endif
53
54typedef struct libtrace_result_t libtrace_result_t;
55
56/**
57 * A collection of types for convenience used in place of a
58 * simple void* to allow a any type of data to be stored.
59 *
60 * This is expected to be 8 bytes in length.
61 */
62typedef union {
63        /* Pointers */
64        void *ptr;
65        libtrace_packet_t *pkt;
66        libtrace_result_t *res;
67
68        /* C99 Integer types */
69        /* NOTE: Standard doesn't require 64-bit
70         * but x32 and x64 gcc does */
71        int64_t sint64;
72        uint64_t uint64;
73
74        uint32_t uint32s[2];
75        int32_t sint32s[2];
76        uint32_t uint32;
77        int32_t sint32;
78
79        uint16_t uint16s[4];
80        int16_t sint16s[4];
81        uint16_t uint16;
82        int16_t sint16;
83
84        uint8_t uint8s[8];
85        int8_t sint8s[8];
86        uint8_t uint8;
87        int8_t sint8;
88
89        size_t size;
90
91        /* C basic types - we cannot be certain of the size */
92        int sint;
93        unsigned int uint;
94
95        signed char schars[8];
96        unsigned char uchars[8];
97        signed char schar;
98        unsigned char uchar;
99
100        /* Real numbers */
101        float rfloat;
102        double rdouble;
103} libtrace_generic_t;
104ct_assert(sizeof(libtrace_generic_t) == 8);
105
106typedef struct libtrace_message_t {
107        int code; /**< The message code see enum libtrace_messages */
108        libtrace_generic_t data; /**< Additional data related to the message */
109        libtrace_thread_t *sender; /**< The thread that sent the message */
110} libtrace_message_t;
111
112/** Structure holding information about a result */
113struct libtrace_result_t {
114        uint64_t key;
115        libtrace_generic_t value;
116        int type;
117};
118
119/** The libtrace_messages enum
120 * All libtrace messages are defined and documented here.
121 *
122 * Some messages can be sent to control the library while others
123 * are received by the per-packet and reporter functions to inform the libtrace
124 * application.
125 *
126 * If a user wishes to send there own custom messages they should use
127 * numbers greater than MESSAGE_USER (1000).
128 *
129 * @note Some messages are for internal use only
130 */
131enum libtrace_messages {
132        /** A libtrace packet is ready, this will only be sent to per
133         * packet threads.
134         * @param data Holds the packet in data.pkt. The packet belongs to
135         * libtrace and should either be returned from the per-packet function
136         * if no longer needed or free'd at some later time using the XXX
137         * function.
138         * @param sender The sender will be set as the current thread
139         */
140        MESSAGE_PACKET,
141        /** A libtrace result is ready, this will only be sent to the reporter
142         * thread.
143         * @param data Holds the result in data.res. The memory holding the
144         * result is allocated by libtrace and should not be free'd. However
145         * note that any data stored within the result might need to be free'd.
146         * @param sender The sender will be set as the current thread
147         */
148        MESSAGE_RESULT,
149
150        /** A message sent to each thread when it starts. This is sent
151         * to both the reporter and per-packet threads. This will be sent once
152         * after trace_pstart() (assuming no errors occurs).
153         *
154         * This can be used to allocate resources required by each thread.
155         *
156         * These can be free'd when MESSAGE_STOPPING is received.
157         *
158         * @param data unused, do not use this
159         * @param sender The sender will be set as the current thread
160         * @return When using a function callback for starting, the returned
161         * value is stored against the thread tls. Otherwise the return is ignored.
162         */
163        MESSAGE_STARTING,
164
165        /** A message sent to each thread when it stops. This is sent
166         * to both the reporter and per-packet threads. This will be sent once
167         * after MESSAGE_STARTING.
168         *
169         * This can be used to free any resources allocated with
170         * MESSAGE_STARTING.
171         *
172         * @param data unused, do not use this
173         * @param sender The sender will be set as the current thread
174         */
175        MESSAGE_STOPPING,
176
177        /** A message sent to each thread when a thread transitions between a
178         * paused (or unstarted) state to running state. This is sent
179         * to both the reporter and per-packet threads. This will be sent after
180         * MESSAGE_STARTING when a trace is first started and when a trace
181         * is started (trace_pstart()) after a pause (trace_ppause()).
182         *
183         * This can be used to allocate resources.
184         *
185         * @param data unused, do not use this
186         * @param sender The sender will be set as the current thread
187         */
188        MESSAGE_RESUMING,
189
190        /** A message sent to each thread when a thread transitions between a
191         * paused (or unstarted) state to running state. This is sent
192         * to both the reporter and per-packet threads. This will be sent after
193         * MESSAGE_STARTING when a trace is first started and when a trace
194         * is started (trace_pstart()) after a pause (trace_ppause()).
195         *
196         * This can be used to allocate resources.
197         *
198         * @param data unused, do not use this
199         * @param sender The sender will be set as the current thread
200         */
201        MESSAGE_PAUSING,
202
203        /** An internal message do not use this */
204        MESSAGE_DO_PAUSE,
205        /** An internal message do not use this */
206        MESSAGE_DO_STOP,
207
208        /** Sent to all per-packet threads (including the sender) and the
209         * reducer when the first packet is seen for a thread.
210         *
211         * @param data The first packet is stored in data.pkt. This packet is
212         * shared by all threads receiving the message and is valid until
213         * MESSAGE_PAUSING is received.
214         * @param sender The per-packet thread which received the packet
215         *
216         * @note Upon pausing and restarting a trace this will be reset and
217         * sent once a new packet is encountered
218         *
219         * @see trace_get_first_packet()
220         */
221        MESSAGE_FIRST_PACKET,
222
223        /** Notify the reporter thread more data is available.
224         *
225         * Triggers the reporter to read as many results as possible.
226         *
227         * @param data unused
228         * @param sender the sending
229         *
230         * @note This message should not be sent directly instead call
231         * trace_post_reporter()
232         *
233         */
234        MESSAGE_POST_REPORTER,
235
236        /** Sent to per-packet threads periodically after the configured time
237         * interval has passed.
238         *
239         * This is sent out-of-band with respect to packets and as a result
240         * can appear after a packet with an later time-stamp, or before one
241         * with an earlier time-stamp.
242         *
243         * @param data data.uint64 holds the system time-stamp in the
244         * erf format
245         * @param sender should be ignored
246         */
247        MESSAGE_TICK_INTERVAL,
248
249        /** Sent to per-packet threads once the configured number of packets
250         * are read from a trace.
251         *
252         * This are sent in-band with respect to packets such that all
253         * threads will see it between the same packets.
254         *
255         * @param data data.uint64 holds the number of packets seen so far across all threads
256         * @param sender Set to the current per-packet thread
257         */
258        MESSAGE_TICK_COUNT,
259
260        /** For specific user defined messages use codes of MESSAGE_USER or above. */
261        MESSAGE_USER = 1000
262};
263
264/** The hasher types available to libtrace application.
265 * These can be selected using trace_set_hasher().
266 */
267enum hasher_types {
268        /** Balance load across per-packet threads as best as possible, this is
269         * basically to say I do not care about where packets are sent. This
270         * might still might be implemented using a hash or round robin etc.
271         * depending on the format and libtrace configuration.
272         */
273        HASHER_BALANCE,
274
275        /** Use a hash which is bi-directional for TCP and UDP flows, that is
276         * packets with the same 5-tuple are sent to the same per-packet thread.
277         * All non TCP/UDP packets will be sent to the same thread.
278         *
279         * @note it is possible that UDP packets may not be spread across
280         * per-packet threads, depending upon the format support. In this case
281         * they would be directed to a single per-packet thread.
282         */
283        HASHER_BIDIRECTIONAL,
284
285        /** Use a hash which is uni-directional across TCP and UDP flows, this
286         * means the opposing directions of the same 5-tuple might end up on
287         * different per-packet threads.
288         * Otherwise this is identical to HASHER_BIDIRECTIONAL
289         */
290        HASHER_UNIDIRECTIONAL,
291
292        /**
293         * Always use the user supplied hasher, this disables native
294         * support in and is likely significantly slower.
295         */
296        HASHER_CUSTOM
297};
298
299typedef struct libtrace_info_t {
300        /**
301         * True if a live format (i.e. packets have to be trace-time).
302         * Otherwise false, indicating packets can be read as fast
303         * as possible from the format.
304         */
305        bool live;
306
307        /**
308         * The maximum number of threads supported by a parallel trace. 1
309         * if parallel support is not native (in this case libtrace will simulate
310         * an unlimited number of threads), -1 means unlimited and 0 unknown.
311         */
312        int max_threads;
313
314        /* TODO hash fn supported list */
315
316        /* TODO consider time/clock details?? */
317} libtrace_info_t;
318
319/**
320 * The methods we use to combine multiple outputs into a single output
321 * This is not considered a stable API however is public.
322 * Where possible use built in combiners.
323 *
324 * @note this structure is duplicated per trace and as such can
325 * have functions rewritten, and in fact should if possible.
326 */
327typedef struct libtrace_combine libtrace_combine_t;
328struct libtrace_combine {
329
330        /**
331         * Called at the start of the trace to allow data-structures
332         * to be initialised and allow functions to be swapped if appropriate.
333         *
334         * Also factors such as whether the trace is live or not can
335         * be used to determine the functions used.
336         * @return 0 if successful, -1 if an error occurs
337         */
338        int (*initialise)(libtrace_t *,libtrace_combine_t *);
339
340        /**
341         * Called when the trace ends, clean up any memory here
342         * from libtrace_t * init.
343         */
344        void (*destroy)(libtrace_t *, libtrace_combine_t *);
345
346        /**
347         * Publish a result against it's a threads queue.
348         * If null publish directly, expected to be used
349         * as a single threaded optimisation and can be
350         * set to NULL by init if this case is detected.
351         *
352         * TODO this is old info
353         */
354        void (*publish)(libtrace_t *, int thread_id, libtrace_combine_t *, libtrace_result_t *);
355
356        /**
357         * Read as many results as possible from the trace.
358         * Directly calls the users code to handle results from here.
359         *
360         * THIS SHOULD BE NON-BLOCKING AND READ AS MANY AS POSSIBLE
361         * If publish is NULL, this probably should be NULL also otherwise
362         * it will not be called.
363         */
364        void (*read)(libtrace_t *, libtrace_combine_t *);
365
366        /**
367         * Called when the trace is finished to flush the final
368         * results to the reporter thread.
369         *
370         * There may be no results, in which case this should
371         * just return.
372         *
373         * Libtrace state:
374         * Called from reporter thread
375         * No perpkt threads will be running, i.e. publish will not be
376         * called again.
377         *
378         * If publish is NULL, this probably should be NULL also otherwise
379         * it will not be called.
380         */
381        void (*read_final)(libtrace_t *, libtrace_combine_t *);
382
383        /**
384         * Pause must make sure any results of the type packet are safe.
385         * That means trace_copy_packet() and destroy the original.
386         * This also should be NULL if publish is NULL.
387         */
388        void (*pause)(libtrace_t *, libtrace_combine_t *);
389
390        /**
391         * Data storage for all the combiner threads
392         */
393        void *queues;
394
395        uint64_t last_count_tick;
396        uint64_t last_ts_tick;
397
398        /**
399         * Configuration options, what this does is up to the combiner
400         * chosen.
401         */
402        libtrace_generic_t configuration;
403};
404
405/**
406 * The definition for the main function that the user supplies to process
407 * messages.
408 *
409 * @param trace The trace the packet is related to.
410 * @param thread The thread identifier.
411 * @param mesg_code The type of data ready, the most important being MESSAGE_PACKET.
412 * In this case data.pkt contains the packet.
413 * @param data A generic union of types that fit into 8 bytes, containing
414 * information dependent upon the mesg_code.
415 * @param sender The thread from which the message originated.
416 * @return If the message type is MESSAGE_PACKET a packet can be returned back
417 * to the library similar to trace_free_packet() otherwise this should be NULL.
418 *
419 * The values of data and sender depend upon the mesg_code. Please see the
420 * documentation for the message as to what value these will contain.
421 */
422typedef void* (*fn_cb_msg)(libtrace_t* trace,
423                           libtrace_thread_t *thread,
424                           int mesg_code,
425                           libtrace_generic_t data,
426                           libtrace_thread_t *sender);
427
428/**
429 * The definition for the main function that the user supplies to process
430 * results from trace_publish_result().
431 *
432 * @param trace The trace the packet is related to.
433 * @param mesg_code The type of data ready, the most important being MESSAGE_RESULT.
434 * In this case data.res contains the result.
435 * @param data A generic union of types that fit into 8 bytes, containing
436 * information dependent upon the mesg_code.
437 * @param sender The thread from which the message originated.
438 *
439 * The values of data and sender depend upon the mesg_code. Please see the
440 * documentation for the message as to what value these will contain.
441 */
442typedef void (*fn_reporter)(libtrace_t* trace,
443                            int mesg_code,
444                            libtrace_generic_t data,
445                            libtrace_thread_t *sender);
446
447/**
448 * The definition for a hasher function, allowing matching packets to be
449 * directed to the same per packet thread for processing.
450 *
451 * @param packet The packet to be hashed.
452 * @param data A void pointer which can contain additional information,
453 * such as configuration of the hasher function.
454 */
455typedef uint64_t (*fn_hasher)(const libtrace_packet_t* packet, void *data);
456
457
458/** Start or restart an input trace in the parallel libtrace framework.
459 *
460 * @param libtrace The input trace to start
461 * @param global_blob Global data related to this trace accessible using trace_get_global()
462 * @param per_packet_cbs A set of user supplied functions to be called in response to events being observed by the per_pkt threads.
463 * @param reporter_cbs A set of user supplied functions to be called in response to events / results being seen by the reporter thread.
464 * Optional if NULL the reporter thread will not be started.
465 * @return 0 on success, otherwise -1 to indicate an error has occurred
466 *
467 * This can also be used to restart an existing parallel trace,
468 * that has previously been paused using trace_ppause().
469 * In this case global_blob, per_packet_cbs and reporter_cbs will only be
470 * updated if they are non-null. Otherwise their previous values will be
471 * maintained.
472 *
473 */
474DLLEXPORT int trace_pstart(libtrace_t *libtrace, void* global_blob,
475                           libtrace_callback_set_t *per_packet_cbs,
476                           libtrace_callback_set_t *reporter_cbs);
477
478/**
479 *
480 * @param libtrace The parallel trace
481 * @param t The thread that is running
482 * @param global The global storage
483 * @return The returned value is stored against the threads tls.
484 *         This is typically passed as tls argument to other messages.
485 */
486typedef void* (*fn_cb_starting)(libtrace_t *libtrace,
487                                     libtrace_thread_t *t,
488                                     void *global);
489
490/**
491 * @param libtrace The parallel trace
492 * @param t The thread that is running
493 * @param global The global storage
494 * @param tls The thread local storage
495 */
496typedef void (*fn_cb_dataless)(libtrace_t *libtrace,
497                                    libtrace_thread_t *t,
498                                    void *global,
499                                    void *tls);
500
501/**
502 * @param libtrace The parallel trace
503 * @param t The thread that is running
504 * @param global The global storage
505 * @param tls The thread local storage
506 */
507typedef void (*fn_cb_first_packet)(libtrace_t *libtrace,
508                                   libtrace_thread_t *t,
509                                   void *global,
510                                   void *tls,
511                                   libtrace_thread_t *sender);
512
513/**
514 * @param libtrace The parallel trace
515 * @param t The thread that is running
516 * @param global The global storage
517 * @param tls The thread local storage
518 * @param uint64_t Either the timestamp or packet count depending on message type
519 */
520typedef void (*fn_cb_tick)(libtrace_t *libtrace,
521                           libtrace_thread_t *t,
522                           void *global,
523                           void *tls,
524                           uint64_t order);
525
526/**
527 * @param libtrace The parallel trace
528 * @param t The thread
529 * @param packet The packet associated with the message
530 * @param global The global storage
531 * @param tls The thread local storage
532 *
533 * @return optionally a packet which is handed back to the library,
534 *         typically this is the packet supplied. Otherwise NULL.
535 */
536typedef libtrace_packet_t* (*fn_cb_packet)(libtrace_t *libtrace,
537                                           libtrace_thread_t *t,
538                                           void *global,
539                                           void *tls,
540                                           libtrace_packet_t *packet);
541
542/**
543 * Callback for handling a result message. Should only be required by the
544 * reporter thread.
545 *
546 * @param libtrace The parallel trace
547 * @param sender The thread that generated this result
548 * @param global The global storage
549 * @param tls The thread local storage
550 * @param result The result associated with the message
551 *
552 */
553typedef void (*fn_cb_result)(libtrace_t *libtrace, libtrace_thread_t *sender,
554                void *global, void *tls, libtrace_result_t *result);
555
556
557/**
558 * Callback for handling any user-defined message types. This will handle
559 * any messages with a type >= MESSAGE_USER.
560 *
561 * @param libtrace The parallel trace
562 * @param t The thread
563 * @param global The global storage
564 * @param tls The thread local storage
565 * @param mesg The code identifying the message type
566 * @param data The data associated with the message
567 *
568 */
569typedef void (*fn_cb_usermessage) (libtrace_t *libtrace, libtrace_thread_t *t,
570                void *global, void *tls, int mesg, libtrace_generic_t data);
571
572/** Registers a built-in message with a handler.
573 * Note we do not include the sending thread as an argument to the reporter.
574 * If set to NULL, the message will be sent to default perpkt handler.
575 *
576 * @param libtrace The input trace to start
577 * @param handler the handler to be called when the message is received
578 * @return 0 if successful otherwise -1.
579 */
580
581DLLEXPORT int trace_set_starting_cb(libtrace_callback_set_t *cbset,
582                fn_cb_starting handler);
583
584DLLEXPORT int trace_set_stopping_cb(libtrace_callback_set_t *cbset,
585                fn_cb_dataless handler);
586
587DLLEXPORT int trace_set_resuming_cb(libtrace_callback_set_t *cbset,
588                fn_cb_dataless handler);
589
590DLLEXPORT int trace_set_pausing_cb(libtrace_callback_set_t *cbset,
591                fn_cb_dataless handler);
592
593DLLEXPORT int trace_set_packet_cb(libtrace_callback_set_t *cbset,
594                fn_cb_packet handler);
595
596DLLEXPORT int trace_set_first_packet_cb(libtrace_callback_set_t *cbset,
597                fn_cb_first_packet handler);
598
599DLLEXPORT int trace_set_result_cb(libtrace_callback_set_t *cbset,
600                fn_cb_result handler);
601
602DLLEXPORT int trace_set_tick_count_cb(libtrace_callback_set_t *cbset,
603                fn_cb_tick handler);
604
605DLLEXPORT int trace_set_tick_interval_cb(libtrace_callback_set_t *cbset,
606                fn_cb_tick handler);
607
608DLLEXPORT int trace_set_user_message_cb(libtrace_callback_set_t *cbset,
609                fn_cb_usermessage handler);
610
611/** Create a callback set that can be used to define callbacks for parallel
612  * libtrace threads.
613  *
614  * @return A pointer to a freshly allocated callback set.
615  */
616DLLEXPORT libtrace_callback_set_t *trace_create_callback_set(void);
617
618/** Destroys a callback set, freeing up an resources it was using.
619 *
620 * @param cbset         The callback set to be destroyed.
621 */
622DLLEXPORT void trace_destroy_callback_set(libtrace_callback_set_t *cbset);
623
624
625/** Pauses a trace previously started with trace_pstart()
626 *
627 * @param libtrace The parallel trace to be paused
628 * @return 0 on success, otherwise -1 to indicate an error has occurred
629 *
630 */
631DLLEXPORT int trace_ppause(libtrace_t *libtrace);
632
633/** Stops a parallel trace, causing all threads to exit as if an EOF
634 * has occurred. This replaces trace_interrupt(), allowing
635 * a specified trace to be stopped.
636 *
637 * @param libtrace The parallel trace to be stopped
638 * @return 0 on success, otherwise -1 to indicate an error has occurred
639 *
640 * This should only be called by the main thread.
641 *
642 */
643DLLEXPORT int trace_pstop(libtrace_t *libtrace);
644
645/** Waits for a trace to finish and all threads to join.
646 *
647 * @param trace The parallel trace
648 *
649 * Waits for a trace to finish, whether this be due to
650 * an error occurring, an EOF or trace_pstop.
651 *
652 */
653DLLEXPORT void trace_join(libtrace_t * trace);
654
655/**
656 * @name User Data Storage
657 *
658 * These method provide a way for users to store data against a trace or
659 * a thread.
660 *
661 * Alternatively one could use global variables and thread local
662 * storage (__thread), respectively, which in many cases could be simpler.
663 *
664 * @note We do not lock on reads, instead we rely on the
665 * processor making any writes appear atomically.
666 *
667 * @{
668 */
669
670/** Returns the data stored against a trace.
671 *
672 * @param trace The parallel trace
673 * @return The stored data.
674 */
675DLLEXPORT void * trace_get_local(libtrace_t *trace);
676
677/** Store data against a trace so that all threads can access it
678 * using trace_get_global().
679 *
680 * @param trace The parallel trace.
681 * @param data The new value to save against the trace
682 * @return The previously stored value
683 *
684 * The update to the previous value is atomic and thread-safe.
685 *
686 * @note Although this is thread-safe another thread may still be
687 * using the previous data, as such further synchronisation is needed
688 * if a thread wanted to free the existing value.
689 */
690DLLEXPORT void * trace_set_local(libtrace_t *trace, void * data);
691
692/** Returns the users data stored against a thread.
693 *
694 * @param thread The thread
695 * @return The stored data
696 */
697DLLEXPORT void * trace_get_tls(libtrace_thread_t *thread);
698
699/** Store data against a thread.
700 *
701 * @param thread The thread
702 * @param data The new value to save against the thread
703 * @return The previously stored value
704 *
705 * This function is not thread-safe and is intended only to be
706 * called on the currently running thread.
707 */
708DLLEXPORT void * trace_set_tls(libtrace_thread_t *thread, void * data);
709
710/// @}
711
712
713/**
714 * @name Parallel Configuration
715 *
716 * These methods provide a way to configure the parallel libtrace library.
717 *
718 * Many of these options are typically unneeded by most applications as they
719 * control tuning aspects of the library and are more useful to the
720 * end user.
721 *
722 * To allow the end user to change this configuration libtrace will search for
723 * three environment variables and apply them to the configuration in the
724 * following order. Such that the first has the lowest priority.
725 *
726 * 1. LIBTRACE_CONF, The global environment configuration
727 * 2. LIBTRACE_CONF_<FORMAT>, Applied to a given format
728 * 3. LIBTRACE_CONF_<FORMAT_URI>, Applied the specified trace
729 *
730 * E.g.
731 * - int:eth0 would match LIBTRACE_CONF, LIBTRACE_CONF_INT, LIBTRACE_CONF_INT_ETH0
732 * - dag:/dev/dag0,0 would match LIBTRACE_CONF, LIBTRACE_CONF_DAG, LIBTRACE_CONF_DAG__DEV_DAG0_0
733 * - test.erf would match LIBTRACE_CONF, LIBTRACE_CONF_ERF, LIBTRACE_CONF_ERF_TEST_ERF
734 *
735 * @note All environment variables names MUST only contain
736 * [A-Z], [0-9] and [_] (underscore). Any characters
737 * outside of this range should be capitalised if possible or replaced with an
738 * underscore.
739 * @{
740 */
741
742/** Set the maximum number of perpkt threads to use in a trace.
743 *
744 * @param[in] trace The parallel input trace
745 * @param[in] nb The number of threads to use. If 0 use default.
746 * @return 0 if successful otherwise -1
747 */
748DLLEXPORT int trace_set_perpkt_threads(libtrace_t *trace, int nb);
749
750/** Set the interval between tick messages in milliseconds.
751 *
752 * @param[in] trace The parallel input trace
753 * @param[in] millisec The interval in milliseconds. If 0 this is disabled [default].
754 * @return 0 if successful otherwise -1
755 *
756 * When a underlying parallel live trace is used MESSAGE_TICK_INTERVAL is sent
757 * every tick interval to all per-packet threads to ensure data is received.
758 * This allows results to be printed even in cases flows are not being directed
759 * to a per-packet thread, while still maintaining order etc.
760 *
761 * @note Tick count is preferred over tick interval and will be used rather
762 * than tick interval if possible.
763 * @see MESSAGE_TICK_INTERVAL, trace_set_tick_count()
764 */
765DLLEXPORT int trace_set_tick_interval(libtrace_t *trace, size_t millisec);
766
767/** Set the count between tick messages.
768 *
769 * @param[in] trace The parallel input trace
770 * @param[in] count The tick count.  If 0 this is disabled [default].
771 * @return 0 if successful otherwise -1
772 *
773 * When an underlying trace is accessed internally by libtrace in a
774 * single-threaded manner MESSAGE_TICK_COUNT is sent to all per-packet threads
775 * after every count packets have been seen in the trace. This allows results
776 * to be printed even in cases flows are not being directed to a per-packet
777 * thread, while still maintaining order etc.
778 *
779 * @see MESSAGE_TICK_COUNT, trace_set_tick_interval()
780 */
781DLLEXPORT int trace_set_tick_count(libtrace_t *trace, size_t count);
782
783/**
784 * Delays packets so they are played back in trace-time rather than as fast
785 * as possible (real-time).
786 *
787 * @param trace A parallel input trace
788 * @param tracetime If true packets are released with time intervals matching
789 * the original trace. Otherwise packets are read as fast as possible.
790 * @return 0 if successful otherwise -1
791 */
792DLLEXPORT int trace_set_tracetime(libtrace_t *trace, bool tracetime);
793
794/** This sets the maximum size of the freelist used to store empty packets
795 * and their memory buffers.
796 *
797 * @param trace A parallel input trace
798 * @param size The number of empty packets to cache in memory. Set to the
799 * default, 0, to autoconfigure this value.
800 * @return 0 if successful otherwise -1
801 *
802 * Internally libtrace maintains a buffer of packet structures, this buffer
803 * includes a cache per thread and a shared main pool. This configures
804 * the size of the main pool. If an application is not passing packets
805 * through to the reducer step --- that is to say returns packets from
806 * the perpkt function --- this buffer will not need to be used.
807 *
808 * @note Setting this too low could cause performance issues or a deadlock. An
809 * unblockable warning will be printed.
810 *
811 * @see trace_set_thread_cache_size(), trace_set_fixed_count()
812 */
813DLLEXPORT int trace_set_cache_size(libtrace_t *trace, size_t size);
814
815/** This sets the maximum size of the freelist thread cache's used to provide
816 * faster access than the main shared pool.
817 *
818 * @param trace A parallel input trace
819 * @param size The number of empty packets to cache in memory. Set to the
820 * default, 0, to autoconfigure this value.
821 * @return 0 if successful otherwise -1
822 *
823 * @see trace_set_cache_size(), trace_set_fixed_count()
824 */
825DLLEXPORT int trace_set_thread_cache_size(libtrace_t *trace, size_t size);
826
827/** If true the total number of packets that can be created by a trace is limited
828 * to that set by trace_set_cache_size(), otherwise once exceeded malloc
829 * and free will be used to create and free packets, this will be slower than
830 * using the freelist and could run a machine out of memory.
831 *
832 * @param trace A parallel input trace
833 * @param fixed If true the total number of packets is limited, otherwise
834 * it is not. Defaults to false.
835 * @return 0 if successful otherwise -1
836 *
837 * @see trace_set_thread_cache_size(), trace_set_cache_size()
838 */
839DLLEXPORT int trace_set_fixed_count(libtrace_t *trace, bool fixed);
840
841/** The number of packets to batch together for processing internally
842 * by libtrace.
843 *
844 * @param trace A parallel input trace
845 * @param size The total number of packets to batch together. Set to the
846 * default, 0, to autoconfigure this value.
847 * @return 0 if successful otherwise -1
848 *
849 * Internally libtrace will attempt to read up to this number of packets from
850 * a format typically values of 10 will get good performance and increasing
851 * beyond that will should little difference.
852 *
853 * @note We still pass a single packet at a time to the perpkt function
854 */
855DLLEXPORT int trace_set_burst_size(libtrace_t *trace, size_t size);
856
857/**
858 * See diagrams, this sets the maximum size of buffers used between
859 * the single hasher thread and the buffer.
860 * NOTE setting this to less than recommend could cause deadlock a
861 * trace that manages its own packets.
862 * A unblockable warning message will be printed to stderr in this case.
863 */
864/** The number of packets that can queue per thread from hasher thread */
865DLLEXPORT int trace_set_hasher_queue_size(libtrace_t *trace, size_t size);
866
867/** If true use a polling hasher queue, that means that we will spin/or yield
868 * when data is not available rather than blocking on a condition.
869 *
870 * @param trace A parallel input trace
871 * @param polling If true the hasher will poll waiting for data, otherwise
872 * it is not. Defaults to false.
873 *
874 * We note this is likely to waste many CPU cycles and could even decrease
875 * performance.
876 *
877 * @return 0 if successful otherwise -1
878 */
879DLLEXPORT int trace_set_hasher_polling(libtrace_t *trace, bool polling);
880
881/** If true the reporter thread will continuously poll waiting for results
882 * if false they are only checked when a message is received, this message
883 * is controlled by reporter_thold.
884 *
885 * @param trace A parallel input trace
886 * @param polling If true the reporter will poll waiting for data, otherwise
887 * it is not. Defaults to false.
888 * @return 0 if successful otherwise -1
889 *
890 * We note this is likely to waste many CPU cycles and could even decrease
891 * performance.
892 *
893 * @note This setting could be ignored by some reporters.
894 */
895DLLEXPORT int trace_set_reporter_polling(libtrace_t *trace, bool polling);
896
897/** Set the perpkt thread result queue size before triggering the reporter
898 * to read results.
899 *
900 * @param trace A parallel input trace
901 * @param thold The threshold on the number of results to enqueue before
902 * notifying the reporter thread to read them.
903 * @return 0 if successful otherwise -1
904 *
905 *
906 * @note This setting is generally ignored if trace_set_reporter_polling() is
907 * set however some combiner functions might ignore trace_set_reporter_polling()
908 * and still require this to be set.
909 * @see trace_publish_result(), trace_post_reporter()
910 */
911DLLEXPORT int trace_set_reporter_thold(libtrace_t *trace, size_t thold);
912
913/** Prints a line to standard error for every state change
914 * for both the trace as a whole and for each thread.
915 *
916 * @param trace A parallel input trace
917 * @param debug_state If true debug is printed. Defaults false.
918 * @return 0 if successful otherwise -1.
919 *
920 */
921DLLEXPORT int trace_set_debug_state(libtrace_t *trace, bool debug_state);
922
923/** Set the hasher function for a parallel trace.
924 *
925 * @param[in] trace The parallel trace to apply the hasher to
926 * @param[in] type The type of hashing to apply, see enum hasher_types
927 * @param[in] hasher A hasher function to use [Optional]
928 * @param[in] data Data passed to the hasher function [Optional]
929 *
930 * @return 0 if successful otherwise -1 on error
931 *
932 * The hasher function in a parallel trace can be used to control which
933 * per-packet thread a packets is processed by.
934 *
935 * HASHER_BALANCE is the default and will dispatch packets as fast as possible
936 * to all threads arbitrarily. As such when called the hasher and
937 * data parameters must be set to NULL.
938 *
939 * HASHER_CUSTOM will force the libtrace to use the user defined function. As
940 * such the hasher parameter must be supplied.
941 *
942 * With other defined hasher types we will try to push the hashing into the format
943 * by default. In this case the hasher parameter is optional and will be
944 * preferred over the default supplied by libtrace.
945 *
946 * @note When supplying a hasher function it should be thread-safe so it can
947 * be run in parallel by libtrace. Ideally this should rely upon no state, other
948 * than some form of seed value supplied in data.
949 */
950DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type,
951                               fn_hasher hasher, void *data);
952
953/// @}
954
955
956/** Types of results.
957 * Some result types require special handling by combiners
958 * as such making use of built-in types is important.
959 *
960 * Custom result types users should be defined as RESULT_USER(1000) or greater.
961 *
962 */
963enum result_types {
964        /**
965         * The result is a packet in some circumstances special handling needs
966         * to be performed. As such packets should always be published as so.
967         *
968         * @param key (Typically) The packets order, see trace_packet_get_order()
969         */
970        RESULT_PACKET,
971
972        /** The result is a tick message
973         *
974         * @param key The erf time-stamp of the tick
975         */
976        RESULT_TICK_INTERVAL,
977
978        /** The result is a tick message
979         *
980         * @param key The sequence number of the tick message
981         */
982        RESULT_TICK_COUNT,
983
984        /** Any user specific codes should be above this.
985         *
986         */
987        RESULT_USER = 1000
988
989};
990
991/** Publish a result for to the combiner destined for the reporter thread
992 *
993 * @param[in] libtrace The parallel input trace
994 * @param[in] t The current per-packet thread
995 * @param[in] key The key of the result (used for sorting by the combiner)
996 * @param[in] value The value of the result
997 * @param[in] type The type of result see the documentation for the result_types enum
998 */
999DLLEXPORT void trace_publish_result(libtrace_t *libtrace,
1000                                    libtrace_thread_t *t,
1001                                    uint64_t key,
1002                                    libtrace_generic_t value,
1003                                    int type);
1004
1005/** Check if a dedicated hasher thread is being used.
1006 *
1007 * @param[in] libtrace The parallel input trace
1008 * @return True if the trace has dedicated hasher thread otherwise false.
1009 *
1010 * This is valid once the trace is running after calling trace_pstart().
1011 */
1012DLLEXPORT bool trace_has_dedicated_hasher(libtrace_t * libtrace);
1013
1014/** Checks if a trace is using a reporter
1015 *
1016 * @param[in] libtrace The parallel input trace
1017 * @return True if the trace is using a reporter otherwise false
1018 */
1019DLLEXPORT bool trace_has_reporter(libtrace_t * libtrace);
1020
1021/** Post a message to the reporter thread requesting it to check for more
1022 * results.
1023 *
1024 * @param[in] The parallel input trace
1025 * @return -1 upon error indicating the message has not been sent otherwise a
1026 * backlog indicator (the number of messages the reporter has not yet read).
1027 */
1028DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);
1029
1030/** Check the number of messages waiting in a queue
1031 *
1032 * @param[in] libtrace The input trace
1033 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
1034 *
1035 * @return packets in the queue otherwise -1 upon error.
1036 *
1037 * @note For best performance it is recommended to supply the thread argument
1038 * even if it is the current thread.
1039 */
1040DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace,
1041                                                libtrace_thread_t *t);
1042
1043/** Read a message from a thread in a blocking fashion
1044 *
1045 * @param[in] libtrace The input trace
1046 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
1047 * @param[out] message A pointer to libtrace_message_t structure which will be
1048 * filled with the retrieved message.
1049 *
1050 * @return The number of messages remaining otherwise -1 upon error.
1051 *
1052 *
1053 * @note For best performance it is recommended to supply the thread argument
1054 * even if it is the current thread.
1055 */
1056DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace,
1057                                          libtrace_thread_t *t,
1058                                          libtrace_message_t * message);
1059
1060/** Read a message from a thread in a blocking fashion
1061 *
1062 * @param[in] libtrace The input trace
1063 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
1064 * @param[out] message A pointer to libtrace_message_t structure which will be
1065 * filled with the retrieved message.
1066 *
1067 * @return 0 if successful otherwise -1 upon error or if no packets were available.
1068 *
1069 *
1070 * @note For best performance it is recommended to supply the thread argument
1071 * even if it is the current thread.
1072 */
1073DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace,
1074                                              libtrace_thread_t *t,
1075                                              libtrace_message_t * message);
1076
1077/** Send a message to the reporter thread
1078 *
1079 * @param[in] libtrace The parallel trace
1080 * @param[in] message The message to be sent, if sender is NULL libtrace will
1081 * attempt to fill this in. It is faster to assign this if it is known.
1082 *
1083 * @return -1 upon error indicating the message has not been sent otherwise a
1084 * backlog indicator (the number of messages the reporter has not yet read).
1085 */
1086DLLEXPORT int trace_message_reporter(libtrace_t * libtrace,
1087                                     libtrace_message_t * message);
1088
1089/** Send a message to all per-packet threads
1090 *
1091 * @param[in] libtrace The parallel trace
1092 * @param[in] message The message to be sent, if sender is NULL libtrace will
1093 * attempt to fill this in. It is faster to assign this if it is known.
1094 *
1095 * @return 0 if successful otherwise a negative number indicating the number
1096 * of per-packet threads the message was not sent to (i.e. -1 means one thread
1097 * could not be sent the message).
1098 */
1099DLLEXPORT int trace_message_perpkts(libtrace_t * libtrace,
1100                                    libtrace_message_t * message);
1101
1102/** Send a message to a thread
1103 *
1104 * @param[in] libtrace The parallel trace
1105 * @param[in] t The thread to message
1106 * @param[in] message The message to be sent, if sender is NULL libtrace will
1107 * attempt to fill this in. It is faster to assign this if it is known.
1108 *
1109 * @return -1 upon error indicating the message has not been sent otherwise a
1110 * backlog indicator (the number of messages the thread has not yet read).
1111 */
1112DLLEXPORT int trace_message_thread(libtrace_t * libtrace,
1113                                   libtrace_thread_t *t,
1114                                   libtrace_message_t * message);
1115
1116/** Check if a parallel trace has finished reading packets
1117 *
1118 * @return True if the trace has finished reading packets (even if all results
1119 * have not yet been processed). Otherwise false.
1120 *
1121 * @note This returns true even if all results have not yet been processed.
1122 */
1123DLLEXPORT bool trace_has_finished(libtrace_t * libtrace);
1124
1125
1126/** Check if libtrace is directly reading from multiple queues
1127 * from the format (such as a NICs hardware queues).
1128 *
1129 * When a parallel trace is running, or if checked after its completion
1130 * this returns true if a trace was able to run natively parallel
1131 * from the format. Otherwise false is returned, meaning libtrace is
1132 * distibuting packets across multiple threads from a single source.
1133 *
1134 * Factors that may stop this happening despite the format supporting
1135 * native parallel reads include: the choice of hasher function,
1136 * the number of threads choosen (such as 1 or more than the trace supports)
1137 * or another error when trying to start the parallel format.
1138 *
1139 * If this is called before the trace is started. I.e. before pstart
1140 * this returns an indication that the trace has the possiblity to support
1141 * native parallel reads. After trace pstart is called this should be
1142 * checked again to confirm this has happened.
1143 *
1144 *
1145 * @return true if the trace is parallel or false if the library is splitting
1146 * the trace into multiple threads.
1147 */
1148DLLEXPORT bool trace_is_parallel(libtrace_t * libtrace);
1149
1150/** Returns either the sequence number or erf timestamp of a packet.
1151 *
1152 * @param[in] packet
1153 * @return A 64bit sequence number or erf timestamp.
1154 *
1155 * The returned value can be used to compare if packets come before or after
1156 * others.
1157 */
1158DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
1159
1160/** Returns the hash of a packet.
1161 *
1162 * @param[in] packet
1163 * @return A 64-bit hash
1164 *
1165 * @note In many cases this might not be filled in, only in cases where
1166 * a custom hash is being used. You can use trace_has_dedicated_hasher()
1167 * to check if this will be valid.
1168 */
1169DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
1170
1171/** Sets the order of a packet.
1172 *
1173 * @param[in] packet
1174 * @param[in] order the new order of a packet
1175 *
1176 * @note many combiners rely on this value, ensure changing this conforms to
1177 * the combiners requirements.
1178 */
1179DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
1180
1181/** Sets the hash of a packet.
1182 *
1183 * @param[in] packet
1184 * @param[in] hash the new hash
1185 *
1186 * Once handed to the user the libtrace library has little use for this field
1187 * and as such this can essentially be used for any storage the user requires.
1188 */
1189DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
1190
1191/** TODO WHAT TO DO WITH THIS ? */
1192DLLEXPORT uint64_t tv_to_usec(const struct timeval *tv);
1193
1194
1195/** Returns the first packet of a parallel trace since it was started or
1196 * restarted.
1197 *
1198 * @param[in] libtrace the parallel input trace
1199 * @param[in] t Either a per packet thread or NULL to retrieve the first packet
1200 * of across all per packet threads.
1201 * @param[out] packet A pointer to the first packet in the trace. [Optional]
1202 * @param[out] tv The system time-stamp when this packet was received. [Optional]
1203 * @return 1 if we are confident this is the first packet. Otherwise 0 if this
1204 * is a best guess (this is only possible int the case t=NULL)
1205 * in which case we recommend calling this at a later time.
1206 * -1 is returned if an error occurs, such as supplied a invalid thread.
1207 *
1208 * The packet and timeval returned by this function is shared by all threads
1209 * and remain valid until MESSAGE_PAUSING is received.
1210 */
1211DLLEXPORT int trace_get_first_packet(libtrace_t *libtrace,
1212                                     libtrace_thread_t *t,
1213                                     const libtrace_packet_t **packet,
1214                                     const struct timeval **tv);
1215
1216/** Makes a packet safe, a packet will become invalid after a
1217 * pausing a trace.
1218 *
1219 * @param[in,out] pkt The packet to make safe
1220 *
1221 * This copies a packet in such a way that it will be able to survive a pause.
1222 * However this will not allow the packet to be used after
1223 * the format is destroyed.
1224 */
1225DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);
1226
1227/** Makes a result safe if a result contains a packet.
1228 *
1229 * @param[in,out] res The result to make safe.
1230 *
1231 * This ensures the internal content of a result is safe to survive a pause.
1232 * See libtrace_make_packet_safe().
1233 */
1234DLLEXPORT void libtrace_make_result_safe(libtrace_result_t *res);
1235
1236/** In a parallel trace, free a packet back to libtrace.
1237 *
1238 * @param[in] libtrace A parallel input trace
1239 * @param[in] packet The packet to be released back to libtrace
1240 *
1241 * The packet should not be used after calling this function.
1242 *
1243 * @note All packets should be free'd before a trace is destroyed.
1244 */
1245DLLEXPORT void trace_free_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
1246
1247
1248DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);
1249
1250/** Sets the configuration of a trace based upon a comma separated list of
1251 * key value pairs.
1252 *
1253 * @param trace A parallel trace which is not running or destroyed
1254 * @param str A comma separated list of key=value pairs.
1255 * E.g. \em "burst_size=20,perpkt_threads=2,fixed_count=true"
1256 * @return 0 if successful otherwise -1. If bad options are passed we will
1257 * print the error to stderr but still return successful.
1258 *
1259 * List of keys:
1260 * * \b cache_size,\b cs see trace_set_cache_size() [size_t]
1261 * * \b thread_cache_size,\b tcs see trace_set_thread_cache_size() [size_t]
1262 * * \b fixed_count,\b fc see trace_set_fixed_count() [bool]
1263 * * \b burst_size,\b bs see trace_set_burst_size() [size_t]
1264 * * \b tick_interval,\b ti see trace_set_tick_interval() [size_t]
1265 * * \b tick_count,\b tc see trace_set_tick_count() [size_t]
1266 * * \b perpkt_threads,\b pt see trace_set_perpkt_threads() [XXX TBA XXX]
1267 * * \b hasher_queue_size,\b hqs see trace_set_hasher_queue_size() [size_t]
1268 * * \b hasher_polling,\b hp see trace_set_hasher_polling() [bool]
1269 * * \b reporter_polling,\b rp see trace_set_reporter_polling() [bool]
1270 * * \b reporter_thold,\b rt see trace_set_reporter_thold() [size_t]
1271 * * \b debug_state,\b ds see trace_set_debug_state() [bool]
1272 *
1273 * Booleans can be set as 0/1 or false/true.
1274 *
1275 * @note a environment variable interface is provided by default to users via
1276 * LIBTRACE_CONF, see Parallel Configuration for more information.
1277 *
1278 * @note this interface is provided to allow a user to configure an application
1279 * if a libtrace applicate wishes to configure a setting it should use a
1280 * trace_set_*() function with the same name.
1281 */
1282DLLEXPORT int trace_set_configuration(libtrace_t *trace, const char * str);
1283
1284/** Sets configuration from a file. This reads every line from the file and
1285 * interprets each line with trace_set_configuration().
1286 *
1287 * @param trace A parallel trace which is not running or destroyed
1288 * @param file A file pointer which we read each line from
1289 * @return 0 if successful otherwise -1. If bad options are passed we will
1290 * print the error to stderr but still return successful.
1291 *
1292 * @note We do not close the file pointer upon completion
1293 */
1294DLLEXPORT int trace_set_configuration_file(libtrace_t *trace, FILE *file);
1295
1296DLLEXPORT int trace_get_perpkt_threads(libtrace_t* t); 
1297
1298/**
1299 * Sets a combiner function against the trace.
1300 *
1301 * @param trace The input trace
1302 * @combiner The combiner to use
1303 * @config config Configuration information. Dependent upon the combiner in use
1304 *
1305 * Sets a combiner against a trace, this should only be called on a
1306 * non-started or paused trace.  By default combiner_unordered
1307 * will be used.
1308 */
1309DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config);
1310
1311/**
1312 * Takes unordered (or ordered) input and produces unordered output.
1313 * Basically you get the result quickly but in no particular order.
1314 */
1315extern const libtrace_combine_t combiner_unordered;
1316
1317/**
1318 * Takes ordered input and produces ordered output. Perpkt threads
1319 * the output results must be ordered for this to work correctly!!
1320 */
1321extern const libtrace_combine_t combiner_ordered;
1322
1323/**
1324 * Like classic Google Map/Reduce, the results are sorted
1325 * in ascending order, this is only done when the trace finishes.
1326 *
1327 * This only works with a limited number of results, otherwise
1328 * we will just run out of memory and crash!! You should always
1329 * use combiner_ordered if you can.
1330 */
1331extern const libtrace_combine_t combiner_sorted;
1332
1333#ifdef __cplusplus
1334}
1335#endif
1336
1337#endif // LIBTRACE_PARALLEL_H
Note: See TracBrowser for help on using the repository browser.