io-memory 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65cddba6258b4275777fda4eef9777255547ac351b3ca3c7e9f64c84f0540a5f
+  data.tar.gz: bf3066d3b0a616346326cfd1df300ce7e0d81183675bb778b62ab77eb1329ef7
+SHA512:
+  metadata.gz: c256056fa025c5e215c22b41a672b657e4bb92db4f2fe08dddd679e8a5c9397a1b293139e5122250de4644e9e04583c00a89e0b54f47e5caf9901e9ce60fe6cc
+  data.tar.gz: fe1371a70acf30c6e91a4f258bae9aeb82a9ec2e2af148d423c744e8e00f8aedde117ca479ca7f2e781e0bb5c333c0a7f5e766302f656cb1a32a134259429f18

data/lib/io/memory/generic.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+
+require "tempfile"
+
+module IO::Memory
+	# Generic implementation of memory-mapped IO using temporary files.
+	# This implementation provides maximum compatibility across platforms
+	# by using Ruby's built-in Tempfile class and file descriptor mapping.
+	# The temporary files are unlinked immediately after creation to behave
+	# like anonymous memory objects.
+	module Generic
+		extend self
+
+		module Implementation
+			# Handle class that wraps the IO and manages tempfile cleanup
+			class Handle
+				def initialize(io, tempfile, size)
+					@io = io
+					@tempfile = tempfile
+					@size = size
+				end
+									
+				def io
+					@io
+				end
+									
+				def map(size = nil)
+					size ||= @size
+					::IO::Buffer.map(@io, size)
+				end
+									
+				def close
+					@io.close unless @io.closed?
+				ensure
+					# Clean up tempfile
+					if @tempfile && !@tempfile.closed?
+						@tempfile.close
+						@tempfile = nil
+					end
+				end
+									
+				def closed?
+					@io.closed?
+				end
+			end
+			
+			def self.create_handle(size)
+				# Create a temporary file
+				tempfile = Tempfile.new(["io_memory", ".tmp"])
+									
+				begin
+					# Set the size
+					tempfile.truncate(size) if tempfile.respond_to?(:truncate)
+											
+					# Immediately unlink the file so it's deleted when closed
+					# This makes it behave more like memfd - it exists only in memory/cache
+					File.unlink(tempfile.path)
+											
+					# Create IO from file descriptor and wrap in Handle
+					io = ::IO.for_fd(tempfile.fileno, autoclose: false)
+					
+					return Handle.new(io, tempfile, size)
+				rescue => error
+					# Clean up on error
+					tempfile.close
+					tempfile.unlink if File.exist?(tempfile.path)
+					raise IO::Memory::MemoryError, "Failed to create temporary file buffer!"
+				end
+			end
+		end
+		
+		private_constant :Implementation
+
+		# Check if the generic temporary file implementation is supported on this system.
+		# This implementation always returns true as it uses standard Ruby temporary files
+		# which are available on all platforms. It serves as a fallback when platform-specific
+		# implementations like Linux memfd_create or POSIX shm_open are not available.
+		# @returns [Boolean] always true, as temporary files are universally supported
+		def self.supported?
+			true
+		end
+
+		# Create a new memory-mapped buffer using a temporary file.
+		# The temporary file is immediately unlinked to behave like
+		# anonymous memory, existing only in the filesystem cache.
+		# @parameter size [Integer] size of the memory buffer in bytes
+		# @returns [Object] a handle object that provides access to the memory buffer
+		def new(size)
+			Implementation.create_handle(size)
+		end
+
+		# Create a memory-mapped buffer and yield it to a block.
+		# The buffer is automatically cleaned up when the block exits,
+		# regardless of whether an exception is raised.
+		# @parameter size [Integer] size of the memory buffer in bytes
+		# @yields {|handle| ...}
+		# 	@parameter handle [Object] the handle to the memory buffer with access to IO and mapping operations
+		# @returns [Object] the result of the block execution
+		def with(size, &block)
+			handle = new(size)
+			begin
+				yield handle
+			ensure
+				handle.close
+			end
+		end
+	end
+end 

data/lib/io/memory/linux.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+
+require "fiddle"
+require "fiddle/import"
+
+module IO::Memory
+	# Linux-specific implementation of memory-mapped IO using memfd_create.
+	# This implementation provides the most efficient memory mapping on Linux
+	# by using the memfd_create system call to create anonymous memory objects
+	# that exist only in memory without being backed by any filesystem.
+	module Linux
+		extend self
+
+		module Implementation
+			extend Fiddle::Importer
+			
+			def self.supported?
+				@supported
+			end
+							
+			# memfd_create system call constants
+			MFD_CLOEXEC = 0x01
+			
+			# Load system functions
+			LIBC = Fiddle.dlopen(nil)
+			
+			# Load memfd_create function
+			MEMFD_CREATE = Fiddle::Function.new(
+				LIBC["memfd_create"],
+				[Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT],
+				Fiddle::TYPE_INT
+			)
+			
+			# Load ftruncate function
+			FTRUNCATE = Fiddle::Function.new(
+				LIBC["ftruncate"],
+				[Fiddle::TYPE_INT, Fiddle::TYPE_LONG],
+				Fiddle::TYPE_INT
+			)
+
+			CLOSE = Fiddle::Function.new(
+				LIBC["close"],
+				[Fiddle::TYPE_INT],
+				Fiddle::TYPE_INT
+			)
+
+			# Handle class that wraps the IO
+			class Handle
+				def initialize(io, size)
+					@io = io
+					@size = size
+				end
+									
+				def io
+					@io
+				end
+									
+				def map(size = nil)
+					size ||= @size
+					::IO::Buffer.map(@io, size)
+				end
+									
+				def close
+					@io.close unless @io.closed?
+				end
+									
+				def closed?
+					@io.closed?
+				end
+			end
+
+			def self.create_handle(size)
+				# Create the memory file descriptor
+				file_descriptor = MEMFD_CREATE.call("io_memory", MFD_CLOEXEC)
+									
+				if file_descriptor == -1
+					raise IO::Memory::MemoryError, "Failed to create memfd!"
+				end
+									
+				# Set the size
+				if FTRUNCATE.call(file_descriptor, size) == -1
+					# Clean up on error
+					begin
+						CLOSE.call(file_descriptor)
+					rescue
+						# Ignore cleanup errors
+					end
+					raise IO::Memory::MemoryError, "Failed to set memfd size!"
+				end
+									
+				# Convert to IO object and wrap in Handle
+				io = ::IO.for_fd(file_descriptor, autoclose: true)
+				
+				return Handle.new(io, size)
+			rescue => error
+				# Clean up on any error
+				if file_descriptor and file_descriptor != -1
+					begin
+						CLOSE.call(file_descriptor)
+					rescue
+						# Ignore cleanup errors
+					end
+				end
+				raise
+			end
+
+			@supported = true
+		rescue
+			@supported = false
+		end
+
+		private_constant :Implementation
+
+		# Check if the Linux memfd_create implementation is supported on this system.
+		# This implementation uses the memfd_create() system call available on Linux 3.17+
+		# and provides the most efficient memory mapping by creating anonymous memory objects.
+		# @returns [Boolean] true if memfd_create is available, false otherwise
+		def self.supported?
+			Implementation.supported?
+		end
+
+		if supported?
+			# Create a new memory-mapped buffer using Linux memfd_create.
+			# This creates an anonymous memory object that exists only in memory
+			# without being backed by any filesystem.
+			# @parameter size [Integer] size of the memory buffer in bytes
+			# @returns [Object] a handle object that provides access to the memory buffer
+			def new(size)
+				Implementation.create_handle(size)
+			end
+
+			# Create a memory-mapped buffer and yield it to a block.
+			# The buffer is automatically cleaned up when the block exits,
+			# regardless of whether an exception is raised.
+			# @parameter size [Integer] size of the memory buffer in bytes
+			# @yields {|handle| ...}
+			# 	@parameter handle [Object] the handle to the memory buffer with access to IO and mapping operations
+			# @returns [Object] the result of the block execution
+			def with(size, &block)
+				handle = new(size)
+				begin
+					yield handle
+				ensure
+					handle.close
+				end
+			end
+		end
+	end
+end

data/lib/io/memory/posix.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+
+require "fiddle"
+require "securerandom"
+
+module IO::Memory
+	# POSIX implementation of memory-mapped IO using shm_open.
+	# This implementation provides efficient memory mapping on POSIX-compliant
+	# systems (macOS, BSD, etc.) by using the shm_open system call to create
+	# shared memory objects. These objects can be shared between processes
+	# and provide zero-copy memory operations.
+	module POSIX
+		extend self
+
+		module Implementation
+			def self.supported?
+				@supported
+			end
+			
+			# Use Ruby's File constants instead of hardcoded values for cross-platform compatibility
+			O_CREAT = IO::CREAT
+			O_EXCL = IO::EXCL
+			O_RDWR = IO::RDWR
+							
+			# Load system functions
+			LIBC = Fiddle.dlopen(nil)
+			
+			SHM_OPEN = Fiddle::Function.new(
+				LIBC["shm_open"],
+				[Fiddle::TYPE_VOIDP, Fiddle::TYPE_INT, Fiddle::TYPE_INT],
+				Fiddle::TYPE_INT
+			)
+			
+			SHM_UNLINK = Fiddle::Function.new(
+				LIBC["shm_unlink"], 
+				[Fiddle::TYPE_VOIDP],
+				Fiddle::TYPE_INT
+			)
+			
+			FTRUNCATE = Fiddle::Function.new(
+				LIBC["ftruncate"],
+				[Fiddle::TYPE_INT, Fiddle::TYPE_LONG],
+				Fiddle::TYPE_INT
+			)
+
+			class MemoryError < StandardError; end
+							
+			# Handle class that wraps the IO and manages shared memory cleanup
+			class Handle
+				def initialize(io, shm_name, size)
+					@io = io
+					@shm_name = shm_name
+					@size = size
+				end
+									
+				def io
+					@io
+				end
+									
+				def map(size = nil)
+					size ||= @size
+					::IO::Buffer.map(@io, size)
+				end
+									
+				def close
+					@io.close unless @io.closed?
+				ensure
+					# Unlink the shared memory object
+					if @shm_name
+						Implementation::SHM_UNLINK.call(@shm_name)
+						@shm_name = nil
+					end
+				end
+									
+				def closed?
+					@io.closed?
+				end
+			end
+
+			def self.create_handle(size)
+				# Generate a unique name using multiple entropy sources to avoid collisions
+				# in high-concurrency situations
+				max_attempts = 8
+				last_error = nil
+				
+				max_attempts.times do
+					# The most portable maximum length for a POSIX shared memory name is 14 characters:
+					shm_name = "/#{SecureRandom.hex(7)}"
+					
+					# Create shared memory object with O_EXCL to ensure uniqueness
+					shm_fd = SHM_OPEN.call(shm_name, O_CREAT | O_EXCL | O_RDWR, 0600)
+					
+					if shm_fd >= 0
+						# Success! Set the size of the shared memory object
+						if FTRUNCATE.call(shm_fd, size) == 0
+							# Create IO object from file descriptor
+							io = ::IO.for_fd(shm_fd, autoclose: true)
+
+							# Return Handle that manages both IO and cleanup
+							return Handle.new(io, shm_name, size)
+						else
+							# ftruncate failed, clean up
+							SHM_UNLINK.call(shm_name)
+							raise IO::Memory::MemoryError, "Failed to set shared memory size to #{size}!"
+						end
+					else
+						# Store the error for potential debugging
+						last_error = Fiddle.last_error
+					end
+					# If we get here, shm_open failed (likely name collision), try again with new name
+				end
+				
+				# If we've exhausted all attempts:
+				if last_error
+					cause = SystemCallError.new(last_error)
+				end
+				
+				raise IO::Memory::MemoryError, "Failed to create shared memory object after #{max_attempts} attempts!", cause: cause
+			end
+
+			@supported = true
+		rescue
+			@supported = false
+		end
+					
+		private_constant :Implementation
+
+		# Check if the POSIX shared memory implementation is supported on this system.
+		# This implementation uses shm_open() and is available on POSIX-compliant systems
+		# like macOS, BSD, and some Linux configurations with shared memory support.
+		# @returns [Boolean] true if POSIX shared memory is available, false otherwise
+		def self.supported?
+			Implementation.supported?
+		end
+
+		if supported?
+			# Create a new memory-mapped buffer using POSIX shared memory.
+			# This creates a shared memory object using shm_open that can be
+			# shared between processes and provides zero-copy operations.
+			# @parameter size [Integer] size of the memory buffer in bytes
+			# @returns [Object] a handle object that provides access to the memory buffer
+			def new(size)
+				Implementation.create_handle(size)
+			end
+
+			# Create a memory-mapped buffer and yield it to a block.
+			# The buffer is automatically cleaned up when the block exits,
+			# regardless of whether an exception is raised.
+			# @parameter size [Integer] size of the memory buffer in bytes
+			# @yields {|handle| ...}
+			# 	@parameter handle [Object] the handle to the memory buffer with access to IO and mapping operations
+			# @returns [Object] the result of the block execution
+			def with(size, &block)
+				handle = new(size)
+				begin
+					yield handle
+				ensure
+					handle.close
+				end
+			end
+		end
+	end
+end 

data/lib/io/memory/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+
+# @namespace
+class IO
+	# @namespace
+	module Memory
+		VERSION = "0.0.1"
+	end
+end

data/lib/io/memory.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# Released under the MIT License.
+# Copyright, 2025, by Shopify Inc.
+
+require_relative "memory/version"
+
+require_relative "memory/linux"
+require_relative "memory/posix"
+require_relative "memory/generic"
+
+# Provides memory-mapped IO objects for zero-copy data sharing with cross-platform support.
+# This module automatically selects the best available implementation based on the platform:
+# - Linux: Uses memfd_create() for anonymous memory objects
+# - POSIX: Uses shm_open() for shared memory objects  
+# - Generic: Uses temporary files for maximum compatibility
+module IO::Memory
+	# Exception raised when memory operations fail.
+	# This includes errors during memory buffer creation, mapping, or cleanup operations.
+	class MemoryError < StandardError; end
+	
+	# Select the best available implementation
+	# Priority: Linux (memfd_create) > POSIX (shm_open) > Generic (tempfile)
+	if Linux.supported?
+		extend Linux
+	elsif POSIX.supported?
+		extend POSIX
+	else
+		extend Generic
+	end
+end 

data/license.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright, 2025, by Shopify Inc.  
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/readme.md

@@ -0,0 +1,80 @@
+# `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.
+
+[![Development Status](https://github.com/socketry/io-memory/workflows/Test/badge.svg)](https://github.com/socketry/io-memory/actions?workflow=Test)
+
+## 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](https://socketry.github.io/io-memory/) for more details.
+
+  - [Getting Started](https://socketry.github.io/io-memory/guides/getting-started/index) - This guide explains how to use `io-memory` for efficient memory operations and zero-copy data sharing.
+
+  - [Process Memory Sharing](https://socketry.github.io/io-memory/guides/process-sharing/index) - 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](https://socketry.github.io/io-memory/releases/index) 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](https://developercertificate.org/). 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.

data/releases.md

@@ -0,0 +1,10 @@
+# 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

metadata

@@ -0,0 +1,61 @@
+--- !ruby/object:Gem::Specification
+name: io-memory
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Shopify Inc.
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/io/memory.rb
+- lib/io/memory/generic.rb
+- lib/io/memory/linux.rb
+- lib/io/memory/posix.rb
+- lib/io/memory/version.rb
+- license.md
+- readme.md
+- releases.md
+homepage: https://github.com/socketry/io-memory
+licenses:
+- MIT
+metadata:
+  documentation_uri: https://socketry.github.io/io-memory/
+  source_code_uri: https://github.com/socketry/io-memory.git
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Memory-mapped IO objects for zero-copy data sharing.
+test_files: []