local_bus 0.1.2 → 0.3.0

data/lib/local_bus/bus.rb

@@ -3,29 +3,35 @@
 # rbs_inline: enabled
 
 class LocalBus
-  # Local in-process single threaded "message bus" with non-blocking I/O
+  # The Bus acts as a direct transport mechanism for messages, akin to placing a passenger directly onto a bus.
+  # When a message is published to the Bus, it is immediately delivered to all subscribers, ensuring prompt execution of tasks.
+  # This is achieved through non-blocking I/O operations, which allow the Bus to handle multiple tasks efficiently without blocking the main thread.
+  #
+  # @note While the Bus uses asynchronous operations to optimize performance,
+  #       the actual processing of a message may still experience slight delays due to I/O wait times from prior messages.
+  #       This means that while the Bus aims for immediate processing, the nature of asynchronous operations can introduce some latency.
   class Bus
     include MonitorMixin
 
     # Constructor
-    # @note Creates a new Bus instance with specified concurrency
-    # @rbs concurrency: Integer -- maximum number of concurrent tasks (default: Concurrent.processor_count)
-    def initialize(concurrency: Concurrent.processor_count)
+    # @note Creates a new Bus instance with specified max concurrency (i.e. number of tasks that can run in parallel)
+    # @rbs concurrency: Integer -- maximum number of concurrent tasks (default: Etc.nprocessors)
+    def initialize(concurrency: Etc.nprocessors)
       super()
       @concurrency = concurrency.to_i
-      @subscriptions = Concurrent::Hash.new do |hash, key|
-        hash[key] = Concurrent::Set.new
+      @subscriptions = Hash.new do |hash, key|
+        hash[key] = Set.new
       end
     end
 
     # Maximum number of concurrent tasks that can run in "parallel"
-    # @rbs return: Integer -- current concurrency value
+    # @rbs return: Integer
     def concurrency
       synchronize { @concurrency }
     end
 
-    # Sets the concurrency
-    # @rbs concurrency: Integer -- max number of concurrent tasks that can run in "parallel"
+    # Sets the max concurrency
+    # @rbs value: Integer -- max number of concurrent tasks that can run in "parallel"
     # @rbs return: Integer -- new concurrency value
     def concurrency=(value)
       synchronize { @concurrency = value.to_i }
@@ -34,14 +40,16 @@ class LocalBus
     # Registered topics that have subscribers
     # @rbs return: Array[String] -- list of topic names
     def topics
-      @subscriptions.keys
+      synchronize { @subscriptions.keys }
     end
 
     # Registered subscriptions
     # @rbs return: Hash[String, Array[callable]] -- mapping of topics to callables
     def subscriptions
-      @subscriptions.each_with_object({}) do |(topic, callables), memo|
-        memo[topic] = callables.to_a
+      synchronize do
+        @subscriptions.each_with_object({}) do |(topic, callables), memo|
+          memo[topic] = callables.to_a
+        end
       end
     end
 
@@ -54,7 +62,7 @@ class LocalBus
     def subscribe(topic, callable: nil, &block)
       callable ||= block
       raise ArgumentError, "Subscriber must respond to #call" unless callable.respond_to?(:call, false)
-      @subscriptions[topic.to_s].add callable
+      synchronize { @subscriptions[topic.to_s].add callable }
       self
     end
 
@@ -64,8 +72,10 @@ class LocalBus
     # @rbs return: self
     def unsubscribe(topic, callable:)
       topic = topic.to_s
-      @subscriptions[topic].delete callable
-      @subscriptions.delete(topic) if @subscriptions[topic].empty?
+      synchronize do
+        @subscriptions[topic].delete callable
+        @subscriptions.delete(topic) if @subscriptions[topic].empty?
+      end
       self
     end
 
@@ -74,8 +84,10 @@ class LocalBus
     # @rbs return: self
     def unsubscribe_all(topic)
       topic = topic.to_s
-      @subscriptions[topic].clear
-      @subscriptions.delete topic
+      synchronize do
+        @subscriptions[topic].clear
+        @subscriptions.delete topic
+      end
       self
     end
 
@@ -88,7 +100,7 @@ class LocalBus
       unsubscribe_all topic
     end
 
-    # Publishes a message to a topic
+    # Publishes a message
     #
     # @note If subscribers are rapidly created/destroyed mid-publish, there's a theoretical
     #       possibility of object_id reuse. However, this is extremely unlikely in practice.
@@ -98,20 +110,26 @@ class LocalBus
     #
     # @note If the timeout is exceeded, the task will be cancelled before all subscribers have completed.
     #
-    # Check the Subscriber for any errors.
+    # Check individual Subscribers for possible errors.
     #
     # @rbs topic: String -- topic name
-    # @rbs timeout: Float -- seconds to wait before cancelling (default: 300)
+    # @rbs timeout: Float -- seconds to wait for subscribers to process the message before cancelling (default: 60)
     # @rbs payload: Hash -- message payload
-    # @rbs return: Array[Subscriber] -- list of performed subscribers (empty if no subscribers)
-    def publish(topic, timeout: 300, **payload)
+    # @rbs return: Message
+    def publish(topic, timeout: 60, **payload)
+      publish_message Message.new(topic, timeout: timeout.to_f, **payload)
+    end
+
+    # Publishes a pre-built message
+    # @rbs message: Message -- message to publish
+    # @rbs return: Message
+    def publish_message(message)
       barrier = Async::Barrier.new
-      message = Message.new(topic, timeout: timeout, **payload)
       subscribers = subscriptions.fetch(message.topic, []).map { Subscriber.new _1, message }
 
       if subscribers.any?
         Sync do |task|
-          task.with_timeout timeout.to_f do
+          task.with_timeout message.timeout do
             semaphore = Async::Semaphore.new(concurrency, parent: barrier)
 
             subscribers.each do |subscriber|
@@ -129,7 +147,8 @@ class LocalBus
         end
       end
 
-      Pledge.new(barrier, *subscribers)
+      message.publication = Publication.new(barrier, *subscribers)
+      message
     end
   end
 end

data/lib/local_bus/message.rb

@@ -11,50 +11,82 @@ class LocalBus
     # @rbs timeout: Float? -- optional timeout for message processing (in seconds)
     # @rbs payload: Hash -- the message payload
     def initialize(topic, timeout: nil, **payload)
-      @id = SecureRandom.uuid_v7
-      @topic = topic.to_s.freeze
-      @payload = payload.transform_keys(&:to_sym).freeze
-      @created_at = Time.now
-      @thread_id = Thread.current.object_id
-      @timeout = timeout.to_f
       @metadata ||= {
-        id: id,
-        topic: topic,
-        payload: payload,
-        created_at: created_at,
-        thread_id: thread_id,
-        timeout: timeout
+        id: SecureRandom.uuid_v7,
+        topic: topic.to_s.freeze,
+        payload: payload.transform_keys(&:to_sym).freeze,
+        created_at: Time.now,
+        thread_id: Thread.current.object_id,
+        timeout: timeout.to_f
       }.freeze
-      freeze
     end
 
+    # Metadata for the message
+    # @rbs return: Hash[Symbol, untyped]
+    attr_reader :metadata
+
+    # Publication representing the Async barrier and subscribers handling the message
+    # @note May be nil if processing hasn't happened yet (e.g. it was published via Station)
+    # @rbs return: Publication?
+    attr_accessor :publication
+
     # Unique identifier for the message
     # @rbs return: String
-    attr_reader :id
+    def id
+      metadata[:id]
+    end
 
     # Message topic
     # @rbs return: String
-    attr_reader :topic
+    def topic
+      metadata[:topic]
+    end
 
     # Message payload
     # @rbs return: Hash
-    attr_reader :payload
+    def payload
+      metadata[:payload]
+    end
 
     # Time when the message was created or published
     # @rbs return: Time
-    attr_reader :created_at
+    def created_at
+      metadata[:created_at]
+    end
 
     # ID of the thread that created the message
     # @rbs return: Integer
-    attr_reader :thread_id
+    def thread_id
+      metadata[:thread_id]
+    end
 
     # Timeout for message processing (in seconds)
     # @rbs return: Float
-    attr_reader :timeout
+    def timeout
+      metadata[:timeout]
+    end
 
-    # Metadata for the message
-    # @rbs return: Hash[Symbol, untyped]
-    attr_reader :metadata
+    # Blocks and waits for the message to process
+    # @rbs interval: Float -- time to wait between checks (default: 0.1)
+    # @rbs return: void
+    def wait(interval: 0.1)
+      @timers ||= Timers::Group.new.tap { _1.every(interval) {} }
+      loop do
+        break if publication
+        @timers.wait
+      end
+      publication&.wait
+    ensure
+      @timers&.cancel
+      @timers = nil
+    end
+
+    # Blocks and waits for the message process then returns all subscribers
+    # @rbs return: Array[Subscriber]
+    def subscribers
+      wait
+      publication.subscribers
+    end
 
     # Converts the message to a hash
     # @rbs return: Hash[Symbol, untyped]

data/lib/local_bus/publication.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+class LocalBus
+  # Wraps an Async::Barrier and a list of Subscribers that are processing a Message.
+  class Publication
+    # Constructor
+    # @rbs barrier: Async::Barrier -- barrier used to wait for all subscribers
+    # @rbs subscribers: Array[Subscriber]
+    def initialize(barrier, *subscribers)
+      @barrier = barrier
+      @subscribers = subscribers
+    end
+
+    # Blocks and waits for the barrier (i.e. all subscribers to complete)
+    # @rbs return: void
+    def wait
+      @barrier.wait
+      self
+    end
+
+    # List of Subscribers that are processing a Message
+    # @note Blocks until all subscribers complete
+    # @rbs return: Array[Subscriber]
+    def subscribers
+      wait
+      @subscribers
+    end
+  end
+end

data/lib/local_bus/station.rb

@@ -5,119 +5,137 @@
 # rubocop:disable Style/ArgumentsForwarding
 
 class LocalBus
-  # An in-process message queuing system that buffers and publishes messages to Bus.
-  # This class acts as an intermediary, queuing messages internally before publishing them to the Bus.
+  # The Station serves as a queuing system for messages, similar to a bus station where passengers wait for their bus.
   #
-  # @note Station shares the same interface as Bus and is thus a message bus.
-  #       The key difference is that Stations are multi-threaded and will not block the main thread.
+  # When a message is published to the Station, it is queued and processed at a later time, allowing for deferred execution.
+  # This is particularly useful for tasks that can be handled later.
   #
-  # Three fallback policies are supported:
-  # 1. `abort` - Raises an exception and discards the task when the queue is full (default)
-  # 2. `discard` - Discards the task when the queue is full
-  # 3. `caller_runs` - Executes the task on the calling thread when the queue is full,
-  #                 This effectively jumps the queue (and blocks the main thread) but ensures the task is performed
-  #
-  # IMPORTANT: Be sure to release resources like database connections in subscribers when publishing via Station.
+  # The Station employs a thread pool to manage message processing, enabling high concurrency and efficient resource utilization.
+  # Messages can also be prioritized, ensuring that higher-priority tasks are processed first.
   #
+  # @note: While the Station provides a robust mechanism for background processing,
+  #        it's important to understand that the exact timing of message processing is not controlled by the publisher,
+  #        and messages will be processed as resources become available.
   class Station
     include MonitorMixin
 
-    class TimeoutError < StandardError; end
-
-    # Default options for Concurrent::FixedThreadPool (can be overridden via the constructor)
-    # @see https://ruby-concurrency.github.io/concurrent-ruby/1.3.4/Concurrent/ThreadPoolExecutor.html
-    THREAD_POOL_OPTIONS = {
-      max_queue: 5_000, # max number of pending tasks allowed in the queue
-      fallback_policy: :caller_runs # Options: :abort, :discard, :caller_runs
-    }.freeze
+    class CapacityError < StandardError; end
 
     # Constructor
+    #
+    # @note Delays process exit in an attempt to flush the queue to avoid dropping messages.
+    #       Exit flushing makes a "best effort" to process all messages, but it's not guaranteed.
+    #       Will not delay process exit when the queue is empty.
+    #
     # @rbs bus: Bus -- local message bus (default: Bus.new)
-    # @rbs threads: Integer -- number of threads (default: Concurrent.processor_count)
-    # @rbs default_timeout: Float -- seconds to wait for a future to complete
-    # @rbs shutdown_timeout: Float -- seconds to wait for all futures to complete on process exit
-    # @rbs options: Hash[Symbol, untyped] -- Concurrent::FixedThreadPool options
+    # @rbs interval: Float -- queue polling interval in seconds (default: 0.01)
+    # @rbs limit: Integer -- max queue size (default: 10_000)
+    # @rbs threads: Integer -- number of threads to use (default: Etc.nprocessors)
+    # @rbs timeout: Float -- seconds to wait for subscribers to process the message before cancelling (default: 60)
+    # @rbs wait: Float -- seconds to wait for the queue to flush at process exit (default: 5)
     # @rbs return: void
-    def initialize(
-      bus: Bus.new,
-      threads: Concurrent.processor_count,
-      default_timeout: 0,
-      shutdown_timeout: 8,
-      **options
-    )
+    def initialize(bus: Bus.new, interval: 0.01, limit: 10_000, threads: Etc.nprocessors, timeout: 60, wait: 5)
       super()
       @bus = bus
-      @threads = [2, threads].max.to_i
-      @default_timeout = default_timeout.to_f
-      @shutdown_timeout = shutdown_timeout.to_f
-      @shutdown = Concurrent::AtomicBoolean.new(false)
-      start(**options)
+      @interval = [interval.to_f, 0.01].max
+      @limit = limit.to_i.positive? ? limit.to_i : 10_000
+      @threads = [threads.to_i, 1].max
+      @timeout = timeout.to_f
+      @queue = Containers::PriorityQueue.new
+      at_exit { stop timeout: [wait.to_f, 1].max }
+      start
     end
 
     # Bus instance
     # @rbs return: Bus
     attr_reader :bus
 
-    # Number of threads used to process messages
+    # Queue polling interval in seconds
+    # @rbs return: Float
+    attr_reader :interval
+
+    # Max queue size
+    # @rbs return: Integer
+    attr_reader :limit
+
+    # Number of threads to use
     # @rbs return: Integer
     attr_reader :threads
 
     # Default timeout for message processing (in seconds)
     # @rbs return: Float
-    attr_reader :default_timeout
-
-    # Timeout for graceful shutdown (in seconds)
-    # @rbs return: Float
-    attr_reader :shutdown_timeout
+    attr_reader :timeout
 
-    # Starts the broker
-    # @rbs options: Hash[Symbol, untyped] -- Concurrent::FixedThreadPool options
+    # Starts the station
+    # @rbs interval: Float -- queue polling interval in seconds (default: 0.01)
+    # @rbs threads: Integer -- number of threads to use (default: self.threads)
     # @rbs return: void
-    def start(**options)
+    def start(interval: self.interval, threads: self.threads)
+      interval = [interval.to_f, 0.01].max
+      threads = [threads.to_i, 1].max
+
       synchronize do
-        return if running?
+        return if running? || stopping?
+
+        timers = Timers::Group.new
+        @pool = []
+        threads.times do
+          @pool << Thread.new do
+            Thread.current.report_on_exception = true
+            timers.every interval do
+              message = synchronize { @queue.pop unless @queue.empty? || stopping? }
+              bus.send :publish_message, message if message
+            end
 
-        start_shutdown_handler
-        @pool = Concurrent::FixedThreadPool.new(threads, THREAD_POOL_OPTIONS.merge(options))
-        enable_safe_shutdown on: ["HUP", "INT", "QUIT", "TERM"]
+            loop do
+              timers.wait
+              break if stopping?
+            end
+          ensure
+            timers.cancel
+          end
+        end
       end
     end
 
-    # Stops the broker
-    # @rbs timeout: Float -- seconds to wait for all futures to complete
+    # Stops the station
+    # @rbs timeout: Float -- seconds to wait for message processing before killing the thread pool (default: nil)
     # @rbs return: void
-    def stop(timeout: shutdown_timeout)
-      return unless @shutdown.make_true # Ensure we only stop once
-
+    def stop(timeout: nil)
       synchronize do
-        if running?
-          # First try graceful shutdown
-          pool.shutdown
-
-          # If graceful shutdown fails, force termination
-          pool.kill unless pool.wait_for_termination(timeout)
-
-          @pool = nil
-        end
-      rescue
-        nil # ignore errors during shutdown
+        return unless running?
+        return if stopping?
+        @stopping = true
       end
 
-      # Clean up shutdown handler
-      if @shutdown_thread&.alive?
-        @shutdown_queue&.close
-        @shutdown_thread&.join timeout
+      @pool&.each do |thread|
+        timeout.is_a?(Numeric) ? thread.join(timeout) : thread.join
       end
+    ensure
+      @stopping = false
+      @pool = nil
+    end
 
-      @shutdown_thread = nil
-      @shutdown_queue = nil
-      @shutdown_completed&.set
+    def stopping?
+      synchronize { !!@stopping }
     end
 
-    # Indicates if the broker is running
+    # Indicates if the station is running
     # @rbs return: bool
     def running?
-      synchronize { pool&.running? }
+      synchronize { !!@pool }
+    end
+
+    # Indicates if the queue is empty
+    # @rbs return: bool
+    def empty?
+      synchronize { @queue.empty? }
+    end
+
+    # Number of unprocessed messages in the queue
+    # @rbs return: Integer
+    def count
+      synchronize { @queue.size }
     end
 
     # Subscribe to a topic
@@ -125,103 +143,46 @@ class LocalBus
     # @rbs callable: (Message) -> untyped -- callable that will process messages published to the topic
     # @rbs &block: (Message) -> untyped -- alternative way to provide a callable
     # @rbs return: self
-    def subscribe(topic, callable: nil, &block)
-      bus.subscribe(topic, callable: callable || block)
+    def subscribe(...)
+      bus.subscribe(...)
       self
     end
 
-    # Unsubscribe from a topic
+    # Unsubscribes a callable from a topic
     # @rbs topic: String -- topic name
+    # @rbs callable: (Message) -> untyped -- subscriber that should no longer receive messages
     # @rbs return: self
-    def unsubscribe(topic)
-      bus.unsubscribe(topic)
+    def unsubscribe(...)
+      bus.unsubscribe(...)
       self
     end
 
     # Unsubscribes all subscribers from a topic and removes the topic
     # @rbs topic: String -- topic name
     # @rbs return: self
-    def unsubscribe_all(topic)
-      bus.unsubscribe_all topic
+    def unsubscribe_all(...)
+      bus.unsubscribe_all(...)
       self
     end
 
-    # Publishes a message to Bus on a separate thread keeping the main thread free for additional work.
-    #
-    # @note This allows you to publish messages when performing operations like handling web requests
-    #       without blocking the main thread and slowing down the response.
-    #
-    # @see https://ruby-concurrency.github.io/concurrent-ruby/1.3.4/Concurrent/Promises/Future.html
+    # Publishes a message
     #
     # @rbs topic: String | Symbol -- topic name
+    # @rbs priority: Integer -- priority of the message, higher number == higher priority (default: 1)
     # @rbs timeout: Float -- seconds to wait before cancelling
     # @rbs payload: Hash[Symbol, untyped] -- message payload
-    # @rbs return: Concurrent::Promises::Future
-    def publish(topic, timeout: default_timeout, **payload)
-      timeout = timeout.to_f
-
-      future = Concurrent::Promises.future_on(pool) do
-        case timeout
-        in 0 then bus.publish(topic, **payload).value
-        else bus.publish(topic, timeout: timeout, **payload).value
-        end
-      end
-
-      # ensure calls to future.then use the thread pool
-      executor = pool
-      future.singleton_class.define_method :then do |&block|
-        future.then_on(executor, &block)
-      end
-
-      future
-    end
-
-    private
-
-    # Thread pool used for asynchronous operations
-    # @rbs return: Concurrent::FixedThreadPool
-    attr_reader :pool
-
-    # Starts the shutdown handler thread
-    # @rbs return: void
-    def start_shutdown_handler
-      return if @shutdown.true?
-
-      @shutdown_queue = Queue.new
-      @shutdown_completed = Concurrent::Event.new
-      @shutdown_thread = Thread.new do
-        catch :shutdown do
-          loop do
-            signal = @shutdown_queue.pop # blocks until something is available
-            throw :shutdown if @shutdown_queue.closed?
-
-            stop # initiate shutdown sequence
-
-            # Re-raise the signal to let the process terminate
-            if signal
-              # Remove our trap handler before re-raising
-              trap signal, "DEFAULT"
-              Process.kill signal, Process.pid
-            end
-          rescue ThreadError, ClosedQueueError
-            break # queue was closed, exit gracefully
-          end
-        end
-        @shutdown_completed.set
-      end
+    # @rbs return: Message
+    def publish(topic, priority: 1, timeout: self.timeout, **payload)
+      publish_message Message.new(topic, timeout: timeout, **payload), priority: priority
     end
 
-    # Enables safe shutdown on process exit by trapping specified signals
-    # @rbs on: Array[String] -- signals to trap
-    # @rbs return: void
-    def enable_safe_shutdown(on:)
-      at_exit { stop }
-      on.each do |signal|
-        trap signal do
-          @shutdown_queue.push signal unless @shutdown.true?
-        rescue
-          nil
-        end
+    # Publishes a pre-built message
+    # @rbs message: Message -- message to publish
+    # @rbs return: Message
+    def publish_message(message, priority: 1)
+      synchronize do
+        raise CapacityError, "Station is at capacity! (limit: #{limit})" if @queue.size >= limit
+        @queue.push message, priority
       end
     end
   end

data/lib/local_bus/subscriber.rb

@@ -5,6 +5,8 @@
 class LocalBus
   # Wraps a Callable (Proc) and Message intended for asynchronous execution.
   class Subscriber
+    include MonitorMixin
+
     # Custom error class for Subscriber errors
     class Error < StandardError
       # Constructor
@@ -24,6 +26,7 @@ class LocalBus
     # @rbs callable: #call -- the subscriber's callable object
     # @rbs message: Message -- the message to be processed
     def initialize(callable, message)
+      super()
       @callable = callable
       @message = message
       @id = callable.object_id
@@ -68,21 +71,29 @@ class LocalBus
       metadata.any?
     end
 
-    # Checks if the subscriber is pending
+    # Indicates if the subscriber is pending or unperformed
     # @rbs return: bool
     def pending?
       metadata.empty?
     end
 
+    # Indicates if the subscriber has errored
+    # @rbs return: bool
+    def errored?
+      !!error
+    end
+
     # Performs the subscriber's callable
     # @rbs return: void
     def perform
-      return if performed?
-
-      with_metadata do
-        @value = callable.call(message)
-      rescue => cause
-        @error = Error.new("Invocation failed! #{cause.message}", cause: cause)
+      synchronize do
+        return if performed?
+
+        with_metadata do
+          @value = callable.call(message)
+        rescue => cause
+          @error = Error.new("Invocation failed! #{cause.message}", cause: cause)
+        end
       end
     end
 
@@ -129,7 +140,7 @@ class LocalBus
         finished_at: Time.now,
         duration: Time.now - started_at,
         latency: Time.now - message.created_at,
-        message: message
+        message: message.to_h
       }.freeze
     end
   end