/* 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
#include <ltt/time.h>
#include <glib.h>
+#include <gtk/gtk.h>
typedef GQuark LttvTraceInfo;
LTTV_REQUESTS_QUEUE,
LTTV_REQUESTS_CURRENT,
LTTV_NOTIFY_QUEUE,
- LTTV_NOTIFY_CURRENT;
+ 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,
+ LTTV_AFTER_CHUNK_TRACESET,
+ LTTV_AFTER_CHUNK_TRACE,
+ LTTV_AFTER_CHUNK_TRACEFILE,
+ LTTV_BEFORE_REQUEST,
+ LTTV_AFTER_REQUEST,
+ LTTV_EVENT_HOOK,
+ LTTV_EVENT_HOOK_BY_ID,
+ LTTV_HOOK_ADDER,
+ LTTV_HOOK_REMOVER,
+ LTTV_IN_PROGRESS,
+ LTTV_READY,
+ LTTV_LOCK;
+
+
/* Get a trace by its path name.
*
*
* The memory allocated for the request will be managed by the API.
*
+ * @param tab parent Window
* @param trace the trace to compute
* @param module_name the name of the module which registered global computation
* hooks.
*/
void lttvwindowtraces_background_request_queue
- (LttvTrace *trace, gchar *module_name);
+ (GtkWidget *widget, LttvTrace *trace, gchar *module_name);
/**
* Remove a background request from a trace.
void lttvwindowtraces_background_request_remove
(LttvTrace *trace, gchar *module_name);
+
+
+/**
+ * Find a background request in a trace
+ *
+ */
+
+gboolean lttvwindowtraces_background_request_find
+ (LttvTrace *trace, gchar *module_name);
+
/**
* Register a callback to be called when requested data is passed in the next
* queued background processing.
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
projects / lttv.git / blobdiff