pgtk 0.24.0 → 0.24.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b16d736e3b32a69aabf5a87fff3d4611f0af14c6c87e72fb7dc3e84d2ee027ee
-  data.tar.gz: 1c989c0af1b8ce28e325b0b9e146295e3cd24f02bb2cec0fee7ed2ac714ed2d6
+  metadata.gz: 88c5e888b9c116ec175abea3c43fa02d2a878a3edbc61c901be4a07f5a7730d4
+  data.tar.gz: 608f79d18ee7799c1a4bd200d8157a64f25033431ab972fe41072ac7223dae44
 SHA512:
-  metadata.gz: a6dcaac89f9ea200f9030505df810fb4a0a2136387e98833960f830be10d19aa9f1b55f7c3f8e6fd447c8df30235233aafd8f7730bde99c8751cb910416e660f
-  data.tar.gz: 34e7b0682c858ce58397abf4c8694cdb849453f70d0d0fe1c220d96eb800a425602ae693a149b53b7b2a1fc1b8afafee3f9c72a494b1214393d21d2d1dbafebd
+  metadata.gz: 788a641261c89c9da31133e8d38a9cfcb1bbb91d6d1e2b43161ade3827930ff54baf6096e1ac7c54f13d7921928aefc163d2a5750000e3a916a17c212ea8097e
+  data.tar.gz: 237557831c63cc930743f152abd2a08cd5783d664f4a56f3a5faf24bd359097799463fa0eb66440085b99c46e50a338faf3b76677addc36b0a3f21fb0b415fbe

data/README.md

@@ -220,6 +220,19 @@ require 'pgtk/stash'
 stash = Pgtk::Stash.new(pgsql)
 ```
 
+You can configure `Stash` with optional parameters:
+
+```ruby
+stash = Pgtk::Stash.new(
+  pgsql,
+  cap: 10_000,          # Maximum cached query results (default: 10,000)
+  cap_interval: 60,     # Seconds between cache size enforcement (default: 60)
+  refill_interval: 16,  # Seconds between stale query refilling (default: 16)
+  threads: 4,           # Worker threads for background refilling (default: 4)
+  max_queue_length: 128 # Maximum refilling tasks in queue (default: 128)
+)
+```
+
 `Stash` automatically caches read queries and invalidates the cache
 when tables are modified:
 

data/lib/pgtk/stash.rb

@@ -19,6 +19,12 @@ require_relative '../pgtk'
 #
 # The implementation is very naive! Use it at your own risk.
 #
+# @example Basic usage
+#   pool = Pgtk::Pool.new(...)
+#   stash = Pgtk::Stash.new(pool, cap: 1000, refill_interval: 30)
+#   stash.start!
+#   result = stash.exec('SELECT * FROM users WHERE id = $1', [42])
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2019-2025 Yegor Bugayenko
 # License:: MIT
@@ -35,16 +41,24 @@ class Pgtk::Stash
 
   # Initialize a new Stash with query caching.
   #
-  # @param [Object] pool Original object
-  # @param [Hash] stash Optional existing stash to use (default: new empty stash)
-  # @option [Hash] queries Internal cache data (default: {})
-  # @option [Hash] tables Internal cache data (default: {})
-  # @param [Integer] refill_interval Interval in seconds for recalculate stale queries
-  # @param [Integer] cap How many queries to keep in cache (if more, oldest ones are deleted)
-  # @param [Integer] cap_interval Interval in seconds for cap the cache (remove old queries)
-  # @param [Integer] max_queue_length Number of refilling tasks in the queue
-  # @param [Integer] threads Number of threads in tpool
-  # @param [Loog] loog Logger for debugging (default: null logger)
+  # @param [Object] pool The underlying connection pool that executes actual database queries
+  # @param [Hash] stash Internal cache structure containing queries and tables hashes for sharing state
+  #   across transactions
+  # @param [Integer] refill_interval Interval in seconds between background tasks that recalculate stale
+  #   cached queries
+  # @param [Integer] max_queue_length Maximum number of refilling tasks allowed in the thread pool queue
+  #   before new tasks are skipped
+  # @param [Integer] threads Number of worker threads in the background thread pool for cache refilling
+  #   operations
+  # @param [Integer] cap Maximum number of cached query results to retain; oldest queries are evicted when
+  #   this limit is exceeded
+  # @param [Integer] cap_interval Interval in seconds between background tasks that enforce the cache size
+  #   cap by removing old queries
+  # @param [Loog] loog Logger instance for debugging and monitoring cache operations (default: null logger)
+  # @param [Concurrent::ReentrantReadWriteLock] entrance Read-write lock for thread-safe cache access
+  #   shared across instances
+  # @param [Concurrent::AtomicBoolean] launched Atomic boolean flag tracking whether background tasks have
+  #   been started to prevent multiple launches
   def initialize(
     pool,
     stash: { queries: {}, tables: {} },
@@ -70,7 +84,13 @@ class Pgtk::Stash
     @tpool = Concurrent::FixedThreadPool.new(@threads)
   end
 
-  # Start a new connection pool with the given arguments.
+  # Start the connection pool and launch background cache management tasks.
+  #
+  # Initializes background timer tasks for cache refilling and size capping.
+  # The refill task periodically updates stale cached queries based on popularity.
+  # The cap task removes oldest queries when cache size exceeds the configured limit.
+  #
+  # @return [void]
   def start!
     launch!
     @pool.start!
@@ -83,6 +103,11 @@ class Pgtk::Stash
   end
 
   # Convert internal state into text.
+  #
+  # Generates a detailed report of the cache state including query counts,
+  # popularity scores, stale queries, and thread pool status.
+  #
+  # @return [String] Multi-line text representation of the current cache state
   def dump
     qq =
       @stash[:queries].map do |q, kk|
@@ -97,8 +122,11 @@ class Pgtk::Stash
     [
       @pool.dump,
       '',
-      "Pgtk::Stash (refill_interval=#{@refill_interval}s, max_queue_length=#{@max_queue_length}, threads=#{@threads}):",
+      # rubocop:disable Layout/LineLength
+      "Pgtk::Stash (refill_interval=#{@refill_interval}s, max_queue_length=#{@max_queue_length}, threads=#{@threads}, cap=#{@cap}, cap_interval=#{@cap_interval}s):",
+      # rubocop:enable Layout/LineLength
       "  #{'not ' if @launched.false?}launched",
+      "  #{stash_size} queries stashed (#{stash_size > @cap ? 'above' : 'below'} the cap)",
       "  #{@tpool.queue_length} task(s) in the thread pool",
       "  #{@stash[:tables].count} table(s) in cache",
       "  #{qq.sum { |a| a[:s] }} stale quer(ies) in cache:",
@@ -115,11 +143,14 @@ class Pgtk::Stash
   # Execute a SQL query with optional caching.
   #
   # Read queries are cached, while write queries bypass the cache and invalidate related entries.
+  # Queries containing modification keywords (INSERT, UPDATE, DELETE, etc.) are executed directly
+  # and trigger invalidation of cached queries for affected tables. Read queries (SELECT)
+  # are cached by query text and parameter values. Queries containing NOW() are never cached.
   #
-  # @param [String, Array<String>] query The SQL query to execute
-  # @param [Array] params Query parameters
-  # @param [Integer] result Should be 0 for text results, 1 for binary
-  # @return [PG::Result] Query result
+  # @param [String, Array<String>] query The SQL query to execute as a string or array of strings to be joined
+  # @param [Array] params Query parameters for placeholder substitution in prepared statements (default: empty array)
+  # @param [Integer] result Result format code where 0 requests text format and 1 requests binary format (default: 0)
+  # @return [PG::Result] Query result object containing rows and metadata from the database
   def exec(query, params = [], result = 0)
     pure = (query.is_a?(Array) ? query.join(' ') : query).gsub(/\s+/, ' ').strip
     if MODS_RE.match?(pure) || /(^|\s)pg_[a-z_]+\(/.match?(pure)
@@ -186,12 +217,28 @@ class Pgtk::Stash
 
   private
 
+  # Calculate total number of cached query results.
+  #
+  # Counts all cached query-parameter combinations across all queries.
+  #
+  # @return [Integer] Total count of cached query results
+  def stash_size
+    @stash[:queries].values.sum { |kk| kk.values.size }
+  end
+
+  # Launch background tasks for cache management.
+  #
+  # Starts two concurrent timer tasks: one for enforcing cache size cap by removing
+  # oldest queries, and another for refilling stale cached queries based on popularity.
+  # This method can only be called once per cache instance.
+  #
+  # @return [nil]
+  # @raise [RuntimeError] if background tasks have already been launched on this cache instance
   def launch!
     raise 'Cannot launch multiple times on same cache data' unless @launched.make_true
     Concurrent::TimerTask.execute(execution_interval: @cap_interval, executor: @tpool) do
       loop do
-        s = @stash[:queries].values.sum { |kk| kk.values.size }
-        break if s <= @cap
+        break if stash_size <= @cap
         @entrance.with_write_lock do
           @stash[:queries].each_key do |q|
             m = @stash[:queries][q].values.map { |h| h[:used] }.min

data/lib/pgtk/version.rb

@@ -11,5 +11,5 @@ require_relative '../pgtk'
 # License:: MIT
 module Pgtk
   # Current version of the library.
-  VERSION = '0.24.0'
+  VERSION = '0.24.1'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: pgtk
 version: !ruby/object:Gem::Version
-  version: 0.24.0
+  version: 0.24.1
 platform: ruby
 authors:
 - Yegor Bugayenko