async_magic 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c78bb8f9e0a8a26288148d46b325f23e6dfe1e5cdcff4a050efab84bba83eeb6
+  data.tar.gz: 8e76dde7e7c7ededa633c78980ced678e97b5fb81d84b1bff5585a53c786ff41
+SHA512:
+  metadata.gz: 99d6c619806f99675fe75020d74e6076bf95953ef134576ff7334aadeab4b1efaa08945ce063fca12fb55ab8a5de02f13fe0aa59b929d3a83ab9299640884c1e
+  data.tar.gz: da8498a477bc14c89ffa967b41cc3152bec26f53720df9aab5153c6e1a2f575d0751eeb2d87a2c0e6dd5478fc13137105a4846b7a55e1c1be100f46cd6340fad

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2024-12-10
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Igor Kasyanchuk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,179 @@
+# AsyncMagic
+
+![AsyncMagic](docs/async_magic.png)
+
+AsyncMagic is a lightweight Ruby gem that makes it effortless to add asynchronous method execution to your Ruby classes. With a simple `async` declaration, your methods will execute in a managed thread pool, providing non-blocking operations while maintaining clean, readable code.
+
+Inspired by Rails [`async`](https://github.com/rails/rails/blob/9ffd264e016ee5501b19286c2f48d952e910e96c/activejob/lib/active_job/queue_adapters/async_adapter.rb#L89) methods.
+
+## Features
+
+- ✨ Simple `async` declaration for asynchronous methods
+- 🧵 Managed thread pool with configurable options
+- 🚂 Rails integration with ActiveRecord support
+- 🎯 Support for both instance and class methods
+- 📝 Built-in error logging
+- ⚡ Non-blocking execution with Future objects
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+  gem 'async_magic'
+```
+
+```bash
+  $ bundle install
+```
+
+## Usage
+
+By default, AsyncMagic will include the methods in all Objects. But you can configure it to include in specific objects (ActiveRecord models, etc.) or manually include it in your classes.
+
+See the [Configuration](./lib/async_magic.rb) for more details.
+
+```ruby
+class UserHeavyLogic
+  async
+  def send_welcome_email(user)
+    # ... your code
+  end
+
+  async
+  def self.batch_process(users)
+    # ... your code
+  end
+end
+
+# or
+
+class UsersController < ApplicationController
+  def index
+    # ... your code
+    log_user_activity
+  end
+
+  private
+
+  async
+  def log_user_activity
+    # ... your code
+  end
+end
+```
+
+## More examples
+
+- check if completed
+- get the result
+
+```ruby
+  mailer = UserMailer.new
+  future = mailer.send_welcome_email(user)
+  # Check if completed
+  future.completed?
+  # Get the result (blocks until complete)
+  result = future.value
+```
+
+- initializer to configure the thread pool
+
+```ruby
+  # config/initializers/async_magic.rb
+
+  AsyncMagic.configure do |config|
+    # Include in all ActiveRecord models
+    config.include_in = :active_record
+    # Or include globally (available everywhere)
+    # config.include_in = :global
+    # Or disable auto-inclusion
+    # config.include_in = nil
+  end
+```
+
+- configure the thread pool
+
+```ruby
+AsyncMagic.configure do |config|
+  config.executor_options = {
+    min_threads: 10, # Minimum number of threads
+    max_threads: 50, # Maximum number of threads
+    auto_terminate: true, # Automatically terminate threads
+    idletime: 60, # Thread idle time (seconds)
+    max_queue: 0, # Unlimited queue size
+    fallback_policy: :caller_runs # What to do when queue is full
+  }
+  end
+```
+
+- error handling
+```ruby
+  class MyService
+    include AsyncMagic
+
+    async
+    def risky_operation
+      # If this raises an error, it will be logged
+      raise "Something went wrong!"
+    end
+  end
+```
+
+The error will be logged and the future will contain the error
+
+```ruby
+  future = MyService.new.risky_operation
+  future.rejected? # => true
+  future.reason # => #<RuntimeError: Something went wrong!>
+```
+
+- manually include AsyncMagic
+
+```ruby
+  class DataProcessor
+    include AsyncMagic
+
+    async
+    def process_data(data)
+    # Heavy processing here
+    end
+  end
+```
+
+```ruby
+  processor = DataProcessor.new
+  future = processor.process_data(large_dataset)
+  # Wait for completion with timeout
+  if future.wait(5) # waits up to 5 seconds
+    result = future.value
+  else
+    puts "Processing is taking too long!"
+  end
+```
+
+```ruby
+  AsyncMagic.shutdown # Waits up to 5 seconds for completion
+```
+
+## Code style
+
+Just use:
+
+```bash
+  $ bundle exec standardrb
+  # or
+  $ bundle exec standardrb --fix
+```
+
+## Contributing
+
+You are welcome to contribute to this gem.
+
+## License
+
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Thanks AI to help me write this gem faster :)

data/Rakefile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "standard/rake"
+
+task default: :standard

data/lib/async_magic/async.rb

@@ -0,0 +1,79 @@
+require "concurrent"
+require "logger"
+require "active_support/concern"
+
+module AsyncMagic
+  extend ActiveSupport::Concern
+
+  DEFAULT_EXECUTOR_OPTIONS = {
+    min_threads: 10,
+    max_threads: 50,
+    auto_terminate: true,
+    idletime: 60, # 1 minute
+    max_queue: 0, # unlimited
+    fallback_policy: :caller_runs
+  }.freeze
+
+  THREAD_POOL = Concurrent::ThreadPoolExecutor.new(DEFAULT_EXECUTOR_OPTIONS)
+
+  ASYNC_LOGGER = Logger.new($stdout)
+  ASYNC_LOGGER.level = Logger::ERROR
+
+  included do
+    class_attribute :async_methods_list, instance_accessor: false, default: Set.new
+    class_attribute :async_class_methods_list, instance_accessor: false, default: Set.new
+  end
+
+  module ClassMethods
+    def async
+      @async_next_method = true
+    end
+
+    def singleton_method_added(method_name)
+      super
+      if defined?(@async_next_method) && @async_next_method
+        @async_next_method = false
+
+        original_method = method(method_name)
+        define_singleton_method(method_name) do |*args, &block|
+          future = Concurrent::Future.execute(executor: THREAD_POOL) do
+            original_method.call(*args, &block)
+          rescue => e
+            ASYNC_LOGGER.error("Async class method #{method_name} failed: #{e.message}")
+            ASYNC_LOGGER.error(e.backtrace.join("\n"))
+            raise e
+          end
+          future
+        end
+
+        async_class_methods_list << method_name
+      end
+    end
+
+    def method_added(method_name)
+      super
+      if defined?(@async_next_method) && @async_next_method
+        @async_next_method = false
+
+        original_method = instance_method(method_name)
+        define_method(method_name) do |*args, &block|
+          future = Concurrent::Future.execute(executor: THREAD_POOL) do
+            original_method.bind_call(self, *args, &block)
+          rescue => e
+            ASYNC_LOGGER.error("Async method #{method_name} failed: #{e.message}")
+            ASYNC_LOGGER.error(e.backtrace.join("\n"))
+            raise e
+          end
+          future
+        end
+
+        async_methods_list << method_name
+      end
+    end
+  end
+
+  def self.shutdown
+    THREAD_POOL.shutdown
+    THREAD_POOL.wait_for_termination(5) # Wait up to 5s
+  end
+end

data/lib/async_magic/railtie.rb

@@ -0,0 +1,23 @@
+require "rails/railtie"
+
+module AsyncMagic
+  class Railtie < ::Rails::Railtie
+    initializer "async_magic.configure_inclusion" do
+      case AsyncMagic.include_in
+      when :active_record
+        ActiveSupport.on_load(:active_record) do
+          ActiveRecord::Base.include AsyncMagic
+        end
+      when :global
+        Object.include AsyncMagic
+      else
+        # If :include_in is anything else (including nil), do not auto-include.
+        # The user must manually include AsyncMagic in their classes.
+      end
+    end
+
+    at_exit do
+      AsyncMagic.shutdown
+    end
+  end
+end

data/lib/async_magic/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AsyncMagic
+  VERSION = "0.1.0"
+end

data/lib/async_magic.rb

@@ -0,0 +1,23 @@
+require "async_magic/version"
+require "async_magic/async"
+require "async_magic/railtie" if defined?(Rails)
+
+module AsyncMagic
+  mattr_accessor :executor_options, default: DEFAULT_EXECUTOR_OPTIONS
+  mattr_accessor :include_in, default: :global
+
+  def self.configure
+    yield self
+    rebuild_executor
+  end
+
+  def self.rebuild_executor
+    THREAD_POOL.shutdown
+    THREAD_POOL.wait_for_termination(5)
+    AsyncMagic.send(:remove_const, :THREAD_POOL) if AsyncMagic.const_defined?(:THREAD_POOL)
+    AsyncMagic.const_set(
+      :THREAD_POOL,
+      Concurrent::ThreadPoolExecutor.new(executor_options)
+    )
+  end
+end

metadata

@@ -0,0 +1,139 @@
+--- !ruby/object:Gem::Specification
+name: async_magic
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Igor Kasyanchuk
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-12-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: diff-lcs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Simple async methods for Ruby, Ruby on Rails applications
+email:
+- igorkasyanchuk@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".standard.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/async_magic.png
+- lib/async_magic.rb
+- lib/async_magic/async.rb
+- lib/async_magic/railtie.rb
+- lib/async_magic/version.rb
+homepage: https://github.com/igorkasyanchuk/async_magic
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/igorkasyanchuk/async_magic
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Simple async methods for Ruby, Ruby on Rails applications
+test_files: []