IO::Memory

Memory-mapped IO objects for zero-copy data sharing with cross-platform support for Linux (memfd_create), POSIX (shm_open), and generic implementations.

Motivation

Modern applications increasingly require efficient memory sharing and zero-copy operations, especially in high-performance scenarios like web servers, data processing pipelines, and inter-process communication. IO::Memory provides a cross-platform abstraction over memory-mapped files that automatically selects the best available implementation based on your platform:

• Linux: Uses memfd_create() for anonymous memory objects with file descriptor passing
• POSIX: Uses shm_open() for POSIX shared memory objects
• Generic: Falls back to temporary files for maximum compatibility

This gem is designed to work seamlessly with Ruby's IO::Buffer class, providing efficient memory mapping capabilities that integrate well with modern Ruby's IO subsystem.

Features

• Cross-platform: Automatically selects the best memory implementation for your platform
• Zero-copy: Direct memory mapping without data copying
• IO::Buffer integration: Works seamlessly with Ruby's built-in buffer objects
• File descriptor passing: Share memory between processes (where supported)
• Automatic cleanup: Built-in resource management with with blocks
• Multiple sizes: Support for buffers from zero bytes to multiple gigabytes

Usage

Please see the project documentation for more details.

• Getting Started - This guide explains how to use io-memory for efficient memory operations and zero-copy data sharing.

• Process Memory Sharing - This guide demonstrates how to share memory between processes using io-memory for high-performance inter-process communication (IPC).

Platform Support

Platform	Implementation	Features
Linux	memfd_create()	Anonymous memory, file descriptor passing
macOS/BSD	shm_open()	POSIX shared memory, file descriptor passing
Windows/Other	Temporary files	File descriptor passing, maximum compatibility

Performance

IO::Memory provides significant performance benefits for memory-intensive operations:

• Zero-copy: No data copying when mapping memory
• OS-optimized: Uses the most efficient memory primitives available
• Large buffer support: Handles multi-gigabyte buffers efficiently
• Shared memory: Enable inter-process communication without serialization

Releases

Please see the project releases for all releases.

v0.0.1

• Initial implementation with cross-platform memory mapping support
• Linux memfd_create() implementation for anonymous memory objects
• POSIX shm_open() implementation for shared memory
• Generic temporary file fallback for maximum compatibility
• Integration with Ruby's IO::Buffer class
• Automatic resource cleanup with with blocks

Contributing

We welcome contributions to this project.

1. Fork it.
2. Create your feature branch (git checkout -b my-new-feature).
3. Commit your changes (git commit -am 'Add some feature').
4. Push to the branch (git push origin my-new-feature).
5. Create new Pull Request.

Developer Certificate of Origin

In order to protect users of this project, we require all contributors to comply with the Developer Certificate of Origin. This ensures that all contributions are properly licensed and attributed.

Community Guidelines

This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.