source: lib/libtrace_parallel.h @ f2066fa

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since f2066fa was f2066fa, checked in by Richard Sanger <rsangerarj@…>, 5 years ago

Fix #5 make trace_pstart fallback to the single threaded format

If starting a parallel format fails we now retry as a single threaded format.
This fixes ring/int on older (pre 3.1 kernels) machines without PACKET_FANOUT.
This behaviour can be detected using trace_is_parallel()

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