Package org.eclipse.cdt.core.index

Interface IIndex

public interface IIndex
Interface for accessing the index for one or more projects.
Since:
4.0
Restriction:
This interface is not intended to be implemented by clients.
Restriction:
This interface is not intended to be extended by clients.

  • Field Details

    • DEPTH_INFINITE

      static final int DEPTH_INFINITE
      Constant to specify infinite depth.
      See Also:

    • DEPTH_ZERO

      static final int DEPTH_ZERO
      Constant to find direct includes, only.
      See Also:

    • FIND_DECLARATIONS

      static final int FIND_DECLARATIONS
      Constant to search for declarations. This does not include definitions.
      See Also:

    • FIND_DEFINITIONS

      static final int FIND_DEFINITIONS
      Constant to search for definitions. This does not include declarations.
      See Also:

    • FIND_REFERENCES

      static final int FIND_REFERENCES
      Constant to search for references. This does not include declarations or definitions.
      See Also:

    • SEARCH_ACROSS_LANGUAGE_BOUNDARIES

      static final int SEARCH_ACROSS_LANGUAGE_BOUNDARIES
      Constant to search for occurrences across language boundaries. Can be used to find the occurrences of a C++-function declared with 'extern "C"' within the c-linkage.
      See Also:

    • FIND_POTENTIAL_MATCHES

      static final int FIND_POTENTIAL_MATCHES
      Constant to include potential matches in the results of a search. An example of a potential match might be a function definition that does match a declaration exactly in signature.
      Since:
      6.5
      See Also:

    • FIND_DECLARATIONS_DEFINITIONS

      static final int FIND_DECLARATIONS_DEFINITIONS
      Constant to search for all declarations including definitions.
      See Also:

    • FIND_ALL_OCCURRENCES

      static final int FIND_ALL_OCCURRENCES
      Constant to search for all occurrences of a binding. This includes declarations, definitions and references.
      See Also:

  • Method Details

    • acquireReadLock

      void acquireReadLock() throws InterruptedException
      Before making calls to an index you have to obtain a lock. The objects returned by an index become invalid as soon as the indexer writes to the index. You may obtain nested read locks. Make sure you release the lock.
      Throws:
      InterruptedException
      See Also:

    • releaseReadLock

      void releaseReadLock()
      Any lock obtained by acquireReadLock() must be released.

    • hasWaitingReaders

      boolean hasWaitingReaders()
      Returns:
      true if there are threads waiting for read locks.
      Since:
      5.2

    • getLastWriteAccess

      long getLastWriteAccess()
      Returns a timestamp of when the index was last written to. This can be used to figure out whether information read from the index is still reliable or not. 
       long timestamp;
 IBinding binding= null;
 index.acquireReadLock();
 try {
    timestamp= index.getLastWriteAccess();
    binding= index.findBinding(...);
 } finally {
    index.releaseReadLock();
 }
 ...
 index.acqureReadLock();
 try {
    if (index.getLastWriteAccess() != timestamp) {
       // don't use binding, it's not valid anymore
       binding= index.findBinding(...);
    }
    String name= binding.getName();
    ...
 } finally {
    index.releaseReadLock();
 }

    • getFile

      @Deprecated IIndexFile getFile(int linkageID, IIndexFileLocation location) throws org.eclipse.core.runtime.CoreException
      Deprecated.
      Use getFile(int, IIndexFileLocation, ISignificantMacros) or getFiles(int, IIndexFileLocation).
      Throws:
      org.eclipse.core.runtime.CoreException
      Restriction:
      This method is not intended to be referenced by clients.

    • getFile

      IIndexFile getFile(int linkageID, IIndexFileLocation location, ISignificantMacros significantMacros) throws org.eclipse.core.runtime.CoreException
      Returns the file for the given location, linkage, and significant macros May return null, if no such file exists.
      Parameters:
      linkageID - the id of the linkage in which the file has been parsed.
      location - the IIndexFileLocation representing the location of the file
      significantMacros - The names and definitions of the macros used to disambiguate between variants of the file contents corresponding to different inclusion points.
      Returns:
      the file for the location, or null if the file is not present in the index
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      5.4

    • getFiles

      IIndexFile[] getFiles(int linkageID, IIndexFileLocation location) throws org.eclipse.core.runtime.CoreException
      Returns the file objects for the given location and linkage. Multiple files are returned when a header file is stored in the index in multiple variants for different sets of macro definitions. This method may only return files that are actually managed by this fragment. This method returns files without content, also.
      Parameters:
      linkageID - the id of the linkage in which the file has been parsed.
      location - the IIndexFileLocation representing the location of the file
      Returns:
      the files for the location and the linkage.
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      5.4

    • getFiles

      IIndexFile[] getFiles(IIndexFileLocation location) throws org.eclipse.core.runtime.CoreException
      Returns the file objects for the given location in any linkage.
      Parameters:
      location - an IIndexFileLocation representing the location of the file
      Returns:
      an array of file-objects.
      Throws:
      org.eclipse.core.runtime.CoreException

    • findIncludes

      IIndexInclude[] findIncludes(IIndexFile file) throws org.eclipse.core.runtime.CoreException
      Looks for include relations originated by the given file. This is the same as 
       findIncludes(file, DEPTH_ZERO);
      Parameters:
      file - the file containing the include directives
      Returns:
      an array of include relations
      Throws:
      org.eclipse.core.runtime.CoreException

    • findIncludedBy

      IIndexInclude[] findIncludedBy(IIndexFile file) throws org.eclipse.core.runtime.CoreException
      Looks for include relations pointing to the given file. This is the same as 
       findIncludedBy(file, DEPTH_ZERO);
      Parameters:
      file - the file included by the directives to be found
      Returns:
      an array of include relations
      Throws:
      org.eclipse.core.runtime.CoreException

    • findIncludes

      IIndexInclude[] findIncludes(IIndexFile file, int depth) throws org.eclipse.core.runtime.CoreException
      Looks recursively for include relations originated by the given file.
      Parameters:
      file - the file containing the include directives
      depth - depth to which includes are followed, should be one of DEPTH_ZERO or DEPTH_INFINITE
      Returns:
      an array of include relations
      Throws:
      org.eclipse.core.runtime.CoreException

    • findIncludedBy

      IIndexInclude[] findIncludedBy(IIndexFile file, int depth) throws org.eclipse.core.runtime.CoreException
      Looks recursively for include relations pointing to the given file.
      Parameters:
      file - the file the include directives point to
      depth - depth to which includes are followed, should be one of DEPTH_ZERO or DEPTH_INFINITE
      Returns:
      an array of include relations
      Throws:
      org.eclipse.core.runtime.CoreException

    • resolveInclude

      IIndexFile resolveInclude(IIndexInclude include) throws org.eclipse.core.runtime.CoreException
      Resolves the file that is included by the given include directive. May return null in case the file cannot be found. This is usually more efficient than using: 
       getFiles(include.getIncludesLocation())
      Parameters:
      include -
      Returns:
      the file included or null.
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      4.0

    • findMacros

      IIndexMacro[] findMacros(char[] name, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches for all macros with a given name.
      Parameters:
      name - a name, that has to be matched by the macros.
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor to report progress, may be null.
      Returns:
      an array of macros matching the name.
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      4.0.2

    • findMacrosForPrefix

      IIndexMacro[] findMacrosForPrefix(char[] prefix, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches for all macros with names that start with the given prefix.
      Parameters:
      prefix - the prefix with which all returned macros must start
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor for progress reporting and cancellation, may be null
      Returns:
      an array of bindings with the prefix
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      4.0.2

    • findBinding

      IIndexBinding findBinding(IName name) throws org.eclipse.core.runtime.CoreException
      Searches for the binding of a name. The name may be originated by an AST or by a search in an index. May return null.
      Parameters:
      name - a name to find the binding for
      Returns:
      the binding or null
      Throws:
      org.eclipse.core.runtime.CoreException

    • findBindings

      IIndexBinding[] findBindings(Pattern pattern, boolean isFullyQualified, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches for all bindings with simple names that match the given pattern. In case a binding exists in multiple projects, no duplicate bindings are returned. This is fully equivalent to 
       findBindings(new Pattern[] {pattern}, isFullyQualified, filter, monitor);
      Parameters:
      pattern - the pattern the name of the binding has to match.
      isFullyQualified - if true, binding must be in global scope
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor to report progress, may be null.
      Returns:
      an array of bindings matching the pattern
      Throws:
      org.eclipse.core.runtime.CoreException

    • findBindings

      IIndexBinding[] findBindings(Pattern[] patterns, boolean isFullyQualified, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches for all bindings with qualified names that seen as an array of simple names match the given array of patterns. In case a binding exists in multiple projects, no duplicate bindings are returned. You can search with an array of patterns that specifies a partial qualification only.
      Parameters:
      patterns - an array of patterns the components of the qualified name of the bindings have to match.
      isFullyQualified - if true, the array of pattern specifies the fully qualified name
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor to report progress, may be null.
      Returns:
      an array of bindings matching the pattern
      Throws:
      org.eclipse.core.runtime.CoreException

    • findMacroContainers

      IIndexBinding[] findMacroContainers(Pattern pattern, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches for all macro containers (one for macros with the same name) with names that match the given pattern. In case a binding exists in multiple projects, no duplicate bindings are returned.
      Parameters:
      pattern - a pattern the name of the bindings have to match.
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor to report progress, may be null
      Returns:
      an array of bindings matching the pattern
      Throws:
      org.eclipse.core.runtime.CoreException

    • findBindings

      IIndexBinding[] findBindings(char[][] names, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches for all bindings in global scope with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns.
      Parameters:
      names - an array of names, which has to be matched by the qualified name of the bindings.
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor to report progress, may be null.
      Returns:
      an array of bindings matching the pattern
      Throws:
      org.eclipse.core.runtime.CoreException

    • findBindings

      IIndexBinding[] findBindings(char[] name, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches the global scope for all bindings with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns. This is fully equivalent to 
       findBindings(name, true, filter, monitor);
      Parameters:
      name - a name, which has to be matched by the qualified name of the bindings.
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor to report progress, may be null.
      Returns:
      an array of bindings matching the pattern
      Throws:
      org.eclipse.core.runtime.CoreException

    • findBindings

      IIndexBinding[] findBindings(char[] name, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches the global scope and optionally all other scopes for bindings with a given name. In case a binding exists in multiple projects, no duplicate bindings are returned. This method makes use of the BTree and is faster than the methods using patterns.
      Parameters:
      name - a name, which has to be matched by the qualified name of the bindings.
      fileScopeOnly - if true, only bindings at file scope are returned
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor to report progress, may be null.
      Returns:
      an array of bindings matching the pattern
      Throws:
      org.eclipse.core.runtime.CoreException

    • findBindingsForPrefix

      IIndexBinding[] findBindingsForPrefix(char[] prefix, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Searches for all bindings with names that start with the given prefix.
      Parameters:
      prefix - the prefix with which all returned bindings must start
      fileScopeOnly - if true, only bindings at file scope are returned
      filter - a filter that allows for skipping parts of the index
      monitor - a monitor for progress reporting and cancellation, may be null
      Returns:
      an array of bindings with the prefix
      Throws:
      org.eclipse.core.runtime.CoreException

    • findBindingsForContentAssist

      IIndexBinding[] findBindingsForContentAssist(char[] prefix, boolean fileScopeOnly, IndexFilter filter, org.eclipse.core.runtime.IProgressMonitor monitor) throws org.eclipse.core.runtime.CoreException
      Throws:
      org.eclipse.core.runtime.CoreException
      Restriction:
      This method is not intended to be referenced by clients.

    • findNames

      IIndexName[] findNames(IBinding binding, int flags) throws org.eclipse.core.runtime.CoreException
      Searches for all names that resolve to the given binding. The search can be limited to references, declarations or definitions, or a combination of those.
      Parameters:
      binding - a binding for which names are searched for
      flags - a combination of FIND_DECLARATIONS, FIND_DEFINITIONS, FIND_REFERENCES, SEARCH_ACROSS_LANGUAGE_BOUNDARIES, and FIND_POTENTIAL_MATCHES.
      Returns:
      an array of names
      Throws:
      org.eclipse.core.runtime.CoreException

    • findReferences

      IIndexName[] findReferences(IBinding binding) throws org.eclipse.core.runtime.CoreException
      Searches for all references that resolve to the given binding. This is fully equivalent to 
       findNames(binding, IIndex.FIND_REFERENCES);
      Parameters:
      binding - a binding for which references are searched for
      Returns:
      an array of names
      Throws:
      org.eclipse.core.runtime.CoreException

    • findDeclarations

      IIndexName[] findDeclarations(IBinding binding) throws org.eclipse.core.runtime.CoreException
      Searches for all declarations and definitions that resolve to the given binding. This is fully equivalent to 
       findNames(binding, IIndex.FIND_DECLARATIONS_DEFINITIONS);
      Parameters:
      binding - a binding for which declarations are searched for
      Returns:
      an array of names
      Throws:
      org.eclipse.core.runtime.CoreException

    • findDefinitions

      IIndexName[] findDefinitions(IBinding binding) throws org.eclipse.core.runtime.CoreException
      Searches for all definitions that resolve to the given binding. This is fully equivalent to 
       findNames(binding, IIndex.FIND_DEFINITIONS);
      Parameters:
      binding - a binding for which declarations are searched for
      Returns:
      an array of names
      Throws:
      org.eclipse.core.runtime.CoreException

    • adaptBinding

      IIndexBinding adaptBinding(IBinding binding)
      Returns an IIndexBinding for this index that is equivalent to the specified binding, or null if such a binding does not exist in this index. This is useful for adapting bindings obtained from IIndex objects that might have been created for a different scope or for IBinding objects obtained directly from the AST.
      Parameters:
      binding - an AST or an index binding
      Returns:
      an IIndexBinding for this index that is equivalent to the specified binding

    • createFileSet

      IIndexFileSet createFileSet()
      Creates a file-set that can be used with this index as long as the caller holds a read-lock.

    • getAllFiles

      IIndexFile[] getAllFiles() throws org.eclipse.core.runtime.CoreException
      Returns an array of all files that are part of this index. If a file is parsed in two linkages or in multiple fragments, only one of the files will be returned.
      Throws:
      org.eclipse.core.runtime.CoreException

    • getDefectiveFiles

      IIndexFile[] getDefectiveFiles() throws org.eclipse.core.runtime.CoreException
      Returns an array of files that were indexed with I/O errors.
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      5.4
      Restriction:
      This method is not intended to be referenced by clients.

    • getFilesWithUnresolvedIncludes

      IIndexFile[] getFilesWithUnresolvedIncludes() throws org.eclipse.core.runtime.CoreException
      Returns an array of files containing unresolved includes.
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      5.4
      Restriction:
      This method is not intended to be referenced by clients.

    • getInlineNamespaces

      IScope[] getInlineNamespaces() throws org.eclipse.core.runtime.CoreException
      Returns the global inline c++ namespaces.
      Throws:
      org.eclipse.core.runtime.CoreException
      Since:
      5.3

    • isFullyInitialized

      boolean isFullyInitialized()
      Returns true if the index is fully initialized. An index may not be fully initialized during Eclipse startup, or soon after adding a new project to the workspace.
      Since:
      5.4