local_bus 0.1.2 → 0.3.0

data/lib/local_bus/version.rb

@@ -3,5 +3,5 @@
 # rbs_inline: enabled
 
 class LocalBus
-  VERSION = "0.1.2"
+  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

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: local_bus
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.3.0
 platform: ruby
 authors:
 - Nate Hopkins (hopsoft)
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-05 00:00:00.000000000 Z
+date: 2024-12-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: async
+  name: algorithms
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -25,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: concurrent-ruby
+  name: async
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -39,7 +39,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: zeitwerk
+  name: timers
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,13 +53,13 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: amazing_print
+  name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: fiddle
+  name: amazing_print
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +81,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: fiddle
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -95,7 +95,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest-reporters
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -109,7 +109,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: ostruct
+  name: minitest-reporters
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -123,7 +123,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry-byebug
+  name: ostruct
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -137,7 +137,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry-doc
+  name: pry-byebug
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -151,7 +151,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: pry-doc
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -165,7 +165,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: rbs-inline
+  name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -179,7 +179,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: standard
+  name: rbs-inline
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -193,7 +193,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: tocer
+  name: standard
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -234,10 +234,17 @@ files:
 - lib/local_bus.rb
 - lib/local_bus/bus.rb
 - lib/local_bus/message.rb
-- lib/local_bus/pledge.rb
+- lib/local_bus/publication.rb
 - lib/local_bus/station.rb
 - lib/local_bus/subscriber.rb
 - lib/local_bus/version.rb
+- sig/generated/local_bus.rbs
+- sig/generated/local_bus/bus.rbs
+- sig/generated/local_bus/message.rbs
+- sig/generated/local_bus/publication.rbs
+- sig/generated/local_bus/station.rbs
+- sig/generated/local_bus/subscriber.rbs
+- sig/generated/local_bus/version.rbs
 homepage: https://github.com/hopsoft/local_bus
 licenses:
 - MIT