DObject

DObject - Shared Memory Communication Library

DObject is a high-performance inter-process communication (IPC) library that enables shared memory communication between multiple processes on Windows and Linux platforms.

Overview

DObject provides a simple way to share data between processes using memory-mapped files. It handles process synchronization, memory management, and cross-platform compatibility.

Key features: - Fast shared memory communication - Process synchronization with mutexes and events - Cross-platform support (Windows and Linux) - Automatic process tracking and cleanup - Version compatibility checking - Support for up to 8 concurrent processes

Usage Examples

Basic Usage

// Create or connect to a shared memory object
var sharedObj = new DObject("mySharedData", 1024); // name and size in bytes
// Writing data
byte[] dataToWrite = new byte[] { 1, 2, 3, 4 };
sharedObj.Post(dataToWrite);
// Reading data
var reader = sharedObj.Reader(0, 4); // offset and length
byte[] data = reader();

Wait and Signal Pattern

// Process A
var sharedObj = new DObject("syncData", 1024);
sharedObj.Post(someData);
sharedObj.Set(); // Signal other processes
// Process B
var sharedObj = new DObject("syncData", 1024);
sharedObj.Wait(); // Wait for signal
var reader = sharedObj.Reader(0, dataSize);
var data = reader();

Real-world Example (Camera Frame Sharing)

// Producer (Camera Process)
var frameObj = new DObject("cameraFrame", 1920 1080 3); // RGB frame buffer
unsafe
{
// Write frame metadata
(int)frameObj.myPtr = width;
(int)(frameObj.myPtr + 4) = height;
(int)(frameObj.myPtr + 8) = channels;
// Copy frame data
Marshal.Copy(frameBuffer, 0, (IntPtr)(frameObj.myPtr + 12), frameSize);
frameObj.Set(); // Notify consumers
}
// Consumer (Display Process)
var frameObj = new DObject("cameraFrame", 1920 1080 3);
frameObj.Wait(); // Wait for new frame
unsafe
{
int width = (int)frameObj.myPtr;
int height = (int)(frameObj.myPtr + 4);
int channels = (int)(frameObj.myPtr + 8);
// Process frame data...
}

Important Considerations

Memory Layout

The shared memory is organized as follows: - First 1024 bytes: Metadata (process tracking, version info) - Remaining space: User data slots

Process Limits

• Maximum 8 concurrent processes can share the same DObject
• Process slots are automatically managed and cleaned up

Platform Differences

Windows

• Uses native shared memory with EventWaitHandle
• Supports process-specific event signaling
• Version compatibility checking

Linux

• Uses memory-mapped files
• File-based event synchronization
• Located in system temp directory

Thread Safety

• All operations are thread-safe using mutexes
• Abandoned mutex detection and recovery
• Automatic mutex cleanup

Size Limitations

• Default cache size is 256MB
• Object names limited to 32 characters
• Individual object sizes should be carefully planned

Error Handling

try
{
var sharedObj = new DObject("myData", 1024);
// Use sharedObj...
}
catch (Exception ex)
{
// Handle initialization errors
Console.WriteLine($"DObject error: {ex.Message}");
}

Best Practices

1. Resource Cleanup
   • DObjects are automatically cleaned up when processes exit
   • Use appropriate buffer sizes to avoid memory waste
2. Error Handling
   • Always handle potential exceptions during mutex operations
   • Check return values from Wait operations
3. Performance
   • Minimize the frequency of Post/Set operations
   • Use appropriate buffer sizes for your data
   • Consider using Reader delegates for frequent reads
4. Version Compatibility
   • Different versions of applications using DObject should be compatible
   • Use version checking when required

Limitations

• Maximum 8 concurrent processes
• 32-character name limit
• Default 256MB total shared memory size
• Windows-specific features not available on Linux

Configuration

The behavior can be modified through the configuration:

{
"DObjectForceUseFile": false, // Force file-based sharing even on Windows
"EnsureFlibSame": true, // Enforce version compatibility
"SharedMemorySize": 268435456 // Default 256MB (in bytes)
}

The configuration file flib.json should be placed in: - Windows: Same directory as the executable - or on Linux: ~/.config/flib/flib.json could also be used

Common Issues

1. Mutex Abandonment
   • Handled automatically with retry mechanism
   • May indicate crashed processes
2. Version Mismatch
   • Different versions of applications may be incompatible
   • Check FundamentalLib versions
3. Memory Overflow
   • Monitor buffer sizes
   • Use appropriate initial sizes
4. Process Limits
   • Error when exceeding 8 processes
   • Check active processes if limit reached
5. Configuration Not Found
   • Verify flib.json location
   • Check file permissions
   • Ensure valid JSON format
6. Linux Permission Issues
   • Ensure write access to /tmp
   • Check SELinux policies if applicable
   • Verify user permissions
7. Memory Allocation Failures
   • Check available system memory
   • Monitor total DObject allocations
   • Consider reducing individual object sizes
8. Cross-Platform Compatibility
   • Test on both platforms
   • Handle platform-specific paths
   • Use platform-agnostic event handling