LocatorFileCache Class

Member Function Documentation

LocatorFileCache::LocatorFileCache()

Constructs an invalid cache.

The cache is considered to be in an invalid state after a call to invalidate(), of after a call to setFilePathsGenerator() when passed functions was empty.

It it possible to setup the automatic validator for the cache through the setGeneratorProvider().

See also invalidate, setGeneratorProvider, setFilePathsGenerator, and setFilePaths.

[static] Core::LocatorFileCache::FilePathsGenerator LocatorFileCache::filePathsGenerator(const Utils::FilePaths &filePaths)

Adapts the filePaths list into a LocatorFileCacheGenerator. Useful when implementing GeneratorProvider in case a creation of file paths can't be invoked from the non-main thread.

See also setFilePathsGenerator().

void LocatorFileCache::invalidate()

Invalidates the cache.

In order to validate it, use either setFilePathsGenerator() or setFilePaths(). The cache may be automatically validated if the GeneratorProvider was set through the setGeneratorProvider().

Tasking::ExecutableItem LocatorFileCache::matcher() const

Returns the locator matcher task for the cache. The task, when successfully finished, updates this LocatorFileCache instance if needed.

This method is to be used directly by the FilePaths filters. The FilePaths filter should keep an instance of a LocatorFileCache internally. Ensure the LocatorFileCache instance outlives the running matcher, otherwise the cache won't be updated after the task finished.

When returned LocatorMatcherTask is being run it checks if this cache is valid. When the cache is invalid, it uses GeneratorProvider to update the cache's FilePathsGenerator and validates the cache. If that failed, the task is not started. When the cache is valid, the running task will reuse cached data for calculating the LocatorMatcherTask's results.

After a successful run of the task, this cache is updated according to the last search. When this cache started a new search in meantime, the cache was invalidated or even deleted, the update of the cache after a successful run of the task is ignored.

[static] Utils::FilePaths LocatorFileCache::processFilePaths(const QFuture<void> &future, const Utils::FilePaths &filePaths, bool hasPathSeparator, const QRegularExpression &regExp, const Utils::Link &inputLink, Core::LocatorFileCache::MatchedEntries *entries)

Helper used internally and by SpotlightLocatorFilter.

To be called from non-main thread. The cancellation is controlled by the passed future. This function periodically checks for the cancellation state of the future and returns early when cancellation was detected. Creates lists of matching LocatorFilterEntries categorized by MatcherType. These lists are returned through the entries argument.

Returns a list of all matching files.

This function checks for each file in filePaths if it matches the passed regExp. If so, a new entry is created using hasPathSeparator and inputLink and it's being added into the entries argument and the results list.

void LocatorFileCache::setFilePaths(const Utils::FilePaths &filePaths)

Wraps the passed filePaths into a trivial FilePathsGenerator and sets it as a cache's generator.

See also setGeneratorProvider.

void LocatorFileCache::setFilePathsGenerator(const Core::LocatorFileCache::FilePathsGenerator &generator)

Sets the file path generator.

The generator serves for returning the full input list of file paths when the associated LocatorMatherTask is being run in a separate thread. When the computation of the full list of file paths takes a considerable amount of time, this computation may be potentially moved to the separate thread, provided that all the dependent data may be safely passed to the generator function when this function is being set in the main thread.

The passed generator is always called exclusively from the non-main thread when running LocatorMatcherTask returned by matcher(). It is called when the cached data is empty or when it needs to be regenerated due to a new search which can't reuse the cache from the previous search.

Generating a new file path list may be a time consuming task. In order to finish the task early when being canceled, the future argument of the FilePathsGenerator may be used. The FilePathsGenerator returns the full list of file paths used for file filter's processing.

Whenever it is possible to postpone the creation of a file path list so that it may be done safely later from the non-main thread, based on some other reentrant/thread-safe data, this method should be used. The other dependent data should be passed by lambda capture. The body of the passed generator should take extra care for ensuring that the passed other data via lambda captures are reentrant and the lambda body is thread safe. See the example usage of the generator inside CppIncludesFilter implementation.

Otherwise, when postponing the creation of file paths list isn't safe, use setFilePaths() with ready made list, prepared in main thread.

See also filePathsGenerator(), setGeneratorProvider, and setFilePaths.

void LocatorFileCache::setGeneratorProvider(const Core::LocatorFileCache::GeneratorProvider &provider)

Sets the file path generator provider.

The provider serves for an automatic validation of the invalid cache by recreating the FilePathsGenerator. The automatic validation happens when the LocatorMatcherTask returned by matcher() is being started, and the cache is not valid at that moment. In this case the stored provider is being called.

The passed provider function is always called from the main thread. If needed, it is called prior to starting an asynchronous task that collects the locator filter results.

When this function is called, the cache isn't invalidated. Whenever cache's invalidation happens, e.g. when invalidate(), setFilePathsGenerator() or setFilePaths() is called, the stored GeneratorProvider is being preserved. In order to clear the stored GeneratorProvider, call this method with an empty function {}.