local_bus 0.2.0 → 0.3.0

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

data/lib/local_bus/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 class LocalBus
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/local_bus.rb

@@ -6,20 +6,71 @@ require "zeitwerk"
 loader = Zeitwerk::Loader.for_gem
 loader.setup
 
+require "algorithms"
 require "async"
 require "async/barrier"
 require "async/semaphore"
-require "concurrent-ruby"
+require "etc"
 require "monitor"
 require "securerandom"
 require "singleton"
+require "timers"
 
 class LocalBus
   include Singleton
 
+  # Default Bus instance
+  # @rbs return: Bus
   attr_reader :bus
+
+  # Default Station instance
+  # @rbs return: Station
   attr_reader :station
 
+  class << self
+    # Publishes a message via the default Station
+    #
+    # @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: Message
+    def publish(...)
+      instance.station.publish(...)
+    end
+
+    # Publishes a pre-built message via the default Station
+    # @rbs message: Message -- message to publish
+    # @rbs return: Message
+    def publish_message(...)
+      instance.station.publish_message(...)
+    end
+
+    # Subscribe to a topic via the default Station
+    # @rbs topic: String -- topic name
+    # @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: Station
+    def subscribe(...)
+      instance.station.subscribe(...)
+    end
+
+    # Unsubscribes a callable from a topic via the default Station
+    # @rbs topic: String -- topic name
+    # @rbs callable: (Message) -> untyped -- subscriber that should no longer receive messages
+    # @rbs return: Station
+    def unsubscribe(...)
+      instance.station.unsubscribe(...)
+    end
+
+    # Unsubscribes all subscribers from a topic and removes the topic via the default Station
+    # @rbs topic: String -- topic name
+    # @rbs return: Station
+    def unsubscribe_all(...)
+      instance.station.unsubscribe_all(...)
+    end
+  end
+
   private
 
   def initialize

data/sig/generated/local_bus/bus.rbs

@@ -0,0 +1,83 @@
+# Generated from lib/local_bus/bus.rb with RBS::Inline
+
+class LocalBus
+  # 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 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: Integer) -> untyped
+
+    # Maximum number of concurrent tasks that can run in "parallel"
+    # @rbs return: Integer
+    def concurrency: () -> Integer
+
+    # 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=: (Integer value) -> Integer
+
+    # Registered topics that have subscribers
+    # @rbs return: Array[String] -- list of topic names
+    def topics: () -> Array[String]
+
+    # Registered subscriptions
+    # @rbs return: Hash[String, Array[callable]] -- mapping of topics to callables
+    def subscriptions: () -> Hash[String, Array[callable]]
+
+    # Subscribes a callable to a topic
+    # @rbs topic: String -- topic name
+    # @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
+    # @raise [ArgumentError] if neither callable nor block is provided
+    def subscribe: (String topic, ?callable: Message) { (Message) -> untyped } -> self
+
+    # 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: (String topic, callable: Message) -> self
+
+    # Unsubscribes all subscribers from a topic and removes the topic
+    # @rbs topic: String -- topic name
+    # @rbs return: self
+    def unsubscribe_all: (String topic) -> self
+
+    # Executes a block and unsubscribes all subscribers from the topic afterwards
+    # @rbs topic: String -- topic name
+    # @rbs block: (String) -> void -- block to execute (yields the topic)
+    def with_topic: (String topic) ?{ (?) -> untyped } -> untyped
+
+    # 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.
+    #
+    #       * If subscribers are added mid-publish, they will not receive the message
+    #       * If subscribers are removed mid-publish, they will still receive the message
+    #
+    # @note If the timeout is exceeded, the task will be cancelled before all subscribers have completed.
+    #
+    # Check individual Subscribers for possible errors.
+    #
+    # @rbs topic: String -- topic name
+    # @rbs timeout: Float -- seconds to wait for subscribers to process the message before cancelling (default: 60)
+    # @rbs payload: Hash -- message payload
+    # @rbs return: Message
+    def publish: (String topic, ?timeout: Float, **untyped payload) -> Message
+
+    # Publishes a pre-built message
+    # @rbs message: Message -- message to publish
+    # @rbs return: Message
+    def publish_message: (Message message) -> Message
+  end
+end

data/sig/generated/local_bus/message.rbs

@@ -0,0 +1,60 @@
+# Generated from lib/local_bus/message.rb with RBS::Inline
+
+class LocalBus
+  # Represents a message in the LocalBus system
+  class Message
+    # Constructor
+    # @note Creates a new Message instance with the given topic and payload
+    # @rbs topic: String -- the topic of the message
+    # @rbs timeout: Float? -- optional timeout for message processing (in seconds)
+    # @rbs payload: Hash -- the message payload
+    def initialize: (String topic, ?timeout: Float?, **untyped payload) -> untyped
+
+    # Metadata for the message
+    # @rbs return: Hash[Symbol, untyped]
+    attr_reader metadata: untyped
+
+    # 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: untyped
+
+    # Unique identifier for the message
+    # @rbs return: String
+    def id: () -> String
+
+    # Message topic
+    # @rbs return: String
+    def topic: () -> String
+
+    # Message payload
+    # @rbs return: Hash
+    def payload: () -> Hash
+
+    # Time when the message was created or published
+    # @rbs return: Time
+    def created_at: () -> Time
+
+    # ID of the thread that created the message
+    # @rbs return: Integer
+    def thread_id: () -> Integer
+
+    # Timeout for message processing (in seconds)
+    # @rbs return: Float
+    def timeout: () -> Float
+
+    # 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: Float) -> void
+
+    # Blocks and waits for the message process then returns all subscribers
+    # @rbs return: Array[Subscriber]
+    def subscribers: () -> Array[Subscriber]
+
+    # Allows pattern matching on message attributes
+    # @rbs keys: Array[Symbol] -- keys to extract from the message
+    # @rbs return: Hash[Symbol, untyped]
+    def deconstruct_keys: (Array[Symbol] keys) -> Hash[Symbol, untyped]
+  end
+end

data/sig/generated/local_bus/publication.rbs

@@ -0,0 +1,20 @@
+# Generated from lib/local_bus/publication.rb with RBS::Inline
+
+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: (Async::Barrier barrier, *untyped subscribers) -> untyped
+
+    # Blocks and waits for the barrier (i.e. all subscribers to complete)
+    # @rbs return: void
+    def wait: () -> void
+
+    # List of Subscribers that are processing a Message
+    # @note Blocks until all subscribers complete
+    # @rbs return: Array[Subscriber]
+    def subscribers: () -> Array[Subscriber]
+  end
+end

data/sig/generated/local_bus/station.rbs

@@ -0,0 +1,113 @@
+# Generated from lib/local_bus/station.rb with RBS::Inline
+
+class LocalBus
+  # The Station serves as a queuing system for messages, similar to a bus station where passengers wait for their bus.
+  #
+  # 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.
+  #
+  # 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 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 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, ?interval: Float, ?limit: Integer, ?threads: Integer, ?timeout: Float, ?wait: Float) -> void
+
+    # Bus instance
+    # @rbs return: Bus
+    attr_reader bus: untyped
+
+    # Queue polling interval in seconds
+    # @rbs return: Float
+    attr_reader interval: untyped
+
+    # Max queue size
+    # @rbs return: Integer
+    attr_reader limit: untyped
+
+    # Number of threads to use
+    # @rbs return: Integer
+    attr_reader threads: untyped
+
+    # Default timeout for message processing (in seconds)
+    # @rbs return: Float
+    attr_reader timeout: untyped
+
+    # 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: (?interval: Float, ?threads: Integer) -> void
+
+    # 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: Float) -> void
+
+    def stopping?: () -> untyped
+
+    # Indicates if the station is running
+    # @rbs return: bool
+    def running?: () -> bool
+
+    # Indicates if the queue is empty
+    # @rbs return: bool
+    def empty?: () -> bool
+
+    # Number of unprocessed messages in the queue
+    # @rbs return: Integer
+    def count: () -> Integer
+
+    # Subscribe to a topic
+    # @rbs topic: String -- topic name
+    # @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: () { (Message) -> untyped } -> self
+
+    # 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: () -> self
+
+    # Unsubscribes all subscribers from a topic and removes the topic
+    # @rbs topic: String -- topic name
+    # @rbs return: self
+    def unsubscribe_all: () -> self
+
+    # 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: Message
+    def publish: (String | Symbol topic, ?priority: Integer, ?timeout: Float, **untyped payload) -> Message
+
+    # Publishes a pre-built message
+    # @rbs message: Message -- message to publish
+    # @rbs return: Message
+    def publish_message: (Message message, ?priority: untyped) -> Message
+  end
+end

data/sig/generated/local_bus/subscriber.rbs

@@ -0,0 +1,89 @@
+# Generated from lib/local_bus/subscriber.rb with RBS::Inline
+
+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
+      # @rbs message: String -- error message
+      # @rbs cause: StandardError? -- underlying cause of the error
+      def initialize: (String message, cause: StandardError?) -> untyped
+
+      # Underlying cause of the error
+      # @rbs return: StandardError?
+      attr_reader cause: untyped
+    end
+
+    # Constructor
+    # @rbs callable: #call -- the subscriber's callable object
+    # @rbs message: Message -- the message to be processed
+    def initialize: (untyped callable, Message message) -> untyped
+
+    # Unique identifier for the subscriber
+    # @rbs return: String
+    attr_reader id: untyped
+
+    # Source location of the callable
+    # @rbs return: Array[String, Integer]?
+    attr_reader source_location: untyped
+
+    # Callable object -- Proc, lambda, etc. (must respond to #call)
+    # @rbs return: #call
+    attr_reader callable: untyped
+
+    # Error if the subscriber fails (available after performing)
+    # @rbs return: Error?
+    attr_reader error: untyped
+
+    # Message for the subscriber to process
+    # @rbs return: Message
+    attr_reader message: untyped
+
+    # Metadata for the subscriber (available after performing)
+    # @rbs return: Hash[Symbol, untyped]
+    attr_reader metadata: untyped
+
+    # Value returned by the callable (available after performing)
+    # @rbs return: untyped
+    attr_reader value: untyped
+
+    # Indicates if the subscriber has been performed
+    # @rbs return: bool
+    def performed?: () -> bool
+
+    # Indicates if the subscriber is pending or unperformed
+    # @rbs return: bool
+    def pending?: () -> bool
+
+    # Indicates if the subscriber has errored
+    # @rbs return: bool
+    def errored?: () -> bool
+
+    # Performs the subscriber's callable
+    # @rbs return: void
+    def perform: () -> void
+
+    # Handles timeout for the subscriber
+    # @rbs cause: StandardError -- the cause of the timeout
+    # @rbs return: void
+    def timeout: (StandardError cause) -> void
+
+    # Returns the subscriber's data as a hash
+    # @rbs return: Hash[Symbol, untyped]
+    def to_h: () -> Hash[Symbol, untyped]
+
+    # Allows pattern matching on subscriber attributes
+    # @rbs keys: Array[Symbol] -- keys to extract from the subscriber
+    # @rbs return: Hash[Symbol, untyped]
+    def deconstruct_keys: (Array[Symbol] keys) -> Hash[Symbol, untyped]
+
+    private
+
+    # Captures metadata for the subscriber's performance
+    # @rbs return: void
+    def with_metadata: () -> void
+  end
+end

data/sig/generated/local_bus/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/local_bus/version.rb with RBS::Inline
+
+class LocalBus
+  VERSION: ::String
+end

data/sig/generated/local_bus.rbs

@@ -0,0 +1,49 @@
+# Generated from lib/local_bus.rb with RBS::Inline
+
+class LocalBus
+  include Singleton
+
+  # Default Bus instance
+  # @rbs return: Bus
+  attr_reader bus: untyped
+
+  # Default Station instance
+  # @rbs return: Station
+  attr_reader station: untyped
+
+  # Publishes a message via the default Station
+  #
+  # @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: Message
+  def self.publish: () -> Message
+
+  # Publishes a pre-built message via the default Station
+  # @rbs message: Message -- message to publish
+  # @rbs return: Message
+  def self.publish_message: () -> Message
+
+  # Subscribe to a topic via the default Station
+  # @rbs topic: String -- topic name
+  # @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: Station
+  def self.subscribe: () { (Message) -> untyped } -> Station
+
+  # Unsubscribes a callable from a topic via the default Station
+  # @rbs topic: String -- topic name
+  # @rbs callable: (Message) -> untyped -- subscriber that should no longer receive messages
+  # @rbs return: Station
+  def self.unsubscribe: () -> Station
+
+  # Unsubscribes all subscribers from a topic and removes the topic via the default Station
+  # @rbs topic: String -- topic name
+  # @rbs return: Station
+  def self.unsubscribe_all: () -> Station
+
+  private
+
+  def initialize: () -> untyped
+end