source: lib/libtrace_parallel.h @ 1407294

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

Remove HASHER_HARDWARE and doc/code tidies

We don't want to expose this option to the user as it was only used internally.
As it happens we can completely remove it if needed.

Remove error handling from start thread and fix gcc warning in start thread.

  • Property mode set to 100644
File size: 32.8 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 certian 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
115typedef enum {
116        /**
117         * Sets the hasher function, if NULL(default) no hashing is used a
118         * cores will get packets on a first in first served basis
119         */
120        TRACE_OPTION_SET_HASHER,
121
122        /**
123         * Libtrace set perpkt thread count
124         */
125        TRACE_OPTION_SET_PERPKT_THREAD_COUNT,
126
127        /**
128         * Delays packets so they are played back in trace-time rather than as fast
129         * as possible.
130         */
131        TRACE_OPTION_TRACETIME,
132
133        /**
134         * Specifies the interval between tick packets in milliseconds, if 0
135         * or less this is ignored.
136         */
137        TRACE_OPTION_TICK_INTERVAL,
138        TRACE_OPTION_GET_CONFIG,
139        TRACE_OPTION_SET_CONFIG
140} trace_parallel_option_t;
141
142/** The libtrace_messages enum
143 * All libtrace messages are defined and documented here.
144 *
145 * Some messages can be sent to control the library while others
146 * are received by the per-packet and reporter functions to inform the libtrace
147 * application.
148 *
149 * If a user wishes to send there own custom messages they should use
150 * numbers greater than MESSAGE_USER (1000).
151 *
152 * @note Some messages are for internal use only
153 */
154enum libtrace_messages {
155        /** A libtrace packet is ready, this will only be sent to per
156         * packet threads.
157         * @param data Holds the packet in data.pkt. The packet belongs to
158         * libtrace and should either be returned from the per-packet function
159         * if no longer needed or free'd at some later time using the XXX
160         * function.
161         * @param sender The sender will be set as the current thread
162         */
163        MESSAGE_PACKET,
164        /** A libtrace result is ready, this will only be sent to the reporter
165         * thread.
166         * @param data Holds the result in data.res. The memory holding the
167         * result is allocated by libtrace and should not be free'd. However
168         * note that any data stored within the result might need to be free'd.
169         * @param sender The sender will be set as the current thread
170         */
171        MESSAGE_RESULT,
172
173        /** A message sent to each thread when it starts. This is sent
174         * to both the reporter and per-packet threads. This will be sent once
175         * after trace_pstart() (assuming no errors occurs).
176         *
177         * This can be used to allocate resources required by each thread.
178         *
179         * These can be free'd when MESSAGE_STOPPING is received.
180         *
181         * @param data unused, do not use this
182         * @param sender The sender will be set as the current thread
183         */
184        MESSAGE_STARTING,
185
186        /** A message sent to each thread when it stops. This is sent
187         * to both the reporter and per-packet threads. This will be sent once
188         * after MESSAGE_STARTING.
189         *
190         * This can be used to free any resources allocated with
191         * MESSAGE_STARTING.
192         *
193         * @param data unused, do not use this
194         * @param sender The sender will be set as the current thread
195         */
196        MESSAGE_STOPPING,
197
198        /** A message sent to each thread when a thread transitions between a
199         * paused (or unstarted) state to running state. This is sent
200         * to both the reporter and per-packet threads. This will be sent after
201         * MESSAGE_STARTING when a trace is first started and when a trace
202         * is started (trace_pstart()) after a pause (trace_ppause()).
203         *
204         * This can be used to allocate resources.
205         *
206         * @param data unused, do not use this
207         * @param sender The sender will be set as the current thread
208         */
209        MESSAGE_RESUMING,
210
211        /** A message sent to each thread when a thread transitions between a
212         * paused (or unstarted) state to running state. This is sent
213         * to both the reporter and per-packet threads. This will be sent after
214         * MESSAGE_STARTING when a trace is first started and when a trace
215         * is started (trace_pstart()) after a pause (trace_ppause()).
216         *
217         * This can be used to allocate resources.
218         *
219         * @param data unused, do not use this
220         * @param sender The sender will be set as the current thread
221         */
222        MESSAGE_PAUSING,
223
224        /** An internal message do not use this */
225        MESSAGE_DO_PAUSE,
226        /** An internal message do not use this */
227        MESSAGE_DO_STOP,
228
229        /** Sent to all per-packet threads (including the sender) and the
230         * reducer when the first packet is seen for a thread.
231         *
232         * @param data The first packet is stored in data.pkt. This packet is
233         * shared by all threads receiving the message and is valid until
234         * MESSAGE_PAUSING is received.
235         * @param sender The per-packet thread which received the packet
236         *
237         * @note Upon pausing and restarting a trace this will be reset and
238         * sent once a new packet is encountered
239         *
240         * @
241         */
242        MESSAGE_FIRST_PACKET,
243
244        /** Notify the reporter thread more data is available.
245         *
246         * Triggers the reporter to read as many results as possible.
247         *
248         * @param data unused
249         * @param sender the sending
250         *
251         * @note This message should not be sent directly instead call
252         * trace_post_reporter()
253         *
254         * @see trace_get_first_packet()
255         */
256        MESSAGE_POST_REPORTER,
257
258        /** Sent to per-packet threads perodically after the configured time
259         * interval has passed.
260         *
261         * This is sent out-of-band with respect to packets and as a result
262         * can appear after a packet with an later timestamp, or before one
263         * with an earlier timestamp.
264         *
265         * @param data data.uint64_t holds the system timestamp in the
266         * erf format
267         * @param sender should be ignored
268         */
269        MESSAGE_TICK_INTERVAL,
270
271        /** Sent to per-packet threads once the configured number of packets
272         * are read from a trace.
273         *
274         * This are sent in-band with respect to packets such that all
275         * threads will see it between the same packets.
276         *
277         * @param data The number of packets seen so far across all threads
278         * @param sender Set to the current per-packet thread
279         */
280        MESSAGE_TICK_COUNT,
281
282        /** For specific user defined messages use codes above MESSAGE_USER. */
283        MESSAGE_USER = 1000
284};
285
286/** The hasher types avaliable to libtrace application.
287 * These can be selected using trace_set_hasher().
288 */
289enum hasher_types {
290        /** Balance load across per-packet threads as best as possible, this is
291         * basically to say I do not care about where packets are sent. This
292         * might still might be implemented using a hash or round robin etc.
293         * depending on the format and libtrace configuration.
294         */
295        HASHER_BALANCE,
296
297        /** Use a hash which is bi-directional for TCP and UDP flows, that is
298         * packets with the same 5-tuple are sent to the same per-packet thread.
299         * All non TCP/UDP packets will be sent to the same thread.
300         *
301         * @note it is possible that UDP packets may not be spread across
302         * per-packet threads, depending upon the format support. In this case
303         * they would be directed to a single per-packet thread.
304         */
305        HASHER_BIDIRECTIONAL,
306
307        /** Use a hash which is uni-directional across TCP and UDP flows, this
308         * means the opposing directions of the same 5-tuple might end up on
309         * different per-packet threads.
310         * Otherwise this is identical to HASHER_BIDIRECTIONAL
311         */
312        HASHER_UNIDIRECTIONAL,
313
314        /**
315         * Always use the user supplied hasher, this disables native
316         * support in and is likely significantly slower.
317         */
318        HASHER_CUSTOM
319};
320
321typedef struct libtrace_info_t {
322        /**
323         * True if a live format (i.e. packets have to be tracetime).
324         * Otherwise false, indicating packets can be read as fast
325         * as possible from the format.
326         */
327        bool live;
328
329        /**
330         * The maximum number of threads supported by a parallel trace. 1
331         * if parallel support is not native (in this case libtrace will simulate
332         * an unlimited number of threads), -1 means unlimited and 0 unknown.
333         */
334        int max_threads;
335
336        /* TODO hash fn supported list */
337
338        /* TODO consider time/clock details?? */
339} libtrace_info_t;
340
341
342/**
343 * Tuning the parallel sizes
344 */
345struct user_configuration {
346        // Packet memory cache settings (ocache_init) total
347        /**
348         * See diagrams, this sets the maximum size of freelist used to
349         * maintain packets and their memory buffers.
350         * NOTE setting this to less than recommend could cause deadlock a
351         * trace that manages its own packets.
352         * A unblockable error message will be printed.
353         */
354        size_t packet_cache_size;
355        /**
356         * Per thread local cache size for the packet freelist
357         */
358        size_t packet_thread_cache_size;
359        /**
360         * If true the total number of packets that can be created by a trace is limited
361         * to the packet_cache_size, otherwise once packet_cache_size is exceeded alloc
362         * and free will be used to create and free packets, this will be slower than
363         * using the freelist and could run a machine out of memory.
364         *
365         * However this does make it easier to ensure that deadlocks will not occur
366         * due to running out of packets
367         */
368        bool fixed_packet_count;
369        /**
370         * When reading from a single threaded input source to reduce
371         * lock contention a 'burst' of packets is read per pkt thread
372         * this determines the bursts size.
373         */
374        size_t burst_size;
375        // Each perpkt thread has a queue leading into the reporter
376        //size_t reporter_queue_size;
377
378        /**
379         * The tick interval - in milliseconds
380         * When a live trace is used messages are sent at the tick
381         * interval to ensure that all perpkt threads receive data
382         * this allows results to be printed in cases flows are
383         * not being directed to a certian thread, while still
384         * maintaining order.
385         */
386        size_t tick_interval;
387
388        /**
389         * Like the tick interval but used in the case of file format
390         * This specifies the number of packets before inserting a tick to
391         * every thread.
392         */
393        size_t tick_count;
394
395        /**
396         * The number of per packet threads requested, 0 means use default.
397         * Default typically be the number of processor threads detected less one or two.
398         */
399        size_t perpkt_threads;
400
401        /**
402         * See diagrams, this sets the maximum size of buffers used between
403         * the single hasher thread and the buffer.
404         * NOTE setting this to less than recommend could cause deadlock a
405         * trace that manages its own packets.
406         * A unblockable warning message will be printed to stderr in this case.
407         */
408        /** The number of packets that can queue per thread from hasher thread */
409        size_t hasher_queue_size;
410
411        /**
412         * If true use a polling hasher queue, that means that we will spin/or yeild
413         * when rather than blocking on a lock. This applies to both the hasher thread
414         * and perpkts reading the queues.
415         */
416        bool hasher_polling;
417
418        /**
419         * If true the reporter thread will continuously poll waiting for results
420         * if false they are only checked when a message is received, this message
421         * is controlled by reporter_thold.
422         */
423        bool reporter_polling;
424
425        /**
426         * Perpkt thread result queue size before triggering the reporter step to read results
427         */
428        size_t reporter_thold;
429
430        /**
431         * Prints a line to standard error for every state change
432         * for both the trace as a whole and for each thread.
433         */
434        bool debug_state;
435};
436
437/**
438 * The methods we use to combine multiple outputs into a single output
439 * This is not considered a stable API however is public.
440 * Where possible use built in combiners
441 *
442 * NOTE this structure is duplicated per trace and as such can
443 * have functions rewritten, and in fact should if possible.
444 */
445typedef struct libtrace_combine libtrace_combine_t;
446struct libtrace_combine {
447
448        /**
449         * Called at the start of the trace to allow datastructures
450         * to be initilised and allow functions to be swapped if approriate.
451         *
452         * Also factors such as whether the trace is live or not can
453         * be used to determine the functions used.
454         * @return 0 if successful, -1 if an error occurs
455         */
456        int (*initialise)(libtrace_t *,libtrace_combine_t *);
457
458        /**
459         * Called when the trace ends, clean up any memory here
460         * from libtrace_t * init.
461         */
462        void (*destroy)(libtrace_t *, libtrace_combine_t *);
463
464        /**
465         * Publish a result against it's a threads queue.
466         * If null publish directly, expected to be used
467         * as a single threaded optimisation and can be
468         * set to NULL by init if this case is detected.
469         *
470         * TODO this is old info
471         */
472        void (*publish)(libtrace_t *, int thread_id, libtrace_combine_t *, libtrace_result_t *);
473
474        /**
475         * Read as many results as possible from the trace.
476         * Directy calls the users code to handle results from here.
477         *
478         * THIS SHOULD BE NON-BLOCKING AND READ AS MANY AS POSSIBLE
479         * If publish is NULL, this probably should be NULL also otherwise
480         * it will not be called.
481         */
482        void (*read)(libtrace_t *, libtrace_combine_t *);
483
484        /**
485         * Called when the trace is finished to flush the final
486         * results to the reporter thread.
487         *
488         * There may be no results, in which case this should
489         * just return.
490         *
491         * Libtrace state:
492         * Called from reporter thread
493         * No perpkt threads will be running, i.e. publish will not be
494         * called again.
495         *
496         * If publish is NULL, this probably should be NULL also otherwise
497         * it will not be called.
498         */
499        void (*read_final)(libtrace_t *, libtrace_combine_t *);
500
501        /**
502         * Pause must make sure any results of the type packet are safe.
503         * That means trace_copy_packet() and destroy the original.
504         * This also should be NULL if publish is NULL.
505         */
506        void (*pause)(libtrace_t *, libtrace_combine_t *);
507
508        /**
509         * Data storage for all the combiner threads
510         */
511        void *queues;
512
513        /**
514         * Configuration options, what this does is upto the combiner
515         * chosen.
516         */
517        libtrace_generic_t configuration;
518};
519
520/**
521 * The definition for the main function that the user supplies to process
522 * packets.
523 *
524 * @param trace The trace the packet is related to.
525 * @param thread The thread identifier.
526 * @param mesg_code The type of data ready, the most important being MESSAGE_PACKET.
527 * In this case data.pkt contains the packet.
528 * @param data A generic union of types that fit into 8 bytes, containing
529 * information dependent upon the mesg_code.
530 * @param sender The thread from which the message originated.
531 * @return If the message type is MESSAGE_PACKET a packet can be returned back
532 * to the library similar to trace_free_packet() otherwise this should be NULL.
533 *
534 * The values of data and sender depend upon the mesg_code. Please see the
535 * documentation for the message as to what value these will contain.
536 */
537typedef void* (*fn_per_pkt)(libtrace_t* trace,
538                            libtrace_thread_t *thread,
539                            int mesg_code,
540                            libtrace_generic_t data,
541                            libtrace_thread_t *sender);
542
543/**
544 * The definition for the main function that the user supplies to process
545 * results from trace_publish_result().
546 *
547 * @param trace The trace the packet is related to.
548 * @param mesg_code The type of data ready, the most important being MESSAGE_RESULT.
549 * In this case data.res contains the result.
550 * @param data A generic union of types that fit into 8 bytes, containing
551 * information dependent upon the mesg_code.
552 * @param sender The thread from which the message originated.
553 *
554 * The values of data and sender depend upon the mesg_code. Please see the
555 * documentation for the message as to what value these will contain.
556 */
557typedef void (*fn_reporter)(libtrace_t* trace,
558                            int mesg_code,
559                            libtrace_generic_t data,
560                            libtrace_thread_t *sender);
561
562/**
563 * The definition for a hasher function, allowing matching packets to be
564 * directed to the same per packet thread for processing.
565 *
566 * @param packet The packet to be hashed.
567 * @param data A void pointer which can contain additional information,
568 * such as configuration of the hasher function.
569 */
570typedef uint64_t (*fn_hasher)(const libtrace_packet_t* packet, void *data);
571
572
573/** Start or restart an input trace in the parallel libtrace framework.
574 *
575 * @param libtrace The input trace to start
576 * @param global_blob Global data related to this trace accessable using trace_get_global()
577 * @param per_pkt A user supplied function called when a packet is ready
578 * @param reporter A user supplied function called when a result is ready.
579 * Optional if NULL the reporter thread will not be started.
580 * @return 0 on success, otherwise -1 to indicate an error has occured
581 *
582 * This can also be used to restart an existing parallel trace,
583 * that has previously been paused using trace_ppause().
584 * In this case global_blob,per_pkt and reporter will only be updated
585 * if they are non-null. Otherwise their previous values will be maintained.
586 *
587 */
588DLLEXPORT int trace_pstart(libtrace_t *libtrace, void* global_blob,
589                           fn_per_pkt per_pkt, fn_reporter reporter);
590
591/** Pauses a trace previously started with trace_pstart()
592 *
593 * @param libtrace The parallel trace to be paused
594 * @return 0 on success, otherwise -1 to indicate an error has occured
595 *
596 */
597DLLEXPORT int trace_ppause(libtrace_t *libtrace);
598
599/** Stops a parallel trace, causing all threads to exit as if an EOF
600 * has occured. This replaces trace_interrupt(), allowing
601 * a specified trace to be stopped.
602 *
603 * @param libtrace The parallel trace to be stopped
604 * @return 0 on success, otherwise -1 to indicate an error has occured
605 *
606 * This should only be called by the main thread.
607 *
608 */
609DLLEXPORT int trace_pstop(libtrace_t *libtrace);
610
611/** Waits for a trace to finish and all threads to join.
612 *
613 * @param trace The parallel trace
614 *
615 * Waits for a trace to finish, whether this be due to
616 * an error occuring, an EOF or trace_pstop.
617 *
618 */
619DLLEXPORT void trace_join(libtrace_t * trace);
620
621/**
622 * @name User Data Storage
623 *
624 * These method provide a way for users to store data agaist a trace or
625 * a thread.
626 *
627 * Alternatively one could use global variables and thread local
628 * storage (__thread), respectively, which in many cases could be simplier.
629 *
630 * @note We do not lock on reads, instead we rely on the
631 * processor making any writes appear atomically.
632 *
633 * @{
634 */
635
636/** Returns the data stored against a trace.
637 *
638 * @param trace The parallel trace
639 * @return The stored data.
640 */
641DLLEXPORT void * trace_get_local(libtrace_t *trace);
642
643/** Store data against a trace so that all threads can access it
644 * using trace_get_global().
645 *
646 * @param trace The parallel trace.
647 * @param data The new value to save agaisnt the trace
648 * @return The previously stored value
649 *
650 * The update to the previous value is atomic and thread-safe.
651 *
652 * @note Although this is thread-safe another thread may still be
653 * using the previous data, as such further synchronisation is needed
654 * if a thread wanted to free the existing value.
655 */
656DLLEXPORT void * trace_set_local(libtrace_t *trace, void * data);
657
658/** Returns the users data stored against a thread.
659 *
660 * @param thread The thread
661 * @return The stored data
662 */
663DLLEXPORT void * trace_get_tls(libtrace_thread_t *thread);
664
665/** Store data against a thread.
666 *
667 * @param The parallel trace.
668 * @param data The new value to save agaisnt the trace
669 * @return The previously stored value
670 *
671 * This function is not thread-safe and is intented only to be
672 * called on the currently running thread.
673 */
674DLLEXPORT void * trace_set_tls(libtrace_thread_t *thread, void * data);
675
676/// @}
677
678/** Set the hasher function for a parallel trace.
679 *
680 * @param[in] trace The parallel trace to apply the hasher to
681 * @param[in] type The type of hashing to apply, see enum hasher_types
682 * @param[in] hasher A hasher function to use [Optional]
683 * @param[in] data Data passed to the hasher function [Optional]
684 *
685 * @return 0 if successful otherwise -1 on error
686 *
687 * The hasher function in a parallel trace can be used to control which
688 * per-packet thread a packets is processed by.
689 *
690 * HASHER_BALANCE is the default and will dispatch packets as fast as possible
691 * to all threads arbitrarily. As such when called the hasher and
692 * data parameters must be set to NULL.
693 *
694 * HASHER_CUSTOM will force the libtrace to use the user defined function. As
695 * such the hasher parameter must be supplied.
696 *
697 * With other defined hasher types we will try to push the hashing into the format
698 * by default. In this case the hasher parameter is optional and will be
699 * preferred over the default supplied by libtrace.
700 *
701 * @note When supplying a hasher function it should be thread-safe as it could
702 * be run in parallel by libtrace. Ideally this should rely upon no state, other
703 * than some form of seed value supplied in data.
704 */
705DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type, fn_hasher hasher, void *data);
706
707/** Types of results.
708 * Some result types require special handling by combiners
709 * as such making use of built-in types is important.
710 *
711 * Custom result types users should be defined as RESULT_USER(1000) or greater.
712 *
713 */
714enum result_types {
715        /**
716         * The result is a packet in some circumstances special handling needs
717         * to be performed. As such packets should always be published as so.
718         *
719         * @param key (Typically) The packets order, see trace_packet_get_order()
720         * @param
721         */
722        RESULT_PACKET,
723
724        /** The result is a tick message
725         *
726         * @param key The erf timestamp of the tick
727         */
728        RESULT_TICK_INTERVAL,
729
730        /** The result is a tick message
731         *
732         * @param key The sequence number of the tick message
733         */
734        RESULT_TICK_COUNT,
735
736        /** Any user specific codes should be above this.
737         *
738         */
739        RESULT_USER = 1000
740
741};
742
743/** Publish a result for to the combiner destined for the reporter thread
744 *
745 * @param libtrace[in] The parallel input trace
746 * @param t[in] The current per-packet thread
747 * @param key[in] The key of the result (used for sorting by the combiner)
748 * @param value[in] The value of the result
749 * @param type[in] The type of result see the documentation for the result_types enum
750 */
751DLLEXPORT void trace_publish_result(libtrace_t *libtrace,
752                                    libtrace_thread_t *t,
753                                    uint64_t key,
754                                    libtrace_generic_t value,
755                                    int type);
756
757/** Check if a dedicated hasher thread is being used.
758 *
759 * @return True if the trace has dedicated hasher thread otherwise false.
760 *
761 * This is valid once the trace is running after calling trace_pstart().
762 */
763DLLEXPORT bool trace_has_dedicated_hasher(libtrace_t * libtrace);
764
765/** Checks if a trace is using a reporter
766 *
767 * @param[in] The parallel input trace
768 * @return True if the trace is using a reporter otherwise false
769 */
770DLLEXPORT bool trace_has_reporter(libtrace_t * libtrace);
771
772/** Post a message to the reporter thread requesting it to check for more
773 * results.
774 *
775 * @param[in] The parallel input trace
776 * @return -1 upon error indicating the message has not been sent otherwise a
777 * backlog indicator (the number of messages the reporter has not yet read).
778 */
779DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);
780
781/** Check the number of messages waiting in a queue
782 *
783 * @param[in] libtrace The input trace
784 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
785 *
786 * @return packets in the queue otherwise -1 upon error.
787 *
788 * @note For best performance it is recommended to supply the thread argument
789 * even if it is the current thread.
790 */
791DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace,
792                                                libtrace_thread_t *t);
793
794/** Read a message from a thread in a blocking fashion
795 *
796 * @param[in] libtrace The input trace
797 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
798 * @param[out] message A pointer to libtrace_message_t structure which will be
799 * filled with the retrived message.
800 *
801 * @return The number of messages remaining otherwise -1 upon error.
802 *
803 *
804 * @note For best performance it is recommended to supply the thread argument
805 * even if it is the current thread.
806 */
807DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace,
808                                          libtrace_thread_t *t,
809                                          libtrace_message_t * message);
810
811/** Read a message from a thread in a blocking fashion
812 *
813 * @param[in] libtrace The input trace
814 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
815 * @param[out] message A pointer to libtrace_message_t structure which will be
816 * filled with the retrived message.
817 *
818 * @return 0 if successful otherwise -1 upon error or if no packets were available.
819 *
820 *
821 * @note For best performance it is recommended to supply the thread argument
822 * even if it is the current thread.
823 */
824DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace,
825                                              libtrace_thread_t *t,
826                                              libtrace_message_t * message);
827
828/** Send a message to the reporter thread
829 *
830 * @param[in] libtrace The parallel trace
831 * @param[in] message The message to be sent, if sender is NULL libtrace will
832 * attempt to fill this in. It is faster to assign this if it is known.
833 *
834 * @return -1 upon error indicating the message has not been sent otherwise a
835 * backlog indicator (the number of messages the reporter has not yet read).
836 */
837DLLEXPORT int trace_message_reporter(libtrace_t * libtrace,
838                                     libtrace_message_t * message);
839
840/** Send a message to all per-packet threads
841 *
842 * @param[in] libtrace The parallel trace
843 * @param[in] message The message to be sent, if sender is NULL libtrace will
844 * attempt to fill this in. It is faster to assign this if it is known.
845 *
846 * @return 0 if successful otherwise a negative number indicating the number
847 * of per-packet threads the message was not sent to (i.e. -1 means one thread
848 * could not be sent the message).
849 */
850DLLEXPORT int trace_message_perpkts(libtrace_t * libtrace,
851                                    libtrace_message_t * message);
852
853/** Send a message to a thread
854 *
855 * @param[in] libtrace The parallel trace
856 * @param[in] t The thread to message
857 * @param[in] message The message to be sent, if sender is NULL libtrace will
858 * attempt to fill this in. It is faster to assign this if it is known.
859 *
860 * @return -1 upon error indicating the message has not been sent otherwise a
861 * backlog indicator (the number of messages the thread has not yet read).
862 */
863DLLEXPORT int trace_message_thread(libtrace_t * libtrace,
864                                   libtrace_thread_t *t,
865                                   libtrace_message_t * message);
866
867/** Check if a parallel trace has finished reading packets
868 *
869 * @return True if the trace has finished reading packets (even if all results
870 * have not yet been processed). Otherwise false.
871 *
872 * @note This returns true even if all results have not yet been processed.
873 */
874DLLEXPORT bool trace_has_finished(libtrace_t * libtrace);
875
876/** Returns either the sequence number or erf timestamp of a packet.
877 *
878 * @param[in] packet
879 * @return A 64bit sequence number or erf timestamp.
880 *
881 * The returned value can be used to compare if packets come before or after
882 * others.
883 */
884DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
885
886/** Returns the hash of a packet.
887 *
888 * @param[in] packet
889 * @return A 64-bit hash
890 *
891 * @note In many cases this might not be filled in, only in cases where
892 * a custom hash is being used. You can use trace_has_dedicated_hasher()
893 * to check if this will be valid.
894 */
895DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
896
897/** Sets the order of a packet.
898 *
899 * @param[in] packet
900 * @param[in] order the new order of a packet
901 *
902 * @note many combiners rely on this value, ensure changing this conforms to
903 * the combiners requirements.
904 */
905DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
906
907/** Sets the hash of a packet.
908 *
909 * @param[in] packet
910 * @param[in] hash the new hash
911 *
912 * Once handed to the user the libtrace library has little use for this field
913 * and as such this can essentially be used for any storage the user requires.
914 */
915DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
916
917/** TODO WHAT TO DO WITH THIS ? */
918DLLEXPORT uint64_t tv_to_usec(struct timeval *tv);
919
920
921/** Returns the first packet of a parallel trace since it was started or
922 * restarted.
923 *
924 * @param[in] libtrace the parallel input trace
925 * @param[in] t Either a per packet thread or NULL to retrive the first packet
926 * of across all per packet threads.
927 * @param[out] packet A pointer to the first packet in the trace. [Optional]
928 * @param[out] tv The system timestamp when this packet was received. [Optional]
929 * @return 1 if we are confident this is the first packet. Otherwise 0 if this
930 * is a best guess (this is only possible int the case t=NULL)
931 * in which case we recommend calling this at a later time.
932 * -1 is returned if an error occurs, such as supplied a invalid thread.
933 *
934 * The packet returned by this function is shared by all threads and remains
935 * valid until MESSAGE_PAUSING is received.
936 */
937DLLEXPORT int trace_get_first_packet(libtrace_t *libtrace,
938                                     libtrace_thread_t *t,
939                                     libtrace_packet_t **packet,
940                                     struct timeval **tv);
941
942/** Makes a packet safe, a packet will become invaild after a
943 * pausing a trace.
944 *
945 * @param pkt[in,out] The packet to make safe
946 *
947 * This copies a packet in such a way that it will be able to survive a pause.
948 * However this will not allow the packet to be used after
949 * the format is destroyed.
950 */
951DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);
952
953/** Makes a result safe if a result contains a packet.
954 *
955 * @param res[in,out] The result to make safe.
956 *
957 * This ensures the internal content of a result is safe to survive a pause.
958 * See libtrace_make_packet_safe().
959 */
960DLLEXPORT void libtrace_make_result_safe(libtrace_result_t *res);
961
962
963DLLEXPORT int trace_parallel_config(libtrace_t *libtrace, trace_parallel_option_t option, void *value);
964
965/** In a parallel trace, free a packet back to libtrace.
966 *
967 * @param[in] libtrace A parallel input trace
968 * @param[in] packet The packet to be released back to libtrace
969 *
970 * The packet should not be used after calling this function.
971 *
972 * @note All packets should be free'd before a trace is destroyed.
973 */
974DLLEXPORT void trace_free_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
975
976
977DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);
978DLLEXPORT void parse_user_config(struct user_configuration* uc, char * str);
979DLLEXPORT void parse_user_config_file(struct user_configuration* uc, FILE *file);
980DLLEXPORT int libtrace_get_perpkt_count(libtrace_t* t);
981
982/**
983 * Sets a combiner function against the trace.
984 *
985 * @param trace The input trace
986 * @combiner The combiner to use
987 * @config config Configuration information. Dependent upon the combiner in use
988 *
989 * Sets a combiner against a trace, this should only be called on a
990 * non-started or paused trace.
991 */
992DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config);
993
994#define ZERO_USER_CONFIG(config) memset(&config, 0, sizeof(struct user_configuration));
995
996#endif // LIBTRACE_PARALLEL_H
Note: See TracBrowser for help on using the repository browser.