async-pool 0.6.1 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f1ad63ef9b3e6a6e062277b976adefe9e254b9717aa47a33bf9ede37f5009e86
-  data.tar.gz: 362cd05e427993817b230ff97ae1844f2299cb0fc5544dbdfafa690e501cbaab
+  metadata.gz: cfc00b6087965cc5fc3f58ae151a0048fc8cf351aab9c06bdaf46b0eb65bb877
+  data.tar.gz: 7f9e3067d5bc75de995735ac4a025cb6cea4ee72e0e63201ec4f28c000301cc2
 SHA512:
-  metadata.gz: 2484b795cff61e71ff9c1fd2207c7600f809ed7b8352e86e084079dedf0b8451c6c5f096aedd25714146410db3287685e6aa863c057923a36e7d30380bc25eee
-  data.tar.gz: 053a39d997a23028079fc17517f5d45bf370dae42e834b55c3956cc5811912993a0f64ddd91d2d4f50e1a2fbea85d1083fd6181871c8cec64f67ccbd0b3a915f
+  metadata.gz: e6933852df812446375faf0c0c921c137bdd972beec9f1e392f6bdfc0c803ddf1cf62151323fbd18f8431c9ab1021eaac2c90ab461f03679d3e93cebfbc039b0
+  data.tar.gz: 76a83cc5cc6a5dc2230ae6ad3eedc12a0e4fc24170d7391d5a1c032553d4a5653fc89b12060e331bd64687fefb5308d64785bbdc9cc70701b3f86e394de718f2

data/lib/async/pool/controller.rb

@@ -13,11 +13,19 @@ require 'async/semaphore'
 
 module Async
 	module Pool
+		# A resource pool controller.
 		class Controller
+			# Create a new resource pool, using the given block to create new resources.
 			def self.wrap(**options, &block)
 				self.new(block, **options)
 			end
 			
+			# Create a new resource pool.
+			#
+			# @parameter constructor [Proc] A block which creates a new resource.
+			# @parameter limit [Integer | Nil] The maximum number of resources that this pool can have at any given time. If nil, the pool can have an unlimited number of resources.
+			# @parameter concurrency [Integer] The maximum number of concurrent tasks that can be creating a new resource.
+			# @parameter policy [Policy] The pool policy.
 			def initialize(constructor, limit: nil, concurrency: (limit || 1), policy: nil)
 				@constructor = constructor
 				@limit = limit
@@ -45,6 +53,7 @@ module Async
 			# @attribute [Integer] The maximum number of resources that this pool can have at any given time.
 			attr_accessor :limit
 			
+			# Generate a human-readable representation of the pool.
 			def to_s
 				if @resources.empty?
 					"\#<#{self.class}(#{usage_string})>"
@@ -53,6 +62,7 @@ module Async
 				end
 			end
 			
+			# Generate a JSON representation of the pool.
 			def as_json(...)
 				{
 					limit: @limit,
@@ -62,6 +72,7 @@ module Async
 				}
 			end
 			
+			# Generate a JSON representation of the pool.
 			def to_json(...)
 				as_json.to_json(...)
 			end
@@ -71,6 +82,7 @@ module Async
 				@guard.limit
 			end
 			
+			# Set the maximum number of concurrent tasks that can be creating a new resource.
 			def concurrency= value
 				@guard.limit = value
 			end
@@ -81,6 +93,7 @@ module Async
 			# @attribute [Hash(Resource, Integer)] all allocated resources, and their associated usage.
 			attr :resources
 			
+			# The number of resources in the pool.
 			def size
 				@resources.size
 			end
@@ -109,10 +122,12 @@ module Async
 				@notification.wait
 			end
 			
+			# Whether the pool is empty.
 			def empty?
 				@resources.empty?
 			end
 			
+			# Acquire a resource from the pool. If a block is provided, the resource will be released after the block has been executed.
 			def acquire
 				resource = wait_for_resource
 				
@@ -139,6 +154,7 @@ module Async
 				retire(resource) unless processed
 			end
 			
+			# Close all resources in the pool.
 			def close
 				@available.clear
 				
@@ -146,7 +162,7 @@ module Async
 					resource, usage = pair
 					
 					if usage > 0
-						Console.logger.warn(self, resource: resource, usage: usage) {"Closing resource while still in use!"}
+						Console.warn(self, resource: resource, usage: usage) {"Closing resource while still in use!"}
 					end
 					
 					resource.close
@@ -156,8 +172,8 @@ module Async
 			end
 			
 			# Retire (and close) all unused resources. If a block is provided, it should implement the desired functionality for unused resources.
-			# @param retain [Integer] the minimum number of resources to retain.
-			# @yield resource [Resource] unused resources.
+			# @parameter retain [Integer] the minimum number of resources to retain.
+			# @yields {|resource| ...} Any unused resource.
 			def prune(retain = 0)
 				unused = []
 				
@@ -190,8 +206,9 @@ module Async
 				return unused.size
 			end
 			
+			# Retire a specific resource.
 			def retire(resource)
-				Console.logger.debug(self) {"Retire #{resource}"}
+				Console.debug(self) {"Retire #{resource}"}
 				
 				@resources.delete(resource)
 				
@@ -244,10 +261,10 @@ module Async
 			# end
 			
 			def reuse(resource)
-				Console.logger.debug(self) {"Reuse #{resource}"}
+				Console.debug(self) {"Reuse #{resource}"}
 				usage = @resources[resource]
 				
-				if usage.zero?
+				if usage.nil? || usage.zero?
 					raise "Trying to reuse unacquired resource: #{resource}!"
 				end
 				
@@ -269,7 +286,7 @@ module Async
 					@notification.wait
 				end
 				
-				Console.logger.debug(self) {"Wait for resource -> #{resource}"}
+				Console.debug(self) {"Wait for resource -> #{resource}"}
 				
 				# if resource.concurrency > 1
 				# 	@notification.signal
@@ -336,7 +353,7 @@ module Async
 				end
 				
 				if @limit.nil? or @resources.size < @limit
-					Console.logger.debug(self) {"No available resources, allocating new one..."}
+					Console.debug(self) {"No available resources, allocating new one..."}
 					
 					return create_resource
 				end

data/lib/async/pool/resource.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require 'console/logger'
 
@@ -17,6 +17,9 @@ module Async
 				self.new
 			end
 			
+			# Create a new resource.
+			#
+			# @parameter concurrency [Integer] The concurrency of this resource.
 			def initialize(concurrency = 1)
 				@concurrency = concurrency
 				@closed = false

data/lib/async/pool/version.rb

@@ -5,6 +5,6 @@
 
 module Async
 	module Pool
-		VERSION = "0.6.1"
+		VERSION = "0.7.1"
 	end
 end

data/lib/async/pool.rb

@@ -1,7 +1,14 @@
 # frozen_string_literal: true
 
 # Released under the MIT License.
-# Copyright, 2019-2022, by Samuel Williams.
+# Copyright, 2019-2024, by Samuel Williams.
 
 require_relative 'pool/version'
 require_relative 'pool/controller'
+
+# @namespace
+module Async
+	# @namespace
+	module Pool
+	end
+end

data/readme.md

@@ -4,44 +4,11 @@ Provides support for connection pooling both singleplex and multiplex resources.
 
 [![Development Status](https://github.com/socketry/async-pool/workflows/Test/badge.svg)](https://github.com/socketry/async-pool/actions?workflow=Test)
 
-## Installation
-
-Add this line to your application's Gemfile:
-
-``` ruby
-gem 'async-pool'
-```
-
-And then execute:
-
-``` bash
-$ bundle
-```
-
-Or install it yourself as:
-
-``` bash
-$ gem install async-pool
-```
-
 ## Usage
 
-`Async::Pool::Controller` provides support for both singleplex (one stream at a time) and multiplex resources (multiple streams at a time).
-
-`Async::Pool::Resource` is provided as an interface and to document how to use the pools. However, you wouldn't need to use this in practice and just implement the appropriate interface on your own objects.
-
-``` ruby
-pool = Async::Pool::Controller.new(Async::Pool::Resource)
-
-pool.acquire do |resource|
-	# resource is implicitly released when exiting the block.
-end
-
-resource = pool.acquire
+Please see the [project documentation](https://socketry.github.io/async-pool/) for more details.
 
-# Return the resource back to the pool:
-pool.release(resource)
-```
+  - [Getting Started](https://socketry.github.io/async-pool/guides/getting-started/index) - This guide explains how to use the `async-pool` gem to manage connection pooling.
 
 ## Contributing
 
@@ -55,8 +22,8 @@ We welcome contributions to this project.
 
 ### Developer Certificate of Origin
 
-This project uses the [Developer Certificate of Origin](https://developercertificate.org/). All contributors to this project must agree to this document to have their contributions accepted.
+In order to protect users of this project, we require all contributors to comply with the [Developer Certificate of Origin](https://developercertificate.org/). This ensures that all contributions are properly licensed and attributed.
 
-### Contributor Covenant
+### Community Guidelines
 
-This project is governed by the [Contributor Covenant](https://www.contributor-covenant.org/). All contributors and participants agree to abide by its terms.
+This project is best served by a collaborative and respectful environment. Treat each other professionally, respect differing viewpoints, and engage constructively. Harassment, discrimination, or harmful behavior is not tolerated. Communicate clearly, listen actively, and support one another. If any issues arise, please inform the project maintainers.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: async-pool
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.7.1
 platform: ruby
 authors:
 - Samuel Williams
@@ -40,7 +40,7 @@ cert_chain:
   Q2K9NVun/S785AP05vKkXZEFYxqG6EW012U4oLcFl5MySFajYXRYbuUpH6AY+HP8
   voD0MPg1DssDLKwXyt1eKD/+Fq0bFWhwVM/1XiAXL7lyYUyOq24KHgQ2Csg=
   -----END CERTIFICATE-----
-date: 2024-04-22 00:00:00.000000000 Z
+date: 2024-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -90,7 +90,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: A singleplex and multiplex resource pool for implementing robust clients.