X-Git-Url: http://git.lttng.org./?a=blobdiff_plain;f=ltt%2Fbranches%2Fpoly%2Flttv%2Fmodules%2Fgui%2Flttvwindow%2Flttvwindow%2Flttvwindowtraces.h;h=8de3ba357694bedbe8db68dd5b6c4028494b14b7;hb=bf33dd5091178cd0ad175b1914d74056db60e7af;hp=a7d6d81feab41302e7f08b760b61651620edee23;hpb=8bc02ec867a018f18cda9fe362f8e49ca6db7c81;p=lttv.git diff --git a/ltt/branches/poly/lttv/modules/gui/lttvwindow/lttvwindow/lttvwindowtraces.h b/ltt/branches/poly/lttv/modules/gui/lttvwindow/lttvwindow/lttvwindowtraces.h index a7d6d81f..8de3ba35 100644 --- a/ltt/branches/poly/lttv/modules/gui/lttvwindow/lttvwindow/lttvwindowtraces.h +++ b/ltt/branches/poly/lttv/modules/gui/lttvwindow/lttvwindow/lttvwindowtraces.h @@ -18,6 +18,53 @@ /* This file is the API used to launch any background computation on a trace */ +/* lttvwindowtraces + * + * This API consists in two main parts. The first one is for the background + * computation provider and the second is for the viewer which needs this + * information. + * + * A computation provider, i.e. a statistics computation module or a state + * computation module, have two things in common : they append data to a trace + * in an extensible container (LttvAttributes). This extended information, once + * computed, can be kept all along with the trace and does not need to be + * recomputed : a computation done on a trace must result in a identical result + * each time it is done. + * + * This API provides functions for computation provider to register their + * computation functions (or computation functions insertion and removal + * functions). Once the computation provider is registered with its module name, + * extended computation for a trace can be requested by any viewer by specifying + * the module name, as we will describe in a moment. + * + * A viewer which needs extended information about a trace must ask for it to be + * computed by doing a background computation request. It may also ask to be + * notified of the completion of its request by doing a notify request. + * + * Before asking for the computation, it must check for its readiness. If it is + * ready, the information has already been computed, so it is ready to use. If + * the information is not ready, in must check whether or not the processing of + * this task is in progress. If it is, it must not do any background computation + * request. It must only do a background notification request of the current + * processing to be informed of its completion. If the information is not ready + * and not being processed, then the viewer may do a background computation + * request and add a notify request to the notify queue. + * + * When a context takes control of a trace, it must lock the trace. This is a + * way of ensuring that not conflict will occur between two traceset contexts + * and shared traces. It will generate an error if a context try to get a lock + * on a trace what is not unlocked. Upon every trace locking, + * lttv_process_traceset_synchronize_tracefiles should be used to resynchronize + * the traces with the trace context information. + * + * The usefulness of the lock in this framework can be questionable in a + * single threaded environment, but can be great in the eventuality of + * multiple threads. + * + */ + + + #ifndef LTTVWINDOWTRACES_H #define LTTVWINDOWTRACES_H @@ -34,6 +81,7 @@ extern LttvTraceInfo LTTV_TRACES, LTTV_NOTIFY_CURRENT, LTTV_COMPUTATION_TRACESET, LTTV_COMPUTATION_TRACESET_CONTEXT, + LTTV_COMPUTATION_SYNC_POSITION, LTTV_BEFORE_CHUNK_TRACESET, LTTV_BEFORE_CHUNK_TRACE, LTTV_BEFORE_CHUNK_TRACEFILE, @@ -44,8 +92,11 @@ extern LttvTraceInfo LTTV_TRACES, LTTV_AFTER_REQUEST, LTTV_EVENT_HOOK, LTTV_EVENT_HOOK_BY_ID, + LTTV_HOOK_ADDER, + LTTV_HOOK_REMOVER, LTTV_IN_PROGRESS, - LTTV_READY; + LTTV_READY, + LTTV_LOCK; @@ -153,4 +204,106 @@ void lttvwindowtraces_background_notify_current void lttvwindowtraces_background_notify_remove(gpointer owner); +/** + * Tells if the information computed by a module for a trace is ready. + * + * Must be checked before a background processing request. + * + * @param module_name A GQuark : the name of the module which computes the + * information. + * @param trace The trace for which the information is verified. + */ + +gboolean lttvwindowtraces_get_ready(LttvAttributeName module_name, + LttvTrace *trace); + +/** + * Tells if the information computed by a module for a trace is being processed. + * + * Must be checked before a background processing request. + * + * If it is effectively processed, the typical thing to do is to call + * lttvwindowtraces_background_notify_current to be notified when the current + * processing will be over. + * + * @param module_name A GQuark : the name of the module which computes the + * information. + * @param trace The trace for which the information is verified. + */ + +gboolean lttvwindowtraces_get_in_progress(LttvAttributeName module_name, + LttvTrace *trace); + +/** + * Register the background computation hooks for a specific module. It adds the + * computation hooks to the global attrubutes, under "computation/module name" + * + * @param module_name A GQuark : the name of the module which computes the + * information. + */ +void lttvwindowtraces_register_computation_hooks(LttvAttributeName module_name, + LttvHooks *before_chunk_traceset, + LttvHooks *before_chunk_trace, + LttvHooks *before_chunk_tracefile, + LttvHooks *after_chunk_traceset, + LttvHooks *after_chunk_trace, + LttvHooks *after_chunk_tracefile, + LttvHooks *before_request, + LttvHooks *after_request, + LttvHooks *event_hook, + LttvHooksById *event_hook_by_id, + LttvHooks *hook_adder, + LttvHooks *hook_remover); +/** + * Unregister the background computation hooks for a specific module. + * + * It also removes all the requests than can be currently processed by the + * background computation algorithm for all the traces (list_in and list_out). + * + * @param module_name A GQuark : the name of the module which computes the + * information. + */ + +void lttvwindowtraces_unregister_computation_hooks + (LttvAttributeName module_name); + + +/** + * It removes all the requests than can be currently processed by the + * background computation algorithm for all the traces (list_in and list_out). + * + * Leaves the flag to in_progress or none.. depending if current or queue + * + * @param module_name A GQuark : the name of the module which computes the + * information. + */ +void lttvwindowtraces_unregister_requests(LttvAttributeName module_name); + + +/** + * Lock a trace so no other instance can use it. + * + * @param trace The trace to lock. + * @return 0 on success, -1 if cannot get lock. + */ +gint lttvwindowtraces_lock(LttvTrace *trace); + + +/** + * Unlock a trace. + * + * @param trace The trace to unlock. + * @return 0 on success, -1 if cannot unlock (not locked ?). + */ +gint lttvwindowtraces_unlock(LttvTrace *trace); + +/** + * Verify if a trace is locked. + * + * @param trace The trace to verify. + * @return TRUE if locked, FALSE is unlocked. + */ +gint lttvwindowtraces_get_lock_state(LttvTrace *trace); + + #endif //LTTVWINDOWTRACES_H