Commit | Line | Data |
---|---|---|
20658947 FC |
1 | /******************************************************************************* |
2 | * Copyright (c) 2012 Ericsson | |
3 | * | |
4 | * All rights reserved. This program and the accompanying materials are | |
5 | * made available under the terms of the Eclipse Public License v1.0 which | |
6 | * accompanies this distribution, and is available at | |
7 | * http://www.eclipse.org/legal/epl-v10.html | |
8 | * | |
9 | * Contributors: | |
10 | * Francois Chouinard - Initial API and implementation | |
11 | *******************************************************************************/ | |
12 | ||
13 | package org.eclipse.linuxtools.tmf.core.trace; | |
14 | ||
15 | import org.eclipse.linuxtools.tmf.core.event.ITmfEvent; | |
16 | import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp; | |
9e0640dc | 17 | import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange; |
20658947 FC |
18 | |
19 | /** | |
9e0640dc | 20 | * The generic trace indexer in TMF with support for incremental indexing. |
f7703ed6 | 21 | * |
f7703ed6 FC |
22 | * @version 1.0 |
23 | * @author Francois Chouinard | |
24 | * | |
25 | * @see ITmfTrace | |
26 | * @see ITmfEvent | |
20658947 FC |
27 | */ |
28 | public interface ITmfTraceIndexer<T extends ITmfTrace<ITmfEvent>> { | |
29 | ||
30 | /** | |
31 | * Start an asynchronous index building job and waits for the job completion | |
32 | * if required. Typically, the indexing job sends notifications at regular | |
33 | * intervals to indicate its progress. | |
9e0640dc FC |
34 | * <p> |
35 | * <b>Example 1</b>: Index a whole trace asynchronously | |
36 | * <pre> | |
37 | * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, false); | |
38 | * </pre> | |
39 | * <b>Example 2</b>: Index a whole trace synchronously | |
40 | * <pre> | |
41 | * trace.getIndexer().buildIndex(0, TmfTimeRange.ETERNITY, true); | |
42 | * </pre> | |
43 | * <b>Example 3</b>: Index a trace asynchronously, starting at rank 100 | |
44 | * <pre> | |
45 | * trace.getIndexer().buildIndex(100, TmfTimeRange.ETERNITY, false); | |
46 | * </pre> | |
47 | * <b>Example 4</b>: Index a trace asynchronously, starting at rank 100 for events between | |
48 | * T1 and T2 (inclusive). This is used for incremental indexing. | |
49 | * <pre> | |
50 | * TmfTimeRange range = new TmfTimeRange(T1, T2); | |
51 | * trace.getIndexer().buildIndex(100, range, false); | |
52 | * </pre> | |
20658947 | 53 | * |
9e0640dc FC |
54 | * @param offset The offset of the first event to consider |
55 | * @param range The time range to consider | |
20658947 FC |
56 | * @param waitForCompletion |
57 | */ | |
9e0640dc FC |
58 | public void buildIndex(long offset, TmfTimeRange range, boolean waitForCompletion); |
59 | ||
60 | /** | |
61 | * Indicates that the indexer is busy indexing the trace. | |
62 | * Will always return false if the indexing is done synchronously. | |
63 | * | |
64 | * @return the state of the indexer (indexing or not) | |
65 | */ | |
66 | public boolean isIndexing(); | |
20658947 FC |
67 | |
68 | /** | |
69 | * Adds an entry to the trace index. | |
70 | * | |
71 | * @param context | |
20658947 FC |
72 | * @param timestamp |
73 | */ | |
d337369a | 74 | public void updateIndex(ITmfContext context, ITmfTimestamp timestamp); |
20658947 FC |
75 | |
76 | /** | |
77 | * Returns the context of the checkpoint immediately preceding the requested | |
78 | * timestamp (or at the timestamp if it coincides with a checkpoint). | |
79 | * | |
80 | * @param timestamp the requested timestamp | |
81 | * @return the checkpoint context | |
82 | */ | |
83 | public ITmfContext seekIndex(ITmfTimestamp timestamp); | |
84 | ||
85 | /** | |
86 | * Returns the context of the checkpoint immediately preceding the requested | |
87 | * rank (or at rank if it coincides with a checkpoint). | |
88 | * | |
89 | * @param rank the requested event rank | |
90 | * @return the checkpoint context | |
91 | */ | |
92 | public ITmfContext seekIndex(long rank); | |
93 | ||
b5ee6881 FC |
94 | /** |
95 | * Perform cleanup when the indexer is no longer required. | |
96 | */ | |
97 | public void dispose(); | |
98 | ||
20658947 | 99 | } |