source: lib/libtrace_parallel.h @ c1205bd

cachetimestampsdevelopetsiliverc-4.0.4ringdecrementfixringperformance
Last change on this file since c1205bd was c1205bd, checked in by Shane Alcock <salcock@…>, 4 years ago

Add packet reference counting API

This API allows users to keep track of references to libtrace
packet structures that are not being released by the per packet
processing threads, e.g. those passed to the reporter or to
any user-created pthreads.

If you only have one reference to a packet at any given time,
you won't need this API. However, if you have multiple
concurrent references, this API will allow you to ensure that the
packet is correctly freed only once all references have been
finished with.

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