X-Git-Url: https://git.liburcu.org/?a=blobdiff_plain;f=liblttd%2Fliblttd.h;h=aac1e5dcd0b2bc74d095a2765ab573aa8a565cae;hb=HEAD;hp=bd76eeb58cc7e68053ac53cb582b94177b039766;hpb=008e25154ca2db688516bafcb134c984f08a5f10;p=ltt-control.git diff --git a/liblttd/liblttd.h b/liblttd/liblttd.h index bd76eeb..aac1e5d 100644 --- a/liblttd/liblttd.h +++ b/liblttd/liblttd.h @@ -1,218 +1,268 @@ -/* liblttd header file +/* + * liblttd header file * + * Copyright 2005-2010 - + * Mathieu Desnoyers * Copyright 2010- * Oumarou Dicko * Michael Sills-Lavoie * + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2 of the License, or - * (at your option) any later version. - * - * This program is distributed in the hope that it will be useful, + * This library is distributed in the hope that it will be useful, * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. * + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ #ifndef _LIBLTTD_H #define _LIBLTTD_H #include +#include +#include /** -* This structure contains the data associated with the channel file descriptor. -* The lib user can use user_data to store the data associated to the specified -* channel. The lib user can read but MUST NOT change the other attributes. -*/ + * struct fd_pair - Contains the data associated with the channel file + * descriptor. The lib user can use user_data to store the data associated to + * the specified channel. The lib user can read but MUST NOT change the other + * attributes. + * @channel: channel file descriptor + * @n_sb: the number of subbuffer for this channel + * @max_sb_size: the subbuffer size for this channel + * @mmap: Not used anymore. + * @mutex: a mutex for internal library usage + * @user_data: library user data + * @offset: write position in the output file descriptor (optional) + */ struct fd_pair { - /** - * This is the channel file descriptor. - */ int channel; - - /** - * This is the number of subbuffer for this channel. - */ unsigned int n_sb; - - /** - * This is the subbuffer size for this channel. - */ unsigned int max_sb_size; - - /** - * Not used anymore. - */ void *mmap; - - /** - * This is a mutex for internal library usage. - */ pthread_mutex_t mutex; - - /** - * Library user data. - */ void *user_data; + off_t offset; +}; + +struct channel_trace_fd { + struct fd_pair *pair; + int num_pairs; +}; + +struct inotify_watch { + int wd; + char path_channel[PATH_MAX]; + char *base_path_channel; }; +struct inotify_watch_array { + struct inotify_watch *elem; + int num; +}; + +struct liblttd_callbacks; + /** -* This structure contains the necessary callbacks for a tracing session. The -* user can set the unnecessary functions to NULL if he does not need them. + * struct liblttd_instance - Contains the data associated with a trace instance. + * The lib user can read but MUST NOT change any attributes but callbacks. + * @callbacks: Contains the necessary callbacks for a tracing session. + */ +struct liblttd_instance { + struct liblttd_callbacks *callbacks; + + int inotify_fd; + struct channel_trace_fd fd_pairs; + struct inotify_watch_array inotify_watch_array; + + /* protects fd_pairs and inotify_watch_array */ + pthread_rwlock_t fd_pairs_lock; + + char channel_name[PATH_MAX]; + unsigned long num_threads; + int quit_program; + int dump_flight_only; + int dump_normal_only; + int verbose_mode; +}; + +/** +* struct liblttd_callbacks - Contains the necessary callbacks for a tracing +* session. The user can set the unnecessary functions to NULL if he does not +* need them. */ struct liblttd_callbacks { /** - * This callback is called after a channel file is open. - * - * @args data This argument is a pointeur to the callbacks struct that - * has been passed to the lib. - * @args pair This structure contains the data associated with the - * channel file descriptor. The lib user can use user_data to - * store the data associated to the specified channel. - * @args relative_channel_path This argument represents a relative path - * to the channel file. This path is relative to the root - * folder of the trace channels. - * - * @return Should return 0 if the callback succeeds else not 0. - */ - int(*on_open_channel)(struct liblttd_callbacks *data, - struct fd_pair *pair, char *relative_channel_path); + * on_open_channel - Is called after a channel file is open. + * + * @data: pointer to the callbacks structure that has been passed to + * the lib. + * @pair: structure that contains the data associated with the + * channel file descriptor. The library user can use user_data to + * store the data associated to the specified channel. + * @relative_channel_path: + * represents a relative path to the channel file. This path is + * relative to the root folder of the trace channels. + * + * Returns 0 if the callback succeeds else not 0. + */ + int (*on_open_channel)(struct liblttd_callbacks *data, + struct fd_pair *pair, + char *relative_channel_path); /** - * This callback is called after a channel file is closed. - * - * @remarks After a channel file has been closed, it will never be read - * again. - * - * @args data This argument is a pointeur to the callbacks struct that - * has been passed to the lib. - * @args pair This structure contains the data associated with the - * channel file descriptor. The lib user should clean - * user_data at this time. - * - * @return Should return 0 if the callback succeeds else not 0. - */ - int(*on_close_channel)(struct liblttd_callbacks *data, - struct fd_pair *pair); - + * on_close_channel - Is called after a channel file is closed. + * + * @data: pointer to the callbacks structure that has been passed to the + * lib. + * @pair: structure that contains the data associated with the channel + * file descriptor. The lib user should clean user_data at this + * time. + * + * Returns 0 if the callback succeeds else not 0. + * + * After a channel file has been closed, it will never be read again. + */ + int (*on_close_channel)(struct liblttd_callbacks *data, + struct fd_pair *pair); /** - * This callback is called when the library enter in a new subfolder - * while it is scanning the trace channel tree. It can be used to create - * the output file structure of the trace. - * - * @args data This argument is a pointeur to the callbacks struct that - * has been passed to the lib. - * @args relative_folder_path This argument represents a relative path - * to the channel folder. This path is relative to the root - * folder of the trace channels. - * - * @return Should return 0 if the callback succeeds else not 0. - */ - int(*on_new_channels_folder)(struct liblttd_callbacks *data, - char *relative_folder_path); + * on_new_channels_folder - Is called when the library enter in a new + * subfolder while it is scanning the trace channel tree. It can be used + * to create the output file structure of the trace. + * + * @data: pointer to the callbacks structure that has been passed to the + * library. + * @relative_folder_path: + * represents a relative path to the channel folder. This path is + * relative to the root folder of the trace channels. + * + * Returns 0 if the callback succeeds else not 0. + */ + int (*on_new_channels_folder)(struct liblttd_callbacks *data, + char *relative_folder_path); /** - * This callback is called after a subbuffer is a reserved. - * - * @attention It has to be thread safe, it'll be called by many threads. - * - * @args data This argument is a pointeur to the callbacks struct that - * has been passed to the lib. - * @args pair This structure contains the data associated with the - * channel file descriptor. The lib user should clean - * user_data at this time. - * @args len This argument represents the length the data that has to be - * read. - * - * @return Should return 0 if the callback succeeds else not 0. - */ - int(*on_read_subbuffer)(struct liblttd_callbacks *data, - struct fd_pair *pair, unsigned int len); + * on_read_subbuffer - Is called after a subbuffer is a reserved. + * + * @data: pointer to the callbacks structure that has been passed to the + * library. + * @pair: structure that contains the data associated with the channel + * file descriptor. + * @len: represents the length the data that has to be read. + * + * Returns 0 if the callback succeeds else not 0. + * + * It has to be thread safe, because it is called by many threads. + */ + int (*on_read_subbuffer)(struct liblttd_callbacks *data, + struct fd_pair *pair, unsigned int len); /** - * This callback is called at the very end of the tracing session. At - * this time, all the channels have been closed and the threads have been - * destroyed. - * - * @remarks After this callback is called, no other callback will be - * called again. - * - * @attention It has to be thread safe, it'll be called by many threads. - * - * @args data This argument is a pointeur to the callbacks struct that - * has been passed to the lib. - * - * @return Should return 0 if the callback succeeds else not 0. - */ - int(*on_trace_end)(struct liblttd_callbacks *data); + * on_trace_en - Is called at the very end of the tracing session. At + * this time, all the channels have been closed and the threads have + * been destroyed. + * + * @instance: pointer to the instance structure that has been passed to + * the library. + * + * Returns 0 if the callback succeeds else not 0. + * + * After this callback is called, no other callback will be called + * again and the tracing instance will be deleted automatically by + * liblttd. After this call, the user must not use the liblttd instance. + */ + int (*on_trace_end)(struct liblttd_instance *instance); /** - * This callback is called after a new thread has been created. - * - * @attention It has to be thread safe, it'll be called by many threads. - * - * @args data This argument is a pointeur to the callbacks struct that - * has been passed to the lib. - * @args thread_num This argument represents the id of the thread. - * - * @return Should return 0 if the callback succeeds else not 0. - */ - int(*on_new_thread)(struct liblttd_callbacks *data, - unsigned long thread_num); + * on_new_thread - Is called after a new thread has been created. + * + * @data: pointer to the callbacks structure that has been passed to the + * lib. + * @thread_num: represents the id of the thread. + * + * Returns 0 if the callback succeeds else not 0. + * + * It has to be thread safe, because it is called by many threads. + */ + int (*on_new_thread)(struct liblttd_callbacks *data, + unsigned long thread_num); /** - * This callback is called just before a thread is destroyed. - * - * @attention It has to be thread safe, it'll be called by many threads. - * - * @args data This argument is a pointeur to the callbacks struct that - * has been passed to the lib. - * @args thread_num This argument represents the number of the thread. - * - * @return Should return 0 if the callback succeeds else not 0. - */ - int(*on_close_thread)(struct liblttd_callbacks *data, - unsigned long thread_num); + * on_close_thread - Is called just before a thread is destroyed. + * + * @data: pointer to the callbacks structure that has been passed to the + * library. + * @thread_num: represents the number of the thread. + * + * Returns 0 if the callback succeeds else not 0. + * + * It has to be thread safe, because it is called by many threads. + */ + int (*on_close_thread)(struct liblttd_callbacks *data, + unsigned long thread_num); /** - * This is where the user can put the library's data. - */ + * The library's data. + */ void *user_data; }; /** -* This function is called to start a new tracing session. -* -* @attention It has to be thread safe, it'll be called by many threads. -* -* @args channel_path This argument is a path to the root folder of the trace's -* channels. -* @args n_threads This argument represents the number of threads that will be -* used by the library. -* @args flight_only If this argument to set to 1, only the channel that are in -* flight recorder mode will be recorded. -* @args normal_only If this argument to set to 1, only the channel that are in -* normal mode will be recorded. -* @args verbose If this argument to set to 1, more informations will be printed. -* @args user_data This argument is a pointeur to the callbacks struct that -* contains the user's functions. -* -* @return Return 0 if the function succeeds else not 0. -*/ -int liblttd_start(char *channel_path, unsigned long n_threads, - int flight_only, int normal_only, int verbose, - struct liblttd_callbacks *user_data); + * liblttd_new_instance - Is called to create a new tracing session. + * + * @callbacks: Pointer to a callbacks structure that contain the user + * callbacks and data. + * @channel_path: This argument is a path to the root folder of the trace's + * channels. + * @n_threads: This argument represents the number of threads that will be + * used by the library. + * @flight_only: If this argument to set to 1, only the channel that are in + * flight recorder mode will be recorded. + * @normal_only: If this argument to set to 1, only the channel that are in + * normal mode will be recorded. + * @verbose: If this argument to set to 1, more informations will be + * printed. + * + * Returns the instance if the function succeeds else NULL. + */ +struct liblttd_instance * +liblttd_new_instance(struct liblttd_callbacks *callbacks, char *channel_path, + unsigned long n_threads, int flight_only, int normal_only, + int verbose); /** -* This function is called to stop a tracing session. -* -* @return Return 0 if the function succeeds. -*/ -int liblttd_stop(); + * liblttd_start - Is called to start a new tracing session. + * + * @instance: The tracing session instance that needs to be started. + * + * Returns 0 if the function succeeds. + * + * This is a blocking function. The caller will be blocked on it until the + * tracing session is stopped by the user using liblttd_stop_instance or until + * the trace is stopped by LTTng directly. + */ +int liblttd_start_instance(struct liblttd_instance *instance); -#endif /*_LIBLTTD_H */ +/** + * liblttd_stop - Is called to stop a tracing session. + * + * @instance: The tracing session instance that needs to be stoped. + * + * Returns 0 if the function succeeds. + * + * This function returns immediately, it only tells liblttd to stop the + * instance. The on_trace_end callback will be called when the tracing session + * will really be stopped (after every thread has finished using it). The + * instance is deleted automatically by liblttd after on_trace_end is called. + */ +int liblttd_stop_instance(struct liblttd_instance *instance); +#endif /*_LIBLTTD_H */