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

   1 /*******************************************************************************
   2  * Copyright (c) 2016 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
  11 package org.eclipse.tracecompass.tmf.ui.symbols;
  12
  13 import org.eclipse.core.runtime.IProgressMonitor;
  14 import org.eclipse.jdt.annotation.NonNull;
  15 import org.eclipse.jdt.annotation.Nullable;
  16 import org.eclipse.tracecompass.tmf.core.event.lookup.ITmfCallsite;
  17 import org.eclipse.tracecompass.tmf.core.trace.ITmfTrace;
  18 import org.eclipse.tracecompass.tmf.core.trace.TmfTrace;
  19
  20 /**
  21  * An ISymbolProvider is used to map symbol addresses that might be found inside
  22  * an {@link TmfTrace} into human readable strings.
  23  *
  24  * @author Robert Kiss
  25  * @since 2.0
  26  * @see ISymbolProviderFactory
  27  */
  28 public interface ISymbolProvider {
  29
  30     /**
  31      * @return the trace that this class resolves symbols for
  32      */
  33     @NonNull ITmfTrace getTrace();
  34
  35     /**
  36      * Some providers might have configurations that take some time to load. All
  37      * the CPU intensive load operations shall be done in this method. The
  38      * adopters shall call this method at an opportune moment when cancellation
  39      * and UI feedback is possible. However, the implementors of this interface
  40      * shall not assume that this method has been called.
  41      *
  42      * @param monitor
  43      *            The progress monitor to use, can be null
  44      */
  45     void loadConfiguration(IProgressMonitor monitor);
  46
  47     /**
  48      * Return the symbol text corresponding to the given address or null if
  49      * there is no such symbol
  50      *
  51      * @param address
  52      *            the address of the symbol
  53      * @return the symbol text or null if the symbol cannot be found
  54      */
  55     @Nullable String getSymbolText(long address);
  56
  57     /**
  58      * Return additional information regarding the symbol from the given address
  59      * or null if the symbol cannot be found
  60      *
  61      * @param address
  62      *            the address of the symbol
  63      * @return the symbol {@link ITmfCallsite} information or null if the symbol
  64      *         cannot be found
  65      */
  66     @Nullable ITmfCallsite getSymbolInfo(long address);
  67
  68     /**
  69      * Return the symbol text corresponding to the given pid/timestamp/address
  70      * tuple, or null if there is no such symbol.
  71      *
  72      * @param pid
  73      *            The process Id for which to query
  74      * @param timestamp
  75      *            The timestamp of the query
  76      * @param address
  77      *            the address of the symbol
  78      * @return the symbol text or null if the symbol cannot be found
  79      */
  80     default @Nullable String getSymbolText(int pid, long timestamp, long address) {
  81         return getSymbolText(address);
  82     }
  83
  84     /**
  85      * Return additional information regarding the symbol from the given
  86      * pid/timestamp/address tuple, or null if the symbol cannot be found.
  87      *
  88      * @param pid
  89      *            The process Id for which to query
  90      * @param timestamp
  91      *            The timestamp of the query
  92      * @param address
  93      *            the address of the symbol
  94      * @return the symbol {@link ITmfCallsite} information or null if the symbol
  95      *         cannot be found
  96      */
  97     default @Nullable ITmfCallsite getSymbolInfo(int pid, long timestamp, long address) {
  98         return getSymbolInfo(address);
  99     }
 100
 101     /**
 102      * Create the {@link ISymbolProviderPreferencePage} that can be used to
 103      * configure this {@link ISymbolProvider}
 104      *
 105      * @return the {@link ISymbolProviderPreferencePage} or null if this symbol
 106      *         provider does not offer a configuration UI
 107      */
 108     @Nullable ISymbolProviderPreferencePage createPreferencePage();
 109
 110 }