raktr 0.0.1

data/lib/raktr/connection.rb

@@ -0,0 +1,339 @@
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+require_relative 'connection/error'
+require_relative 'connection/callbacks'
+require_relative 'connection/peer_info'
+require_relative 'connection/tls'
+
+class Raktr
+
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Connection
+    include Callbacks
+
+    # Maximum amount of data to be written or read at a time.
+    #
+    # We set this to the same max block size as the OpenSSL buffers because more
+    # than this tends to cause SSL errors and broken #select behavior --
+    # 1024 * 16 at the time of writing.
+    BLOCK_SIZE = OpenSSL::Buffering::BLOCK_SIZE
+
+    # @return     [Socket]
+    #   Ruby `Socket` associated with this connection.
+    attr_reader   :socket
+
+    # @return     [Reactor]
+    #   Reactor associated with this connection.
+    attr_accessor :raktr
+
+    # @return     [Symbol]
+    #   `:client` or `:server`
+    attr_reader   :role
+
+    # @return   [Bool, nil]
+    #   `true` when using a UNIX-domain socket, `nil` if no {#socket} is
+    #   available, `false` otherwise.
+    def unix?
+        return @is_unix if !@is_unix.nil?
+        return if !to_io
+        return false if !Raktr.supports_unix_sockets?
+
+        @is_unix = to_io.is_a?( UNIXServer ) || to_io.is_a?( UNIXSocket )
+    end
+
+    # @return   [Bool]
+    #   `true` when using an Internet socket, `nil` if no {#socket} is
+    #   available, `false` otherwise.
+    def inet?
+        return @is_inet if !@is_inet.nil?
+        return if !to_io
+
+        @is_inet = to_io.is_a?( TCPServer ) || to_io.is_a?( TCPSocket ) || to_io.is_a?( Socket )
+    end
+
+    # @return   [IO, nil]
+    #   IO stream or `nil` if no {#socket} is available.
+    def to_io
+        return if !@socket
+        @socket.to_io
+    end
+
+    # @return   [Bool]
+    #   `true` if the connection is a server listener.
+    def listener?
+        return @is_listener if !@is_listener.nil?
+        return if !to_io
+
+        @is_listener = to_io.is_a?( TCPServer ) || (unix? && to_io.is_a?( UNIXServer ))
+    end
+
+    # @note The data will be buffered and sent in future {Reactor} ticks.
+    #
+    # @param    [String]    data
+    #   Data to send to the peer.
+    def write( data )
+        @raktr.schedule do
+            write_buffer << data
+        end
+    end
+
+    # @return   [Bool]
+    #   `true` if the connection is {Reactor#attached?} to a {#raktr},
+    #   `false` otherwise.
+    def attached?
+        @raktr && @raktr.attached?( self )
+    end
+
+    # @return   [Bool]
+    #   `true` if the connection is not {Reactor#attached?} to a {#raktr},
+    #   `false` otherwise.
+    def detached?
+        !attached?
+    end
+
+    # @note Will first detach if already {#attached?}.
+    # @note Sets {#raktr}.
+    # @note Calls {#on_attach}.
+    #
+    # @param    [Reactor]   reactor
+    #   {Reactor} to which to attach {Reactor#attach}.
+    #
+    # @return   [Bool]
+    #   `true` if the connection was attached, `nil` if the connection was
+    #   already attached.
+    def attach( raktr )
+        return if raktr.attached?( self )
+        detach if attached?
+
+        raktr.attach self
+
+        true
+    end
+
+    # @note Removes {#raktr}.
+    # @note Calls {#on_detach}.
+    #
+    # {Reactor#detach Detaches} `self` from the {#raktr}.
+    #
+    # @return   [Bool]
+    #   `true` if the connection was detached, `nil` if the connection was
+    #   already detached.
+    def detach
+        return if detached?
+
+        @raktr.detach self
+
+        true
+    end
+
+    # @note Will not call {#on_close}.
+    #
+    # Closes the connection and {#detach detaches} it from the {Reactor}.
+    def close_without_callback
+        return if closed?
+        @closed = true
+
+        if listener? && unix? && (path = to_io.path) && File.exist?( path )
+            File.delete( path )
+        end
+
+        if @socket
+            @socket.close rescue nil
+        end
+
+        detach
+
+        nil
+    end
+
+    # @return   [Bool]
+    #   `true` if the connection has been {#close closed}, `false` otherwise.
+    def closed?
+        !!@closed
+    end
+
+    # @return   [Bool]
+    #   `true` if the connection has {#write outgoing data} that have not
+    #   yet been {#write written}, `false` otherwise.
+    def has_outgoing_data?
+        !write_buffer.empty?
+    end
+
+    # @note Will call {#on_close} right before closing the socket and detaching
+    #   from the Reactor.
+    #
+    # Closes the connection and {Reactor#detach detaches} it from the {Reactor}.
+    #
+    # @param    [Exception] reason
+    #   Reason for the close.
+    def close( reason = nil )
+        return if closed?
+
+        on_close reason
+        close_without_callback
+        nil
+    end
+
+    # Accepts a new client connection.
+    #
+    # @return   [Connection, nil]
+    #   New connection or `nil` if the socket isn't ready to accept new
+    #   connections yet.
+    #
+    # @private
+    def accept
+        return if !(accepted = socket_accept)
+
+        connection = @server_handler.call
+        connection.configure socket: accepted, role: :server
+        @raktr.attach connection
+        connection
+    end
+
+    # @param    [Socket]    socket
+    #   Ruby `Socket` associated with this connection.
+    # @param    [Symbol]    role
+    #   `:server` or `:client`.
+    # @param    [Block]    server_handler
+    #   Block that generates a handler as specified in {Reactor#listen}.
+    #
+    # @private
+    def configure( options = {} )
+        @socket         = options[:socket]
+        @role           = options[:role]
+        @host           = options[:host]
+        @port           = options[:port]
+        @server_handler = options[:server_handler]
+
+        # If we're a server without a handler then we're an accepted connection.
+        if unix? || role == :server
+            @connected = true
+            on_connect
+        end
+
+        nil
+    end
+
+    def connected?
+        !!@connected
+    end
+
+    # @private
+    def _connect
+        return true if unix? || connected?
+
+        begin
+            Error.translate do
+                socket.connect_nonblock( Socket.sockaddr_in( @port, @host ) )
+            end
+        # Already connected. :)
+        rescue Errno::EISCONN, Errno::EALREADY
+        end
+
+        @connected = true
+        on_connect
+
+        true
+    rescue IO::WaitReadable, IO::WaitWritable, Errno::EINPROGRESS
+    rescue Error => e
+        close e
+    end
+
+    # @note If this is a server {#listener?} it will delegate to {#accept}.
+    # @note If this is a normal socket it will read {BLOCK_SIZE} amount of data.
+    #   and pass it to {#on_read}.
+    #
+    # Processes a `read` event for this connection.
+    #
+    # @private
+    def _read
+        return _connect if !listener? && !connected?
+        return accept   if listener?
+
+        Error.translate do
+            on_read @socket.read_nonblock( BLOCK_SIZE )
+        end
+
+    # Not ready to read or write yet, we'll catch it on future Reactor ticks.
+    rescue IO::WaitReadable, IO::WaitWritable
+    rescue Error => e
+        close e
+    end
+
+    # @note Will call {#on_write} every time any of the buffer is consumed,
+    #   can be multiple times when performing partial writes.
+    # @note Will call {#on_flush} once all of the buffer has been consumed.
+    #
+    # Processes a `write` event for this connection.
+    #
+    # Consumes and writes {BLOCK_SIZE} amount of data from the the beginning of
+    # the {#write} buffer to the socket.
+    #
+    # @return   [Integer]
+    #   Amount of the buffer consumed.
+    #
+    # @private
+    def _write
+        return _connect if !connected?
+
+        chunk = write_buffer.byteslice( 0, BLOCK_SIZE )
+        total_written = 0
+
+        begin
+            Error.translate do
+                # Send out the chunk, **all** of it, or at least try to.
+                loop do
+                    total_written += written = @socket.write_nonblock( chunk )
+                    @write_buffer = @write_buffer.byteslice( written..-1 )
+
+                    # Call #on_write every time any of the buffer is consumed.
+                    on_write
+
+                    break if written == chunk.bytesize
+                    chunk = chunk.byteslice( written..-1 )
+                end
+            end
+
+        # Not ready to read or write yet, we'll catch it on future Reactor ticks.
+        rescue IO::WaitReadable, IO::WaitWritable
+        end
+
+        if write_buffer.empty?
+            @socket.flush
+            on_flush
+        end
+
+        total_written
+    rescue Error => e
+        close e
+    end
+
+    private
+
+    def write_buffer
+        @write_buffer ||= ''
+    end
+
+    # Accepts a new client connection.
+    #
+    # @return   [Socket, nil]
+    #   New connection or `nil` if the socket isn't ready to accept new
+    #   connections yet.
+    #
+    # @private
+    def socket_accept
+        begin
+            @socket.accept_nonblock
+        rescue IO::WaitReadable, IO::WaitWritable
+        end
+    end
+
+end
+
+end

data/lib/raktr/global.rb

@@ -0,0 +1,24 @@
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+require 'singleton'
+
+class Raktr
+
+# **Do not use directly!**
+#
+# Use the {Reactor} class methods to manage a globally accessible {Reactor}
+# instance.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+# @private
+class Global < Raktr
+    include Singleton
+end
+
+end

data/lib/raktr/iterator.rb

@@ -0,0 +1,249 @@
+
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+class Raktr
+
+# @note Pretty much an `EventMachine::Iterator` rip-off.
+#
+# A simple iterator for concurrent asynchronous work.
+#
+# Unlike Ruby's built-in iterators, the end of the current iteration cycle is
+# signaled manually, instead of happening automatically after the yielded block
+# finishes executing.
+#
+# @example Direct initialization.
+#
+#     Iterator.new( reactor, 0..10 ).each { |num, iterator| iterator.next }
+#
+# @example Reactor factory.
+#
+#     raktr.create_iterator( 0..10 ).each { |num, iterator| iterator.next }
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Iterator
+
+    # @return   [Reactor]
+    attr_reader :raktr
+
+    # @return   [Integer]
+    attr_reader :concurrency
+
+    # @example Create a new parallel async iterator with specified concurrency.
+    #
+    #     i = Iterator.new( reactor, 1..100, 10 )
+    #
+    # @param    [Reactor]   reactor
+    # @param    [#to_a] list
+    #   List to iterate.
+    # @param    [Integer]   concurrency
+    #   Parallel workers to spawn.
+    def initialize( reactor, list, concurrency = 1 )
+        raise ArgumentError, 'argument must be an array' unless list.respond_to?(:to_a)
+        raise ArgumentError, 'concurrency must be bigger than zero' unless concurrency > 0
+
+        @raktr     = reactor
+        @list        = list.to_a.dup
+        @concurrency = concurrency
+
+        @started = false
+        @ended   = false
+    end
+
+    # Change the concurrency of this iterator. Workers will automatically be
+    # spawned or destroyed to accommodate the new concurrency level.
+    #
+    # @param    [Integer]   val
+    #   New concurrency.
+    def concurrency=( val )
+        old          = @concurrency
+        @concurrency = val
+
+        spawn_workers if val > old && @started && !@ended
+
+        val
+    end
+
+    # @example Iterate over a set of items using the specified block or proc.
+    #
+    #   Iterator.new( reactor, 1..100 ).each do |num, iterator|
+    #       puts num
+    #       iterator.next
+    #   end
+    #
+    # @example An optional second proc is invoked after the iteration is complete.
+    #
+    #   Iterator.new( reactor, 1..100 ).each(
+    #       proc { |num, iterator| iterator.next },
+    #       proc { puts 'all done' }
+    #   )
+    def each( foreach = nil, after = nil, &block )
+        raise ArgumentError, 'Proc or Block required for iteration.' unless foreach ||= block
+        raise RuntimeError, 'Cannot iterate over an iterator more than once.' if @started or @ended
+
+        @started = true
+        @pending = 0
+        @workers = 0
+
+        all_done = proc do
+            after.call if after && @ended && @pending == 0
+        end
+
+        @process_next = proc do
+            if @ended || @workers > @concurrency
+                @workers -= 1
+            else
+                if @list.empty?
+                    @ended    = true
+                    @workers -= 1
+
+                    all_done.call
+                else
+                    item      = @list.shift
+                    @pending += 1
+
+                    is_done = false
+                    on_done = proc do
+                        raise RuntimeError, 'Already completed this iteration.' if is_done
+                        is_done = true
+
+                        @pending -= 1
+
+                        if @ended
+                            all_done.call
+                        else
+                            @raktr.next_tick(&@process_next)
+                        end
+                    end
+
+                    class << on_done
+                        alias :next :call
+                    end
+
+                    foreach.call(item, on_done)
+                end
+            end
+        end
+
+        spawn_workers
+
+        self
+    end
+
+    # @example Collect the results of an asynchronous iteration into an array.
+    #
+    #   Iterator.new( reactor, %w(one two three four), 2 ).map(
+    #       proc do |string, iterator|
+    #           iterator.return( string.size )
+    #       end,
+    #       proc do |results|
+    #           p results
+    #       end
+    #   )
+    #
+    # @param    [Proc]  foreach
+    #   `Proc` to handle each entry.
+    # @param    [Proc]  after
+    #   `Proc` to handle the results.
+    def map( foreach, after )
+        index = 0
+
+        inject( [],
+            proc do |results, item, iter|
+                i      = index
+                index += 1
+
+                is_done = false
+                on_done = proc do |res|
+                    raise RuntimeError, 'Already returned a value for this iteration.' if is_done
+                    is_done = true
+
+                    results[i] = res
+                    iter.return(results)
+                end
+
+                class << on_done
+                    alias :return :call
+                    def next
+                        raise NoMethodError, 'Must call #return on a map iterator.'
+                    end
+                end
+
+                foreach.call( item, on_done )
+            end,
+
+            proc do |results|
+                after.call(results)
+            end
+        )
+    end
+
+    # @example Inject the results of an asynchronous iteration onto a given object.
+    #
+    #   Iterator.new( reactor, %w(one two three four), 2 ).inject( {},
+    #       proc do |hash, string, iterator|
+    #           hash.merge!( string => string.size )
+    #           iterator.return( hash )
+    #       end,
+    #       proc do |results|
+    #           p results
+    #       end
+    #   )
+    #
+    # @param    [Object]  object
+    # @param    [Proc]  foreach
+    #   `Proc` to handle each entry.
+    # @param    [Proc]  after
+    #   `Proc` to handle the results.
+    def inject( object, foreach, after )
+        each(
+            proc do |item, iter|
+                is_done = false
+                on_done = proc do |res|
+                    raise RuntimeError, 'Already returned a value for this iteration.' if is_done
+                    is_done = true
+
+                    object = res
+                    iter.next
+                end
+
+                class << on_done
+                    alias :return :call
+                    def next
+                        raise NoMethodError, 'Must call #return on an inject iterator.'
+                    end
+                end
+
+                foreach.call( object, item, on_done )
+            end,
+
+            proc do
+                after.call(object)
+            end
+        )
+    end
+
+    private
+
+    # Spawn workers to consume items from the iterator's enumerator based on the
+    # current concurrency level.
+    def spawn_workers
+        @raktr.next_tick( &proc { |task|
+            next if @workers >= @concurrency || @ended
+
+            @workers += 1
+            @process_next.call
+            @raktr.next_tick(&task.to_proc)
+        })
+
+        nil
+    end
+
+end
+
+end

data/lib/raktr/queue.rb

@@ -0,0 +1,89 @@
+
+=begin
+
+    This file is part of the Raktr project and may be subject to
+    redistribution and commercial restrictions. Please see the Raktr
+    web site for more information on licensing and terms of use.
+
+=end
+
+class Raktr
+
+# @note Pretty much an `EventMachine::Queue` rip-off.
+#
+# A cross thread, {Raktr#schedule Raktr scheduled}, linear queue.
+#
+# This class provides a simple queue abstraction on top of the
+# {Raktr#schedule scheduler}.
+#
+# It services two primary purposes:
+#
+# * API sugar for stateful protocols.
+# * Pushing processing onto the {Raktr#thread reactor thread}.
+#
+# @author Tasos "Zapotek" Laskos <tasos.laskos@gmail.com>
+class Queue
+
+    # @return   [Raktr]
+    attr_reader :raktr
+
+    # @param    [Reactor]   reactor
+    def initialize( reactor )
+        @raktr = reactor
+        @items   = []
+        @waiting = []
+    end
+
+    # @param    [Block] block
+    #   Block to be {Reactor#schedule scheduled} by the {Reactor} and passed
+    #   an item from the queue as soon as one becomes available.
+    def pop( &block )
+        @raktr.schedule do
+            if @items.empty?
+                @waiting << block
+            else
+                block.call @items.shift
+            end
+        end
+
+        nil
+    end
+
+    # @param    [Object] item
+    #   {Reactor#schedule Schedules} an item for addition to the queue.
+    def push( item )
+        @raktr.schedule do
+            @items.push( item )
+            @waiting.shift.call @items.shift until @items.empty? || @waiting.empty?
+        end
+
+        nil
+    end
+    alias :<< :push
+
+    # @note This is a peek, it's not thread safe, and may only tend toward accuracy.
+    #
+    # @return [Boolean]
+    def empty?
+        @items.empty?
+    end
+
+    # @note This is a peek, it's not thread safe, and may only tend toward accuracy.
+    #
+    # @return [Integer]
+    #   Queue size.
+    def size
+        @items.size
+    end
+
+    # @note Accuracy cannot be guaranteed.
+    #
+    # @return [Integer]
+    #   Number of jobs that are currently waiting on the Queue for items to appear.
+    def num_waiting
+        @waiting.size
+    end
+
+end
+
+end