From 06c5923a3ecec04025b7addf40e56f615c429bd3 Mon Sep 17 00:00:00 2001 From: Andriy Tyurnikov Date: Thu, 11 Apr 2024 20:26:53 +0300 Subject: [PATCH] version 0.1.0 --- .github/workflows/main.yml | 27 +++++ .gitignore | 8 ++ .rubocop.yml | 19 +++ Gemfile | 12 ++ Gemfile.lock | 49 ++++++++ README.md | 31 +++++ Rakefile | 12 ++ bin/console | 11 ++ bin/setup | 8 ++ bipolar_cache.gemspec | 40 +++++++ lib/bipolar_cache.rb | 38 ++++++ lib/bipolar_cache/sequel/plugin_alpha.rb | 143 +++++++++++++++++++++++ lib/bipolar_cache/version.rb | 5 + sig/bipolar_cache.rbs | 4 + test/test_bipolar_cache.rb | 52 +++++++++ test/test_helper.rb | 7 ++ 16 files changed, 466 insertions(+) create mode 100644 .github/workflows/main.yml create mode 100644 .gitignore create mode 100644 .rubocop.yml create mode 100644 Gemfile create mode 100644 Gemfile.lock create mode 100644 README.md create mode 100644 Rakefile create mode 100755 bin/console create mode 100755 bin/setup create mode 100644 bipolar_cache.gemspec create mode 100644 lib/bipolar_cache.rb create mode 100644 lib/bipolar_cache/sequel/plugin_alpha.rb create mode 100644 lib/bipolar_cache/version.rb create mode 100644 sig/bipolar_cache.rbs create mode 100644 test/test_bipolar_cache.rb create mode 100644 test/test_helper.rb diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml new file mode 100644 index 0000000..37a9318 --- /dev/null +++ b/.github/workflows/main.yml @@ -0,0 +1,27 @@ +name: Ruby + +on: + push: + branches: + - main + + pull_request: + +jobs: + build: + runs-on: ubuntu-latest + name: Ruby ${{ matrix.ruby }} + strategy: + matrix: + ruby: + - '3.3.0' + + steps: + - uses: actions/checkout@v4 + - name: Set up Ruby + uses: ruby/setup-ruby@v1 + with: + ruby-version: ${{ matrix.ruby }} + bundler-cache: true + - name: Run the default task + run: bundle exec rake diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..9106b2a --- /dev/null +++ b/.gitignore @@ -0,0 +1,8 @@ +/.bundle/ +/.yardoc +/_yardoc/ +/coverage/ +/doc/ +/pkg/ +/spec/reports/ +/tmp/ diff --git a/.rubocop.yml b/.rubocop.yml new file mode 100644 index 0000000..63d5e45 --- /dev/null +++ b/.rubocop.yml @@ -0,0 +1,19 @@ +AllCops: + TargetRubyVersion: 3.0 + SuggestExtensions: false + NewCops: disable + +Metrics/AbcSize: + Enabled: false + +Metrics/MethodLength: + Enabled: false + +Style/Documentation: + Enabled: false + +Style/StringLiterals: + EnforcedStyle: double_quotes + +Style/StringLiteralsInInterpolation: + EnforcedStyle: double_quotes diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..3ea3648 --- /dev/null +++ b/Gemfile @@ -0,0 +1,12 @@ +# frozen_string_literal: true + +source "https://rubygems.org" + +# Specify your gem's dependencies in bipolar_cache.gemspec +gemspec + +gem "rake", "~> 13.0" + +gem "minitest", "~> 5.16" + +gem "rubocop", "~> 1.21" diff --git a/Gemfile.lock b/Gemfile.lock new file mode 100644 index 0000000..01a6209 --- /dev/null +++ b/Gemfile.lock @@ -0,0 +1,49 @@ +PATH + remote: . + specs: + bipolar_cache (0.1.0) + +GEM + remote: https://rubygems.org/ + specs: + ast (2.4.2) + json (2.7.1) + language_server-protocol (3.17.0.3) + minitest (5.22.3) + parallel (1.24.0) + parser (3.3.0.5) + ast (~> 2.4.1) + racc + racc (1.7.3) + rainbow (3.1.1) + rake (13.2.1) + regexp_parser (2.9.0) + rexml (3.2.6) + rubocop (1.62.0) + json (~> 2.3) + language_server-protocol (>= 3.17.0) + parallel (~> 1.10) + parser (>= 3.3.0.2) + rainbow (>= 2.2.2, < 4.0) + regexp_parser (>= 1.8, < 3.0) + rexml (>= 3.2.5, < 4.0) + rubocop-ast (>= 1.31.1, < 2.0) + ruby-progressbar (~> 1.7) + unicode-display_width (>= 2.4.0, < 3.0) + rubocop-ast (1.31.2) + parser (>= 3.3.0.4) + ruby-progressbar (1.13.0) + unicode-display_width (2.5.0) + +PLATFORMS + arm64-darwin-23 + ruby + +DEPENDENCIES + bipolar_cache! + minitest (~> 5.16) + rake (~> 13.0) + rubocop (~> 1.21) + +BUNDLED WITH + 2.5.7 diff --git a/README.md b/README.md new file mode 100644 index 0000000..9eeac24 --- /dev/null +++ b/README.md @@ -0,0 +1,31 @@ +# BipolarCache + +TODO: Delete this and the text below, and describe your gem + +Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/bipolar_cache`. To experiment with that code, run `bin/console` for an interactive prompt. + +## Installation + +TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org. + +Install the gem and add to the application's Gemfile by executing: + + $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG + +If bundler is not being used to manage dependencies, install the gem by executing: + + $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG + +## Usage + +TODO: Write usage instructions here + +## Development + +After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment. + +To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org). + +## Contributing + +Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/bipolar_cache. diff --git a/Rakefile b/Rakefile new file mode 100644 index 0000000..2bf771f --- /dev/null +++ b/Rakefile @@ -0,0 +1,12 @@ +# frozen_string_literal: true + +require "bundler/gem_tasks" +require "minitest/test_task" + +Minitest::TestTask.create + +require "rubocop/rake_task" + +RuboCop::RakeTask.new + +task default: %i[test rubocop] diff --git a/bin/console b/bin/console new file mode 100755 index 0000000..d19b004 --- /dev/null +++ b/bin/console @@ -0,0 +1,11 @@ +#!/usr/bin/env ruby +# frozen_string_literal: true + +require "bundler/setup" +require "bipolar_cache" + +# You can add fixtures and/or initialization code here to make experimenting +# with your gem easier. You can also use a different console, if you like. + +require "irb" +IRB.start(__FILE__) diff --git a/bin/setup b/bin/setup new file mode 100755 index 0000000..dce67d8 --- /dev/null +++ b/bin/setup @@ -0,0 +1,8 @@ +#!/usr/bin/env bash +set -euo pipefail +IFS=$'\n\t' +set -vx + +bundle install + +# Do any other automated setup that you need to do here diff --git a/bipolar_cache.gemspec b/bipolar_cache.gemspec new file mode 100644 index 0000000..74d19ea --- /dev/null +++ b/bipolar_cache.gemspec @@ -0,0 +1,40 @@ +# frozen_string_literal: true + +require_relative "lib/bipolar_cache/version" + +Gem::Specification.new do |spec| + spec.name = "bipolar_cache" + spec.version = BipolarCache::VERSION + spec.authors = ["Andriy Tyurnikov"] + spec.email = ["Andriy.Tyurnikov@gmail.com"] + + spec.summary = "BipolarCache. Probabalistic caching toolkit." + spec.description = "Probabalistic caching toolkit useful for caching of database counters, and other operations." + spec.homepage = "https://github.com/rubakas/bipolar_cache" + spec.required_ruby_version = ">= 3.0.0" + + # spec.metadata["allowed_push_host"] = "TODO: Set to your gem server 'https://example.com'" + + spec.metadata["homepage_uri"] = spec.homepage + spec.metadata["source_code_uri"] = spec.homepage + spec.metadata["changelog_uri"] = spec.homepage + + # Specify which files should be added to the gem when it is released. + # The `git ls-files -z` loads the files in the RubyGem that have been added into git. + gemspec = File.basename(__FILE__) + spec.files = IO.popen(%w[git ls-files -z], chdir: __dir__, err: IO::NULL) do |ls| + ls.readlines("\x0", chomp: true).reject do |f| + (f == gemspec) || + f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile]) + end + end + spec.bindir = "exe" + spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) } + spec.require_paths = ["lib"] + + # Uncomment to register a new dependency of your gem + # spec.add_dependency "example-gem", "~> 1.0" + + # For more information and examples about making a new gem, check out our + # guide at: https://bundler.io/guides/creating_gem.html +end diff --git a/lib/bipolar_cache.rb b/lib/bipolar_cache.rb new file mode 100644 index 0000000..b6741c8 --- /dev/null +++ b/lib/bipolar_cache.rb @@ -0,0 +1,38 @@ +# frozen_string_literal: true + +require_relative "bipolar_cache/version" + +module BipolarCache + class Error < StandardError; end + + ## + # It may read actual value, + # it may read cached value, + # or it may write actual value into cache! + # It depends on chance. + # Call it at your peril. + # + # @param actual [Proc] callable to perform an operation (cacheable) + # @param cached [Proc] callable to read cached value + # @param chance [Proc(Object)] callable to compute chance of cache hit + # @param if [Proc] callable to enable/disable caching + # @param rescue [Proc(StandardError)] callable to be invoked on exception + # @param update [Proc(Object)] callable to update cached value + # @return [Object] + def self.read!(**procs) + return procs[:actual].call unless procs[:if].call + + cached_value = procs[:cached].call + + if procs[:chance].call(cached_value) > rand + cached_value + else + actual_value = procs[:actual].call + procs[:update].call(actual_value) if cached_value != actual_value + + actual_value + end + rescue StandardError => e + procs[:rescue].call(e) if procs[:rescue].is_a?(Proc) + end +end diff --git a/lib/bipolar_cache/sequel/plugin_alpha.rb b/lib/bipolar_cache/sequel/plugin_alpha.rb new file mode 100644 index 0000000..c0da290 --- /dev/null +++ b/lib/bipolar_cache/sequel/plugin_alpha.rb @@ -0,0 +1,143 @@ +# frozen_string_literal: true + +module BipolarCache + module Sequel + module PluginAlpha + module ClassMethods + def instance_dataset_bipolar_count_cache(name, **opts) + opts = opts.merge({ name: name }) + method_name = opts[:method] || "#{name}_count" + + define_method method_name do + bcsp_cache(**fetch_or_build_procs(**opts)) + end + + define_method "#{method_name}_refresh!" do + procs = fetch_or_build_procs(**opts) + actual_value = procs[:actual].call + procs[:update].call(actual_value) if actual_value != procs[:cached].call + actual_value + end + + define_method "#{method_name}_increment!" do |by: 1| + procs = fetch_or_build_procs(**opts) + + procs[:update].call(by + procs[:cached].call) + end + + define_method "#{method_name}_decrement!" do |by: 1| + procs = fetch_or_build_procs(**opts) + + procs[:update].call((-by) + procs[:cached].call) + end + end + end + + def self.included(base) + base.extend ClassMethods + end + + def bcsp_cache(**procs) + BipolarCache.read!(**procs) + end + + def fetch_or_build_procs(**opts) + # create cached store for instance procs, if none + instance_variable_set(:@bcsp_proc_store, {}) unless instance_variable_defined?(:@bcsp_proc_store) + + if instance_variable_get(:@bcsp_proc_store)[opts[:name]].nil? + instance_variable_get(:@bcsp_proc_store)[opts[:name]] = + { + actual: bcsp_proc_actual_from(**opts), + cached: bcsp_proc_cached_from(**opts), + update: bcsp_proc_update_from(**opts), + chance: bcsp_proc_chance_from(**opts), + rescue: bcsp_proc_rescue_from(**opts), + if: bcsp_proc_if_from(**opts) + } + end + + # stored procs + instance_variable_get(:@bcsp_proc_store)[opts[:name]] + end + + def bcsp_proc_actual_from(**opts) + case opts[:actual] + when Proc + opts[:actual] + when String, Symbol + -> { send(opts[:actual]) } + else + -> { send("#{opts[:name]}_dataset").count } + end + end + + def bcsp_proc_cached_from(**opts) + case opts[:cached] + when Proc + opts[:cached] + when String, Symbol + -> { send(opts[:cached]) } + else + -> { send("#{opts[:name]}_count_cache") } + end + end + + def bcsp_proc_update_from(**opts) + cache_name = if opts[:cached].is_a?(String) || opts[:cached].is_a?(Symbol) + opts[:cached] + else + "#{opts[:name]}_count_cache" + end + + case opts[:update] + when Proc + opts[:update] + when String, Symbol + -> { send(opts[:update]) } + else + ->(value) { update({ cache_name => value }) } + end + end + + def bcsp_proc_chance_from(**opts) + case opts[:chance] + when Proc + opts[:chance] + when Integer, Float + normalised_chance = if opts[:chance] > 1 + opts[:chance] / 100 + else + opts[:chance] + end + ->(_value) { normalised_chance } + else # default + ->(value) { value < 10 ? 0.1 : 0.9 } + end + end + + def bcsp_proc_rescue_from(**opts) + if opts[:rescue].is_a? Proc + opts[:rescue] + else # default + lambda { |e| + e.inspect + 0 + } + end + end + + def bcsp_proc_if_from(**opts) + case opts[:if] + when Proc + opts[:if] + when TrueClass, FalseClass + value = opts[:if] + -> { value } + else # default + -> { true } + end + end + end + end +end diff --git a/lib/bipolar_cache/version.rb b/lib/bipolar_cache/version.rb new file mode 100644 index 0000000..ce9f1af --- /dev/null +++ b/lib/bipolar_cache/version.rb @@ -0,0 +1,5 @@ +# frozen_string_literal: true + +module BipolarCache + VERSION = "0.1.0" +end diff --git a/sig/bipolar_cache.rbs b/sig/bipolar_cache.rbs new file mode 100644 index 0000000..f0d17fb --- /dev/null +++ b/sig/bipolar_cache.rbs @@ -0,0 +1,4 @@ +module BipolarCache + VERSION: String + # See the writing guide of rbs: https://github.com/ruby/rbs#guides +end diff --git a/test/test_bipolar_cache.rb b/test/test_bipolar_cache.rb new file mode 100644 index 0000000..c742c2a --- /dev/null +++ b/test/test_bipolar_cache.rb @@ -0,0 +1,52 @@ +# frozen_string_literal: true + +require "test_helper" + +class TestBipolarCache < Minitest::Test + def setup + @value = 42 + @cache = 0 + + @example_procs = { + actual: -> { @value }, + cached: -> { @cache }, + chance: ->(_v) { 1 }, + if: -> { true }, + rescue: ->(e) { e }, + update: ->(v) { @cache = v } + } + + @bipolar_cache = BipolarCache + end + + def test_that_it_has_a_version_number + refute_nil ::BipolarCache::VERSION + end + + def test_it_hits_cache_when_chance_is_one + procs = @example_procs.merge({ chance: ->(_v) { 1 } }) + assert_equal 0, @bipolar_cache.read!(**procs) + end + + def test_it_misses_and_updates_cache_when_chance_is_zero + procs = @example_procs.merge({ chance: ->(_v) { 0 } }) + result = @bipolar_cache.read!(**procs) + assert_equal 42, result + assert_equal 42, @cache + end + + def test_it_misses_cache_when_if_is_false_does_not_update + procs = @example_procs.merge({ chance: ->(_v) { 1 }, if: -> { false } }) + result = @bipolar_cache.read!(**procs) + assert_equal 42, result + assert_equal 0, @cache + end + + def test_it_updates_cache_when_chance_is_one + procs = @example_procs.merge({ chance: ->(_v) { 1 } }) + result = @bipolar_cache.read!(**procs) + assert_equal 0, result + assert_equal 42, @value + assert_equal 0, @cache + end +end diff --git a/test/test_helper.rb b/test/test_helper.rb new file mode 100644 index 0000000..595d2cf --- /dev/null +++ b/test/test_helper.rb @@ -0,0 +1,7 @@ +# frozen_string_literal: true + +$LOAD_PATH.unshift File.expand_path("../lib", __dir__) +require "bipolar_cache" + +require "minitest/autorun" +require "minitest/pride"