How iikuzmychov/bidirectionaldictionary works
1. This repository is a .NET class library, not an application. Its main product is a bidirectional dictionary package that lets you look up key -> value and value -> key with the same data structure.
2. The core architecture centers on three implementation types under src/BidirectionalDictionary/Types:
- BidirectionalDictionary<TKey, TValue>: the mutable in-memory implementation.
- ConcurrentBidirectionalDictionary<TKey, TValue>: the thread-safe implementation.
- ReadOnlyBidirectionalDictionary<TKey, TValue>: a wrapper that exposes read-only access while preserving inverse lookup.
3. The fundamental data-flow is symmetric indexing: inserts and removals must keep two internal views in sync, one for forward lookup and one for reverse lookup. That is the key architectural constraint of the library.
4. The package exposes abstraction boundaries through two interfaces in src/BidirectionalDictionary/Interfaces:
- IBidirectionalDictionary<TKey, TValue>
- IReadOnlyBidirectionalDictionary<TKey, TValue>
These allow consumers to program against contracts while swapping between mutable, concurrent, and read-only implementations.
5. The public API surface is intentionally broad and dictionary-like. The concrete types implement standard collection contracts such as dictionary/enumerable behavior, and the repository has separate test coverage for:
- dictionary access
- read-only dictionary access
- enumeration
- key collections
- value collections
- inverse views via Inverse
6. The read-only model is a wrapper, not a copy. ReadOnlyBidirectionalDictionary and AsReadOnly() share the same underlying data with the mutable source, but block mutation through the read-only API. That makes the read-only boundary a facade over the same storage.
7. The concurrent implementation is a distinct subsystem with different synchronization behavior. The README states that reads are lock-free and writes use fine-grained stripe locks rather than a single global lock, so the concurrency boundary is localized around mutation while keeping lookup fast.
8. The Extensions folder adds LINQ-based creation helpers. These extension methods convert:
- IEnumerable<KeyValuePair<TKey, TValue>>
- tuple sequences
- arbitrary sequences with selector functions
into a bidirectional dictionary. This is a construction pipeline into the core types, not a separate data model.
9. The DebugViews folder contains debugger-only visualization helpers for dictionary items, keys, and values. These do not affect runtime behavior, but they improve inspectability and are part of the developer experience boundary around the collections.
10. The library is multi-targeted. The PublicAPI folders for netstandard2.0, netstandard2.1, net6.0, and net9.0 indicate version-specific API baselines and shipped/unshipped public surface tracking. This is important for compatibility management and release discipline.
11. Testing is a major part of the architecture. tests/BidirectionalDictionary.Tests is organized by implementation type and by contract, with separate suites for the mutable, concurrent, and read-only variants. There are also specialized enumerator and collection tests, showing that enumeration semantics are treated as first-class behavior.
12. Concurrency validation is stronger than ordinary unit tests. The concurrent dictionary has stress tests and a Coyote-based test file, which indicates model/checker-based exploration of multithreaded behavior in addition to conventional test cases.
13. Benchmarking is an explicit subsystem under benchmarks/BidirectionalDictionary.Benchmarks. It contains separate benchmark classes for the mutable, concurrent, and read-only implementations, suggesting the project compares lookup and mutation costs across variants rather than optimizing a single path in isolation.
14. The repo is packaged and released through CI. GitHub Actions workflows exist for CI and publishing, and codecov.yml plus the badge in the README show coverage reporting is part of the build pipeline. The overall lifecycle is: source code → tests/benchmarks/coverage → packaged NuGet release.
15. For an architecture diagram, the most important boundaries are:
- external consumers using the NuGet package
- the core bidirectional indexing engine
- the read-only wrapper boundary
- the concurrent synchronization boundary
- supporting layers for extensions, debug views, tests, and benchmarks
- release/quality tooling around the library
Main entry points: BidirectionalDictionary.cs BidirectionalDictionary · ConcurrentBidirectionalDictionary.cs ConcurrentDictionary · ReadOnlyBidirectionalDictionary.cs ReadOnlyDictionary · BidirectionalDictionary.Tests Library tests
Components 17
Consumers
External code using the NuGet package and its contracts.
- Consumers · Code that uses the package through mutable, concurrent, or read-only contracts.
Core library
Public interfaces and concrete bidirectional dictionary implementations.
- IBidirectionalDictionary · Mutable bidirectional dictionary contract with inverse lookup behavior.
src/BidirectionalDictionary/Interfaces/IBidirectionalDictionary.cs - IReadOnlyBidirectionalDictionary · Read-only contract that still exposes forward and reverse lookup.
src/BidirectionalDictionary/Interfaces/IReadOnlyBidirectionalDictionary.cs - BidirectionalDictionary · In-memory implementation that keeps forward and reverse indexes synchronized.
src/BidirectionalDictionary/Types/BidirectionalDictionary.cs - ConcurrentDictionary · Thread-safe implementation with lock-free reads and striped write synchronization.
src/BidirectionalDictionary/Types/ConcurrentBidirectionalDictionary.cs - ReadOnlyDictionary · Facade over shared storage that blocks mutation while preserving inverse lookup.
src/BidirectionalDictionary/Types/ReadOnlyBidirectionalDictionary.cs - Forward index · Primary lookup side for key-to-value access within the implementations.
- Reverse index · Inverse lookup side kept in sync with the forward index.
- Sync rules · Symmetric update/removal logic that maintains both views consistently.
- Stripe locks · Concurrency control boundary around writes, while reads stay fast.
Support
Extensions and debugger-facing helpers around the core collections.
- LINQ helpers · Construction helpers from key-value pairs, tuples, and selector-based sequences.
src/BidirectionalDictionary/Extensions/BidirectionalDictionaryEnumerableExtensions.cs - Debug views · Debugger-only views for items, keys, and values.
src/BidirectionalDictionary/DebugViews/DictionaryDebugView.cs
Quality
Tests, benchmarks, and release/compatibility tooling.
- Public API · Versioned shipped and unshipped API tracking across target frameworks.
src/BidirectionalDictionary/PublicAPI/net6.0/PublicAPI.Shipped.txt - Library tests · Contract and behavior tests for mutable, concurrent, and read-only variants.
tests/BidirectionalDictionary.Tests - Stress checks · Stress and Coyote-based validation for multithreaded correctness.
tests/BidirectionalDictionary.Tests/Types/ConcurrentBidirectionalDictionary/ConcurrentBidirectionalDictionaryTests.Coyote.cs - Benchmarks · Performance comparisons across mutable, concurrent, and read-only implementations.
benchmarks/BidirectionalDictionary.Benchmarks
Release
CI and packaging pipeline for the library.
- CI publish · GitHub Actions workflows for validation, coverage, and NuGet publishing.
.github/workflows/ci.yml
Connections 28
- Consumers → IBidirectionalDictionary: code against · Consumers use the mutable contract when they need write access.
- Consumers → IReadOnlyBidirectionalDictionary: code against · Consumers use the read-only contract for lookup-only access.
- IBidirectionalDictionary → BidirectionalDictionary: implemented by · The mutable implementation fulfills the primary bidirectional contract.
- IBidirectionalDictionary → ConcurrentDictionary: implemented by · The concurrent implementation also fulfills the mutable contract.
- IReadOnlyBidirectionalDictionary → ReadOnlyDictionary: implemented by · The read-only wrapper fulfills the read-only contract.
- BidirectionalDictionary → Forward index: stores · Holds the forward map for key-to-value lookup.
- BidirectionalDictionary → Reverse index: stores · Holds the reverse map for value-to-key lookup.
- Sync rules → Forward index: keeps in sync · Updates must preserve consistency in the forward view.
- Sync rules → Reverse index: keeps in sync · Updates must preserve consistency in the reverse view.
- BidirectionalDictionary → Sync rules: enforces · Mutable operations maintain the symmetric indexing invariant.
- ConcurrentDictionary → Sync rules: enforces · Concurrent mutation must preserve the same indexing invariant.
- ConcurrentDictionary → Stripe locks: uses · Synchronization is localized around writes with striped locking.
- ReadOnlyDictionary → BidirectionalDictionary: wraps · Read-only access shares the same underlying data with the mutable source.
- ReadOnlyDictionary → Sync rules: preserves · The wrapper exposes consistency of both directions without mutation.
- LINQ helpers → BidirectionalDictionary: creates · LINQ helpers materialize bidirectional dictionaries from sequences.
- Debug views → BidirectionalDictionary: inspects · Debugger views expose collection state without changing runtime behavior.
- Public API → IBidirectionalDictionary: tracks · API baselines record the public contract surface.
- Public API → IReadOnlyBidirectionalDictionary: tracks · API baselines record the public contract surface.
- Library tests → BidirectionalDictionary: verifies · Tests cover mutable dictionary behavior and contract compliance.
- Library tests → ConcurrentDictionary: verifies · Tests cover concurrent behavior and collection semantics.
- Library tests → ReadOnlyDictionary: verifies · Tests cover wrapper behavior and read-only access.
- Stress checks → ConcurrentDictionary: stresses · Concurrency-specific validation explores multithreaded correctness.
- Benchmarks → BidirectionalDictionary: measures · Benchmarks compare mutable operations and lookup cost.
- Benchmarks → ConcurrentDictionary: measures · Benchmarks compare concurrent performance characteristics.
- Benchmarks → ReadOnlyDictionary: measures · Benchmarks compare the read-only wrapper path.
- CI publish → Library tests: runs · CI validates the library through the test suite.
- CI publish → Public API: guards · Release pipeline preserves compatibility baselines.
- CI publish → Benchmarks: publishes · Benchmarking supports performance visibility alongside releases.