Ignore:
Timestamp:
03/12/15 17:14:42 (7 years ago)
Author:
Richard Sanger <rsangerarj@…>
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:
a978dec
Parents:
b54e2da
Message:

More documentation, including some renaming and modifications to behaviour

  • Removes accessor functions for libtrace_result_t, instead directly access the structure
  • Documentation for most functions
  • Split tick into interval and count messages for the two modes of operation
  • Normalise interval and packet order to use the erf timestamp format
  • Rename trace_send_message_to_XXX to trace trace_message_XXX
File:
1 edited

Legend:

Unmodified
Added
Removed
  • lib/libtrace_parallel.h

    r6a082f8 r6a6e6a8  
    4949
    5050typedef struct libtrace_result_t libtrace_result_t;
     51
    5152/**
    5253 * A collection of types for convenience used in place of a
     
    100101
    101102typedef struct libtrace_message_t {
    102         int code;
    103         libtrace_generic_t additional;
    104         libtrace_thread_t *sender;
     103        int code; /**< The message code see enum libtrace_messages */
     104        libtrace_generic_t data; /**< Additional data related to the message */
     105        libtrace_thread_t *sender; /**< The thread that sent the message */
    105106} libtrace_message_t;
    106107
     
    139140} trace_parallel_option_t;
    140141
     142/** The libtrace_messages enum
     143 * All libtrace messages are defined and documented here.
     144 *
     145 * Some messages can be sent to control the library while others
     146 * are received by the per-packet and reporter functions to inform the libtrace
     147 * application.
     148 *
     149 * If a user wishes to send there own custom messages they should use
     150 * numbers greater than MESSAGE_USER (1000).
     151 *
     152 * @note Some messages are for internal use only
     153 */
    141154enum libtrace_messages {
     155        /** A libtrace packet is ready, this will only be sent to per
     156         * packet threads.
     157         * @param data Holds the packet in data.pkt. The packet belongs to
     158         * libtrace and should either be returned from the per-packet function
     159         * if no longer needed or free'd at some later time using the XXX
     160         * function.
     161         * @param sender The sender will be set as the current thread
     162         */
    142163        MESSAGE_PACKET,
     164        /** A libtrace result is ready, this will only be sent to the reporter
     165         * thread.
     166         * @param data Holds the result in data.res. The memory holding the
     167         * result is allocated by libtrace and should not be free'd. However
     168         * note that any data stored within the result might need to be free'd.
     169         * @param sender The sender will be set as the current thread
     170         */
    143171        MESSAGE_RESULT,
     172
     173        /** A message sent to each thread when it starts. This is sent
     174         * to both the reporter and per-packet threads. This will be sent once
     175         * after trace_pstart() (assuming no errors occurs).
     176         *
     177         * This can be used to allocate resources required by each thread.
     178         *
     179         * These can be free'd when MESSAGE_STOPPING is received.
     180         *
     181         * @param data unused, do not use this
     182         * @param sender The sender will be set as the current thread
     183         */
    144184        MESSAGE_STARTING,
     185
     186        /** A message sent to each thread when it stops. This is sent
     187         * to both the reporter and per-packet threads. This will be sent once
     188         * after MESSAGE_STARTING.
     189         *
     190         * This can be used to free any resources allocated with
     191         * MESSAGE_STARTING.
     192         *
     193         * @param data unused, do not use this
     194         * @param sender The sender will be set as the current thread
     195         */
     196        MESSAGE_STOPPING,
     197
     198        /** A message sent to each thread when a thread transitions between a
     199         * paused (or unstarted) state to running state. This is sent
     200         * to both the reporter and per-packet threads. This will be sent after
     201         * MESSAGE_STARTING when a trace is first started and when a trace
     202         * is started (trace_pstart()) after a pause (trace_ppause()).
     203         *
     204         * This can be used to allocate resources.
     205         *
     206         * @param data unused, do not use this
     207         * @param sender The sender will be set as the current thread
     208         */
    145209        MESSAGE_RESUMING,
    146         MESSAGE_STOPPING,
     210
     211        /** A message sent to each thread when a thread transitions between a
     212         * paused (or unstarted) state to running state. This is sent
     213         * to both the reporter and per-packet threads. This will be sent after
     214         * MESSAGE_STARTING when a trace is first started and when a trace
     215         * is started (trace_pstart()) after a pause (trace_ppause()).
     216         *
     217         * This can be used to allocate resources.
     218         *
     219         * @param data unused, do not use this
     220         * @param sender The sender will be set as the current thread
     221         */
    147222        MESSAGE_PAUSING,
     223
     224        /** An internal message do not use this */
    148225        MESSAGE_DO_PAUSE,
     226        /** An internal message do not use this */
    149227        MESSAGE_DO_STOP,
     228
     229        /** Sent to all per-packet threads (including the sender) and the
     230         * reducer when the first packet is seen for a thread.
     231         *
     232         * @param data The first packet is stored in data.pkt. This packet is
     233         * shared by all threads receiving the message and is valid until
     234         * MESSAGE_PAUSING is received.
     235         * @param sender The per-packet thread which received the packet
     236         *
     237         * @note Upon pausing and restarting a trace this will be reset and
     238         * sent once a new packet is encountered
     239         *
     240         * @
     241         */
    150242        MESSAGE_FIRST_PACKET,
    151         MESSAGE_PERPKT_ENDED,
    152         MESSAGE_PERPKT_RESUMED,
    153         MESSAGE_PERPKT_PAUSED,
    154         MESSAGE_PERPKT_EOF,
     243
     244        /** Notify the reporter thread more data is available.
     245         *
     246         * Triggers the reporter to read as many results as possible.
     247         *
     248         * @param data unused
     249         * @param sender the sending
     250         *
     251         * @note This message should not be sent directly instead call
     252         * trace_post_reporter()
     253         *
     254         * @see trace_get_first_packet()
     255         */
    155256        MESSAGE_POST_REPORTER,
    156         MESSAGE_POST_RANGE,
    157         MESSAGE_TICK,
     257
     258        /** Sent to per-packet threads perodically after the configured time
     259         * interval has passed.
     260         *
     261         * This is sent out-of-band with respect to packets and as a result
     262         * can appear after a packet with an later timestamp, or before one
     263         * with an earlier timestamp.
     264         *
     265         * @param data data.uint64_t holds the system timestamp in the
     266         * erf format
     267         * @param sender should be ignored
     268         */
     269        MESSAGE_TICK_INTERVAL,
     270
     271        /** Sent to per-packet threads once the configured number of packets
     272         * are read from a trace.
     273         *
     274         * This are sent in-band with respect to packets such that all
     275         * threads will see it between the same packets.
     276         *
     277         * @param data The number of packets seen so far across all threads
     278         * @param sender Set to the current per-packet thread
     279         */
     280        MESSAGE_TICK_COUNT,
     281
     282        /** For specific user defined messages use codes above MESSAGE_USER. */
    158283        MESSAGE_USER = 1000
    159284};
     
    404529 * information dependent upon the mesg_code.
    405530 * @param sender The thread from which the message originated.
     531 * @return If the message type is MESSAGE_PACKET a packet can be returned back
     532 * to the library similar to trace_free_packet() otherwise this should be NULL.
    406533 *
    407534 * The values of data and sender depend upon the mesg_code. Please see the
     
    451578 * @param reporter A user supplied function called when a result is ready.
    452579 * Optional if NULL the reporter thread will not be started.
    453  * @returns 0 on success, otherwise -1 to indicate an error has occured
     580 * @return 0 on success, otherwise -1 to indicate an error has occured
    454581 *
    455582 * This can also be used to restart an existing parallel trace,
     
    465592 *
    466593 * @param libtrace The parallel trace to be paused
    467  * @returns 0 on success, otherwise -1 to indicate an error has occured
     594 * @return 0 on success, otherwise -1 to indicate an error has occured
    468595 *
    469596 */
     
    475602 *
    476603 * @param libtrace The parallel trace to be stopped
    477  * @returns 0 on success, otherwise -1 to indicate an error has occured
     604 * @return 0 on success, otherwise -1 to indicate an error has occured
    478605 *
    479606 * This should only be called by the main thread.
     
    491618 */
    492619DLLEXPORT void trace_join(libtrace_t * trace);
    493 
    494620
    495621/**
     
    555681DLLEXPORT int trace_set_hasher(libtrace_t *trace, enum hasher_types type, fn_hasher hasher, void *data);
    556682
    557 #define RESULT_NORMAL 0
    558 #define RESULT_PACKET 1
    559 #define RESULT_TICK   2
    560 
    561 DLLEXPORT void libtrace_result_set_key(libtrace_result_t * result, uint64_t key);
    562 DLLEXPORT uint64_t libtrace_result_get_key(libtrace_result_t * result);
    563 DLLEXPORT void libtrace_result_set_value(libtrace_result_t * result, libtrace_generic_t value);
    564 DLLEXPORT libtrace_generic_t libtrace_result_get_value(libtrace_result_t * result);
    565 DLLEXPORT void libtrace_result_set_key_value(libtrace_result_t * result, uint64_t key, libtrace_generic_t value);
    566 DLLEXPORT void trace_destroy_result(libtrace_result_t ** result);
    567 
    568 DLLEXPORT void trace_publish_result(libtrace_t *libtrace, libtrace_thread_t *t, uint64_t key, libtrace_generic_t value, int type);
    569 
     683/** Types of results.
     684 * Some result types require special handling by combiners
     685 * as such making use of built-in types is important.
     686 *
     687 * User specific results should be defined as values greater than RESULT_USER(1000)
     688 *
     689 */
     690enum result_types {
     691        /**
     692         * The result is a packet in some circumstances special handling needs
     693         * to be performed. As such packets should always be published as so.
     694         *
     695         * @param key (Typically) The packets order, see trace_packet_get_order()
     696         * @param
     697         */
     698        RESULT_PACKET,
     699
     700        /** The result is a tick message
     701         *
     702         * @param key The erf timestamp of the tick
     703         */
     704        RESULT_TICK_INTERVAL,
     705
     706        /** The result is a tick message
     707         *
     708         * @param key The sequence number of the tick message
     709         */
     710        RESULT_TICK_COUNT,
     711
     712        /** Any user specific codes should be above this.
     713         *
     714         */
     715        RESULT_USER = 1000
     716
     717};
     718
     719/** Publish a result for to the combiner destined for the reporter thread
     720 *
     721 * @param libtrace[in] The parallel input trace
     722 * @param t[in] The current per-packet thread
     723 * @param key[in] The key of the result (used for sorting by the combiner)
     724 * @param value[in] The value of the result
     725 * @param type[in] The type of result see the documentation for the result_types enum
     726 */
     727DLLEXPORT void trace_publish_result(libtrace_t *libtrace,
     728                                    libtrace_thread_t *t,
     729                                    uint64_t key,
     730                                    libtrace_generic_t value,
     731                                    int type);
     732
     733/** Check if a dedicated hasher thread is being used
     734 *
     735 * @return True if the trace has dedicated hasher thread otherwise false.
     736 */
     737DLLEXPORT bool trace_has_dedicated_hasher(libtrace_t * libtrace);
     738
     739/** Checks if a trace is using a reporter
     740 *
     741 * @param[in] The parallel input trace
     742 * @return True if the trace is using a reporter otherwise false
     743 */
     744DLLEXPORT bool trace_has_reporter(libtrace_t * libtrace);
     745
     746/** Post a message to the reporter thread requesting it to check for more
     747 * results.
     748 *
     749 * @param[in] The parallel input trace
     750 * @return -1 upon error indicating the message has not been sent otherwise a
     751 * backlog indicator (the number of messages the reporter has not yet read).
     752 */
    570753DLLEXPORT int trace_post_reporter(libtrace_t *libtrace);
    571 DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace);
    572 DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace, libtrace_message_t * message);
    573 DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace, libtrace_message_t * message);
    574 DLLEXPORT int trace_send_message_to_reporter(libtrace_t * libtrace, libtrace_message_t * message);
    575 DLLEXPORT int trace_send_message_to_perpkts(libtrace_t * libtrace, libtrace_message_t * message);
    576 DLLEXPORT int trace_send_message_to_thread(libtrace_t * libtrace, libtrace_thread_t *t, libtrace_message_t * message);
    577 DLLEXPORT int trace_finished(libtrace_t * libtrace);
     754
     755/** Check the number of messages waiting in a queue
     756 *
     757 * @param[in] libtrace The input trace
     758 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
     759 *
     760 * @return packets in the queue otherwise -1 upon error.
     761 *
     762 * @note For best performance it is recommended to supply the thread argument
     763 * even if it is the current thread.
     764 */
     765DLLEXPORT int libtrace_thread_get_message_count(libtrace_t * libtrace,
     766                                                libtrace_thread_t *t);
     767
     768/** Read a message from a thread in a blocking fashion
     769 *
     770 * @param[in] libtrace The input trace
     771 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
     772 * @param[out] message A pointer to libtrace_message_t structure which will be
     773 * filled with the retrived message.
     774 *
     775 * @return The number of messages remaining otherwise -1 upon error.
     776 *
     777 *
     778 * @note For best performance it is recommended to supply the thread argument
     779 * even if it is the current thread.
     780 */
     781DLLEXPORT int libtrace_thread_get_message(libtrace_t * libtrace,
     782                                          libtrace_thread_t *t,
     783                                          libtrace_message_t * message);
     784
     785/** Read a message from a thread in a blocking fashion
     786 *
     787 * @param[in] libtrace The input trace
     788 * @param[in] t The thread to check, if NULL the current thread will be used [Optional]
     789 * @param[out] message A pointer to libtrace_message_t structure which will be
     790 * filled with the retrived message.
     791 *
     792 * @return 0 if successful otherwise -1 upon error or if no packets were available.
     793 *
     794 *
     795 * @note For best performance it is recommended to supply the thread argument
     796 * even if it is the current thread.
     797 */
     798DLLEXPORT int libtrace_thread_try_get_message(libtrace_t * libtrace,
     799                                              libtrace_thread_t *t,
     800                                              libtrace_message_t * message);
     801
     802/** Send a message to the reporter thread
     803 *
     804 * @param[in] libtrace The parallel trace
     805 * @param[in] message The message to be sent, if sender is NULL libtrace will
     806 * attempt to fill this in. It is faster to assign this if it is known.
     807 *
     808 * @return -1 upon error indicating the message has not been sent otherwise a
     809 * backlog indicator (the number of messages the reporter has not yet read).
     810 */
     811DLLEXPORT int trace_message_reporter(libtrace_t * libtrace,
     812                                     libtrace_message_t * message);
     813
     814/** Send a message to all per-packet threads
     815 *
     816 * @param[in] libtrace The parallel trace
     817 * @param[in] message The message to be sent, if sender is NULL libtrace will
     818 * attempt to fill this in. It is faster to assign this if it is known.
     819 *
     820 * @return 0 if successful otherwise a negative number indicating the number
     821 * of per-packet threads the message was not sent to (i.e. -1 means one thread
     822 * could not be sent the message).
     823 */
     824DLLEXPORT int trace_message_perpkts(libtrace_t * libtrace,
     825                                    libtrace_message_t * message);
     826
     827/** Send a message to a thread
     828 *
     829 * @param[in] libtrace The parallel trace
     830 * @param[in] t The thread to message
     831 * @param[in] message The message to be sent, if sender is NULL libtrace will
     832 * attempt to fill this in. It is faster to assign this if it is known.
     833 *
     834 * @return -1 upon error indicating the message has not been sent otherwise a
     835 * backlog indicator (the number of messages the thread has not yet read).
     836 */
     837DLLEXPORT int trace_message_thread(libtrace_t * libtrace,
     838                                   libtrace_thread_t *t,
     839                                   libtrace_message_t * message);
     840
     841/** Check if a parallel trace has finished reading packets
     842 *
     843 * @return True if the trace has finished reading packets (even if all results
     844 * have not yet been processed). Otherwise false.
     845 *
     846 * @note This returns true even if all results have not yet been processed.
     847 */
     848DLLEXPORT bool trace_has_finished(libtrace_t * libtrace);
     849
     850/** Returns either the sequence number or erf timestamp of a packet.
     851 *
     852 * @param[in] packet
     853 * @return A 64bit sequence number or erf timestamp.
     854 *
     855 * The returned value can be used to compare if packets come before or after
     856 * others.
     857 */
    578858DLLEXPORT uint64_t trace_packet_get_order(libtrace_packet_t * packet);
     859
     860/** Returns the hash of a packet.
     861 *
     862 * @param[in] packet
     863 * @return A 64-bit hash
     864 *
     865 * @note In many cases this might not be filled in, only in cases where
     866 * a custom hash is being used. You can use trace_has_dedicated_hasher()
     867 * to check if this will be valid.
     868 */
    579869DLLEXPORT uint64_t trace_packet_get_hash(libtrace_packet_t * packet);
     870
     871/** Sets the order of a packet.
     872 *
     873 * @param[in] packet
     874 * @param[in] order the new order of a packet
     875 *
     876 * @note many combiners rely on this value, ensure changing this conforms to
     877 * the combiners requirements.
     878 */
    580879DLLEXPORT void trace_packet_set_order(libtrace_packet_t * packet, uint64_t order);
     880
     881/** Sets the hash of a packet.
     882 *
     883 * @param[in] packet
     884 * @param[in] hash the new hash
     885 *
     886 * Once handed to the user the libtrace library has little use for this field
     887 * and as such this can essentially be used for any storage the user requires.
     888 */
    581889DLLEXPORT void trace_packet_set_hash(libtrace_packet_t * packet, uint64_t hash);
     890
     891/** TODO WHAT TO DO WITH THIS ? */
    582892DLLEXPORT uint64_t tv_to_usec(struct timeval *tv);
    583893
    584 DLLEXPORT int retrive_first_packet(libtrace_t *libtrace, libtrace_packet_t **packet, struct timeval **tv);
    585 
     894
     895/** Returns the first packet of a parallel trace since it was started or
     896 * restarted.
     897 *
     898 * @param[in] libtrace the parallel input trace
     899 * @param[in] t Either a per packet thread or NULL to retrive the first packet
     900 * of across all per packet threads.
     901 * @param[out] packet A pointer to the first packet in the trace. [Optional]
     902 * @param[out] tv The system timestamp when this packet was received. [Optional]
     903 * @return 1 if we are confident this is the first packet. Otherwise 0 if this
     904 * is a best guess (this is only possible int the case t=NULL)
     905 * in which case we recommend calling this at a later time.
     906 * -1 is returned if an error occurs, such as supplied a invalid thread.
     907 *
     908 * The packet returned by this function is shared by all threads and remains
     909 * valid until MESSAGE_PAUSING is received.
     910 */
     911DLLEXPORT int trace_get_first_packet(libtrace_t *libtrace,
     912                                     libtrace_thread_t *t,
     913                                     libtrace_packet_t **packet,
     914                                     struct timeval **tv);
     915
     916/** Makes a packet safe, a packet will become invaild after a
     917 * pausing a trace.
     918 *
     919 * @param pkt[in,out] The packet to make safe
     920 *
     921 * This copies a packet in such a way that it will be able to survive a pause.
     922 * However this will not allow the packet to be used after
     923 * the format is destroyed.
     924 */
    586925DLLEXPORT void libtrace_make_packet_safe(libtrace_packet_t *pkt);
     926
     927/** Makes a result safe if a result contains a packet.
     928 *
     929 * @param res[in,out] The result to make safe.
     930 *
     931 * This ensures the internal content of a result is safe to survive a pause.
     932 * See libtrace_make_packet_safe().
     933 */
    587934DLLEXPORT void libtrace_make_result_safe(libtrace_result_t *res);
    588935
    589936
    590937DLLEXPORT int trace_parallel_config(libtrace_t *libtrace, trace_parallel_option_t option, void *value);
    591 DLLEXPORT libtrace_packet_t* trace_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
    592 DLLEXPORT void trace_free_result_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
     938
     939/** In a parallel trace, free a packet back to libtrace.
     940 *
     941 * @param[in] libtrace A parallel input trace
     942 * @param[in] packet The packet to be released back to libtrace
     943 *
     944 * The packet should not be used after calling this function.
     945 *
     946 * @note All packets should be free'd before a trace is destroyed.
     947 */
     948DLLEXPORT void trace_free_packet(libtrace_t * libtrace, libtrace_packet_t * packet);
     949
     950
    593951DLLEXPORT libtrace_info_t *trace_get_information(libtrace_t * libtrace);
    594 
    595 
    596952DLLEXPORT void parse_user_config(struct user_configuration* uc, char * str);
    597953DLLEXPORT void parse_user_config_file(struct user_configuration* uc, FILE *file);
    598954DLLEXPORT int libtrace_get_perpkt_count(libtrace_t* t);
    599955
    600 
    601 
    602956/**
    603957 * Sets a combiner function against the trace.
Note: See TracChangeset for help on using the changeset viewer.