source: lib/libtrace_parallel.h @ c22a4bb

cachetimestampsdevelopetsiliverc-4.0.4ringdecrementfixringperformance
Last change on this file since c22a4bb was c22a4bb, checked in by Richard Sanger <rsanger@…>, 2 years ago

Return error if change perpkt threads on paused trace

We do not have code to change the number of perpkt threads, once
a trace had been started. However, you could set the perpkt threads
without an error being returned on a paused trace - but this never
got applied.

This clarifies docs and returns an error to match with the behaviour.

  • Property mode set to 100644
File size: 51.1 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 * Only valid on a new trace, that has not be started. Once started
734 * the number of threads cannot be changed without destroying the trace.
735 *
736 * @param[in] trace The parallel input trace
737 * @param[in] nb The number of threads to use. If set to 0, libtrace will
738 *    try to auto-detect how many threads it can use.
739 * @return 0 if successful otherwise -1
740 */
741DLLEXPORT int trace_set_perpkt_threads(libtrace_t *trace, int nb);
742
743/** Set the interval between tick messages in milliseconds.
744 *
745 * @param[in] trace The parallel input trace
746 * @param[in] millisec The interval in milliseconds. If 0 this is disabled
747 *     [default].
748 * @return 0 if successful, otherwise -1.
749 *
750 * When enabled, MESSAGE_TICK_INTERVAL will be sent every tick interval to all
751 * processing threads. This allows results to be published even in cases where
752 * new packets are not being directed to a processing thread, while still
753 * maintaining order etc.
754 *
755 * @see MESSAGE_TICK_INTERVAL, trace_set_tick_count()
756 */
757DLLEXPORT int trace_set_tick_interval(libtrace_t *trace, size_t millisec);
758
759/** Set the number of packets to be read between tick messages.
760 *
761 * @param[in] trace The parallel input trace
762 * @param[in] count The tick count.  If 0 this is disabled [default].
763 * @return 0 if successful otherwise -1
764 *
765 * When enabled, MESSAGE_TICK_COUNT will be sent to all processing threads
766 * after every 'count' packets have been read from the trace. This allows
767 * results to be published even in cases where new packets are not being
768 * directed to a processing thread, while still maintaining order etc.
769 *
770 * @see MESSAGE_TICK_COUNT, trace_set_tick_interval()
771 */
772DLLEXPORT int trace_set_tick_count(libtrace_t *trace, size_t count);
773
774/**
775 * Delays packets so they are played back in trace-time rather than as fast
776 * as possible (real-time).
777 *
778 * @param trace A parallel input trace
779 * @param tracetime If true packets are released with time spacing that matches
780 * the original trace. Otherwise packets are read as fast as possible.
781 * @return 0 if successful otherwise -1
782 */
783DLLEXPORT int trace_set_tracetime(libtrace_t *trace, bool tracetime);
784
785/** Sets the maximum size of the freelist used to store empty packets
786 * and their memory buffers.
787 *
788 * @param trace A parallel input trace
789 * @param size The number of empty packets to cache in memory. Set to the
790 * default, 0, to autoconfigure this value.
791 * @return 0 if successful otherwise -1
792 *
793 * Internally libtrace maintains a buffer of packet structures which
794 * includes a cache per thread and a shared main pool. This option configures
795 * the size of the main pool. If an application is not passing packets
796 * through to the reporter thread, i.e. the packet callback always returns
797 * the packet, then the main pool is not used.
798 *
799 * @note Setting this too low could cause performance issues or a deadlock. An
800 * unblockable warning will be printed.
801 *
802 * @see trace_set_thread_cache_size(), trace_set_fixed_count()
803 */
804DLLEXPORT int trace_set_cache_size(libtrace_t *trace, size_t size);
805
806/** This sets the maximum size of the freelist cache owned by each thread
807 * used to provide faster access to empty packets than the main shared pool.
808 *
809 * @param trace A parallel input trace
810 * @param size The number of empty packets to cache in memory. Set to the
811 * default, 0, to autoconfigure this value.
812 * @return 0 if successful otherwise -1
813 *
814 * @see trace_set_cache_size(), trace_set_fixed_count()
815 */
816DLLEXPORT int trace_set_thread_cache_size(libtrace_t *trace, size_t size);
817
818/** Determines whether a trace is allowed to create additional packets
819 *  beyond the cache size.
820 *
821 *  If set to true, libtrace will cease reading packets once the cache is used
822 *  up until the other threads release some packets back to the cache.
823 *
824 *  If set to false (the default), libtrace will use malloc and free to create
825 *  additional packets when the cache is exhausted. This will be slower than
826 *  getting a packet from the cache and will eventually run the machine out
827 *  of memory if packets are allocated faster than they are released.
828 *
829 * @param trace A parallel input trace
830 * @param fixed If true the total number of packets is limited, otherwise
831 * it is not. Defaults to false.
832 * @return 0 if successful otherwise -1
833 *
834 * @see trace_set_thread_cache_size(), trace_set_cache_size()
835 */
836DLLEXPORT int trace_set_fixed_count(libtrace_t *trace, bool fixed);
837
838/** The number of packets to batch together for processing internally
839 * by libtrace.
840 *
841 * @param trace A parallel input trace
842 * @param size The total number of packets to batch together. Set to the
843 * default, 0, to autoconfigure this value.
844 * @return 0 if successful otherwise -1
845 *
846 * Internally libtrace will attempt to read up to this number of packets from
847 * a format at a time. Typically, values of 10 will get good performance and
848 * increasing beyond that will should little difference.
849 *
850 * @note We still pass a single packet at a time to the packet callback
851 * function.
852 */
853DLLEXPORT int trace_set_burst_size(libtrace_t *trace, size_t size);
854
855/**
856 * Sets the maximum size of the buffer used between the single hasher thread
857 * and the packet processing thread.
858 *
859 * Setting this to less than recommend could cause a deadlock for an input
860 * trace that manages its own packets.
861 * A unblockable warning message will be printed to stderr in this case.
862 */
863DLLEXPORT int trace_set_hasher_queue_size(libtrace_t *trace, size_t size);
864
865/**
866 * Enables or disables polling of the hasher queue.
867 *
868 * If enabled, the processing threads will poll on the hasher queue, yielding
869 * if no data is available.
870 *
871 * If disabled, the processing threads will block on a condition variable
872 * if there is no data available from the hasher.
873 *
874 * @param trace A parallel input trace
875 * @param polling If true the hasher will poll waiting for data, otherwise
876 * it will use a condition variable. Defaults to false.
877 *
878 * We note polling is likely to waste many CPU cycles and could even decrease
879 * performance.
880 *
881 * @return 0 if successful otherwise -1
882 */
883DLLEXPORT int trace_set_hasher_polling(libtrace_t *trace, bool polling);
884
885/**
886 * Enables or disables polling of the reporter result queue.
887 *
888 * If enabled, the reporter thread will continuously poll for results.
889 * If disabled, the reporter will only check for results if it receives a
890 * MESSAGE_POST_REPORTER.
891 *
892 * @param trace A parallel input trace
893 * @param polling If true the reporter will poll waiting for data, otherwise
894 * it will wait for a MESSAGE_POST_REPORTER. Defaults to false.
895 * @return 0 if successful otherwise -1
896 *
897 * We note polling is likely to waste many CPU cycles and could even decrease
898 * performance.
899 *
900 * @note This setting could be ignored by some reporters.
901 */
902DLLEXPORT int trace_set_reporter_polling(libtrace_t *trace, bool polling);
903
904/**
905 * Set the number of results that are required in the result queue before
906 * a MESSAGE_POST_REPORTER is sent to the reporter so that it can read the
907 * results.
908 *
909 * Set this to 1 to ensure if you require your results to reach the reporter
910 * as soon as possible.
911 *
912 * @param trace A parallel input trace
913 * @param thold The threshold on the number of results to enqueue before
914 * notifying the reporter thread to read them.
915 * @return 0 if successful otherwise -1
916 *
917 *
918 * @note This setting is generally ignored if the reporter is polling. However,
919 * some combiner functions might ignore the polling behaviour and still
920 * require this to be set.
921 * @see trace_publish_result(), trace_post_reporter()
922 */
923DLLEXPORT int trace_set_reporter_thold(libtrace_t *trace, size_t thold);
924
925/**
926 * Enable or disable debug output for parallel libtrace.
927
928 * If enabled, libtrace will print a line to standard error for every
929 * state change observed by both the trace as a whole and by each thread.
930 *
931 * You really shouldn't need to enable this....
932 *
933 * @param trace A parallel input trace
934 * @param debug_state If true debug is printed. Defaults false.
935 * @return 0 if successful otherwise -1.
936 *
937 */
938DLLEXPORT int trace_set_debug_state(libtrace_t *trace, bool debug_state);
939
940/** Set the hasher function for a parallel trace.
941 *
942 * @param[in] trace The parallel trace to apply the hasher to
943 * @param[in] type The type of hashing to apply, see enum hasher_types
944 * @param[in] hasher A hasher function to use [Optional]
945 * @param[in] data Data passed to the hasher function [Optional]
946 *
947 * @return 0 if successful otherwise -1 on error
948 *
949 * The hasher function in a parallel trace can be used to control which
950 * processing thread will receive each packet.
951 *
952 * See hasher_types for a list of hashers supported natively by libtrace.
953 *
954 * HASHER_BALANCE is the default and will dispatch packets as fast as possible
955 * to all threads arbitrarily.
956 *
957 * HASHER_CUSTOM will force the libtrace to use the user defined function. In
958 * this case, the hasher parameter must be supplied.
959 *
960 * With other defined hasher types libtrace will try to push the hashing into
961 * the capture format wherever possible. In this case, the hasher parameter is
962 * optional; if a hasher is provided then it will be preferred over the
963 * libtrace implementation.
964 *
965 * @note When supplying a hasher function it should be thread-safe so it can
966 * be run in parallel by libtrace. Ideally this should rely upon no state, other
967 * than some form of seed value supplied in data.
968 */
969DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type,
970                               fn_hasher hasher, void *data);
971
972/// @}
973
974
975/** Types of results.
976 *
977 * Custom result types users should be defined as RESULT_USER(1000) or greater.
978 *
979 */
980enum result_types {
981        /**
982         * The result contains a pointer to a libtrace_packet_t. This
983         * packet should be freed using trace_free_packet() once the result
984         * is processed by the reporter thread.
985         *
986         * The key for a RESULT_PACKET is the packet order (see
987         * trace_get_packet_order() for more about ordering).
988         *
989         */
990        RESULT_PACKET,
991
992        /**
993         * The result is a tick timestamp. The key is an ERF timestamp.
994         */
995        RESULT_TICK_INTERVAL,
996
997        /**
998         * The result is a tick counter. The key is the sequence number of
999         * the tick, relative to the packets read so far.
1000         */
1001        RESULT_TICK_COUNT,
1002
1003        /**
1004         * Any user-defined result codes should be at or above this value.
1005         */
1006        RESULT_USER = 1000
1007
1008};
1009
1010/** Publish a result to the reporter thread (via the combiner)
1011 *
1012 * @param[in] libtrace The parallel input trace
1013 * @param[in] t The current per-packet thread
1014 * @param[in] key The key of the result (used for sorting by the combiner)
1015 * @param[in] value The value of the result
1016 * @param[in] type The type of result (see result_types)
1017 */
1018DLLEXPORT void trace_publish_result(libtrace_t *libtrace,
1019                                    libtrace_thread_t *t,
1020                                    uint64_t key,
1021                                    libtrace_generic_t value,
1022                                    int type);
1023
1024/** Check if a dedicated hasher thread is being used.
1025 *
1026 * @param[in] libtrace The parallel input trace
1027 * @return true if the trace has dedicated hasher thread otherwise false.
1028 *
1029 * This should only be called after the trace has been started with
1030 * trace_pstart().
1031 */
1032DLLEXPORT bool trace_has_dedicated_hasher(libtrace_t * libtrace);
1033
1034/** Checks if a trace is using a reporter thread.
1035 *
1036 * @param[in] libtrace The parallel input trace
1037 * @return True if the trace is using a reporter otherwise false
1038 */
1039DLLEXPORT bool trace_has_reporter(libtrace_t * libtrace);
1040
1041/** Post a message to the reporter thread requesting that it check for more
1042 * results.
1043 *
1044 * @param[in] The parallel input trace
1045 * @return -1 upon error indicating the message has not been sent otherwise a
1046 * backlog indicator (the number of messages the reporter has not yet read).
1047 */
1048DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);
1049
1050/** Check the number of messages waiting in a thread's message queue
1051 *
1052 * @param[in] libtrace The input trace
1053 * @param[in] t The thread to check; if NULL the current thread will be used.
1054 *
1055 * @return packets in the queue otherwise -1 upon error.
1056 *
1057 * @note For best performance it is recommended to supply the thread argument
1058 * even if it is the current thread.
1059 */
1060DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace,
1061                                                libtrace_thread_t *t);
1062
1063/** Read a message from a thread in a blocking fashion.
1064 *
1065 * @param[in] libtrace The input trace
1066 * @param[in] t The thread to check, if NULL the current thread will be used.
1067 * @param[out] message A pointer to a libtrace_message_t structure which will
1068 * be filled with the retrieved message.
1069 *
1070 * @return The number of messages remaining otherwise -1 upon error.
1071 *
1072 * @note For best performance it is recommended to supply the thread argument
1073 * even if it is the current thread.
1074 */
1075DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace,
1076                                          libtrace_thread_t *t,
1077                                          libtrace_message_t * message);
1078
1079/** Read a message from a thread in a non-blocking fashion.
1080 *
1081 * @param[in] libtrace The input trace
1082 * @param[in] t The thread to check, if NULL the current thread will be used.
1083 * @param[out] message A pointer to a libtrace_message_t structure which will
1084 * be filled with the retrieved message.
1085 *
1086 * @return 0 if successful otherwise -1 upon error or if no message were
1087 * available.
1088 *
1089 * @note For best performance it is recommended to supply the thread argument
1090 * even if it is the current thread.
1091 */
1092DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace,
1093                                              libtrace_thread_t *t,
1094                                              libtrace_message_t * message);
1095
1096/** Send a message to the reporter thread.
1097 *
1098 * @param[in] libtrace The parallel trace
1099 * @param[in] message The message to be sent. If the sender field is NULL,
1100 * libtrace will attempt to fill this in. It is faster to assign this if it is
1101 * known.
1102 *
1103 * @return -1 upon error indicating the message has not been sent. Otherwise,
1104 * will return the number of messages the reporter has not yet read.
1105 */
1106DLLEXPORT int trace_message_reporter(libtrace_t * libtrace,
1107                                     libtrace_message_t * message);
1108
1109/** Send a message to all processing threads.
1110 *
1111 * @param[in] libtrace The parallel trace
1112 * @param[in] message The message to be sent. If the sender field is NULL,
1113 * libtrace will attempt to fill this in. It is faster to assign this if it is
1114 * known.
1115 *
1116 * @return 0 if successful. Otherwise, a negative number is returned that
1117 * indicates the number of processing threads that the message was not sent
1118 * to (i.e. -1 means one thread could not be sent the message).
1119 */
1120DLLEXPORT int trace_message_perpkts(libtrace_t * libtrace,
1121                                    libtrace_message_t * message);
1122
1123/** Send a message to a specific thread.
1124 *
1125 * @param[in] libtrace The parallel trace
1126 * @param[in] t The thread to message
1127 * @param[in] message The message to be sent. If the sender field is NULL,
1128 * libtrace will attempt to fill this in. It is faster to assign this if it is
1129 * known.
1130 *
1131 * @return -1 upon error indicating the message has not been sent. Otherwise,
1132 * will return the number of messages the recipient has not yet read.
1133 */
1134DLLEXPORT int trace_message_thread(libtrace_t * libtrace,
1135                                   libtrace_thread_t *t,
1136                                   libtrace_message_t * message);
1137
1138/** Checks if a parallel trace has finished reading packets.
1139 *
1140 * @return true if the trace has finished reading packets (even if all results
1141 * have not yet been processed). Otherwise false.
1142 *
1143 * @note This returns true even if all results have not yet been processed by
1144 * the reporter thread.
1145 */
1146DLLEXPORT bool trace_has_finished(libtrace_t * libtrace);
1147
1148
1149/** Check if libtrace is directly reading from multiple queues
1150 * from within the capture format (such as a NICs hardware queues).
1151 *
1152 * A trace is considered to be parallel if the input format for the trace
1153 * allows the packets to be read in a natively parallel fashion, i.e. packets
1154 * can be read using multiple pipelines. If this function returns false, the
1155 * packets are instead being read from a single input source and then
1156 * distributed amongst the processing threads.
1157 *
1158 * Factors that may cause this function to return false despite the format
1159 * normally supporting native parallel reads include: the choice of hasher
1160 * function, the number of threads choosen (such as 1 or more than the trace
1161 * supports) or another error when trying to start the parallel format.
1162 *
1163 * If called before the trace is started, i.e. before trace_pstart(), this
1164 * function returns an indication whether the trace has the possiblity to
1165 * support native parallel reads. After trace_pstart() is called this should be
1166 * checked again to confirm that this has happened.
1167 *
1168 * @return true if the trace is parallel or false if the library is splitting
1169 * the trace into multiple threads.
1170 */
1171DLLEXPORT bool trace_is_parallel(libtrace_t * libtrace);
1172
1173/** Returns either the sequence number or erf timestamp of a packet.
1174 *
1175 * @param[in] packet
1176 * @return A 64bit sequence number or erf timestamp.
1177 *
1178 * The returned value can be used to compare the relative ordering of packets.
1179 * Formats that are not natively parallel will typically return a sequence
1180 * number. Natively parallel formats will return a timestamp.
1181 */
1182DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
1183
1184/** Returns the hash of a packet.
1185 *
1186 * @param[in] packet
1187 * @return A 64-bit hash
1188 *
1189 * @note This function will only work in situations where
1190 * a custom hash is being used. You can use trace_has_dedicated_hasher()
1191 * to check if this is the case.
1192 */
1193DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
1194
1195/** Sets the order of a packet.
1196 *
1197 * @param[in] packet
1198 * @param[in] order the new order of a packet
1199 *
1200 * @note Many combiners rely on this value, so please ensure that changing this
1201 * conforms to the expectations of the combiner.
1202 *
1203 * Generally speaking, you probably shouldn't be changing the order of packets!
1204 */
1205DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
1206
1207/** Sets the hash of a packet.
1208 *
1209 * @param[in] packet
1210 * @param[in] hash the new hash
1211 *
1212 * Once a packet reaches the processing thread, the libtrace library has
1213 * little use for this field and as such this can essentially be used for any
1214 * storage that the user requires.
1215 */
1216DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
1217
1218
1219/** Returns the first packet read by a processing thread since the source
1220 * trace was last started or restarted.
1221 *
1222 * @param[in] libtrace the parallel input trace.
1223 * @param[in] t Either a per packet thread or NULL to retrieve the earliest
1224 * packet across all per packet threads.
1225 * @param[out] packet A pointer to the requested packet. [Optional]
1226 * @param[out] tv The system time-stamp when the packet was received. [Optional]
1227 * @return 1 if we are confident this is the first packet. Otherwise 0 if this
1228 * is a best guess (this is only possible int the case t=NULL) in which case
1229 * we recommend trying again at a later time.
1230 * -1 is returned if an error occurs, such as when this function is supplied
1231 * an invalid thread.
1232 *
1233 * The packet and timeval returned by this function is shared by all threads
1234 * and remain valid until MESSAGE_PAUSING is received.
1235 */
1236DLLEXPORT int trace_get_first_packet(libtrace_t *libtrace,
1237                                     libtrace_thread_t *t,
1238                                     const libtrace_packet_t **packet,
1239                                     const struct timeval **tv);
1240
1241/** Makes a packet safe, preventing the packet from becoming invalid after a
1242 * pausing a trace.
1243 *
1244 * @param[in,out] pkt The packet to make safe
1245 *
1246 * This copies a packet in such a way that it will be able to survive a pause.
1247 * However this will not allow the packet to be used after the format is
1248 * destroyed.
1249 */
1250DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);
1251
1252/** Makes a result safe, preventing the result from becoming invalid after
1253 * pausing a trace.
1254 *
1255 * @param[in,out] res The result to make safe.
1256 *
1257 * This ensures the internal content of a result is safe to survive a pause.
1258 * Note that this is only an issue if the result contains a packet.
1259 * See libtrace_make_packet_safe().
1260 */
1261DLLEXPORT void libtrace_make_result_safe(libtrace_result_t *res);
1262
1263/** In a parallel trace, free a packet back to libtrace.
1264 *
1265 * @param[in] libtrace A parallel input trace
1266 * @param[in] packet The packet to be released back to libtrace
1267 *
1268 * The packet should not be used after calling this function.
1269 *
1270 * @note Don't use this inside a packet callback function -- just return
1271 * the packet instead, as this will be faster.
1272 *
1273 * @note All packets should be free'd before a trace is destroyed.
1274 */
1275DLLEXPORT void trace_free_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
1276
1277/** Increments the internal reference counter for a packet.
1278 * @param packet        The packet opaque pointer
1279 *
1280 * You may wish to use this function (and its decrementing counterpart)
1281 * in situations where you are retaining multiple references to a packet
1282 * outside of the core packet processing function. This will ensure that
1283 * the packet is not released until there are no more outstanding references
1284 * to the packet anywhere in your program.
1285 */
1286DLLEXPORT void trace_increment_packet_refcount(libtrace_packet_t *packet);
1287
1288/** Decrements the internal reference counter for a packet.
1289 * @param packet        The packet opaque pointer
1290 *
1291 * If the reference counter goes below one, trace_fin_packet() will be
1292 * called on the packet.
1293 *
1294 * You may wish to use this function (and its incrementing counterpart)
1295 * in situations where you are retaining multiple references to a packet
1296 * outside of the core packet processing function. This will ensure that
1297 * the packet is not released until there are no more outstanding references
1298 * to the packet anywhere in your program.
1299 */
1300DLLEXPORT void trace_decrement_packet_refcount(libtrace_packet_t *packet);
1301
1302
1303/** Provides some basic information about a trace based on its input format.
1304 *
1305 * @param libtrace  The trace that is being inquired about.
1306 * @return a libtrace_info_t structure that contains information about the
1307 * trace format, i.e. is it live or not, how many threads it supports.
1308 *
1309 * See trace_is_parallel(), trace_get_perpkt_threads().
1310 */
1311DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);
1312
1313/** Sets the configuration of a trace based upon a comma separated list of
1314 * key value pairs.
1315 *
1316 * @param trace A parallel trace which is not running or destroyed.
1317 * @param str A comma separated list of key=value pairs:
1318 *   e.g. \em "burst_size=20,perpkt_threads=2,fixed_count=true"
1319 * @return 0 if successful otherwise -1. If bad options are passed we will
1320 * print the error to stderr but still return successful.
1321 *
1322 * List of keys:
1323 * * \b cache_size,\b cs see trace_set_cache_size() [size_t]
1324 * * \b thread_cache_size,\b tcs see trace_set_thread_cache_size() [size_t]
1325 * * \b fixed_count,\b fc see trace_set_fixed_count() [bool]
1326 * * \b burst_size,\b bs see trace_set_burst_size() [size_t]
1327 * * \b tick_interval,\b ti see trace_set_tick_interval() [size_t]
1328 * * \b tick_count,\b tc see trace_set_tick_count() [size_t]
1329 * * \b perpkt_threads,\b pt see trace_set_perpkt_threads() [XXX TBA XXX]
1330 * * \b hasher_queue_size,\b hqs see trace_set_hasher_queue_size() [size_t]
1331 * * \b hasher_polling,\b hp see trace_set_hasher_polling() [bool]
1332 * * \b reporter_polling,\b rp see trace_set_reporter_polling() [bool]
1333 * * \b reporter_thold,\b rt see trace_set_reporter_thold() [size_t]
1334 * * \b debug_state,\b ds see trace_set_debug_state() [bool]
1335 *
1336 * Booleans can be set as 0/1 or false/true.
1337 *
1338 * @note a environment variable interface is provided by default to users via
1339 * LIBTRACE_CONF, see Parallel Configuration for more information.
1340 *
1341 * @note This interface is provided to allow a user to quickly configure an
1342 * application using a single API call. A nicer programatic method for
1343 * configuration would be to use the appropriate trace_set_*() function for
1344 * each option.
1345 */
1346DLLEXPORT int trace_set_configuration(libtrace_t *trace, const char * str);
1347
1348/** Sets configuration from a file. This reads every line from the file and
1349 * interprets each line with trace_set_configuration().
1350 *
1351 * @param trace A parallel trace which is not running or destroyed
1352 * @param file A file pointer which we read each line from
1353 * @return 0 if successful otherwise -1. If bad options are passed we will
1354 * print the error to stderr but still return successful.
1355 *
1356 * @note We do not close the file pointer upon completion
1357 */
1358DLLEXPORT int trace_set_configuration_file(libtrace_t *trace, FILE *file);
1359
1360/** Returns the number of processing threads that have been created for
1361 * a given trace.
1362 *
1363 * @param t A parallel trace.
1364 * @return The number of processing threads owned by that trace.
1365 */
1366DLLEXPORT int trace_get_perpkt_threads(libtrace_t* t); 
1367
1368/** Returns the internal unique ID for a packet processing thread.
1369 *
1370 * @param thread The thread being queried.
1371 * @return The ID number of the thread or -1 if the thread is not a processing
1372 * thread or is otherwise invalid.
1373 */
1374DLLEXPORT int trace_get_perpkt_thread_id(libtrace_thread_t *thread);
1375
1376/**
1377 * Sets a combiner function for an input trace.
1378 *
1379 * @param trace The input trace
1380 * @param combiner The combiner to use
1381 * @param config Configuration information. Dependent upon the combiner.
1382 *
1383 * Sets a combiner against a trace, this should only be called on a
1384 * non-started or paused trace.  By default, combiner_unordered
1385 * will be used if this function is not called before starting the trace.
1386 */
1387DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config);
1388
1389/**
1390 * Takes unordered (or ordered) input and produces unordered output.
1391 * This is the fastest combiner but makes no attempt to ensure you get
1392 * results in a particular order.
1393 */
1394extern const libtrace_combine_t combiner_unordered;
1395
1396/**
1397 * Takes ordered input and produces ordered output. Each processing thread
1398 * must produce results that are strictly ordered for this combiner to
1399 * work correctly.
1400 *
1401 * For example, a thread may publish a series of results with the keys
1402 * (in order) of 1,4,10,11,15,20 as the keys are all in order. It must not
1403 * publish the results in the order 1,4,11,10,15,20 -- 10 comes after 11,
1404 * which is out-of-order.
1405 */
1406extern const libtrace_combine_t combiner_ordered;
1407
1408/**
1409 * Like classic Google Map/Reduce, the results are sorted
1410 * in ascending order based on their key. The sorting is only done when the
1411 * trace finishes and all results are stored internally until then.
1412 *
1413 * This only works with a very limited number of results, otherwise
1414 * libtrace will just run out of memory and crash. You should always
1415 * use combiner_ordered if you can.
1416 */
1417extern const libtrace_combine_t combiner_sorted;
1418
1419#ifdef __cplusplus
1420}
1421#endif
1422
1423#endif // LIBTRACE_PARALLEL_H
Note: See TracBrowser for help on using the repository browser.