查看“DObject”的源代码

<span id="dobject---shared-memory-communication-library"></span>
= 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.

<span id="overview"></span>
== 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

<span id="usage-examples"></span>
== Usage Examples ==

<span id="basic-usage"></span>
=== Basic Usage ===

<syntaxhighlight lang="csharp">// 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();</syntaxhighlight>
<span id="wait-and-signal-pattern"></span>
=== Wait and Signal Pattern ===

<syntaxhighlight lang="csharp">// 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();</syntaxhighlight>
<span id="real-world-example-camera-frame-sharing"></span>
=== Real-world Example (Camera Frame Sharing) ===

<syntaxhighlight lang="csharp">// 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...
}</syntaxhighlight>
<span id="important-considerations"></span>
== Important Considerations ==

<span id="memory-layout"></span>
=== Memory Layout ===

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

<span id="process-limits"></span>
=== Process Limits ===

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

<span id="platform-differences"></span>
=== Platform Differences ===

<span id="windows"></span>
==== Windows ====

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

<span id="linux"></span>
==== Linux ====

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

<span id="thread-safety"></span>
=== Thread Safety ===

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

<span id="size-limitations"></span>
=== Size Limitations ===

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

<span id="error-handling"></span>
== Error Handling ==

<syntaxhighlight lang="csharp">try
{
var sharedObj = new DObject("myData", 1024);
// Use sharedObj...
}
catch (Exception ex)
{
// Handle initialization errors
Console.WriteLine($"DObject error: {ex.Message}");
}</syntaxhighlight>
<span id="best-practices"></span>
== Best Practices ==

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

<span id="limitations"></span>
== Limitations ==

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

<span id="configuration"></span>
== Configuration ==

The behavior can be modified through the configuration:

<syntaxhighlight lang="json">{
"DObjectForceUseFile": false, // Force file-based sharing even on Windows
"EnsureFlibSame": true, // Enforce version compatibility
"SharedMemorySize": 268435456 // Default 256MB (in bytes)
}</syntaxhighlight>
The configuration file <code>flib.json</code> should be placed in: - Windows: Same directory as the executable - or on Linux: <code>~/.config/flib/flib.json</code> could also be used

<span id="common-issues"></span>
== Common Issues ==

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