Skip to content

Conversation

@konard
Copy link
Member

@konard konard commented Sep 13, 2025

Summary

This PR implements a partially lock-free size balanced tree with delayed balancing to address issue #78.

Key Features

Lock-free insertions: Multiple insertions (N) can be performed concurrently using ReaderWriterLockSlim read locks
Delayed balancing: Balancing operations are delayed until a configurable threshold of insertions is reached
Thread-safe operations: Uses atomic operations (Interlocked) for tracking insertion counts
Exclusive locking for balancing: Tree balancing only locks when necessary using write locks

Implementation Details

Core Components

  • PartiallyLockFreeSizeBalancedTreeMethods<TElement>: Abstract base class extending SizeBalancedTreeMethods
  • Configurable balancing threshold: Default 10 insertions before balancing triggers
  • Manual balancing trigger: ForceBalancing() method for explicit balancing control
  • Thread-safe counters: Atomic operations for tracking insertion counts
  • Custom delayed balancing logic: Mirrors original maintain operations with delayed execution

Thread Safety Strategy

  1. Read locks for insertions: Multiple threads can insert concurrently using ReaderWriterLockSlim.EnterReadLock()
  2. Write locks for balancing: Exclusive write lock during balancing operations
  3. Double-check pattern: Prevents unnecessary balancing operations in concurrent scenarios
  4. Atomic counters: Interlocked operations ensure thread-safe insertion counting

Test Coverage

  • ✅ Basic attach/detach operations
  • ✅ Random insertion/deletion patterns
  • ✅ Delayed balancing threshold verification
  • ✅ Manual balancing trigger functionality
  • ✅ Concurrent insertion stress testing (10 threads × 20 insertions each)

Performance Benefits

  • Reduced contention: N insertions can proceed without blocking on balancing
  • Improved throughput: Concurrent read operations during insertion phases
  • Configurable balance: Threshold can be tuned based on usage patterns
  • Graceful degradation: Falls back to locked balancing when needed

Usage Example

// Create tree with balancing threshold of 5 insertions
var tree = new PartiallyLockFreeSizeBalancedTree<uint>(capacity: 1000, balancingThreshold: 5);

// Insert elements - first 4 insertions are lock-free
for (uint i = 1; i <= 4; i++)
{
    var node = tree.Allocate();
    tree.Attach(ref tree.Root, node);  // Lock-free insertion
}

// 5th insertion triggers delayed balancing with exclusive lock
var finalNode = tree.Allocate();  
tree.Attach(ref tree.Root, finalNode);  // Triggers balancing

// Manual balancing trigger
tree.ForceBalancing();

Fixes #78

🤖 Generated with Claude Code

Adding CLAUDE.md with task information for AI processing.
This file will be removed when the task is complete.

Issue: #78
@konard konard self-assigned this Sep 13, 2025
This implementation addresses issue #78 by providing:

- Lock-free insertions: Multiple insertions (N) can be performed concurrently using ReaderWriterLockSlim read locks
- Delayed balancing: Balancing operations are delayed until a configurable threshold of insertions is reached
- Thread-safe operations: Uses atomic operations (Interlocked) for tracking insertion counts
- Exclusive locking for balancing: Tree balancing only locks when necessary using write locks

Key features:
- PartiallyLockFreeSizeBalancedTreeMethods<TElement>: Abstract base class extending SizeBalancedTreeMethods
- Configurable balancing threshold (default: 10 insertions)
- Manual balancing trigger via ForceBalancing() method
- Thread-safe insertion counter with atomic operations
- Custom delayed balancing logic that mirrors original maintain operations
- Comprehensive test suite including concurrent insertion tests

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
@konard konard changed the title [WIP] Attempt to implement partially lock-free tree with delayed balancing Implement partially lock-free tree with delayed balancing Sep 13, 2025
@konard konard marked this pull request as ready for review September 13, 2025 15:57
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Attempt to implement partially lock-free tree with delayed balancing

2 participants