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