tmf/org.eclipse.tracecompass.tmf.core/src/org/eclipse/tracecompass/tmf/core/symbols/ISymbolProvider.java

   1 /*******************************************************************************
   2  * Copyright (c) 2016-2017 Movidius Inc. and others
   3  *
   4  * All rights reserved. This program and the accompanying materials
   5  * are made available under the terms of the Eclipse Public License v1.0
   6  * which accompanies this distribution, and is available at
   7  * http://www.eclipse.org/legal/epl-v10.html
   8  *******************************************************************************/
   9
  10 package org.eclipse.tracecompass.tmf.core.symbols;
  11
  12 import org.eclipse.core.runtime.IProgressMonitor;
  13 import org.eclipse.jdt.annotation.Nullable;
  14 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
  15 import org.eclipse.tracecompass.tmf.core.trace.TmfTrace;
  16
  17 /**
  18  * An ISymbolProvider is used to map symbol addresses that might be found inside
  19  * an {@link TmfTrace} into human readable strings.
  20  *
  21  * @author Matthew Khouzam
  22  * @author Robert Kiss
  23  * @since 2.4
  24  */
  25 public interface ISymbolProvider {
  26
  27     /**
  28      * @return the trace that this class resolves symbols for
  29      */
  30     ITmfTrace getTrace();
  31
  32     /**
  33      * Some providers might have configurations that take some time to load. All
  34      * the CPU intensive load operations shall be done in this method. The
  35      * adopters shall call this method at an opportune moment when cancellation
  36      * and UI feedback is possible. However, the implementors of this interface
  37      * shall not assume that this method has been called.
  38      *
  39      * @param monitor
  40      *            The progress monitor to use, can be null
  41      */
  42     void loadConfiguration(@Nullable IProgressMonitor monitor);
  43
  44     /**
  45      * Return the symbol text corresponding to the given address or null if
  46      * there is no such symbol
  47      *
  48      * @param address
  49      *            the address of the symbol
  50      * @return the symbol text or <code>null</code> if the symbol cannot be found
  51      */
  52     @Nullable String getSymbolText(long address);
  53
  54     /**
  55      * Return the symbol text corresponding to the given pid/timestamp/address
  56      * tuple, or null if there is no such symbol. An implementation that does
  57      * not support pid and timestamp should return the symbol based on address
  58      * only.
  59      *
  60      * A caller that has pid and timestamp information should call this method.
  61      * {@link #getSymbolText(long)} should only be invoked by callers that do
  62      * not have access to the pid and timestamp.
  63      *
  64      * @param pid
  65      *            The process Id for which to query
  66      * @param timestamp
  67      *            The timestamp of the query
  68      * @param address
  69      *            the address of the symbol
  70      * @return the symbol text or <code>null</code> if the symbol cannot be
  71      *         found
  72      */
  73     default @Nullable String getSymbolText(int pid, long timestamp, long address) {
  74         return getSymbolText(address);
  75     }
  76 }