winipc 0.1.0

data/lib/winipc/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Winipc
+  VERSION = "0.1.0"
+end

data/lib/winipc.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require "winipc/version"
+require "winipc/winipc" # native extension: classes + errors + K_* constants
+
+# winipc — Windows local IPC for Ruby: named pipes, shared memory, and named
+# synchronization objects, with a safe-by-default API.
+#
+#   # named pipe, server side
+#   Winipc::Pipe.listen("myapp/control") do |server|
+#     conn = server.accept
+#     puts conn.read(1024)
+#     conn.write("ack")
+#     conn.close
+#   end
+#
+#   # client side (another process)
+#   Winipc::Pipe.connect("myapp/control") do |c|
+#     c.write("hello")
+#     c.read(1024)
+#   end
+module Winipc
+  # ---- Win32 flag values (verified) --------------------------------------
+  PIPE_ACCESS_INBOUND      = 0x00000001
+  PIPE_ACCESS_OUTBOUND     = 0x00000002
+  PIPE_ACCESS_DUPLEX       = 0x00000003
+  FILE_FLAG_OVERLAPPED     = 0x40000000
+  PIPE_TYPE_MESSAGE        = 0x00000004
+  PIPE_READMODE_MESSAGE    = 0x00000002
+  PIPE_WAIT                = 0x00000000
+  PIPE_REJECT_REMOTE_CLIENTS = 0x00000008
+  PIPE_UNLIMITED_INSTANCES = 255
+  GENERIC_READ             = 0x80000000
+  GENERIC_WRITE            = 0x40000000
+
+  # A Windows API failure carries the originating error code (GetLastError /
+  # the failing return), set on the exception in C.
+  class OSError
+    def code
+      @code
+    end
+  end
+
+  module_function
+
+  # Run a blocking native call cooperatively. Under a Fiber scheduler (e.g.
+  # winloop) the call is offloaded to a worker Thread so the calling fiber
+  # parks (Thread#value routes through the scheduler) and the event loop keeps
+  # serving other fibers; with no scheduler it runs inline (the C call already
+  # releases the GVL). On fiber unwind the worker is killed+joined so it can't
+  # leak or consume data destined for a later op.
+  #
+  # Caveat: if the fiber is unwound (e.g. Timeout) in the instant after the
+  # worker acquired a resource but before the value was delivered, that
+  # acquisition is lost — there is no generic way to hand it back (the same
+  # inherent limitation as a cancelled read that already pulled bytes).
+  def run_blocking
+    sched = Fiber.scheduler
+    return yield unless sched
+
+    worker = Thread.new do
+      Thread.current.report_on_exception = false
+      yield
+    end
+    begin
+      worker.value
+    ensure
+      if worker.alive?
+        worker.kill
+        worker.join
+      end
+    end
+  end
+
+  # Normalize a bare pipe name to the \\.\pipe\ namespace (pass a full
+  # \\server\pipe\name through unchanged).
+  def pipe_path(name)
+    s = name.to_s
+    s.start_with?("\\\\") ? s : "\\\\.\\pipe\\#{s}"
+  end
+
+  # Map a bare object name into the Local\ (default) or Global\ namespace.
+  def obj_path(name, scope)
+    prefix = case scope
+             when :local  then "Local\\"
+             when :global then "Global\\"
+             else raise ArgumentError, "scope must be :local or :global, got #{scope.inspect}"
+             end
+    "#{prefix}#{name}"
+  end
+
+  def server_access(direction)
+    case direction
+    when :duplex   then PIPE_ACCESS_DUPLEX
+    when :inbound  then PIPE_ACCESS_INBOUND
+    when :outbound then PIPE_ACCESS_OUTBOUND
+    else raise ArgumentError, "direction must be :duplex/:inbound/:outbound"
+    end
+  end
+  private_class_method :server_access
+
+  def client_access(direction)
+    case direction
+    when :duplex then GENERIC_READ | GENERIC_WRITE
+    when :read   then GENERIC_READ
+    when :write  then GENERIC_WRITE
+    else raise ArgumentError, "direction must be :duplex/:read/:write"
+    end
+  end
+  private_class_method :client_access
+
+  def ms_for(timeout)
+    return -1 if timeout.nil? # INFINITE (block until signaled / connected)
+
+    t = Float(timeout)
+    raise ArgumentError, "timeout must be non-negative, got #{timeout.inspect}" if t.negative?
+
+    ms = (t * 1000).round
+    # Never collapse a tiny-but-positive wait into a non-blocking poll.
+    ms.zero? && t.positive? ? 1 : ms
+  end
+
+  class Pipe
+    # Create a named-pipe server. Yields a Listener (auto-closed) if a block is
+    # given, else returns it.
+    def self.listen(name, mode: :byte, direction: :duplex, max_instances: :unlimited,
+                    in_buffer: 65_536, out_buffer: 65_536, reject_remote: true, access: :owner)
+      open_mode = Winipc.send(:server_access, direction) | FILE_FLAG_OVERLAPPED
+      pipe_mode = PIPE_WAIT
+      pipe_mode |= PIPE_TYPE_MESSAGE | PIPE_READMODE_MESSAGE if mode == :message
+      pipe_mode |= PIPE_REJECT_REMOTE_CLIENTS if reject_remote
+      max = max_instances == :unlimited ? PIPE_UNLIMITED_INSTANCES : Integer(max_instances)
+      raise ArgumentError, "max_instances must be 1..255" unless (1..255).cover?(max)
+
+      listener = _listen(Winipc.pipe_path(name), open_mode, pipe_mode, max,
+                         Integer(in_buffer), Integer(out_buffer), access)
+      return listener unless block_given?
+
+      begin
+        yield listener
+      ensure
+        listener.close
+      end
+    end
+
+    # Connect to a named-pipe server. Yields a Conn (auto-closed) if a block is
+    # given, else returns it.
+    # +timeout+: nil fails fast if the server isn't connectable now; a number of
+    # seconds retries (server busy or not yet up) until it elapses.
+    def self.connect(name, mode: :byte, direction: :duplex, timeout: nil)
+      access = Winipc.send(:client_access, direction)
+      ms =
+        if timeout.nil?
+          0 # fail fast if the server isn't connectable now
+        else
+          t = Float(timeout)
+          raise ArgumentError, "timeout must be non-negative, got #{timeout.inspect}" if t.negative?
+
+          msr = (t * 1000).round
+          msr.zero? && t.positive? ? 1 : msr # a tiny positive timeout still waits, not fail-fast
+        end
+      conn = Winipc.run_blocking do
+        _connect(Winipc.pipe_path(name), access, mode == :message, ms)
+      end
+      return conn unless block_given?
+
+      begin
+        yield conn
+      ensure
+        conn.close
+      end
+    end
+
+    class Listener
+      # Accept the next client. Blocks (cooperatively under a scheduler). With a
+      # timeout, returns nil if none connects in time.
+      def accept(timeout: nil)
+        Winipc.run_blocking { _accept(Winipc.ms_for(timeout)) }
+      end
+
+      # Accept clients in a loop, yielding (and closing) each connection.
+      def serve
+        loop do
+          conn = accept
+          break if conn.nil?
+
+          begin
+            yield conn
+          ensure
+            conn.close
+          end
+        end
+      end
+    end
+
+    class Conn
+      # Read up to +maxlen+ bytes (byte mode). Returns a binary String, or nil
+      # at clean EOF (peer closed).
+      def read(maxlen)
+        Winipc.run_blocking { _read(maxlen) }
+      end
+
+      # Read one whole message (message mode), reassembling across the buffer.
+      # Returns a binary String or nil at EOF.
+      def read_message(maxlen = 65_536)
+        raise ModeError, "winipc: pipe is not in message mode" unless message?
+
+        Winipc.run_blocking { _read_message(maxlen) }
+      end
+
+      # Write +bytes+; returns the number of bytes written.
+      def write(bytes)
+        Winipc.run_blocking { _write(bytes) }
+      end
+      alias write_message write # in message mode each write is one message
+
+      def <<(bytes)
+        write(bytes)
+        self
+      end
+    end
+  end
+
+  class SharedMemory
+    # Create a named, pagefile-backed shared-memory region of +size+ bytes.
+    def self.create(name, size, access: :readwrite, scope: :local, security: :owner)
+      _create(Winipc.obj_path(name, scope), Integer(size), access != :readonly, security)
+    end
+
+    # Open an existing named region.
+    def self.open(name, access: :readwrite, scope: :local)
+      _open(Winipc.obj_path(name, scope), access != :readonly)
+    end
+
+    # Flush a range (default: whole region) to backing storage.
+    def flush(offset = 0, len = nil)
+      _flush(offset, len)
+    end
+  end
+
+  class Mutex
+    def self.create(name, scope: :local, security: :owner)
+      _create(K_MUTEX, Winipc.obj_path(name, scope), nil, nil, security)
+    end
+
+    def self.open(name, scope: :local)
+      _open(K_MUTEX, Winipc.obj_path(name, scope))
+    end
+
+    # NOTE: a Windows mutex is owned by the acquiring THREAD, so Mutex waits are
+    # NOT offloaded to a worker (that would acquire on the wrong thread). They
+    # release the GVL but, under a fiber scheduler, block the loop for the wait.
+    # Use Event/Semaphore for fiber-cooperative coordination.
+    def lock(timeout: nil)
+      _wait(Winipc.ms_for(timeout)) != :timeout # :ok or :abandoned both acquire
+    end
+
+    def try_lock
+      lock(timeout: 0)
+    end
+
+    def unlock
+      _unlock
+      self
+    end
+
+    def synchronize(timeout: nil)
+      result = _wait(Winipc.ms_for(timeout))
+      raise TimeoutError, "winipc: mutex not acquired within timeout" if result == :timeout
+
+      begin
+        if result == :abandoned
+          raise Abandoned, "winipc: mutex was abandoned by a dead owner; shared state may be inconsistent"
+        end
+
+        yield
+      ensure
+        _unlock
+      end
+    end
+  end
+
+  class Event
+    def self.create(name, manual_reset: false, initial: false, scope: :local, security: :owner)
+      _create(K_EVENT, Winipc.obj_path(name, scope), manual_reset, initial, security)
+    end
+
+    def self.open(name, scope: :local)
+      _open(K_EVENT, Winipc.obj_path(name, scope))
+    end
+
+    # Wait for the event to be signaled. Returns true, or false on timeout.
+    def wait(timeout: nil)
+      Winipc.run_blocking { _wait(Winipc.ms_for(timeout)) } == :ok
+    end
+    # #signal and #reset are defined in C.
+  end
+
+  class Semaphore
+    def self.create(name, initial:, maximum:, scope: :local, security: :owner)
+      unless maximum.is_a?(Integer) && maximum > 0 && initial.is_a?(Integer) && initial >= 0 && initial <= maximum
+        raise ArgumentError, "require 0 <= initial <= maximum and maximum > 0"
+      end
+
+      _create(K_SEM, Winipc.obj_path(name, scope), initial, maximum, security)
+    end
+
+    def self.open(name, scope: :local)
+      _open(K_SEM, Winipc.obj_path(name, scope))
+    end
+
+    # Acquire one unit. Returns true, or false on timeout.
+    def acquire(timeout: nil)
+      Winipc.run_blocking { _wait(Winipc.ms_for(timeout)) } == :ok
+    end
+
+    def try_acquire
+      acquire(timeout: 0)
+    end
+
+    # Release +count+ units; returns the previous count.
+    def release(count = 1)
+      _release(count)
+    end
+
+    # Acquire one unit for the duration of the block, then release it. (Use
+    # #acquire / #release directly for multi-unit patterns.)
+    def synchronize(timeout: nil)
+      raise TimeoutError, "winipc: semaphore not acquired within timeout" unless acquire(timeout: timeout)
+
+      begin
+        yield
+      ensure
+        _release(1)
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: winipc
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- ned
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rake-compiler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: vcvars
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.1
+description: |
+  winipc is a native extension that exposes Windows local inter-process
+  communication through an ergonomic, safe-by-default Ruby API: duplex named
+  pipes (byte and message mode, with a server and a connect-with-retry client),
+  pagefile-backed shared memory via named file mappings, and named
+  synchronization objects (mutex, event, semaphore). Pipe handles are opened
+  for overlapped I/O so they cooperate with a fiber scheduler, and objects are
+  created with a restrictive security descriptor by default. Windows MSVC
+  (mswin) Ruby only.
+executables: []
+extensions:
+- ext/winipc/extconf.rb
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- ext/winipc/extconf.rb
+- ext/winipc/winipc.c
+- lib/winipc.rb
+- lib/winipc/version.rb
+homepage: https://github.com/main-path/winipc
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/main-path/winipc
+  changelog_uri: https://github.com/main-path/winipc/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/main-path/winipc/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: 'Windows local IPC for Ruby: named pipes, shared memory, and named synchronization
+  objects.'
+test_files: []