X-Git-Url: https://git.lttng.org/?p=ltt-control.git;a=blobdiff_plain;f=liblttd%2Fliblttd.h;h=02e7e9ce178056f52b3aecf8ed124741a83199f4;hp=bd76eeb58cc7e68053ac53cb582b94177b039766;hb=d6d516b717dfb30a882178494203bf4ceb4810fe;hpb=008e25154ca2db688516bafcb134c984f08a5f10 diff --git a/liblttd/liblttd.h b/liblttd/liblttd.h index bd76eeb..02e7e9c 100644 --- a/liblttd/liblttd.h +++ b/liblttd/liblttd.h @@ -23,196 +23,192 @@ #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 + */ 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; }; +struct liblttd_instance; + /** -* 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_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. - */ + * on_open_channel - Is called after a channel file is open. + * @data: pointeur to the callbacks struct that has been passed to the + * lib. + * @pair: structure that 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. + * @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. - */ + * on_close_channel - Is called after a channel file is closed. + * @data: pointeur to the callbacks struct 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. - */ + * 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: pointeur to the callbacks struct that has been passed to the + * lib. + * @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. - */ + * on_read_subbuffer - Is called after a subbuffer is a reserved. + * + * @data: pointeur to the callbacks struct that has been passed to the + * lib. + * @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, it'll be 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. - */ + * 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. + * + * @data: pointeur to the callbacks struct that has been passed to the + * lib. + * + * Returns 0 if the callback succeeds else not 0. + * + * It has to be thread safe, it'll be called by many threads. + * 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_callbacks *data); /** - * 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. - */ + * on_new_thread - Is called after a new thread has been created. + * + * @data: pointeur to the callbacks struct 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, it'll be 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. - */ + * on_close_thread - Is Called just before a thread is destroyed. + * + * @data: pointeur to the callbacks struct that has been passed to the + * lib. + * @thread_num: represents the number of the thread. + * + * Returns 0 if the callback succeeds else not 0. + * + * It has to be thread safe, it'll be 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 struct 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 starded. + * + * Returns 0 if the function succeeds. + * + * This is a blocking function. The caller will be bloked on it until the + * tracing session is stoped by the user usign liblttd_stop_instance or until + * the trace is stoped by LTTng directly. + */ +int liblttd_start_instance(struct liblttd_instance *instance); + +/** + * 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 return immediately, it only tells liblttd to stop the instance. + * The on_trace_end callback will be called when the tracing session will really + * be stoped (after every thread will be done). The instance is deleted + * automatically by liblttd after on_trace_end is called. + */ +int liblttd_stop_instance(struct liblttd_instance *instance); #endif /*_LIBLTTD_H */