source: lib/libtrace_parallel.h @ d3849c7

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

Remove lots of debug prints

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