← Back to branch summary

~ubuntu-branches/ubuntu/trusty/eclipse-linuxtools/trusty

« back to all changes in this revision

Viewing changes to lttng/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTrace.java

  • Committer: Package Import Robot
  • Author(s): Jakub Adam
  • Date: 2012-06-29 12:07:30 UTC
  • Revision ID: package-import@ubuntu.com-20120629120730-bfri1xys1i71dpn6
Tags: upstream-1.0.0
Import upstream version 1.0.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
lttng/org.eclipse.linuxtools.tmf.core/src/org/eclipse/linuxtools/tmf/core/trace/ITmfTrace.java
 
1
/*******************************************************************************
 
2
 * Copyright (c) 2009, 2011, 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
 *   Francois Chouinard - Updated as per TMF Trace Model 1.0
 
12
 *******************************************************************************/
 
13
 
 
14
package org.eclipse.linuxtools.tmf.core.trace;
 
15
 
 
16
import org.eclipse.core.resources.IProject;
 
17
import org.eclipse.core.resources.IResource;
 
18
import org.eclipse.linuxtools.tmf.core.component.ITmfDataProvider;
 
19
import org.eclipse.linuxtools.tmf.core.event.ITmfEvent;
 
20
import org.eclipse.linuxtools.tmf.core.event.ITmfTimestamp;
 
21
import org.eclipse.linuxtools.tmf.core.event.TmfTimeRange;
 
22
import org.eclipse.linuxtools.tmf.core.exceptions.TmfTraceException;
 
23
 
 
24
/**
 
25
 * The event stream structure in TMF. In its basic form, a trace has:
 
26
 * <ul>
 
27
 * <li> an associated Eclipse resource
 
28
 * <li> a path to its location on the file system
 
29
 * <li> the type of the events it contains
 
30
 * <li> the number of events it contains
 
31
 * <li> the time range (span) of the events it contains
 
32
 * </ul>
 
33
 * Concrete ITmfTrace classes have to provide a parameter-less constructor and
 
34
 * an initialization method (<i>initTrace</i>) if they are to be opened from
 
35
 * the Project View. Also, a validation method (<i>validate</i>) has to be 
 
36
 * provided to ensure that the trace is of the correct type.
 
37
 * <p>
 
38
 * A trace can be accessed simultaneously from multiple threads by various
 
39
 * application components. To avoid obvious multi-threading issues, the trace
 
40
 * uses an ITmfContext as a synchronization aid for its read operations.
 
41
 * <p>
 
42
 * A proper ITmfContext can be obtained by performing a seek operation on the
 
43
 * trace. Seek operations can be performed for a particular event (by rank or
 
44
 * timestamp) or for a plain trace location.
 
45
 * <p>
 
46
 * <b>Example 1</b>: Process a whole trace
 
47
 * <pre>
 
48
 * ITmfContext context = trace.seekEvent(0);
 
49
 * ITmfEvent event = trace.getNext(context);
 
50
 * while (event != null) {
 
51
 *     processEvent(event);
 
52
 *     event = trace.getNext(context);
 
53
 * }
 
54
 * </pre>
 
55
 * <b>Example 2</b>: Process 50 events starting from the 1000th event
 
56
 * <pre>
 
57
 * int nbEventsRead = 0;
 
58
 * ITmfContext context = trace.seekEvent(1000);
 
59
 * ITmfEvent event = trace.getNext(context);
 
60
 * while (event != null && nbEventsRead < 50) {
 
61
 *     nbEventsRead++;
 
62
 *     processEvent(event);
 
63
 *     event = trace.getNext(context);
 
64
 * }
 
65
 * </pre>
 
66
 * <b>Example 3</b>: Process the events between 2 timestamps (inclusive)
 
67
 * <pre>
 
68
 * ITmfTimestamp startTime = ...;
 
69
 * ITmfTimestamp endTime = ...;
 
70
 * ITmfContext context = trace.seekEvent(startTime);
 
71
 * ITmfEvent event = trace.getNext(context);
 
72
 * while (event != null && event.getTimestamp().compareTo(endTime) <= 0) {
 
73
 *     processEvent(event);
 
74
 *     event = trace.getNext(context);
 
75
 * }
 
76
 * </pre>
 
77
 * A trace is also an event provider so it can process event requests
 
78
 * asynchronously (and coalesce compatible, concurrent requests).
 
79
 * <p>
 
80
 * </pre>
 
81
 * <b>Example 4</b>: Process a whole trace (see ITmfEventRequest for variants)
 
82
 * <pre>
 
83
 * ITmfRequest request = new TmfEventRequest&lt;MyEventType&gt;(MyEventType.class) {
 
84
 *     &#64;Override
 
85
 *     public void handleData(MyEventType event) {
 
86
 *         super.handleData(event);
 
87
 *         processEvent(event);
 
88
 *     }
 
89
 *     &#64;Override
 
90
 *     public void handleCompleted() {
 
91
 *         finish();
 
92
 *         super.handleCompleted();
 
93
 *     }
 
94
 * };
 
95
 * 
 
96
 * fTrace.handleRequest(request);
 
97
 * if (youWant) {
 
98
 *     request.waitForCompletion();
 
99
 * } 
 
100
 * </pre>
 
101
 * 
 
102
 * @version 1.0
 
103
 * @author Francois Chouinard
 
104
 * 
 
105
 * @see ITmfContext
 
106
 * @see ITmfEvent
 
107
 * @see ITmfTraceIndexer
 
108
 * @see ITmfEventParser
 
109
 */
 
110
public interface ITmfTrace<T extends ITmfEvent> extends ITmfDataProvider<T> {
 
111
 
 
112
    // ------------------------------------------------------------------------
 
113
    // Constants
 
114
    // ------------------------------------------------------------------------
 
115
 
 
116
    /**
 
117
     * The default trace cache size
 
118
     */
 
119
    public static final int DEFAULT_TRACE_CACHE_SIZE = 1000;
 
120
 
 
121
    // ------------------------------------------------------------------------
 
122
    // Initializers
 
123
    // ------------------------------------------------------------------------
 
124
 
 
125
    /**
 
126
     * Initialize a newly instantiated "empty" trace object. This is used to
 
127
     * properly parameterize an ITmfTrace instantiated with its parameterless
 
128
     * constructor.
 
129
     * <p>
 
130
     * Typically, the parameterless constructor will provide the block size
 
131
     * and its associated parser and indexer.
 
132
     * 
 
133
     * @param resource the trace resource
 
134
     * @param path the trace path
 
135
     * @param type the trace event type
 
136
     * @throws TmfTraceException
 
137
     */
 
138
    public void initTrace(IResource resource, String path, Class<T> type) throws TmfTraceException;
 
139
 
 
140
    /**
 
141
     * Validate that the trace is of the correct type.
 
142
     * 
 
143
     * @param project the eclipse project
 
144
     * @param path the trace path
 
145
     * 
 
146
     * @return true if trace is valid
 
147
     */
 
148
    public boolean validate(IProject project, String path);
 
149
 
 
150
    // ------------------------------------------------------------------------
 
151
    // Basic getters
 
152
    // ------------------------------------------------------------------------
 
153
 
 
154
    /**
 
155
     * @return the trace event type
 
156
     */
 
157
    public Class<T> getEventType();
 
158
 
 
159
    /**
 
160
     * @return the associated trace resource
 
161
     */
 
162
    public IResource getResource();
 
163
 
 
164
    /**
 
165
     * @return the trace path
 
166
     */
 
167
    public String getPath();
 
168
 
 
169
    /**
 
170
     * @return the trace cache size
 
171
     */
 
172
    public int getCacheSize();
 
173
 
 
174
    // ------------------------------------------------------------------------
 
175
    // Trace characteristics getters
 
176
    // ------------------------------------------------------------------------
 
177
 
 
178
    /**
 
179
     * @return the number of events in the trace
 
180
     */
 
181
    public long getNbEvents();
 
182
 
 
183
    /**
 
184
     * @return the trace time range
 
185
     */
 
186
    public TmfTimeRange getTimeRange();
 
187
 
 
188
    /**
 
189
     * @return the timestamp of the first trace event
 
190
     */
 
191
    public ITmfTimestamp getStartTime();
 
192
 
 
193
    /**
 
194
     * @return the timestamp of the last trace event
 
195
     */
 
196
    public ITmfTimestamp getEndTime();
 
197
 
 
198
    /**
 
199
     * @return the streaming interval in ms (0 if not a streaming trace)
 
200
     */
 
201
    public long getStreamingInterval();
 
202
 
 
203
    // ------------------------------------------------------------------------
 
204
    // Trace positioning getters
 
205
    // ------------------------------------------------------------------------
 
206
 
 
207
    /**
 
208
     * @return the current trace location
 
209
     */
 
210
    public ITmfLocation<?> getCurrentLocation();
 
211
 
 
212
    /**
 
213
     * Returns the ratio (proportion) corresponding to the specified location.
 
214
     * 
 
215
     * @param location a trace specific location
 
216
     * @return a floating-point number between 0.0 (beginning) and 1.0 (end)
 
217
     */
 
218
    public double getLocationRatio(ITmfLocation<?> location);
 
219
 
 
220
    // ------------------------------------------------------------------------
 
221
    // SeekEvent operations (returning a trace context)
 
222
    // ------------------------------------------------------------------------
 
223
 
 
224
    /**
 
225
     * Position the trace at the specified (trace specific) location.
 
226
     * <p>
 
227
     * A null location is interpreted as seeking for the first event of the
 
228
     * trace.
 
229
     * <p>
 
230
     * If not null, the location requested must be valid otherwise the returned
 
231
     * context is undefined (up to the implementation to recover if possible).
 
232
     * <p>
 
233
     * @param location the trace specific location
 
234
     * @return a context which can later be used to read the corresponding event
 
235
     */
 
236
    public ITmfContext seekEvent(ITmfLocation<?> location);
 
237
 
 
238
    /**
 
239
     * Position the trace at the 'rank'th event in the trace.
 
240
     * <p>
 
241
     * A rank <= 0 is interpreted as seeking for the first event of the
 
242
     * trace.
 
243
     * <p>
 
244
     * If the requested rank is beyond the last trace event, the context
 
245
     * returned will yield a null event if used in a subsequent read.
 
246
     * 
 
247
     * @param rank the event rank
 
248
     * @return a context which can later be used to read the corresponding event
 
249
     */
 
250
    public ITmfContext seekEvent(long rank);
 
251
 
 
252
    /**
 
253
     * Position the trace at the first event with the specified timestamp. If
 
254
     * there is no event with the requested timestamp, a context pointing to
 
255
     * the next chronological event is returned.
 
256
     * <p>
 
257
     * A null timestamp is interpreted as seeking for the first event of the
 
258
     * trace.
 
259
     * <p>
 
260
     * If the requested timestamp is beyond the last trace event, the context
 
261
     * returned will yield a null event if used in a subsequent read.
 
262
     * 
 
263
     * @param timestamp the timestamp of desired event
 
264
     * @return a context which can later be used to read the corresponding event
 
265
     */
 
266
    public ITmfContext seekEvent(ITmfTimestamp timestamp);
 
267
 
 
268
    /**
 
269
     * Position the trace at the event located at the specified ratio in the
 
270
     * trace file.
 
271
     * <p>
 
272
     * The notion of ratio (0.0 <= r <= 1.0) is trace specific and left
 
273
     * voluntarily vague. Typically, it would refer to the event proportional
 
274
     * rank (arguably more intuitive) or timestamp in the trace file.
 
275
     * 
 
276
     * @param ratio the proportional 'rank' in the trace
 
277
     * @return a context which can later be used to read the corresponding event
 
278
     */
 
279
    public ITmfContext seekEvent(double ratio);
 
280
 
 
281
}