ThreadSafeCollections-FP v0.8.0 Release Notes

Documentation home · Current changelog

Historical release snapshot. This document records v0.8.0 and may contain older APIs, measurements, toolchains, or support statements. Use the current documentation for the present checkout.

Audience: users researching the v0.8.0 release and project maintainers.

Release Date: 2025-12-16

Overview#

Version 0.8.0 is a major performance-focused release that delivers significant speed improvements across all collection types while maintaining 100% backward compatibility. This release focuses on optimizing the underlying data structures and algorithms without changing any public APIs.

🚀 Highlights#

Performance Improvements#

• TThreadSafeDeque: 5-10x faster with new circular array implementation
• TThreadSafeList: 2-3x faster bulk operations with smart pre-allocation
• TThreadSafeDictionary & TThreadSafeHashSet: 1.5-2x faster bulk operations
• Memory efficiency: Up to 100x fewer allocations for deque operations
• Cache locality: Dramatically improved with contiguous memory layout

Key Changes#

1. Deque Architecture Rewrite (Breaking Performance Improvement)

• Converted from linked-list to circular array-based implementation
• Eliminated per-item heap allocations (New/Dispose calls removed)
• Power-of-2 capacity sizing for efficient modulo operations
• 100% API compatible - no code changes required

1. List Pre-allocation Strategy

• New optional constructor: Create(AComparer, AInitialCapacity)
• Default initial capacity increased from 0 to 16 elements
• Smart growth: 2x for small lists, 1.5x for large lists
• Optimized AddRange with single pre-calculated resize

1. Hash Table Bulk Optimization

• AddRange methods now pre-calculate required capacity
• Single resize operation instead of multiple cascading resizes
• Reduced lock contention during bulk operations

📊 Performance Metrics#

Theoretical Improvements#

Real-world Characteristics#

From test suite execution (116 tests):

• List sorting (100k items): ~200-350ms
• Hash operations (10k items): <10ms for add/contains
• Concurrent access: Maintains thread safety with minimal overhead
• Deque operations: Now O(1) push/pop with better constant factors

🔧 Technical Details#

Memory Management Improvements#

• Deque: Eliminated heap allocations for individual nodes, reducing memory fragmentation
• List: Smarter capacity growth reduces wasted allocations
• Hash Tables: Pre-calculation prevents intermediate resize operations

Algorithm Optimizations#

• Deque: Circular array with bitwise AND for wraparound (efficient modulo)
• List: Geometric growth with size-dependent strategy
• Hash Tables: Bulk operation optimization with single resize

📝 API Changes#

New Constructors (Optional)#

TThreadSafeList:

// Before (still works):
List := specialize TThreadSafeList<Integer>.Create(@IntegerComparer);

// After (optional optimization):
List := specialize TThreadSafeList<Integer>.Create(@IntegerComparer, 1000);

TThreadSafeDeque:

// Before (still works):
Deque := specialize TThreadSafeDeque<Integer>.Create;

// After (optional optimization):
Deque := specialize TThreadSafeDeque<Integer>.Create(1000);

Behavior Changes#

• List initial capacity: Changed from 0 to 16 (performance optimization)
• Deque initial capacity: Changed from 0 to 16 (performance optimization)

All existing code continues to work without modifications.

✅ Backward Compatibility#

100% backward compatible - All existing code will work without any changes.

• All public APIs remain unchanged
• All method signatures preserved
• All behaviors maintained (except performance improvements)
• Existing constructors still work as before
• New constructors are optional enhancements

🧪 Testing#

All optimizations verified with comprehensive test suite:

• ✅ 116 tests passing
• ✅ Thread safety verified with concurrent access tests
• ✅ Memory management tested with stress tests
• ✅ Hash collision handling verified
• ✅ Bulk operations tested with large datasets
• ✅ Iterator functionality confirmed
• ✅ Edge cases covered (empty collections, single items, etc.)

🚫 Deferred Features#

The following optimizations were considered but deferred to future releases:

1. Read-write locks (TMultiReadExclusiveWriteSynchronizer)

• Would allow concurrent reads
• Requires extensive refactoring
• Planned for future release

1. Lock-free atomic operations

• For simple checks (IsEmpty, Count)
• Requires significant architecture changes
• Planned for future release

📦 Installation#

No installation changes - same as previous versions:

1. Clone or download the repository
2. Add src directory to your project's search path
3. Add units to your uses clause as needed

🔗 Resources#

• Repository: https://github.com/ikelaiah/threadsafecollections-fp
• Documentation: See ../index.md
• Full Changelog: See CHANGELOG.md
• Issues: https://github.com/ikelaiah/threadsafecollections-fp/issues

🙏 Acknowledgments#

• Free Pascal and Lazarus community
• FPCUnit testing framework
• All contributors and testers

⚠️ Important Notes#

For Production Use#

This library is primarily a learning tool. For production applications, consider:

• FPC Generics.Collections
• FCL-STL
• LGenerics

Upgrading from v0.7.x#

Simply replace your existing source files. No code changes required.

If you want to take advantage of the new performance optimizations:

1. Use the new constructors with capacity hints when you know approximate collection sizes
2. Recompile your application to pick up the performance improvements

---

What's Next?

Future releases will focus on:

• Read-write lock support for concurrent reads
• Lock-free operations for performance-critical paths
• Additional specialized collection types
• More comprehensive benchmarking suite

Thank you for using ThreadSafeCollections-FP!