Changeset 1101175
- Timestamp:
- 09/16/15 17:23:46 (6 years ago)
- Branches:
- 4.0.1-hotfixes, cachetimestamps, develop, dpdk-ndag, etsilive, libtrace4, master, ndag_format, pfring, rc-4.0.1, rc-4.0.2, rc-4.0.3, rc-4.0.4, ringdecrementfix, ringperformance, ringtimestampfixes
- Children:
- c42a2d6
- Parents:
- 8decff7
- Files:
-
- 4 edited
Legend:
- Unmodified
- Added
- Removed
-
lib/libtrace_int.h
rf625817 r1101175 1046 1046 void register_format(struct libtrace_format_t *format); 1047 1047 1048 /** Converts a timeval into a timestamp in microseconds since the epoch. 1049 * 1050 * @param tv The timeval to be converted. 1051 * @return A 64 bit timestamp in microseconds since the epoch. 1052 */ 1053 uint64_t tv_to_usec(const struct timeval *tv); 1054 1048 1055 /** Converts a PCAP DLT into a libtrace link type. 1049 1056 * -
lib/libtrace_parallel.h
r5478d3d r1101175 2 2 * This file is part of libtrace 3 3 * 4 * Copyright (c) 2007 ,2008,2009,2010The University of Waikato, Hamilton,4 * Copyright (c) 2007-2015 The University of Waikato, Hamilton, 5 5 * New Zealand. 6 6 * 7 7 * Authors: Richard Sanger 8 * Shane Alcock 8 9 * 9 10 * All rights reserved. … … 37 38 * @author Richard Sanger 38 39 * 39 * @version $Id$ 40 * 41 * The parallel libtrace framework is a replacement to the libtrace framework. XXX TODO MAKE MORE DOCS HERE. 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. 42 46 */ 43 47 … … 56 60 /** 57 61 * A collection of types for convenience used in place of a 58 * simple void* to allow a any type of data to be stored. 62 * simple void* to allow any type of data to be stored and passed 63 * around easily. 59 64 * 60 65 * This is expected to be 8 bytes in length. … … 104 109 ct_assert(sizeof(libtrace_generic_t) == 8); 105 110 111 /** 112 * Structure describing a message that can be sent to a libtrace thread. 113 */ 106 114 typedef struct libtrace_message_t { 107 int code; /**< The message code seeenum libtrace_messages */115 int code; /**< The message code, as defined in enum libtrace_messages */ 108 116 libtrace_generic_t data; /**< Additional data related to the message */ 109 117 libtrace_thread_t *sender; /**< The thread that sent the message */ … … 112 120 /** Structure holding information about a result */ 113 121 struct libtrace_result_t { 114 uint64_t key; 115 libtrace_generic_t value; 116 int type; 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 */ 117 125 }; 118 126 … … 120 128 * All libtrace messages are defined and documented here. 121 129 * 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 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 127 133 * numbers greater than MESSAGE_USER (1000). 128 134 * … … 130 136 */ 131 137 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 138 /** A libtrace packet is ready, this will trigger the packet callback 139 * for the processing threads. 139 140 */ 140 141 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 142 143 /** A libtrace result is ready, this will trigger the result callback 144 * for the reporter thread. 147 145 */ 148 146 MESSAGE_RESULT, 149 147 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. 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. 162 152 */ 163 153 MESSAGE_STARTING, 164 154 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 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. 174 158 */ 175 159 MESSAGE_STOPPING, 176 160 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 */ 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 */ 188 168 MESSAGE_RESUMING, 189 169 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 */ 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 */ 201 178 MESSAGE_PAUSING, 202 179 203 /** An internal message do not use this */ 180 /** An internal message for forcing another thread to pause. Do not 181 * use this in user-defined callbacks! 182 */ 204 183 MESSAGE_DO_PAUSE, 205 /** An internal message do not use this */ 184 185 /** An internal message for forcing another thread to stop. Do not 186 * use this in user-defined callbacks! 187 */ 206 188 MESSAGE_DO_STOP, 207 189 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 */ 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 */ 221 202 MESSAGE_FIRST_PACKET, 222 203 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 * 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. 233 209 */ 234 210 MESSAGE_POST_REPORTER, … … 245 221 * @param sender should be ignored 246 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 */ 247 233 MESSAGE_TICK_INTERVAL, 248 234 … … 256 242 * @param sender Set to the current per-packet thread 257 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 */ 258 253 MESSAGE_TICK_COUNT, 259 254 260 /** For specific user defined messages use codes of MESSAGE_USER or above. */ 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 */ 261 259 MESSAGE_USER = 1000 262 260 }; 263 261 264 /** The hasher types available to libtrace application.265 * These can be selected using trace_set_hasher().262 /** The hasher types that are available to libtrace applications. 263 * These can be selected using trace_set_hasher(). 266 264 */ 267 265 enum hasher_types { 268 /** Balance load across per-packet threads as best as possible, this is269 * basically to say I do not care about where packets are sent. This270 * might still might be implemented using a hash or round robin etc.271 * depending on theformat and libtrace configuration.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. 272 270 */ 273 271 HASHER_BALANCE, 274 272 275 /** Use a hash which is bi-directional for TCP and UDP flows, that is276 * packets with the same 5-tuple are sent to the same p er-packetthread.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. 277 275 * All non TCP/UDP packets will be sent to the same thread. 278 276 * 279 277 * @note it is possible that UDP packets may not be spread across 280 * p er-packetthreads, depending upon the format support. In this case281 * they would be directed to a single per-packetthread.278 * processing threads, depending upon the format support. In this case 279 * they would be directed to a single thread. 282 280 */ 283 281 HASHER_BIDIRECTIONAL, 284 282 285 /** Use a hash which is uni-directional across TCP and UDP flows, this286 * means the opposing directions of the same 5-tuple mightend up on287 * different p er-packetthreads.288 * Otherwise this is identical to HASHER_BIDIRECTIONAL 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. 289 287 */ 290 288 HASHER_UNIDIRECTIONAL, 291 289 292 290 /** 293 * Always use the user supplied hasher, this disables native294 * support in and is likely significantly slower. 291 * This value indicates that the hasher is a custom user-defined 292 * function. 295 293 */ 296 294 HASHER_CUSTOM … … 307 305 /** 308 306 * 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. 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. 311 310 */ 312 311 int max_threads; … … 317 316 } libtrace_info_t; 318 317 319 /**320 * The methods we use to combine multiple outputs into a single output321 * 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 can325 * have functions rewritten, and in fact should if possible.326 */327 318 typedef 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 */ 328 325 struct libtrace_combine { 329 326 … … 339 336 340 337 /** 341 * Called when the trace ends, clean up any memory here342 * from libtrace_t * init.338 * Called when the trace ends, clean up any memory allocated 339 * by the initialise function. 343 340 */ 344 341 void (*destroy)(libtrace_t *, libtrace_combine_t *); 345 342 346 343 /** 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. 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. 351 355 * 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. 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. 359 366 * 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 367 * There may be no results, in which case this function should 371 368 * just return. 372 369 * 373 370 * Libtrace state: 374 * Called from reporter thread375 * No p erpkt threads will be running, i.e. publish will not be376 *called again.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. 377 374 * 378 * If publish is NULL, this probably should be NULL a lso otherwise379 * it will not be called.375 * If publish is NULL, this probably should be NULL as it will not be 376 * called in that case. 380 377 */ 381 378 void (*read_final)(libtrace_t *, libtrace_combine_t *); 382 379 383 380 /** 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. 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. 387 385 */ 388 386 void (*pause)(libtrace_t *, libtrace_combine_t *); … … 393 391 void *queues; 394 392 393 /** The last counter tick that we saw, so we can avoid duplicating 394 * any ticks that are published. 395 */ 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 */ 396 401 uint64_t last_ts_tick; 397 402 … … 404 409 405 410 /** 406 * The definition for the main function that the user supplies to process407 * 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, containing414 * 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 back417 * 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 the420 * 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 process430 * 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, containing436 * 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 the440 * 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 411 * The definition for a hasher function, allowing matching packets to be 449 * directed to the same per packet thread for processing.412 * directed to the correct thread for processing. 450 413 * 451 414 * @param packet The packet to be hashed. 452 415 * @param data A void pointer which can contain additional information, 453 * such as configuration of the hasher function. 416 * such as configuration for the hasher function. 417 * 418 * @return The id of the thread that should receive this packet. 454 419 */ 455 420 typedef uint64_t (*fn_hasher)(const libtrace_packet_t* packet, void *data); … … 459 424 * 460 425 * @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_packet_cbs A set of user supplied functions to be called in response to events being observed by the per_pkt threads. 463 * @param reporter_cbs A set of user supplied functions to be called in response to events / results being seen by the reporter thread. 464 * Optional if NULL the reporter thread will not be started. 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. 465 433 * @return 0 on success, otherwise -1 to indicate an error has occurred 466 434 * … … 477 445 478 446 /** 479 * 480 * @param libtrace The parallel trace 481 * @param t The thread that is running 482 * @param global The global storage 483 * @return The returned value is stored against the threads tls. 484 * This is typically passed as tls argument to other messages. 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. 485 457 */ 486 458 typedef void* (*fn_cb_starting)(libtrace_t *libtrace, … … 489 461 490 462 /** 491 * @param libtrace The parallel trace 492 * @param t The thread that is running 493 * @param global The global storage 494 * @param tls The thread local storage 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. 495 470 */ 496 471 typedef void (*fn_cb_dataless)(libtrace_t *libtrace, … … 500 475 501 476 /** 502 * @param libtrace The parallel trace 503 * @param t The thread that is running 504 * @param global The global storage 505 * @param tls The thread local storage 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. 506 483 */ 507 484 typedef void (*fn_cb_first_packet)(libtrace_t *libtrace, … … 512 489 513 490 /** 514 * @param libtrace The parallel trace 515 * @param t The thread that is running 516 * @param global The global storage 517 * @param tls The thread local storage 518 * @param uint64_t Either the timestamp or packet count depending on message type 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. 519 499 */ 520 500 typedef void (*fn_cb_tick)(libtrace_t *libtrace, … … 525 505 526 506 /** 527 * @param libtrace The parallel trace 528 * @param t The thread 529 * @param packet The packet associated with the message 530 * @param global The global storage 531 * @param tls The thread local storage 532 * 533 * @return optionally a packet which is handed back to the library, 534 * typically this is the packet supplied. Otherwise NULL. 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. 535 518 */ 536 519 typedef libtrace_packet_t* (*fn_cb_packet)(libtrace_t *libtrace, … … 544 527 * reporter thread. 545 528 * 546 * @param libtrace The parallel trace 547 * @param sender The thread that generated this result 548 * @param global The global storage 549 * @param tls The thread local storage 550 * @param result The result associated with the message 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. 551 534 * 552 535 */ … … 559 542 * any messages with a type >= MESSAGE_USER. 560 543 * 561 * @param libtrace The parallel trace 562 * @param t The thread 563 * @param global The global storage 564 * @param tls The thread local storage 565 * @param mesg The code identifying the message type 566 * @param data The data associated with the message 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. 567 550 * 568 551 */ … … 570 553 void *global, void *tls, int mesg, libtrace_generic_t data); 571 554 572 /** Registers a built-in message with a handler. 573 * Note we do not include the sending thread as an argument to the reporter. 574 * If set to NULL, the message will be sent to default perpkt handler. 575 * 576 * @param libtrace The input trace to start 577 * @param handler the handler to be called when the message is received 578 * @return 0 if successful otherwise -1. 579 */ 580 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 */ 581 563 DLLEXPORT int trace_set_starting_cb(libtrace_callback_set_t *cbset, 582 564 fn_cb_starting handler); 583 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 */ 584 573 DLLEXPORT int trace_set_stopping_cb(libtrace_callback_set_t *cbset, 585 574 fn_cb_dataless handler); 586 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 */ 587 583 DLLEXPORT int trace_set_resuming_cb(libtrace_callback_set_t *cbset, 588 584 fn_cb_dataless handler); 589 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 */ 590 593 DLLEXPORT int trace_set_pausing_cb(libtrace_callback_set_t *cbset, 591 594 fn_cb_dataless handler); 592 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 */ 593 603 DLLEXPORT int trace_set_packet_cb(libtrace_callback_set_t *cbset, 594 604 fn_cb_packet handler); 595 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 */ 596 613 DLLEXPORT int trace_set_first_packet_cb(libtrace_callback_set_t *cbset, 597 614 fn_cb_first_packet handler); 598 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 */ 599 623 DLLEXPORT int trace_set_result_cb(libtrace_callback_set_t *cbset, 600 624 fn_cb_result handler); 601 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 */ 602 633 DLLEXPORT int trace_set_tick_count_cb(libtrace_callback_set_t *cbset, 603 634 fn_cb_tick handler); 604 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 */ 605 643 DLLEXPORT int trace_set_tick_interval_cb(libtrace_callback_set_t *cbset, 606 644 fn_cb_tick handler); 607 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 */ 608 653 DLLEXPORT int trace_set_user_message_cb(libtrace_callback_set_t *cbset, 609 654 fn_cb_usermessage handler); … … 616 661 DLLEXPORT libtrace_callback_set_t *trace_create_callback_set(void); 617 662 618 /** Destroys a callback set, freeing up an resources it was using.663 /** Destroys a callback set, freeing up any resources it was using. 619 664 * 620 665 * @param cbset The callback set to be destroyed. … … 638 683 * @return 0 on success, otherwise -1 to indicate an error has occurred 639 684 * 640 * This should only be called by the main thread. 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. 641 688 * 642 689 */ … … 652 699 */ 653 700 DLLEXPORT void trace_join(libtrace_t * trace); 654 655 /**656 * @name User Data Storage657 *658 * These method provide a way for users to store data against a trace or659 * a thread.660 *661 * Alternatively one could use global variables and thread local662 * storage (__thread), respectively, which in many cases could be simpler.663 *664 * @note We do not lock on reads, instead we rely on the665 * processor making any writes appear atomically.666 *667 * @{668 */669 670 /** Returns the data stored against a trace.671 *672 * @param trace The parallel trace673 * @return The stored data.674 */675 DLLEXPORT void * trace_get_local(libtrace_t *trace);676 677 /** Store data against a trace so that all threads can access it678 * using trace_get_global().679 *680 * @param trace The parallel trace.681 * @param data The new value to save against the trace682 * @return The previously stored value683 *684 * The update to the previous value is atomic and thread-safe.685 *686 * @note Although this is thread-safe another thread may still be687 * using the previous data, as such further synchronisation is needed688 * if a thread wanted to free the existing value.689 */690 DLLEXPORT void * trace_set_local(libtrace_t *trace, void * data);691 692 /** Returns the users data stored against a thread.693 *694 * @param thread The thread695 * @return The stored data696 */697 DLLEXPORT void * trace_get_tls(libtrace_thread_t *thread);698 699 /** Store data against a thread.700 *701 * @param thread The thread702 * @param data The new value to save against the thread703 * @return The previously stored value704 *705 * This function is not thread-safe and is intended only to be706 * called on the currently running thread.707 */708 DLLEXPORT void * trace_set_tls(libtrace_thread_t *thread, void * data);709 710 /// @}711 701 712 702 … … 729 719 * 730 720 * E.g. 731 * - int:eth0 would match LIBTRACE_CONF, LIBTRACE_CONF_INT, LIBTRACE_CONF_INT_ETH0 732 * - dag:/dev/dag0,0 would match LIBTRACE_CONF, LIBTRACE_CONF_DAG, LIBTRACE_CONF_DAG__DEV_DAG0_0 733 * - test.erf would match LIBTRACE_CONF, LIBTRACE_CONF_ERF, LIBTRACE_CONF_ERF_TEST_ERF 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 734 727 * 735 728 * @note All environment variables names MUST only contain … … 743 736 * 744 737 * @param[in] trace The parallel input trace 745 * @param[in] nb The number of threads to use. If 0 use default. 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. 746 740 * @return 0 if successful otherwise -1 747 741 */ … … 751 745 * 752 746 * @param[in] trace The parallel input trace 753 * @param[in] millisec The interval in milliseconds. If 0 this is disabled [default]. 754 * @return 0 if successful otherwise -1 755 * 756 * When a underlying parallel live trace is used MESSAGE_TICK_INTERVAL is sent 757 * every tick interval to all per-packet threads to ensure data is received. 758 * This allows results to be printed even in cases flows are not being directed 759 * to a per-packet thread, while still maintaining order etc. 760 * 761 * @note Tick count is preferred over tick interval and will be used rather 762 * than tick interval if possible. 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 * 763 756 * @see MESSAGE_TICK_INTERVAL, trace_set_tick_count() 764 757 */ 765 758 DLLEXPORT int trace_set_tick_interval(libtrace_t *trace, size_t millisec); 766 759 767 /** Set the countbetween tick messages.760 /** Set the number of packets to be read between tick messages. 768 761 * 769 762 * @param[in] trace The parallel input trace … … 771 764 * @return 0 if successful otherwise -1 772 765 * 773 * When an underlying trace is accessed internally by libtrace in a 774 * single-threaded manner MESSAGE_TICK_COUNT is sent to all per-packet threads 775 * after every count packets have been seen in the trace. This allows results 776 * to be printed even in cases flows are not being directed to a per-packet 777 * thread, while still maintaining order etc. 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. 778 770 * 779 771 * @see MESSAGE_TICK_COUNT, trace_set_tick_interval() … … 786 778 * 787 779 * @param trace A parallel input trace 788 * @param tracetime If true packets are released with time intervals matching780 * @param tracetime If true packets are released with time spacing that matches 789 781 * the original trace. Otherwise packets are read as fast as possible. 790 782 * @return 0 if successful otherwise -1 … … 792 784 DLLEXPORT int trace_set_tracetime(libtrace_t *trace, bool tracetime); 793 785 794 /** This sets the maximum size of the freelist used to store empty packets786 /** Sets the maximum size of the freelist used to store empty packets 795 787 * and their memory buffers. 796 788 * … … 800 792 * @return 0 if successful otherwise -1 801 793 * 802 * Internally libtrace maintains a buffer of packet structures , this buffer803 * includes a cache per thread and a shared main pool. This configures794 * Internally libtrace maintains a buffer of packet structures which 795 * includes a cache per thread and a shared main pool. This option configures 804 796 * the size of the main pool. If an application is not passing packets 805 * through to the re ducer step --- that is to say returns packets from806 * the p erpkt function --- this buffer will not need to beused.797 * through to the reporter thread, i.e. the packet callback always returns 798 * the packet, then the main pool is not used. 807 799 * 808 800 * @note Setting this too low could cause performance issues or a deadlock. An … … 813 805 DLLEXPORT int trace_set_cache_size(libtrace_t *trace, size_t size); 814 806 815 /** This sets the maximum size of the freelist thread cache's used to provide816 * faster access than the main shared pool.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. 817 809 * 818 810 * @param trace A parallel input trace … … 825 817 DLLEXPORT int trace_set_thread_cache_size(libtrace_t *trace, size_t size); 826 818 827 /** If true the total number of packets that can be created by a trace is limited 828 * to that set by trace_set_cache_size(), otherwise once exceeded malloc 829 * and free will be used to create and free packets, this will be slower than 830 * using the freelist and could run a machine out of memory. 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. 831 829 * 832 830 * @param trace A parallel input trace … … 848 846 * 849 847 * Internally libtrace will attempt to read up to this number of packets from 850 * a format typically values of 10 will get good performance and increasing 851 * beyond that will should little difference. 852 * 853 * @note We still pass a single packet at a time to the perpkt function 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. 854 853 */ 855 854 DLLEXPORT int trace_set_burst_size(libtrace_t *trace, size_t size); 856 855 857 856 /** 858 * See diagrams, this sets the maximum size of buffers used between 859 * the single hasher thread and the buffer. 860 * NOTE setting this to less than recommend could cause deadlock a 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 861 * trace that manages its own packets. 862 862 * A unblockable warning message will be printed to stderr in this case. 863 863 */ 864 /** The number of packets that can queue per thread from hasher thread */865 864 DLLEXPORT int trace_set_hasher_queue_size(libtrace_t *trace, size_t size); 866 865 867 /** If true use a polling hasher queue, that means that we will spin/or yield 868 * when data is not available rather than blocking on a condition. 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. 869 874 * 870 875 * @param trace A parallel input trace 871 876 * @param polling If true the hasher will poll waiting for data, otherwise 872 * it is not. Defaults to false.873 * 874 * We note thisis likely to waste many CPU cycles and could even decrease877 * 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 875 880 * performance. 876 881 * … … 879 884 DLLEXPORT int trace_set_hasher_polling(libtrace_t *trace, bool polling); 880 885 881 /** If true the reporter thread will continuously poll waiting for results 882 * if false they are only checked when a message is received, this message 883 * is controlled by reporter_thold. 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. 884 892 * 885 893 * @param trace A parallel input trace 886 894 * @param polling If true the reporter will poll waiting for data, otherwise 887 * it is not. Defaults to false.895 * it will wait for a MESSAGE_POST_REPORTER. Defaults to false. 888 896 * @return 0 if successful otherwise -1 889 897 * 890 * We note thisis likely to waste many CPU cycles and could even decrease898 * We note polling is likely to waste many CPU cycles and could even decrease 891 899 * performance. 892 900 * … … 895 903 DLLEXPORT int trace_set_reporter_polling(libtrace_t *trace, bool polling); 896 904 897 /** Set the perpkt thread result queue size before triggering the reporter 898 * to read results. 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. 899 912 * 900 913 * @param trace A parallel input trace … … 904 917 * 905 918 * 906 * @note This setting is generally ignored if t race_set_reporter_polling() is907 * s et however some combiner functions might ignore trace_set_reporter_polling()908 * and stillrequire this to be set.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. 909 922 * @see trace_publish_result(), trace_post_reporter() 910 923 */ 911 924 DLLEXPORT int trace_set_reporter_thold(libtrace_t *trace, size_t thold); 912 925 913 /** Prints a line to standard error for every state change 914 * for both the trace as a whole and for each thread. 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.... 915 933 * 916 934 * @param trace A parallel input trace … … 931 949 * 932 950 * The hasher function in a parallel trace can be used to control which 933 * per-packet thread a packets is processed by. 951 * processing thread will receive each packet. 952 * 953 * See hasher_types for a list of hashers supported natively by libtrace. 934 954 * 935 955 * HASHER_BALANCE is the default and will dispatch packets as fast as possible 936 * to all threads arbitrarily. As such when called the hasher and937 * data parameters must be set to NULL.938 * 939 * HASHER_CUSTOM will force the libtrace to use the user defined function. As940 * such the hasher parameter must be supplied.941 * 942 * With other defined hasher types we will try to push the hashing into the format943 * by default. In this case the hasher parameter is optional and will be944 * preferred over the default supplied by libtrace.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. 945 965 * 946 966 * @note When supplying a hasher function it should be thread-safe so it can … … 955 975 956 976 /** Types of results. 957 * Some result types require special handling by combiners958 * as such making use of built-in types is important.959 977 * 960 978 * Custom result types users should be defined as RESULT_USER(1000) or greater. … … 963 981 enum result_types { 964 982 /** 965 * The result is a packet in some circumstances special handling needs 966 * to be performed. As such packets should always be published as so. 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). 967 989 * 968 * @param key (Typically) The packets order, see trace_packet_get_order()969 990 */ 970 991 RESULT_PACKET, 971 992 972 /** The result is a tick message 973 * 974 * @param key The erf time-stamp of the tick 993 /** 994 * The result is a tick timestamp. The key is an ERF timestamp. 975 995 */ 976 996 RESULT_TICK_INTERVAL, 977 997 978 /** The result is a tick message979 * 980 * @param key The sequence number of the tick message 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. 981 1001 */ 982 1002 RESULT_TICK_COUNT, 983 1003 984 /** Any user specific codes should be above this.985 * 1004 /** 1005 * Any user-defined result codes should be at or above this value. 986 1006 */ 987 1007 RESULT_USER = 1000 … … 989 1009 }; 990 1010 991 /** Publish a result for to the combiner destined for the reporter thread1011 /** Publish a result to the reporter thread (via the combiner) 992 1012 * 993 1013 * @param[in] libtrace The parallel input trace … … 995 1015 * @param[in] key The key of the result (used for sorting by the combiner) 996 1016 * @param[in] value The value of the result 997 * @param[in] type The type of result see the documentation for the result_types enum1017 * @param[in] type The type of result (see result_types) 998 1018 */ 999 1019 DLLEXPORT void trace_publish_result(libtrace_t *libtrace, … … 1006 1026 * 1007 1027 * @param[in] libtrace The parallel input trace 1008 * @return True if the trace has dedicated hasher thread otherwise false. 1009 * 1010 * This is valid once the trace is running after calling trace_pstart(). 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(). 1011 1032 */ 1012 1033 DLLEXPORT bool trace_has_dedicated_hasher(libtrace_t * libtrace); 1013 1034 1014 /** Checks if a trace is using a reporter 1035 /** Checks if a trace is using a reporter thread. 1015 1036 * 1016 1037 * @param[in] libtrace The parallel input trace … … 1019 1040 DLLEXPORT bool trace_has_reporter(libtrace_t * libtrace); 1020 1041 1021 /** Post a message to the reporter thread requesting it tocheck for more1042 /** Post a message to the reporter thread requesting that it check for more 1022 1043 * results. 1023 1044 * … … 1028 1049 DLLEXPORT int trace_post_reporter(libtrace_t *libtrace); 1029 1050 1030 /** Check the number of messages waiting in a queue1051 /** Check the number of messages waiting in a thread's message queue 1031 1052 * 1032 1053 * @param[in] libtrace The input trace 1033 * @param[in] t The thread to check , if NULL the current thread will be used [Optional]1054 * @param[in] t The thread to check; if NULL the current thread will be used. 1034 1055 * 1035 1056 * @return packets in the queue otherwise -1 upon error. … … 1041 1062 libtrace_thread_t *t); 1042 1063 1043 /** Read a message from a thread in a blocking fashion 1064 /** Read a message from a thread in a blocking fashion. 1044 1065 * 1045 1066 * @param[in] libtrace The input trace 1046 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]1047 * @param[out] message A pointer to libtrace_message_t structure which will be1048 * filled with the retrieved message.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. 1049 1070 * 1050 1071 * @return The number of messages remaining otherwise -1 upon error. 1051 *1052 1072 * 1053 1073 * @note For best performance it is recommended to supply the thread argument … … 1058 1078 libtrace_message_t * message); 1059 1079 1060 /** Read a message from a thread in a blocking fashion1080 /** Read a message from a thread in a non-blocking fashion. 1061 1081 * 1062 1082 * @param[in] libtrace The input trace 1063 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]1064 * @param[out] message A pointer to libtrace_message_t structure which will be1065 * filled with the retrieved message.1066 * 1067 * @return 0 if successful otherwise -1 upon error or if no packets were available.1068 * 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. 1069 1089 * 1070 1090 * @note For best performance it is recommended to supply the thread argument … … 1075 1095 libtrace_message_t * message); 1076 1096 1077 /** Send a message to the reporter thread 1097 /** Send a message to the reporter thread. 1078 1098 * 1079 1099 * @param[in] libtrace The parallel trace 1080 * @param[in] message The message to be sent, if sender is NULL libtrace will 1081 * attempt to fill this in. It is faster to assign this if it is known. 1082 * 1083 * @return -1 upon error indicating the message has not been sent otherwise a 1084 * backlog indicator (the number of messages the reporter has not yet read). 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. 1085 1106 */ 1086 1107 DLLEXPORT int trace_message_reporter(libtrace_t * libtrace, 1087 1108 libtrace_message_t * message); 1088 1109 1089 /** Send a message to all p er-packet threads1110 /** Send a message to all processing threads. 1090 1111 * 1091 1112 * @param[in] libtrace The parallel trace 1092 * @param[in] message The message to be sent, if sender is NULL libtrace will 1093 * attempt to fill this in. It is faster to assign this if it is known. 1094 * 1095 * @return 0 if successful otherwise a negative number indicating the number 1096 * of per-packet threads the message was not sent to (i.e. -1 means one thread 1097 * could not be sent the message). 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). 1098 1120 */ 1099 1121 DLLEXPORT int trace_message_perpkts(libtrace_t * libtrace, 1100 1122 libtrace_message_t * message); 1101 1123 1102 /** Send a message to a thread1124 /** Send a message to a specific thread. 1103 1125 * 1104 1126 * @param[in] libtrace The parallel trace 1105 1127 * @param[in] t The thread to message 1106 * @param[in] message The message to be sent, if sender is NULL libtrace will 1107 * attempt to fill this in. It is faster to assign this if it is known. 1108 * 1109 * @return -1 upon error indicating the message has not been sent otherwise a 1110 * backlog indicator (the number of messages the thread has not yet read). 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. 1111 1134 */ 1112 1135 DLLEXPORT int trace_message_thread(libtrace_t * libtrace, … … 1114 1137 libtrace_message_t * message); 1115 1138 1116 /** Check if a parallel trace has finished reading packets1117 * 1118 * @return True if the trace has finished reading packets (even if all results1139 /** Checks if a parallel trace has finished reading packets. 1140 * 1141 * @return true if the trace has finished reading packets (even if all results 1119 1142 * have not yet been processed). Otherwise false. 1120 1143 * 1121 * @note This returns true even if all results have not yet been processed. 1144 * @note This returns true even if all results have not yet been processed by 1145 * the reporter thread. 1122 1146 */ 1123 1147 DLLEXPORT bool trace_has_finished(libtrace_t * libtrace); … … 1125 1149 1126 1150 /** Check if libtrace is directly reading from multiple queues 1127 * from the format (such as a NICs hardware queues).1128 * 1129 * When a parallel trace is running, or if checked after its completion1130 * this returns true if a trace was able to run natively parallel1131 * from the format. Otherwise false is returned, meaning libtrace is1132 * distibuting packets across multiple threads from a single source.1133 * 1134 * Factors that may stop this happening despite the format supporting1135 * native parallel reads include: the choice of hasher function,1136 * the number of threads choosen (such as 1 or more than the trace supports)1137 * or another error when trying to start the parallel format.1138 * 1139 * If this is called before the trace is started. I.e. before pstart1140 * this returns an indication that the trace has the possiblity to support1141 * native parallel reads. After trace pstart is called this should be1142 * checked again to confirm this has happened.1143 * 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. 1144 1168 * 1145 1169 * @return true if the trace is parallel or false if the library is splitting … … 1153 1177 * @return A 64bit sequence number or erf timestamp. 1154 1178 * 1155 * The returned value can be used to compare if packets come before or after 1156 * others. 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. 1157 1182 */ 1158 1183 DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet); … … 1163 1188 * @return A 64-bit hash 1164 1189 * 1165 * @note In many cases this might not be filled in, only in cases where1190 * @note This function will only work in situations where 1166 1191 * a custom hash is being used. You can use trace_has_dedicated_hasher() 1167 * to check if this will be valid.1192 * to check if this is the case. 1168 1193 */ 1169 1194 DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet); … … 1174 1199 * @param[in] order the new order of a packet 1175 1200 * 1176 * @note many combiners rely on this value, ensure changing this conforms to 1177 * the combiners requirements. 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! 1178 1205 */ 1179 1206 DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order); … … 1184 1211 * @param[in] hash the new hash 1185 1212 * 1186 * Once handed to the user the libtrace library has little use for this field 1187 * and as such this can essentially be used for any storage the user requires. 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. 1188 1216 */ 1189 1217 DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash); 1190 1218 1191 /** TODO WHAT TO DO WITH THIS ? */ 1192 DLLEXPORT uint64_t tv_to_usec(const struct timeval *tv); 1193 1194 1195 /** Returns the first packet of a parallel trace since it was started or 1196 * restarted. 1197 * 1198 * @param[in] libtrace the parallel input trace 1199 * @param[in] t Either a per packet thread or NULL to retrieve the first packet 1200 * of across all per packet threads. 1201 * @param[out] packet A pointer to the first packet in the trace. [Optional] 1202 * @param[out] tv The system time-stamp when this packet was received. [Optional] 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] 1203 1228 * @return 1 if we are confident this is the first packet. Otherwise 0 if this 1204 * is a best guess (this is only possible int the case t=NULL) 1205 * in which case we recommend calling this at a later time. 1206 * -1 is returned if an error occurs, such as supplied a invalid thread. 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. 1207 1233 * 1208 1234 * The packet and timeval returned by this function is shared by all threads … … 1214 1240 const struct timeval **tv); 1215 1241 1216 /** Makes a packet safe, a packet will becomeinvalid after a1242 /** Makes a packet safe, preventing the packet from becoming invalid after a 1217 1243 * pausing a trace. 1218 1244 * … … 1220 1246 * 1221 1247 * This copies a packet in such a way that it will be able to survive a pause. 1222 * However this will not allow the packet to be used after 1223 * the format isdestroyed.1248 * However this will not allow the packet to be used after the format is 1249 * destroyed. 1224 1250 */ 1225 1251 DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt); 1226 1252 1227 /** Makes a result safe if a result contains a packet. 1253 /** Makes a result safe, preventing the result from becoming invalid after 1254 * pausing a trace. 1228 1255 * 1229 1256 * @param[in,out] res The result to make safe. 1230 1257 * 1231 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. 1232 1260 * See libtrace_make_packet_safe(). 1233 1261 */ … … 1241 1269 * The packet should not be used after calling this function. 1242 1270 * 1271 * @note Don't use this inside a packet callback function -- just return 1272 * the packet instead, as this will be faster. 1273 * 1243 1274 * @note All packets should be free'd before a trace is destroyed. 1244 1275 */ 1245 1276 DLLEXPORT void trace_free_packet(libtrace_t * libtrace, libtrace_packet_t * packet); 1246 1277 1247 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 */ 1248 1286 DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace); 1249 1287 … … 1251 1289 * key value pairs. 1252 1290 * 1253 * @param trace A parallel trace which is not running or destroyed 1254 * @param str A comma separated list of key=value pairs .1255 * E.g. \em "burst_size=20,perpkt_threads=2,fixed_count=true"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" 1256 1294 * @return 0 if successful otherwise -1. If bad options are passed we will 1257 1295 * print the error to stderr but still return successful. … … 1276 1314 * LIBTRACE_CONF, see Parallel Configuration for more information. 1277 1315 * 1278 * @note this interface is provided to allow a user to configure an application 1279 * if a libtrace applicate wishes to configure a setting it should use a 1280 * trace_set_*() function with the same name. 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. 1281 1320 */ 1282 1321 DLLEXPORT int trace_set_configuration(libtrace_t *trace, const char * str); … … 1294 1333 DLLEXPORT int trace_set_configuration_file(libtrace_t *trace, FILE *file); 1295 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 */ 1296 1341 DLLEXPORT int trace_get_perpkt_threads(libtrace_t* t); 1297 1342 1298 1343 /** 1299 * Sets a combiner function against thetrace.1344 * Sets a combiner function for an input trace. 1300 1345 * 1301 1346 * @param trace The input trace 1302 * @ combiner The combiner to use1303 * @ config config Configuration information. Dependent upon the combiner in use1347 * @param combiner The combiner to use 1348 * @param config Configuration information. Dependent upon the combiner. 1304 1349 * 1305 1350 * Sets a combiner against a trace, this should only be called on a 1306 * non-started or paused trace. By default combiner_unordered1307 * will be used .1351 * non-started or paused trace. By default, combiner_unordered 1352 * will be used if this function is not called before starting the trace. 1308 1353 */ 1309 1354 DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config); … … 1311 1356 /** 1312 1357 * Takes unordered (or ordered) input and produces unordered output. 1313 * Basically you get the result quickly but in no particular order. 1358 * This is the fastest combiner but makes no attempt to ensure you get 1359 * results in a particular order. 1314 1360 */ 1315 1361 extern const libtrace_combine_t combiner_unordered; 1316 1362 1317 1363 /** 1318 * Takes ordered input and produces ordered output. Perpkt threads 1319 * the output results must be ordered for this to work correctly!! 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. 1320 1372 */ 1321 1373 extern const libtrace_combine_t combiner_ordered; … … 1323 1375 /** 1324 1376 * Like classic Google Map/Reduce, the results are sorted 1325 * in ascending order, this is only done when the trace finishes. 1326 * 1327 * This only works with a limited number of results, otherwise 1328 * we will just run out of memory and crash!! You should always 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 1329 1382 * use combiner_ordered if you can. 1330 1383 */ -
lib/trace_parallel.c
r5478d3d r1101175 2296 2296 } 2297 2297 2298 DLLEXPORT void * trace_get_local(libtrace_t *trace)2299 {2300 return trace->global_blob;2301 }2302 2303 DLLEXPORT void * trace_set_local(libtrace_t *trace, void * data)2304 {2305 void *ret;2306 pthread_mutex_lock(&trace->libtrace_lock);2307 ret = trace->global_blob;2308 trace->global_blob = data;2309 pthread_mutex_unlock(&trace->libtrace_lock);2310 return ret;2311 }2312 2313 DLLEXPORT void * trace_get_tls(libtrace_thread_t *t)2314 {2315 return t->user_data;2316 }2317 2318 DLLEXPORT void * trace_set_tls(libtrace_thread_t *t, void * data)2319 {2320 void *ret = t->user_data;2321 t->user_data = data;2322 return ret;2323 }2324 2325 2298 /** 2326 2299 * Publishes a result to the reduce queue -
tools/tracertstats/tracertstats.c
rf625817 r1101175 263 263 trace_set_perpkt_threads(trace, threadcount); 264 264 265 if (trace_ get_information(trace)->live) {265 if (trace_is_parallel(trace)) { 266 266 trace_set_tick_interval(trace, (int) (packet_interval * 1000)); 267 267 }
Note: See TracChangeset
for help on using the changeset viewer.