shatter 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 21861829b74cc78af7c6dc8db6b9bab8fd13e87c
+  data.tar.gz: 57b5858ca1af53a8c035d83c818f46df455409ea
+SHA512:
+  metadata.gz: cb13accb271cb65b0da9b641544b46131cbef0c2a97f3332e0ad841126aa8e5005058432f39c196db168cf910c70225ffcb3f54ed1824bbd7df915588c102f43
+  data.tar.gz: 6b54e5c27425d2c25f3fa4bb898a5425c6c8a38635d82d273de626417f7ec9b6141ee0084e57d117c4971e2b3b0bef8ba81d4c52b415d35b02cbc3085930f563

data/lib/shatter.rb

@@ -0,0 +1,163 @@
+require 'funtools'
+require 'shatter/controller'
+
+module Shatter
+  extend self
+  VERSION   = '0.0.1'
+  PORTRANGE = 9479..9749
+
+  controller = nil
+  set        = ->(new_controller) { controller ||= new_controller }
+
+  # Public: Set the Controller for the currently running process.  This will be
+  # used directly if the current process is expected to be passed messages.
+  #
+  # parent - Pid to which to report the process's new Pid. (default: nil)
+  #
+  # Returns nothing.
+  define_method(:init)    { |parent=nil| set.(Controller.new(parent)) }
+
+  # Public: Clear the process's Controller, then call init to set a new one.
+  # This is needed after calling fork in order to obtain a new socket.
+  #
+  # parent - Pid representing the parent process from which the new process has
+  #          been forked.
+  #
+  # Returns nothing.
+  define_method(:chip)    { |parent| controller=nil; init(parent) }
+
+  # Public: Wrap Controller#receive, passing a given block to the current
+  # Controller.
+  #
+  # block - Proc which will process messages passed to it from the Controller's
+  #         mailbox.
+  #
+  # Returns the result of block being passed messages from Controller's mailbox.
+  define_method(:receive) { |&block| controller.receive(&block) }
+
+  # Public: Call a given method on a Module, passing in given arguments.
+  #
+  # mod  - Module which contains the method referenced by fun.
+  # fun  - Symbol or String referencing a method on the Module provided.
+  # args - Arguments to be passed to the method.
+  #
+  # Returns the result of invoking fun(*args) on mod.
+  define_method(:mfa)     { |mod, fun, args| mod.send(fun, *args) }
+
+  # Public - Fetch the current Controllers pid if it is set.
+  #
+  # Returns a Pid or else nil.
+  define_method(:pid)     { controller.pid if controller }
+
+  # Public - Return the Pid of the process which spawned the current process if
+  # one exists.
+  #
+  # Returns a Pid or else nil.
+  define_method(:parent)  { controller.parent if controller }
+end
+
+module Kernel
+  private
+
+  # Public: Fork a new process to perform a given job.
+  #
+  # mod  - Module which contains the method referenced by fun.
+  # fun  - Symbol or String referencing a method on the Module provided.
+  # args - Arguments to be passed to the method.
+  #
+  # Returns nothing.
+  def chip(mod, fun, *args)
+    forked = fork do
+      Shatter.chip(Shatter.pid)
+      Shatter.mfa(mod, fun, args)
+    end
+    Process::detach(forked)
+  end
+
+  # Public: Return the current Controller's Pid if applicable.
+  #
+  # Returns a Pid or else nil.
+  def pid
+    Shatter.pid
+  end
+
+  # Public: Wrap Pid#pass.
+  #
+  # Returns nothing.
+  def pass(target, *messages)
+    target.pass(*messages)
+  end
+
+  # Public: Return the current Controller's Parent's Pid if applicable.
+  #
+  # Returns a Pid or else nil.
+  def parent
+    Shatter.parent
+  end
+
+  match_proc = ->(a, b) do
+    if([a,b].map { |o| o.is_a?(Enumerable) && a.class == b.class }.all?)
+      raise ArgumentError unless a.length == b.length
+
+      zipped = a.is_a?(Hash) ? a.sort.zip(b.sort) : a.zip(b)
+
+      zipped.reduce(true) do |c, e|
+        c && match.(*e)
+      end
+    else
+      a.nil? || a == b
+    end
+  end
+
+  # Public: Define a pattern to be matched within the context of a receive
+  # block, providing a block to execute when pattern is matched.
+  #
+  # l - Any number of arguments to define a pattern against which to match.
+  # b - Proc to pass the arguments to if all pattern matches succeed.
+  #
+  # Raises SyntaxError if the thread is not called within the context of a
+  # receive block (as signified by the thread variable :matches).
+  #
+  # Returns nothing.
+  define_method :match do |*l, &b|
+    unless Thread.current[:matches].is_a?(Array)
+      raise(SyntaxError, 'syntax error, unexpected match')
+    end
+
+    Thread.current[:matches] << ->(n) do
+     ->(*m) do
+       if m.length == n.length
+         raise NoMatch unless m.zip(n).map { |e| match_proc.(*e) }.all?
+         instance_exec(*n, &b)
+       end
+     end.(*l)
+    end
+  end
+
+  # Public: Build a pattern list and wrap Controller#receive, receiving items
+  # from the Controller's mailbox and responding to them as appropriate.
+  #
+  # block - Proc containing pattern definitons.
+  #
+  # Returns nothing.
+  def receive(&block)
+    old_matches = Thread.current[:matches]
+    Thread.current[:matches] = []
+
+    yield
+
+    # item is always an array due to the way Controller#receive and Pid#pass
+    # work
+    Shatter.receive do |item|
+      Thread.current[:matches].each do |pattern|
+        begin
+          return instance_exec(item, &pattern)
+        rescue NoMatch
+        end
+      end
+      instance_exec { raise NoMatch }
+    end
+
+    Thread::current[:matches] = old_matches
+  end
+end

data/lib/shatter/controller.rb

@@ -0,0 +1,167 @@
+require 'shatter/pid'
+require 'shatter/pidlist'
+require 'socket'
+require 'thread'
+
+module Shatter
+  class Controller
+    attr_reader :parent
+
+    # Public: Initialize the Controller, setting up the listening Socket and
+    # thread to manage the mailbox.
+    #
+    # parent - Pid of the parent Controller, if applicable.
+    def initialize(parent)
+      @parent  = parent
+      @socket  = listen
+      @mailbox = Queue.new
+      @known   = Shatter::Pidlist.new
+      @chunks  = {}
+
+      pass(@parent, :system, [:childpid, pid]) if @parent
+      Thread.new { mailbox_loop }
+    end
+
+    # Public: Pass items in the current mailbox to a given block, removing them
+    # permanently from the mailbox unless the item doesn't match any pattern in
+    # the block.
+    #
+    # Returns nothing.
+    def receive(&block)
+      newbox = Queue.new
+      item = @mailbox.pop
+      instance_exec { block.(item) }
+    rescue NoMatch
+      newbox << item
+      retry
+    ensure
+      restore_mailbox(@mailbox, newbox, nil)
+    end
+
+    # Public: Return the Pid representing the Controller, initializing the
+    # struct if necessary.
+    #
+    # Returns a Pid.
+    def pid
+      unless @pid
+        _, port, _, ip = @socket.addr.map(&:freeze)
+        @pid           = Shatter::Pid.new($$, ip, port, '')
+      end
+      @pid
+    end
+
+    private
+
+    # Internal: Accept connections on the listening socket, accepting messages
+    # and putting them into the mailbox.  This should be run within its own
+    # thread.
+    #
+    # Does not return.
+    deftail :mailbox_loop do
+      connection = @socket.accept
+      Thread.new do
+        data = connection.read
+        begin
+          message = Marshal.load(data)
+          @mailbox << message unless handle_message(message)
+        rescue ArgumentError
+        end
+      end
+      mailbox_loop
+    end
+
+    # Internal: Open a listening socket on the first available port within a
+    # given range.
+    #
+    # socket - TCPServer if one has been established, or nil. (default: nil)
+    # range  - Range of ports to try to bind to. (default: 9479..9749)
+    # port   - Fixnum indicating the port to attempt to bind to.
+    #          (default: lowest port in range)
+    #
+    # Returns a listening TCPSocket.
+    deftail :listen do |socket=nil, range=PORTRANGE, port=range.min|
+      socket ? socket : listen(get_socket(port, range.max), range, port+1)
+    end
+
+    # Internal: Restore the state of a mailbox from a mailbox and temporary
+    # mailbox, first emptying the mailbox into the temporary queue and then
+    # vise versa, keeping the order consistent.
+    #
+    # a - Queue representing the original mailbox.
+    # b - Queue representing the temporary target mailbox.
+    # c - Status indication - true indicating that the original mailbox is
+    #     ready to be filled, with any other value indicating that the original
+    #     mailbox is still in need of being emptied.
+    #
+    # Returns nothing.
+    defpattern :restore_mailbox do
+      restore_mailbox(nil, nil, true) do |a,b,_|
+        drain_mailbox(a, b)
+      end
+      restore_mailbox(nil, nil, nil)  do |a,b,_|
+        restore_mailbox(b, a, drain_mailbox(a, b))
+      end
+    end
+
+    # Internal: Check for any messages which are meant to be handled by the
+    # system itself (indicated by [:system, [:type, payload]] structure).
+    # Handle any which are encountered, or else return false.  Handlers must
+    # return a truthy value to avoid the system message being added to the
+    # mailbox.
+    #
+    # message - Message to be checked.
+    #
+    # Returns false unless a message is handled.
+    defpattern :handle_message do
+      handle_message([:system, [:childpid, nil]]) { |_, pid| add_pid(pid.last) }
+      handle_message(nil)                         { |_| false }
+    end
+
+    # Internal: Add a Pid of another Controller to a list of known Pids.
+    #
+    # pid - Pid representing another Controller.
+    #
+    # Returns the Pid.
+    def add_pid(pid)
+      @known.insert(pid)
+    end
+
+    # Internal: Remove all messages from a given source Queue, inserting them
+    # into a target Queue.
+    #
+    # source - Queue from which to drain messages.
+    # target - Queue into which messages should be pushed.
+    #
+    # Returns true once source is empty.
+    def drain_mailbox(source, target)
+      loop { target << source.pop(true) }
+    rescue ThreadError
+      true
+    end
+
+    # Internal: Attempt to start a TCPServer on a given port.
+    #
+    # port - Fixnum indicating the port to which to attempt to bind.
+    # max  - Fixnum representing the maximum port allowable.
+    #
+    # Raises StandardError if port is greater than max.
+    #
+    # Returns a TCPServer if bound, or nil if the port is in use.
+    def get_socket(port, max)
+      raise StandardError, "Cannot allocate a port" if port > max
+
+      TCPServer.open('127.0.0.1', port)
+    rescue Errno::EADDRINUSE
+      nil
+    end
+
+    # listen :: Maybe Socket -> Range -> Fixnum -> Socket
+    settype(:listen, [IPSocket, NilClass], Range, Fixnum, IPSocket)
+    # restore_mailbox :: Queue -> Queue -> Bool -> Bool
+    settype(:restore_mailbox, Queue, Queue, [TrueClass, NilClass], TrueClass)
+    # drain_mailbox :: Queue -> Queue -> Bool
+    settype(:drain_mailbox, Queue, Queue, TrueClass)
+    # get_socket :: Fixnum -> Fixnum -> Maybe Socket
+    settype(:get_socket, Fixnum, Fixnum, [NilClass, IPSocket])
+  end
+end

data/lib/shatter/pid.rb

@@ -0,0 +1,26 @@
+require 'socket'
+
+module Shatter
+  class Pid < Struct.new(:pid, :host, :port, :name)
+    # Public: Open a socket to a given Controller and send any number of
+    # messages to it.
+    #
+    # messages - Any number of arguments which will constitute a message to be
+    #            sent to the Controller.
+    #
+    # Returns nothing.
+    def pass(*messages)
+      socket = TCPSocket.new(host, port)
+      socket.send(Marshal.dump(messages), 0)
+      socket.close
+    end
+
+    # Public: Represent the Pid as a String.
+    #
+    # Returns a String.
+    def inspect
+      "<#{pid} #{host}:#{port}#{" (#{name})" unless name.empty?}>"
+    end
+    alias :to_s :inspect
+  end
+end

data/lib/shatter/pidlist.rb

@@ -0,0 +1,60 @@
+require 'funtools'
+require 'thread'
+
+module Shatter
+  class Pidlist
+    include Enumerable
+
+    # Public: Initialize the internal state of the Pidlist.
+    def initialize
+      @known = []
+      @mutex = Mutex.new
+    end
+
+    # Public: Iterate through known Pids.
+    #
+    # Yields each item in the list of known Pids.
+    #
+    # Returns nothing.
+    def each(&block)
+      @known.each(&block)
+    end
+
+    # Public: Add a Pid to the list of known Pids.
+    #
+    # pid - Pid to be tracked.
+    #
+    # Returns nothing.
+    def insert(pid)
+      mutex.synchronize do
+        known << pid
+      end
+    end
+
+    # Internal: Create a method which allows for fetching a Pid by a given
+    # attribute.
+    #
+    # Signature
+    #
+    #   by_<kind>
+    #
+    # kind - String containing the name of the value by which to select.
+    def self.build_fetch_by(kind)
+      define_method("by_#{kind}") do |val|
+        select { |pid| pid.send(kind) == val }
+      end
+    end
+
+    build_fetch_by('name')
+    build_fetch_by('pid')
+    build_fetch_by('host')
+    build_fetch_by('port')
+
+    # insert :: Pid -> [Pid]
+    settype(:insert, Pid, Array)
+
+    private
+
+    attr_reader :known, :mutex
+  end
+end

metadata

@@ -0,0 +1,67 @@
+--- !ruby/object:Gem::Specification
+name: shatter
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Tina Wuest
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-11-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: funtools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.7.1
+description: Framework to facilitate distributed computing with Ruby
+email: tina@wuest.me
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/shatter.rb
+- lib/shatter/controller.rb
+- lib/shatter/pid.rb
+- lib/shatter/pidlist.rb
+homepage: https://gitlab.com/wuest/shatter
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Distributed ruby library
+test_files: []