source: lib/libtrace_parallel.h @ 1101175

4.0.1-hotfixescachetimestampsdevelopdpdk-ndagetsilivelibtrace4ndag_formatpfringrc-4.0.1rc-4.0.2rc-4.0.3rc-4.0.4ringdecrementfixringperformanceringtimestampfixes
Last change on this file since 1101175 was 1101175, checked in by Shane Alcock <salcock@…>, 6 years ago

Polish up all the documentation in libtrace_parallel.h

Removed trace_get_local, trace_set_local, trace_get_tls and trace_set_tls.
These are all covered by parameters to the callback functions, so seem
redundant now.

Moved tv_to_usec into libtrace_int.h.

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