Changeset 1101175


Ignore:
Timestamp:
09/16/15 17:23:46 (6 years ago)
Author:
Shane Alcock <salcock@…>
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
Message:

Polish up all the documentation in libtrace_parallel.h

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

Moved tv_to_usec into libtrace_int.h.

Files:
4 edited

Legend:

Unmodified
Added
Removed

  • lib/libtrace_int.h

    rf625817 r1101175  
    10461046void register_format(struct libtrace_format_t *format);
    10471047
     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 */
     1053uint64_t tv_to_usec(const struct timeval *tv);
     1054
    10481055/** Converts a PCAP DLT into a libtrace link type.
    10491056 *

  • lib/libtrace_parallel.h

    r5478d3d r1101175  
    22 * This file is part of libtrace
    33 *
    4  * Copyright (c) 2007,2008,2009,2010 The University of Waikato, Hamilton,
     4 * Copyright (c) 2007-2015 The University of Waikato, Hamilton,
    55 * New Zealand.
    66 *
    77 * Authors: Richard Sanger
     8 *          Shane Alcock
    89 *
    910 * All rights reserved.
    … …  
    3738 * @author Richard Sanger
    3839 *
    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.
    4246 */
    4347
    … …  
    5660/**
    5761 * 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.
    5964 *
    6065 * This is expected to be 8 bytes in length.
    … …  
    104109ct_assert(sizeof(libtrace_generic_t) == 8);
    105110
     111/**
     112 * Structure describing a message that can be sent to a libtrace thread.
     113 */
    106114typedef struct libtrace_message_t {
    107         int code; /**< The message code see enum libtrace_messages */
     115        int code; /**< The message code, as defined in enum libtrace_messages */
    108116        libtrace_generic_t data; /**< Additional data related to the message */
    109117        libtrace_thread_t *sender; /**< The thread that sent the message */
    … …  
    112120/** Structure holding information about a result */
    113121struct 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 */
    117125};
    118126
    … …  
    120128 * All libtrace messages are defined and documented here.
    121129 *
    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
    127133 * numbers greater than MESSAGE_USER (1000).
    128134 *
    … …  
    130136 */
    131137enum 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.
    139140         */
    140141        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.
    147145         */
    148146        MESSAGE_RESULT,
    149147
    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.
    162152         */
    163153        MESSAGE_STARTING,
    164154
    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.
    174158         */
    175159        MESSAGE_STOPPING,
    176160
    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         */
    188168        MESSAGE_RESUMING,
    189169
    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         */
    201178        MESSAGE_PAUSING,
    202179
    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         */
    204183        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         */
    206188        MESSAGE_DO_STOP,
    207189
    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         */
    221202        MESSAGE_FIRST_PACKET,
    222203
    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.
    233209         */
    234210        MESSAGE_POST_REPORTER,
    … …  
    245221         * @param sender should be ignored
    246222         */
     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         */
    247233        MESSAGE_TICK_INTERVAL,
    248234
    … …  
    256242         * @param sender Set to the current per-packet thread
    257243         */
     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         */
    258253        MESSAGE_TICK_COUNT,
    259254
    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         */
    261259        MESSAGE_USER = 1000
    262260};
    263261
    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().
    266264 */
    267265enum 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.
     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.
    272270         */
    273271        HASHER_BALANCE,
    274272
    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.
     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.
    277275         * All non TCP/UDP packets will be sent to the same thread.
    278276         *
    279277         * @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.
     278         * processing threads, depending upon the format support. In this case
     279         * they would be directed to a single thread.
    282280         */
    283281        HASHER_BIDIRECTIONAL,
    284282
    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
     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.
    289287         */
    290288        HASHER_UNIDIRECTIONAL,
    291289
    292290        /**
    293          * Always use the user supplied hasher, this disables native
    294          * support in and is likely significantly slower.
     291         * This value indicates that the hasher is a custom user-defined
     292         * function.
    295293         */
    296294        HASHER_CUSTOM
    … …  
    307305        /**
    308306         * 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.
    311310         */
    312311        int max_threads;
    … …  
    317316} libtrace_info_t;
    318317
    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  */
    327318typedef 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 */
    328325struct libtrace_combine {
    329326
    … …  
    339336
    340337        /**
    341          * Called when the trace ends, clean up any memory here
    342          * from libtrace_t * init.
     338         * Called when the trace ends, clean up any memory allocated
     339         * by the initialise function.
    343340         */
    344341        void (*destroy)(libtrace_t *, libtrace_combine_t *);
    345342
    346343        /**
    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.
    351355         *
    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.
    359366         *
    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
    371368         * just return.
    372369         *
    373370         * Libtrace state:
    374          * Called from reporter thread
    375          * No perpkt threads will be running, i.e. publish will not be
    376          * 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.
    377374         *
    378          * If publish is NULL, this probably should be NULL also otherwise
    379          * 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.
    380377         */
    381378        void (*read_final)(libtrace_t *, libtrace_combine_t *);
    382379
    383380        /**
    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.
    387385         */
    388386        void (*pause)(libtrace_t *, libtrace_combine_t *);
    … …  
    393391        void *queues;
    394392
     393        /** The last counter tick that we saw, so we can avoid duplicating
     394         *  any ticks that are published.
     395         */
    395396        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         */
    396401        uint64_t last_ts_tick;
    397402
    … …  
    404409
    405410/**
    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 /**
    448411 * 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.
    450413 *
    451414 * @param packet The packet to be hashed.
    452415 * @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.
    454419 */
    455420typedef uint64_t (*fn_hasher)(const libtrace_packet_t* packet, void *data);
    … …  
    459424 *
    460425 * @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.
    465433 * @return 0 on success, otherwise -1 to indicate an error has occurred
    466434 *
    … …  
    477445
    478446/**
    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.
    485457 */
    486458typedef void* (*fn_cb_starting)(libtrace_t *libtrace,
    … …  
    489461
    490462/**
    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.
    495470 */
    496471typedef void (*fn_cb_dataless)(libtrace_t *libtrace,
    … …  
    500475
    501476/**
    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.
    506483 */
    507484typedef void (*fn_cb_first_packet)(libtrace_t *libtrace,
    … …  
    512489
    513490/**
    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.
    519499 */
    520500typedef void (*fn_cb_tick)(libtrace_t *libtrace,
    … …  
    525505
    526506/**
    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.
    535518 */
    536519typedef libtrace_packet_t* (*fn_cb_packet)(libtrace_t *libtrace,
    … …  
    544527 * reporter thread.
    545528 *
    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.
    551534 *
    552535 */
    … …  
    559542 * any messages with a type >= MESSAGE_USER.
    560543 *
    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.
    567550 *
    568551 */
    … …  
    570553                void *global, void *tls, int mesg, libtrace_generic_t data);
    571554
    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 */
    581563DLLEXPORT int trace_set_starting_cb(libtrace_callback_set_t *cbset,
    582564                fn_cb_starting handler);
    583565
     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 */
    584573DLLEXPORT int trace_set_stopping_cb(libtrace_callback_set_t *cbset,
    585574                fn_cb_dataless handler);
    586575
     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 */
    587583DLLEXPORT int trace_set_resuming_cb(libtrace_callback_set_t *cbset,
    588584                fn_cb_dataless handler);
    589585
     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 */
    590593DLLEXPORT int trace_set_pausing_cb(libtrace_callback_set_t *cbset,
    591594                fn_cb_dataless handler);
    592595
     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 */
    593603DLLEXPORT int trace_set_packet_cb(libtrace_callback_set_t *cbset,
    594604                fn_cb_packet handler);
    595605
     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 */
    596613DLLEXPORT int trace_set_first_packet_cb(libtrace_callback_set_t *cbset,
    597614                fn_cb_first_packet handler);
    598615
     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 */
    599623DLLEXPORT int trace_set_result_cb(libtrace_callback_set_t *cbset,
    600624                fn_cb_result handler);
    601625
     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 */
    602633DLLEXPORT int trace_set_tick_count_cb(libtrace_callback_set_t *cbset,
    603634                fn_cb_tick handler);
    604635
     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 */
    605643DLLEXPORT int trace_set_tick_interval_cb(libtrace_callback_set_t *cbset,
    606644                fn_cb_tick handler);
    607645
     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 */
    608653DLLEXPORT int trace_set_user_message_cb(libtrace_callback_set_t *cbset,
    609654                fn_cb_usermessage handler);
    … …  
    616661DLLEXPORT libtrace_callback_set_t *trace_create_callback_set(void);
    617662
    618 /** Destroys a callback set, freeing up an resources it was using.
     663/** Destroys a callback set, freeing up any resources it was using.
    619664 *
    620665 * @param cbset         The callback set to be destroyed.
    … …  
    638683 * @return 0 on success, otherwise -1 to indicate an error has occurred
    639684 *
    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.
    641688 *
    642689 */
    … …  
    652699 */
    653700DLLEXPORT void trace_join(libtrace_t * trace);
    654 
    655 /**
    656  * @name User Data Storage
    657  *
    658  * These method provide a way for users to store data against a trace or
    659  * a thread.
    660  *
    661  * Alternatively one could use global variables and thread local
    662  * storage (__thread), respectively, which in many cases could be simpler.
    663  *
    664  * @note We do not lock on reads, instead we rely on the
    665  * processor making any writes appear atomically.
    666  *
    667  * @{
    668  */
    669 
    670 /** Returns the data stored against a trace.
    671  *
    672  * @param trace The parallel trace
    673  * @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 it
    678  * using trace_get_global().
    679  *
    680  * @param trace The parallel trace.
    681  * @param data The new value to save against the trace
    682  * @return The previously stored value
    683  *
    684  * The update to the previous value is atomic and thread-safe.
    685  *
    686  * @note Although this is thread-safe another thread may still be
    687  * using the previous data, as such further synchronisation is needed
    688  * 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 thread
    695  * @return The stored data
    696  */
    697 DLLEXPORT void * trace_get_tls(libtrace_thread_t *thread);
    698 
    699 /** Store data against a thread.
    700  *
    701  * @param thread The thread
    702  * @param data The new value to save against the thread
    703  * @return The previously stored value
    704  *
    705  * This function is not thread-safe and is intended only to be
    706  * called on the currently running thread.
    707  */
    708 DLLEXPORT void * trace_set_tls(libtrace_thread_t *thread, void * data);
    709 
    710 /// @}
    711701
    712702
    … …  
    729719 *
    730720 * 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
    734727 *
    735728 * @note All environment variables names MUST only contain
    … …  
    743736 *
    744737 * @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.
    746740 * @return 0 if successful otherwise -1
    747741 */
    … …  
    751745 *
    752746 * @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 *
    763756 * @see MESSAGE_TICK_INTERVAL, trace_set_tick_count()
    764757 */
    765758DLLEXPORT int trace_set_tick_interval(libtrace_t *trace, size_t millisec);
    766759
    767 /** Set the count between tick messages.
     760/** Set the number of packets to be read between tick messages.
    768761 *
    769762 * @param[in] trace The parallel input trace
    … …  
    771764 * @return 0 if successful otherwise -1
    772765 *
    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.
    778770 *
    779771 * @see MESSAGE_TICK_COUNT, trace_set_tick_interval()
    … …  
    786778 *
    787779 * @param trace A parallel input trace
    788  * @param tracetime If true packets are released with time intervals matching
     780 * @param tracetime If true packets are released with time spacing that matches
    789781 * the original trace. Otherwise packets are read as fast as possible.
    790782 * @return 0 if successful otherwise -1
    … …  
    792784DLLEXPORT int trace_set_tracetime(libtrace_t *trace, bool tracetime);
    793785
    794 /** This sets the maximum size of the freelist used to store empty packets
     786/** Sets the maximum size of the freelist used to store empty packets
    795787 * and their memory buffers.
    796788 *
    … …  
    800792 * @return 0 if successful otherwise -1
    801793 *
    802  * Internally libtrace maintains a buffer of packet structures, this buffer
    803  * includes a cache per thread and a shared main pool. This configures
     794 * Internally libtrace maintains a buffer of packet structures which
     795 * includes a cache per thread and a shared main pool. This option configures
    804796 * the size of the main pool. If an application is not passing packets
    805  * through to the reducer step --- that is to say returns packets from
    806  * the perpkt function --- this buffer will not need to be used.
     797 * through to the reporter thread, i.e. the packet callback always returns
     798 * the packet, then the main pool is not used.
    807799 *
    808800 * @note Setting this too low could cause performance issues or a deadlock. An
    … …  
    813805DLLEXPORT int trace_set_cache_size(libtrace_t *trace, size_t size);
    814806
    815 /** This sets the maximum size of the freelist thread cache's used to provide
    816  * 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.
    817809 *
    818810 * @param trace A parallel input trace
    … …  
    825817DLLEXPORT int trace_set_thread_cache_size(libtrace_t *trace, size_t size);
    826818
    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.
    831829 *
    832830 * @param trace A parallel input trace
    … …  
    848846 *
    849847 * 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.
    854853 */
    855854DLLEXPORT int trace_set_burst_size(libtrace_t *trace, size_t size);
    856855
    857856/**
    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
    861861 * trace that manages its own packets.
    862862 * A unblockable warning message will be printed to stderr in this case.
    863863 */
    864 /** The number of packets that can queue per thread from hasher thread */
    865864DLLEXPORT int trace_set_hasher_queue_size(libtrace_t *trace, size_t size);
    866865
    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.
    869874 *
    870875 * @param trace A parallel input trace
    871876 * @param polling If true the hasher will poll waiting for data, otherwise
    872  * it is not. Defaults to false.
    873  *
    874  * We note this is likely to waste many CPU cycles and could even decrease
     877 * it will use a condition variable. Defaults to false.
     878 *
     879 * We note polling is likely to waste many CPU cycles and could even decrease
    875880 * performance.
    876881 *
    … …  
    879884DLLEXPORT int trace_set_hasher_polling(libtrace_t *trace, bool polling);
    880885
    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.
    884892 *
    885893 * @param trace A parallel input trace
    886894 * @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.
    888896 * @return 0 if successful otherwise -1
    889897 *
    890  * We note this is likely to waste many CPU cycles and could even decrease
     898 * We note polling is likely to waste many CPU cycles and could even decrease
    891899 * performance.
    892900 *
    … …  
    895903DLLEXPORT int trace_set_reporter_polling(libtrace_t *trace, bool polling);
    896904
    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.
    899912 *
    900913 * @param trace A parallel input trace
    … …  
    904917 *
    905918 *
    906  * @note This setting is generally ignored if trace_set_reporter_polling() is
    907  * set however some combiner functions might ignore trace_set_reporter_polling()
    908  * and still require 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.
    909922 * @see trace_publish_result(), trace_post_reporter()
    910923 */
    911924DLLEXPORT int trace_set_reporter_thold(libtrace_t *trace, size_t thold);
    912925
    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....
    915933 *
    916934 * @param trace A parallel input trace
    … …  
    931949 *
    932950 * 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.
    934954 *
    935955 * HASHER_BALANCE is the default and will dispatch packets as fast as possible
    936  * to all threads arbitrarily. As such when called the hasher and
    937  * data parameters must be set to NULL.
    938  *
    939  * HASHER_CUSTOM will force the libtrace to use the user defined function. As
    940  * such the hasher parameter must be supplied.
    941  *
    942  * With other defined hasher types we will try to push the hashing into the format
    943  * by default. In this case the hasher parameter is optional and will be
    944  * 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.
    945965 *
    946966 * @note When supplying a hasher function it should be thread-safe so it can
    … …  
    955975
    956976/** Types of results.
    957  * Some result types require special handling by combiners
    958  * as such making use of built-in types is important.
    959977 *
    960978 * Custom result types users should be defined as RESULT_USER(1000) or greater.
    … …  
    963981enum result_types {
    964982        /**
    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).
    967989         *
    968          * @param key (Typically) The packets order, see trace_packet_get_order()
    969990         */
    970991        RESULT_PACKET,
    971992
    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.
    975995         */
    976996        RESULT_TICK_INTERVAL,
    977997
    978         /** The result is a tick message
    979          *
    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.
    9811001         */
    9821002        RESULT_TICK_COUNT,
    9831003
    984         /** Any user specific codes should be above this.
    985          *
     1004        /**
     1005         * Any user-defined result codes should be at or above this value.
    9861006         */
    9871007        RESULT_USER = 1000
    … …  
    9891009};
    9901010
    991 /** Publish a result for to the combiner destined for the reporter thread
     1011/** Publish a result to the reporter thread (via the combiner)
    9921012 *
    9931013 * @param[in] libtrace The parallel input trace
    … …  
    9951015 * @param[in] key The key of the result (used for sorting by the combiner)
    9961016 * @param[in] value The value of the result
    997  * @param[in] type The type of result see the documentation for the result_types enum
     1017 * @param[in] type The type of result (see result_types)
    9981018 */
    9991019DLLEXPORT void trace_publish_result(libtrace_t *libtrace,
    … …  
    10061026 *
    10071027 * @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().
    10111032 */
    10121033DLLEXPORT bool trace_has_dedicated_hasher(libtrace_t * libtrace);
    10131034
    1014 /** Checks if a trace is using a reporter
     1035/** Checks if a trace is using a reporter thread.
    10151036 *
    10161037 * @param[in] libtrace The parallel input trace
    … …  
    10191040DLLEXPORT bool trace_has_reporter(libtrace_t * libtrace);
    10201041
    1021 /** Post a message to the reporter thread requesting it to check for more
     1042/** Post a message to the reporter thread requesting that it check for more
    10221043 * results.
    10231044 *
    … …  
    10281049DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);
    10291050
    1030 /** Check the number of messages waiting in a queue
     1051/** Check the number of messages waiting in a thread's message queue
    10311052 *
    10321053 * @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.
    10341055 *
    10351056 * @return packets in the queue otherwise -1 upon error.
    … …  
    10411062                                                libtrace_thread_t *t);
    10421063
    1043 /** Read a message from a thread in a blocking fashion
     1064/** Read a message from a thread in a blocking fashion.
    10441065 *
    10451066 * @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 be
    1048  * 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.
    10491070 *
    10501071 * @return The number of messages remaining otherwise -1 upon error.
    1051  *
    10521072 *
    10531073 * @note For best performance it is recommended to supply the thread argument
    … …  
    10581078                                          libtrace_message_t * message);
    10591079
    1060 /** Read a message from a thread in a blocking fashion
     1080/** Read a message from a thread in a non-blocking fashion.
    10611081 *
    10621082 * @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 be
    1065  * 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.
    10691089 *
    10701090 * @note For best performance it is recommended to supply the thread argument
    … …  
    10751095                                              libtrace_message_t * message);
    10761096
    1077 /** Send a message to the reporter thread
     1097/** Send a message to the reporter thread.
    10781098 *
    10791099 * @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.
    10851106 */
    10861107DLLEXPORT int trace_message_reporter(libtrace_t * libtrace,
    10871108                                     libtrace_message_t * message);
    10881109
    1089 /** Send a message to all per-packet threads
     1110/** Send a message to all processing threads.
    10901111 *
    10911112 * @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).
    10981120 */
    10991121DLLEXPORT int trace_message_perpkts(libtrace_t * libtrace,
    11001122                                    libtrace_message_t * message);
    11011123
    1102 /** Send a message to a thread
     1124/** Send a message to a specific thread.
    11031125 *
    11041126 * @param[in] libtrace The parallel trace
    11051127 * @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.
    11111134 */
    11121135DLLEXPORT int trace_message_thread(libtrace_t * libtrace,
    … …  
    11141137                                   libtrace_message_t * message);
    11151138
    1116 /** Check if a parallel trace has finished reading packets
    1117  *
    1118  * @return True if the trace has finished reading packets (even if all results
     1139/** Checks if a parallel trace has finished reading packets.
     1140 *
     1141 * @return true if the trace has finished reading packets (even if all results
    11191142 * have not yet been processed). Otherwise false.
    11201143 *
    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.
    11221146 */
    11231147DLLEXPORT bool trace_has_finished(libtrace_t * libtrace);
    … …  
    11251149
    11261150/** 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 completion
    1130  * this returns true if a trace was able to run natively parallel
    1131  * from the format. Otherwise false is returned, meaning libtrace is
    1132  * distibuting packets across multiple threads from a single source.
    1133  *
    1134  * Factors that may stop this happening despite the format supporting
    1135  * 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 pstart
    1140  * this returns an indication that the trace has the possiblity to support
    1141  * native parallel reads. After trace pstart is called this should be
    1142  * 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.
    11441168 *
    11451169 * @return true if the trace is parallel or false if the library is splitting
    … …  
    11531177 * @return A 64bit sequence number or erf timestamp.
    11541178 *
    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.
    11571182 */
    11581183DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
    … …  
    11631188 * @return A 64-bit hash
    11641189 *
    1165  * @note In many cases this might not be filled in, only in cases where
     1190 * @note This function will only work in situations where
    11661191 * 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.
    11681193 */
    11691194DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
    … …  
    11741199 * @param[in] order the new order of a packet
    11751200 *
    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!
    11781205 */
    11791206DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
    … …  
    11841211 * @param[in] hash the new hash
    11851212 *
    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.
    11881216 */
    11891217DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
    11901218
    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]
    12031228 * @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.
    12071233 *
    12081234 * The packet and timeval returned by this function is shared by all threads
    … …  
    12141240                                     const struct timeval **tv);
    12151241
    1216 /** Makes a packet safe, a packet will become invalid after a
     1242/** Makes a packet safe, preventing the packet from becoming invalid after a
    12171243 * pausing a trace.
    12181244 *
    … …  
    12201246 *
    12211247 * 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 is destroyed.
     1248 * However this will not allow the packet to be used after the format is
     1249 * destroyed.
    12241250 */
    12251251DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);
    12261252
    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.
    12281255 *
    12291256 * @param[in,out] res The result to make safe.
    12301257 *
    12311258 * 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.
    12321260 * See libtrace_make_packet_safe().
    12331261 */
    … …  
    12411269 * The packet should not be used after calling this function.
    12421270 *
     1271 * @note Don't use this inside a packet callback function -- just return
     1272 * the packet instead, as this will be faster.
     1273 *
    12431274 * @note All packets should be free'd before a trace is destroyed.
    12441275 */
    12451276DLLEXPORT void trace_free_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
    12461277
    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 */
    12481286DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);
    12491287
    … …  
    12511289 * key value pairs.
    12521290 *
    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"
    12561294 * @return 0 if successful otherwise -1. If bad options are passed we will
    12571295 * print the error to stderr but still return successful.
    … …  
    12761314 * LIBTRACE_CONF, see Parallel Configuration for more information.
    12771315 *
    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.
    12811320 */
    12821321DLLEXPORT int trace_set_configuration(libtrace_t *trace, const char * str);
    … …  
    12941333DLLEXPORT int trace_set_configuration_file(libtrace_t *trace, FILE *file);
    12951334
     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 */
    12961341DLLEXPORT int trace_get_perpkt_threads(libtrace_t* t);
    12971342
    12981343/**
    1299  * Sets a combiner function against the trace.
     1344 * Sets a combiner function for an input trace.
    13001345 *
    13011346 * @param trace The input trace
    1302  * @combiner The combiner to use
    1303  * @config config Configuration information. Dependent upon the combiner in use
     1347 * @param combiner The combiner to use
     1348 * @param config Configuration information. Dependent upon the combiner.
    13041349 *
    13051350 * Sets a combiner against a trace, this should only be called on a
    1306  * non-started or paused trace.  By default combiner_unordered
    1307  * 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.
    13081353 */
    13091354DLLEXPORT void trace_set_combiner(libtrace_t *trace, const libtrace_combine_t *combiner, libtrace_generic_t config);
    … …  
    13111356/**
    13121357 * 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.
    13141360 */
    13151361extern const libtrace_combine_t combiner_unordered;
    13161362
    13171363/**
    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.
    13201372 */
    13211373extern const libtrace_combine_t combiner_ordered;
    … …  
    13231375/**
    13241376 * 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
    13291382 * use combiner_ordered if you can.
    13301383 */

  • lib/trace_parallel.c

    r5478d3d r1101175  
    22962296}
    22972297
    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 
    23252298/**
    23262299 * Publishes a result to the reduce queue

  • tools/tracertstats/tracertstats.c

    rf625817 r1101175  
    263263        trace_set_perpkt_threads(trace, threadcount);
    264264
    265         if (trace_get_information(trace)->live) {
     265        if (trace_is_parallel(trace)) {
    266266                trace_set_tick_interval(trace, (int) (packet_interval * 1000));
    267267        }
Note: See TracChangeset for help on using the changeset viewer.