FastFind.Windows 2.4.0

FastFind.NET

Ultra-high performance cross-platform file search library for .NET 10

Packages

Package	Version	Description
FastFind.Core		Core interfaces, SIMD string matching, StringPool
FastFind.Windows		NTFS change-journal enumeration and monitoring
FastFind.Unix		Linux/macOS parallel enumeration, file monitoring
FastFind.SQLite		Disk-backed persistent index

Key Features

• Cross-Platform SIMD: Vector256/Vector128 auto-dispatch (AVX2, SSE2, NEON)
• NTFS change-journal enumeration (Windows, administrator): 136,000–177,000 records/sec measured here; sizes and timestamps are opt-in, because a journal record carries neither
• Parallel BFS Enumeration (Linux/macOS): Channel-based depth-aware parallel traversal
• Real-Time Monitoring: USN Journal (Windows) / inotify (Linux) / FSEvents (macOS)
• Disk-Backed Index: Keep the index in SQLite instead of memory — footprint stays flat as the corpus grows
• Memory Optimized: paths and names are interned, so a repeated directory prefix is stored once
• Auto Platform Detection: ModuleInitializer auto-registration

Installation

dotnet add package FastFind.Core

# Platform-specific (auto-registered at runtime)
dotnet add package FastFind.Windows    # Windows
dotnet add package FastFind.Unix       # Linux / macOS

dotnet add package FastFind.SQLite     # Optional: persistent index

Quick Start

using FastFind;

// Platform auto-detected — creates Windows, Linux, or macOS engine
using var engine = FastFinder.CreateSearchEngine();

await engine.StartIndexingAsync(new IndexingOptions
{
    SpecificDirectories = [@"D:\Projects"],         // Windows
    // MountPoints = ["/home", "/opt"],             // Linux / macOS
    ExcludedPaths = ["node_modules", ".git", "bin", "obj"],
    CollectFileMetadata = true   // sizes and timestamps on the Windows MFT path
});

while (engine.IsIndexing) await Task.Delay(500);

var results = await engine.SearchAsync(new SearchQuery
{
    BasePath = @"D:\Projects",
    SearchText = "controller",
    ExtensionFilter = ".cs",
    MaxResults = 100
});

await foreach (var file in results.Files)
{
    Console.WriteLine($"{file.Name} ({file.SizeFormatted}) - {file.DirectoryPath}");
}

Keeping the index on disk

By default the index lives in memory. Give the engine a persistence store and it answers queries from disk instead, so its footprint does not grow with the number of indexed files:

using FastFind;
using FastFind.SQLite;

await using var store = SqlitePersistence.Create(@"D:\cache\index.db");
await store.InitializeAsync();

using var engine = FastFinder.CreateSearchEngine(store);

// Index once; the store survives the process.
await engine.StartIndexingAsync(new IndexingOptions { SpecificDirectories = [@"D:\Projects"] });
while (engine.IsIndexing) await Task.Delay(500);

Console.WriteLine($"{engine.Index!.Count} files indexed, {engine.Index.MemoryUsage} bytes held in memory");

Pass PersistenceMode.MirrorInMemory instead to keep the in-memory index for speed and use the store purely for durability — that costs the memory of both, and is the right choice only when the corpus comfortably fits.

The engine does not dispose a store you created; you keep ownership.

A store is safe to use from several threads or tasks at once — searching while indexing needs no coordination from the caller, because each operation takes its own pooled connection. See the concurrency notes for what a transaction covers and the one shape that is not supported.

Performance

What an in-memory index retains per entry, measured on two corpus sizes with dotnet run -c Release --project src/FastFind.Benchmarks -- --memory-retention:

At one file per directory — a shape that gives interning nothing to share — both roughly double.

The elevated Windows provider enumerates the NTFS change journal at 136,000–177,000 records/sec here, against a 200,000 target the suite asserts and does not meet. Sizes and timestamps are opt-in (CollectFileMetadata) because a journal record carries neither.

Every published figure, the command that reproduces it, and the claims that were withdrawn for having no reproducible source are in docs/BENCHMARKS.md. Figures are from one machine.

Platform Support

Documentation

• Getting Started — Setup, configuration, examples
• API Reference — Interface and class signatures
• Performance Benchmarks — Detailed benchmark data
• Roadmap — Development plans

License

MIT License - see LICENSE for details.