SymbolResolver Class Reference

#include <src/symbolresolver.h>

Classes
struct	Private

Public Types
enum class	ClearScope { All , Classes , Unresolved }
	Clear the type lookup cache for the current thread. More...

Public Member Functions
	SymbolResolver (const FileDef *fileScope=nullptr)
	~SymbolResolver ()
const ClassDef *	resolveClass (const Definition *scope, const DString &name, bool maybeUnlinkable=false, bool mayBeHidden=false)
	Find the class definition matching name within the scope set.
ClassDefMutable *	resolveClassMutable (const Definition *scope, const DString &name, bool mayBeUnlinkable=false, bool mayBeHidden=false)
	Wrapper around resolveClass that returns a mutable interface to the class object or a nullptr if the symbol is immutable.
const Definition *	resolveSymbol (const Definition *scope, const DString &name, const DString &args=DString(), bool checkCV=false, bool insideCode=false, bool onlyLinkable=false)
	Find the symbool definition matching name within the scope set.
int	isAccessibleFrom (const Definition *scope, const Definition *item)
	Checks if symbol item is accessible from within scope.
int	isAccessibleFromWithExpScope (const Definition *scope, const Definition *item, const DString &explicitScopePart)
	Check if symbol item is accessible from within scope, where it has to match the explicitScopePart.
void	setFileScope (const FileDef *fd)
	Sets or updates the file scope using when resolving symbols.
const MemberDef *	getTypedef () const
	In case a call to resolveClass() resolves to a type member (e.g. an enum) this method will return it.
DString	getTemplateSpec () const
	In case a call to resolveClass() points to a template specialization, the template part is return via this method.
DString	getResolvedType () const
	In case a call to resolveClass() points to a typedef or using declaration.

Static Public Member Functions
static void	clearTypeLookupCache (ClearScope scope)
static void	showCacheUsage ()
	Show usage of the type lookup cache.

Private Attributes
std::unique_ptr< Private >	p

Detailed Description

Helper class to find a class definition or check if A symbol is accessible in a given scope.

Definition at line 31 of file symbolresolver.h.

Member Enumeration Documentation

ClearScope

enum class SymbolResolver::ClearScope

strong

Clear the type lookup cache for the current thread.

Enumerator
All
Classes
Unresolved

Definition at line 102 of file symbolresolver.h.

{ All, Classes, Unresolved };

Constructor & Destructor Documentation

SymbolResolver()

SymbolResolver::SymbolResolver ( const FileDef * fileScope = nullptr )

explicit

Definition at line 1698 of file symbolresolver.cpp.

  : p(std::make_unique<Private>(fileScope))
{
}

References p.

~SymbolResolver()

SymbolResolver::~SymbolResolver

(

)

Definition at line 1703 of file symbolresolver.cpp.

{
}

Member Function Documentation

clearTypeLookupCache()

void SymbolResolver::clearTypeLookupCache ( SymbolResolver::ClearScope scope )

static

Definition at line 1825 of file symbolresolver.cpp.

{
  auto &cache = getTypeLookupCache();
  switch (scope)
  {
    case ClearScope::All:
      cache.clear();
      break;
    case ClearScope::Unresolved:
      {
        StringVector elementsToRemove;
        for (const auto &ci : cache)
        {
          const LookupInfo &li = ci.second;
          if (li.definition==nullptr && li.typeDef==nullptr)
          {
            elementsToRemove.push_back(ci.first);
          }
        }
        for (const auto &k : elementsToRemove)
        {
          cache.remove(k);
        }
      }
      break;
    case ClearScope::Classes:
      {
        StringVector elementsToRemove;
        for (const auto &ci : cache)
        {
          const LookupInfo &li = ci.second;
          if (li.definition)
          {
            elementsToRemove.push_back(ci.first);
          }
        }
        for (const auto &k : elementsToRemove)
        {
          cache.remove(k);
        }
      }
      break;
  }
}

References All, Classes, LookupInfo::definition, getTypeLookupCache(), LookupInfo::typeDef, and Unresolved.

Referenced by flushCachedTemplateRelations(), flushUnresolvedRelations(), and parseInput().

getResolvedType()

DString SymbolResolver::getResolvedType

(

)

const

In case a call to resolveClass() points to a typedef or using declaration.

The type name it resolved to is returned via this method.

Definition at line 1820 of file symbolresolver.cpp.

{
  return p->resolvedType;
}

References p.

Referenced by getCanonicalTypeForIdentifier(), and SymbolResolver::Private::getResolvedTypeRec().

getTemplateSpec()

DString SymbolResolver::getTemplateSpec

(

)

const

In case a call to resolveClass() points to a template specialization, the template part is return via this method.

Definition at line 1815 of file symbolresolver.cpp.

{
  return p->templateSpec;
}

References p.

Referenced by findClassRelation(), and getCanonicalTypeForIdentifier().

getTypedef()

const MemberDef * SymbolResolver::getTypedef

(

)

const

In case a call to resolveClass() resolves to a type member (e.g. an enum) this method will return it.

Definition at line 1810 of file symbolresolver.cpp.

{
  return p->typeDef;
}

References p.

Referenced by findClassRelation(), getCanonicalTypeForIdentifier(), and linkifyText().

isAccessibleFrom()

int SymbolResolver::isAccessibleFrom	(	const Definition *	scope,
		const Definition *	item )

Checks if symbol item is accessible from within scope.

Returns

-1 if item is not accessible or a number indicating how many scope levels up the nearest match was found.

Definition at line 1779 of file symbolresolver.cpp.

{
  AUTO_TRACE("scope={} item={}",
      scope?scope->name():DString(), item?item->name():DString());
  p->reset();
  VisitedKeys visitedKeys;
  AccessStack accessStack;
  int result = p->isAccessibleFrom(visitedKeys,accessStack,scope,item);
  AUTO_TRACE_EXIT("result={}",result);
  return result;
}

References AUTO_TRACE, AUTO_TRACE_EXIT, Definition::name(), and p.

Referenced by SymbolResolver::Private::isAccessibleFrom(), SymbolResolver::Private::isAccessibleFromWithExpScope(), and resolveTypeDef().

isAccessibleFromWithExpScope()

int SymbolResolver::isAccessibleFromWithExpScope	(	const Definition *	scope,
		const Definition *	item,
		const DString &	explicitScopePart )

Check if symbol item is accessible from within scope, where it has to match the explicitScopePart.

Returns

-1 if item is not accessible or a number indicating how many scope levels up the nearest match was found.

Definition at line 1791 of file symbolresolver.cpp.

{
  AUTO_TRACE("scope={} item={} explicitScopePart={}",
      scope?scope->name():DString(), item?item->name():DString(), explicitScopePart);
  p->reset();
  VisitedKeys visitedKeys;
  VisitedNamespaces visitedNamespaces;
  AccessStack accessStack;
  int result = p->isAccessibleFromWithExpScope(visitedKeys,visitedNamespaces,accessStack,scope,item,explicitScopePart);
  AUTO_TRACE_EXIT("result={}",result);
  return result;
}

References AUTO_TRACE, AUTO_TRACE_EXIT, Definition::name(), and p.

Referenced by getMemberFromSymbol(), SymbolResolver::Private::getResolvedSymbol(), SymbolResolver::Private::getResolvedType(), SymbolResolver::Private::isAccessibleFromWithExpScope(), and SymbolResolver::Private::substTypedef().

resolveClass()

const ClassDef * SymbolResolver::resolveClass	(	const Definition *	scope,
		const DString &	name,
		bool	maybeUnlinkable = false,
		bool	mayBeHidden = false )

Find the class definition matching name within the scope set.

Parameters

scope	The scope to search from.
name	The name of the symbol.
maybeUnlinkable	include unlinkable symbols in the search.
mayBeHidden	include hidden symbols in the search.

Note

As a result of this call the getters getTypedef(), getTemplateSpec(), and getResolvedType() are set as well.

Definition at line 1708 of file symbolresolver.cpp.

{
  AUTO_TRACE("scope={} name={} mayBeUnlinkable={} mayBeHidden={}",
      scope?scope->name():DString(), name, mayBeUnlinkable, mayBeHidden);
  p->reset();
 
  auto lang = scope ? scope->getLanguage() :
          p->fileScope() ? p->fileScope()->getLanguage() :
          SrcLangExt::Cpp;  // fallback to C++
 
  if (scope==nullptr ||
      (scope->definitionType()!=Definition::TypeClass &&
       scope->definitionType()!=Definition::TypeNamespace
      ) ||
      (name.stripWhiteSpace().startsWith("::")) ||
      ((lang==SrcLangExt::Java || lang==SrcLangExt::CSharp) && DString(name).find("::")!=DString::npos)
     )
  {
    scope=Doxygen::globalScope;
  }
  const ClassDef *result=nullptr;
  if (Config_getBool(OPTIMIZE_OUTPUT_VHDL))
  {
    result = getClass(name);
  }
  else
  {
    VisitedKeys visitedKeys;
    DString lookupName = lang==SrcLangExt::CSharp ? mangleCSharpGenericName(name) : name;
    AUTO_TRACE_ADD("lookup={}",lookupName);
    result = p->getResolvedTypeRec(getTypeLookupCache(),visitedKeys,scope,lookupName,&p->typeDef,&p->templateSpec,&p->resolvedType);
    if (result==nullptr) // for nested classes imported via tag files, the scope may not
                   // present, so we check the class name directly as well.
                   // See also bug701314
    {
      result = getClass(lookupName);
    }
  }
  if (!mayBeUnlinkable && result && !result->isLinkable())
  {
    if (!mayBeHidden || !result->isHidden())
    {
      AUTO_TRACE_ADD("hiding symbol {}",result->name());
      result=nullptr; // don't link to artificial/hidden classes unless explicitly allowed
    }
  }
  AUTO_TRACE_EXIT("result={}",result?result->name():DString());
  return result;
}

References AUTO_TRACE, AUTO_TRACE_ADD, AUTO_TRACE_EXIT, Config_getBool, Definition::definitionType(), getClass(), Definition::getLanguage(), getTypeLookupCache(), Doxygen::globalScope, Definition::isHidden(), Definition::isLinkable(), mangleCSharpGenericName(), Definition::name(), DString::npos, p, DString::startsWith(), DString::stripWhiteSpace(), Definition::TypeClass, and Definition::TypeNamespace.

Referenced by findClassDefinition(), findClassWithinClassContext(), findUsingDeclImports(), getCanonicalTypeForIdentifier(), isVarWithConstructor(), linkifyText(), normalizeNonTemplateArgumentsInString(), and resolveClassMutable().

resolveClassMutable()

ClassDefMutable * SymbolResolver::resolveClassMutable ( const Definition * scope, const DString & name, bool mayBeUnlinkable = false, bool mayBeHidden = false )

inline

Wrapper around resolveClass that returns a mutable interface to the class object or a nullptr if the symbol is immutable.

Definition at line 57 of file symbolresolver.h.

    {
      return toClassDefMutable(const_cast<ClassDef*>(resolveClass(scope,name,mayBeUnlinkable,mayBeHidden)));
    }

References resolveClass(), and toClassDefMutable().

Referenced by ClassDefImpl::addTypeConstraint(), findClassRelation(), findUsedClassesForClass(), and resolveTemplateInstanceInType().

resolveSymbol()

const Definition * SymbolResolver::resolveSymbol	(	const Definition *	scope,
		const DString &	name,
		const DString &	args = DString(),
		bool	checkCV = false,
		bool	insideCode = false,
		bool	onlyLinkable = false )

Find the symbool definition matching name within the scope set.

Parameters

scope	The scope to search from.
name	The name of the symbol.
args	Argument list associated with the symbol (for functions)
checkCV	Check const/volatile qualifiers (for methods)
insideCode	Is the symbol found in a code fragment
onlyLinkable	Only search linkable definitions

Definition at line 1761 of file symbolresolver.cpp.

{
  AUTO_TRACE("scope={} name={} args={} checkCV={} insideCode={}",
             scope?scope->name():DString(), name, args, checkCV, insideCode);
  p->reset();
  if (scope==nullptr) scope=Doxygen::globalScope;
  VisitedKeys visitedKeys;
  const Definition *result = p->getResolvedSymbolRec(getSymbolLookupCache(),visitedKeys,scope,name,args,checkCV,insideCode,onlyLinkable,&p->typeDef,&p->templateSpec,&p->resolvedType);
  AUTO_TRACE_EXIT("result={}{}", qPrint(result?result->qualifiedName():DString()),
                                 qPrint(result && result->definitionType()==Definition::TypeMember ? toMemberDef(result)->argsString() : DString()));
  return result;
}

References AUTO_TRACE, AUTO_TRACE_EXIT, Definition::definitionType(), getSymbolLookupCache(), Doxygen::globalScope, Definition::name(), p, qPrint(), Definition::qualifiedName(), toMemberDef(), and Definition::TypeMember.

Referenced by findUsingDeclarations(), findUsingDeclImports(), getDefs(), and linkifyText().

setFileScope()

void SymbolResolver::setFileScope

(

const FileDef *

fd

)

Sets or updates the file scope using when resolving symbols.

Definition at line 1805 of file symbolresolver.cpp.

{
  p->setFileScope(fileScope);
}

References p.

Referenced by getDefs().

showCacheUsage()

void SymbolResolver::showCacheUsage ( )

static

Show usage of the type lookup cache.

Definition at line 1886 of file symbolresolver.cpp.

{
  // merge the stats of the main thread
  mergeStatistics(g_typeCacheStatistics,getTypeLookupCache());
  mergeStatistics(g_symbolCacheStatistics,getSymbolLookupCache());
 
  std::lock_guard lock1(g_typeCacheStatistics.mutex);
  std::lock_guard lock2(g_symbolCacheStatistics.mutex);
 
  msg("type lookup cache used {}/{} hits={} misses={}\n",
      g_typeCacheStatistics.size,
      g_typeCacheStatistics.capacity,
      g_typeCacheStatistics.hits,
      g_typeCacheStatistics.misses);
  msg("symbol lookup cache used {}/{} hits={} misses={}\n",
      g_symbolCacheStatistics.size,
      g_symbolCacheStatistics.capacity,
      g_symbolCacheStatistics.hits,
      g_symbolCacheStatistics.misses);
  int typeCacheParam   = computeIdealCacheParam(static_cast<size_t>(g_typeCacheStatistics.misses*2/3)); // part of the cache is flushed, hence the 2/3 correction factor
  int symbolCacheParam = computeIdealCacheParam(static_cast<size_t>(g_symbolCacheStatistics.misses*2/3)); // part of the cache is flushed, hence the 2/3 correction factor
  int cacheParam = std::max(typeCacheParam,symbolCacheParam);
  if (cacheParam>Config_getInt(LOOKUP_CACHE_SIZE))
  {
    msg("Note: based on cache misses the ideal setting for LOOKUP_CACHE_SIZE is {} at the cost of higher memory usage.\n",cacheParam);
  }
}

References CacheStatistics::capacity, computeIdealCacheParam(), Config_getInt, g_symbolCacheStatistics, g_typeCacheStatistics, getSymbolLookupCache(), getTypeLookupCache(), CacheStatistics::hits, mergeStatistics(), CacheStatistics::misses, msg, CacheStatistics::mutex, and CacheStatistics::size.

Referenced by generateOutput().

Member Data Documentation

p

std::unique_ptr<Private> SymbolResolver::p

private

Definition at line 127 of file symbolresolver.h.

Referenced by getResolvedType(), getTemplateSpec(), getTypedef(), isAccessibleFrom(), isAccessibleFromWithExpScope(), resolveClass(), resolveSymbol(), setFileScope(), and SymbolResolver().

---

The documentation for this class was generated from the following files:

• src/symbolresolver.h
• src/symbolresolver.cpp