source: lib/libtrace_parallel.h @ 6a6e6a8

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

More documentation, including some renaming and modifications to behaviour

  • Removes accessor functions for libtrace_result_t, instead directly access the structure
  • Documentation for most functions
  • Split tick into interval and count messages for the two modes of operation
  • Normalise interval and packet order to use the erf timestamp format
  • Rename trace_send_message_to_XXX to trace trace_message_XXX
  • Property mode set to 100644
File size: 31.4 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
286enum hasher_types {
287        /**
288         * Balance load across CPUs best as possible, this is basically to say do
289         * not care about hash. This might still might be implemented
290         * using a hash or round robin etc. under the hood depending on the format
291         */
292        HASHER_BALANCE,
293
294        /** Use a hash which is bi-directional for TCP flows, that is packets with
295         * the same hash are sent to the same thread. All non TCP packets will be
296         * sent to the same thread. UDP may or may not be sent to separate
297         * threads like TCP, this depends on the format support.
298         */
299        HASHER_BIDIRECTIONAL,
300
301        /**
302         * Use a hash which is uni-directional across TCP flows, that means the
303         * opposite directions of the same 5 tuple might end up on separate cores.
304         * Otherwise is identical to HASHER_BIDIRECTIONAL
305         */
306        HASHER_UNIDIRECTIONAL,
307
308        /**
309         * Always use the user supplied hasher, this currently disables native
310         * support and is likely significantly slower.
311         */
312        HASHER_CUSTOM,
313
314        /**
315         * This is not a valid option, used internally only!!! TODO remove
316         * Set by the format if the hashing is going to be done in hardware
317         */
318        HASHER_HARDWARE
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
679/** TODO DOXS
680 */
681DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type, fn_hasher hasher, void *data);
682
683/** Types of results.
684 * Some result types require special handling by combiners
685 * as such making use of built-in types is important.
686 *
687 * User specific results should be defined as values greater than RESULT_USER(1000)
688 *
689 */
690enum result_types {
691        /**
692         * The result is a packet in some circumstances special handling needs
693         * to be performed. As such packets should always be published as so.
694         *
695         * @param key (Typically) The packets order, see trace_packet_get_order()
696         * @param
697         */
698        RESULT_PACKET,
699
700        /** The result is a tick message
701         *
702         * @param key The erf timestamp of the tick
703         */
704        RESULT_TICK_INTERVAL,
705
706        /** The result is a tick message
707         *
708         * @param key The sequence number of the tick message
709         */
710        RESULT_TICK_COUNT,
711
712        /** Any user specific codes should be above this.
713         *
714         */
715        RESULT_USER = 1000
716
717};
718
719/** Publish a result for to the combiner destined for the reporter thread
720 *
721 * @param libtrace[in] The parallel input trace
722 * @param t[in] The current per-packet thread
723 * @param key[in] The key of the result (used for sorting by the combiner)
724 * @param value[in] The value of the result
725 * @param type[in] The type of result see the documentation for the result_types enum
726 */
727DLLEXPORT void trace_publish_result(libtrace_t *libtrace,
728                                    libtrace_thread_t *t,
729                                    uint64_t key,
730                                    libtrace_generic_t value,
731                                    int type);
732
733/** Check if a dedicated hasher thread is being used
734 *
735 * @return True if the trace has dedicated hasher thread otherwise false.
736 */
737DLLEXPORT bool trace_has_dedicated_hasher(libtrace_t * libtrace);
738
739/** Checks if a trace is using a reporter
740 *
741 * @param[in] The parallel input trace
742 * @return True if the trace is using a reporter otherwise false
743 */
744DLLEXPORT bool trace_has_reporter(libtrace_t * libtrace);
745
746/** Post a message to the reporter thread requesting it to check for more
747 * results.
748 *
749 * @param[in] The parallel input trace
750 * @return -1 upon error indicating the message has not been sent otherwise a
751 * backlog indicator (the number of messages the reporter has not yet read).
752 */
753DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);
754
755/** Check the number of messages waiting in a queue
756 *
757 * @param[in] libtrace The input trace
758 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
759 *
760 * @return packets in the queue otherwise -1 upon error.
761 *
762 * @note For best performance it is recommended to supply the thread argument
763 * even if it is the current thread.
764 */
765DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace,
766                                                libtrace_thread_t *t);
767
768/** Read a message from a thread in a blocking fashion
769 *
770 * @param[in] libtrace The input trace
771 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
772 * @param[out] message A pointer to libtrace_message_t structure which will be
773 * filled with the retrived message.
774 *
775 * @return The number of messages remaining otherwise -1 upon error.
776 *
777 *
778 * @note For best performance it is recommended to supply the thread argument
779 * even if it is the current thread.
780 */
781DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace,
782                                          libtrace_thread_t *t,
783                                          libtrace_message_t * message);
784
785/** Read a message from a thread in a blocking fashion
786 *
787 * @param[in] libtrace The input trace
788 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
789 * @param[out] message A pointer to libtrace_message_t structure which will be
790 * filled with the retrived message.
791 *
792 * @return 0 if successful otherwise -1 upon error or if no packets were available.
793 *
794 *
795 * @note For best performance it is recommended to supply the thread argument
796 * even if it is the current thread.
797 */
798DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace,
799                                              libtrace_thread_t *t,
800                                              libtrace_message_t * message);
801
802/** Send a message to the reporter thread
803 *
804 * @param[in] libtrace The parallel trace
805 * @param[in] message The message to be sent, if sender is NULL libtrace will
806 * attempt to fill this in. It is faster to assign this if it is known.
807 *
808 * @return -1 upon error indicating the message has not been sent otherwise a
809 * backlog indicator (the number of messages the reporter has not yet read).
810 */
811DLLEXPORT int trace_message_reporter(libtrace_t * libtrace,
812                                     libtrace_message_t * message);
813
814/** Send a message to all per-packet threads
815 *
816 * @param[in] libtrace The parallel trace
817 * @param[in] message The message to be sent, if sender is NULL libtrace will
818 * attempt to fill this in. It is faster to assign this if it is known.
819 *
820 * @return 0 if successful otherwise a negative number indicating the number
821 * of per-packet threads the message was not sent to (i.e. -1 means one thread
822 * could not be sent the message).
823 */
824DLLEXPORT int trace_message_perpkts(libtrace_t * libtrace,
825                                    libtrace_message_t * message);
826
827/** Send a message to a thread
828 *
829 * @param[in] libtrace The parallel trace
830 * @param[in] t The thread to message
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 thread has not yet read).
836 */
837DLLEXPORT int trace_message_thread(libtrace_t * libtrace,
838                                   libtrace_thread_t *t,
839                                   libtrace_message_t * message);
840
841/** Check if a parallel trace has finished reading packets
842 *
843 * @return True if the trace has finished reading packets (even if all results
844 * have not yet been processed). Otherwise false.
845 *
846 * @note This returns true even if all results have not yet been processed.
847 */
848DLLEXPORT bool trace_has_finished(libtrace_t * libtrace);
849
850/** Returns either the sequence number or erf timestamp of a packet.
851 *
852 * @param[in] packet
853 * @return A 64bit sequence number or erf timestamp.
854 *
855 * The returned value can be used to compare if packets come before or after
856 * others.
857 */
858DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
859
860/** Returns the hash of a packet.
861 *
862 * @param[in] packet
863 * @return A 64-bit hash
864 *
865 * @note In many cases this might not be filled in, only in cases where
866 * a custom hash is being used. You can use trace_has_dedicated_hasher()
867 * to check if this will be valid.
868 */
869DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
870
871/** Sets the order of a packet.
872 *
873 * @param[in] packet
874 * @param[in] order the new order of a packet
875 *
876 * @note many combiners rely on this value, ensure changing this conforms to
877 * the combiners requirements.
878 */
879DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
880
881/** Sets the hash of a packet.
882 *
883 * @param[in] packet
884 * @param[in] hash the new hash
885 *
886 * Once handed to the user the libtrace library has little use for this field
887 * and as such this can essentially be used for any storage the user requires.
888 */
889DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
890
891/** TODO WHAT TO DO WITH THIS ? */
892DLLEXPORT uint64_t tv_to_usec(struct timeval *tv);
893
894
895/** Returns the first packet of a parallel trace since it was started or
896 * restarted.
897 *
898 * @param[in] libtrace the parallel input trace
899 * @param[in] t Either a per packet thread or NULL to retrive the first packet
900 * of across all per packet threads.
901 * @param[out] packet A pointer to the first packet in the trace. [Optional]
902 * @param[out] tv The system timestamp when this packet was received. [Optional]
903 * @return 1 if we are confident this is the first packet. Otherwise 0 if this
904 * is a best guess (this is only possible int the case t=NULL)
905 * in which case we recommend calling this at a later time.
906 * -1 is returned if an error occurs, such as supplied a invalid thread.
907 *
908 * The packet returned by this function is shared by all threads and remains
909 * valid until MESSAGE_PAUSING is received.
910 */
911DLLEXPORT int trace_get_first_packet(libtrace_t *libtrace,
912                                     libtrace_thread_t *t,
913                                     libtrace_packet_t **packet,
914                                     struct timeval **tv);
915
916/** Makes a packet safe, a packet will become invaild after a
917 * pausing a trace.
918 *
919 * @param pkt[in,out] The packet to make safe
920 *
921 * This copies a packet in such a way that it will be able to survive a pause.
922 * However this will not allow the packet to be used after
923 * the format is destroyed.
924 */
925DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);
926
927/** Makes a result safe if a result contains a packet.
928 *
929 * @param res[in,out] The result to make safe.
930 *
931 * This ensures the internal content of a result is safe to survive a pause.
932 * See libtrace_make_packet_safe().
933 */
934DLLEXPORT void libtrace_make_result_safe(libtrace_result_t *res);
935
936
937DLLEXPORT int trace_parallel_config(libtrace_t *libtrace, trace_parallel_option_t option, void *value);
938
939/** In a parallel trace, free a packet back to libtrace.
940 *
941 * @param[in] libtrace A parallel input trace
942 * @param[in] packet The packet to be released back to libtrace
943 *
944 * The packet should not be used after calling this function.
945 *
946 * @note All packets should be free'd before a trace is destroyed.
947 */
948DLLEXPORT void trace_free_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
949
950
951DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);
952DLLEXPORT void parse_user_config(struct user_configuration* uc, char * str);
953DLLEXPORT void parse_user_config_file(struct user_configuration* uc, FILE *file);
954DLLEXPORT int libtrace_get_perpkt_count(libtrace_t* t);
955
956/**
957 * Sets a combiner function against the trace.
958 *
959 * @param trace The input trace
960 * @combiner The combiner to use
961 * @config config Configuration information. Dependent upon the combiner in use
962 *
963 * Sets a combiner against a trace, this should only be called on a
964 * non-started or paused trace.
965 */
966DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config);
967
968#define ZERO_USER_CONFIG(config) memset(&config, 0, sizeof(struct user_configuration));
969
970#endif // LIBTRACE_PARALLEL_H
Note: See TracBrowser for help on using the repository browser.