Module core

Core Module - ThreadShare and SimpleShare

This module provides the core structures for safe data exchange between threads.

Overview

The core module contains two main structures:

• ThreadShare<T> - Full-featured synchronization with change detection
• SimpleShare<T> - Lightweight alternative for basic use cases

ThreadShare

ThreadShare<T> is the main structure that provides comprehensive thread synchronization. It uses Arc<RwLock<T>> internally and provides automatic change notification.

Key Features

• Automatic Cloning: Each thread gets its own clone for safe access
• Change Detection: Built-in waiting mechanisms for data changes
• Flexible Access: Read, write, and update operations with proper locking
• Condition Variables: Efficient waiting for data modifications
• Thread Safety: Implements Send and Sync automatically

Example Usage

use thread_share::ThreadShare;
use std::thread;
use std::time::Duration;

let data = ThreadShare::new(vec![1, 2, 3]);
let clone = data.clone();

// Spawn a thread that modifies the data
thread::spawn(move || {
    thread::sleep(Duration::from_millis(100));
    clone.update(|v| v.push(4));
});

// Wait for changes and read the result
data.wait_for_change_forever();
let result = data.get();
assert_eq!(result, vec![1, 2, 3, 4]);

Performance Characteristics

• Read Operations: Multiple threads can read simultaneously
• Write Operations: Exclusive access during writes
• Change Detection: Efficient condition variable notifications
• Memory Overhead: Minimal overhead from Arc and RwLock structures

SimpleShare

SimpleShare<T> is a simplified version of ThreadShare<T> that provides basic functionality without change detection.

Key Features

• Minimal Overhead: Lighter synchronization primitives
• Essential Operations: Basic get/set/update functionality
• Clone Support: Each thread gets a clone for safe access
• No Change Detection: Simpler implementation without condition variables

Example Usage

use thread_share::SimpleShare;
use std::thread;
use std::time::Duration;

let counter = SimpleShare::new(0);
let clone = counter.clone();

thread::spawn(move || {
    for _ in 0..100 {
        clone.update(|x| *x = *x + 1);
    }
});

thread::sleep(Duration::from_millis(100));
assert_eq!(counter.get(), 100);

When to Use Each

Use ThreadShare when you need:

• Change detection and waiting mechanisms
• Complex synchronization patterns
• Maximum flexibility and features
• Production applications with complex requirements

Use SimpleShare when you need:

• Basic data sharing without change detection
• Minimal overhead and complexity
• Simple producer-consumer patterns
• Learning and prototyping

Thread Safety

Both structures automatically implement Send and Sync traits, making them safe to use across thread boundaries. The internal synchronization primitives ensure that all operations are thread-safe.

Memory Management

• Arc: Provides reference counting for shared ownership
• RwLock: Ensures exclusive write access and concurrent read access
• Mutex: Protects condition variable access
• Condvar: Enables efficient waiting for changes

Best Practices

1. Always clone for thread usage: Use .clone() to get thread-safe copies
2. Use appropriate access patterns: read() for read-only, write() for modifications
3. Consider change detection: Use wait_for_change() when you need to react to updates
4. Minimize lock contention: Keep critical sections as short as possible
5. Handle errors gracefully: Always check return values from operations

Structs

SimpleShare

Simplified version for simple types

ThreadShare

Main structure for data exchange between threads