p99-ruby 0.0.1 → 0.1.0

data/lib/p99/histogram.rb

@@ -0,0 +1,85 @@
+
+# ######################################################################## #
+# File:     p99/histogram.rb
+#
+# Purpose:  Histogram loader for p99.Ruby (pure Ruby; C extension later)
+#
+# Created:  4th August 2026
+# Updated:  4th August 2026
+#
+# Home:     http://github.com/synesissoftware/p99.Ruby
+#
+# Author:   Matthew Wilson
+#
+# Copyright (c) 2026, Matthew Wilson and Synesis Information Systems
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright
+#   notice, this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names of the copyright holder nor the names of its
+#   contributors may be used to endorse or promote products derived from
+#   this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+# ######################################################################## #
+
+
+=begin
+=end
+
+module P99
+
+  # Loads the Histogram implementation.
+  #
+  # Prefers a future C extension when present, unless +P99_PURE_RUBY+ is set
+  # in the environment; otherwise falls back to the pure-Ruby implementation.
+  #
+  # @return [String] +"c"+ or +"ruby"+
+  def self.load_histogram_implementation
+
+    if ENV['P99_PURE_RUBY']
+
+      require 'p99/histogram/pure'
+
+      return 'ruby'
+    end
+
+    begin
+
+      require 'p99/histogram/ext'
+
+      'c'
+    rescue LoadError
+
+      require 'p99/histogram/pure'
+
+      'ruby'
+    end
+  end
+
+  # Active Histogram backend: +"ruby"+ (current) or +"c"+ (when available).
+  IMPLEMENTATION = load_histogram_implementation
+end # module P99
+
+
+# ############################## end of file ############################# #

data/lib/p99/version.rb

@@ -5,7 +5,7 @@
 # Purpose:  Version for p99.Ruby library
 #
 # Created:  4th August 2026
-# Updated:  28th August 2026
+# Updated:  30th August 2026
 #
 # Home:     http://github.com/synesissoftware/p99.Ruby
 #
@@ -50,7 +50,7 @@
 module P99
 
   # Current version of the p99.Ruby library
-  VERSION           = '0.0.1'
+  VERSION           = '0.1.0'
 
   private
   # @!visibility private

data/lib/p99.rb

@@ -54,6 +54,7 @@ end # module P99
 
 
 require 'p99/version'
+require 'p99/histogram'
 
 
 # ############################## end of file ############################# #

data/test/unit/tc_histogram.rb

@@ -0,0 +1,317 @@
+#! /usr/bin/env ruby
+
+$:.unshift File.join(File.dirname(__FILE__), '../../lib')
+
+
+require 'p99'
+
+require 'test/unit'
+
+
+class Test_histogram < Test::Unit::TestCase
+
+  def setup
+
+    @h = P99::Histogram.new
+  end
+
+  def test_implementation_is_ruby
+
+    assert_equal 'ruby', P99::IMPLEMENTATION
+  end
+
+  def test_default_histogram
+
+    assert_equal 0, @h.event_count
+    assert_equal 0, @h.event_time_total
+    assert_equal 0, @h.event_time_total_raw
+    assert_equal false, @h.has_overflowed?
+    assert_nil @h.min_event_time
+    assert_nil @h.max_event_time
+
+    buckets = @h.buckets
+
+    assert_equal P99::BUCKET_COUNT, buckets.size
+
+    P99::BUCKET_COUNT.times do |i|
+
+      assert_equal 0, buckets[i]
+      assert_equal 0, @h.bucket_value(i)
+    end
+
+    assert_nil @h.bucket_value(64)
+    assert_nil @h.bucket_value(-1)
+  end
+
+  def test_bucket_index
+
+    cases = [
+      [ 0, 0 ],
+      [ 1, 0 ],
+      [ 2, 1 ],
+      [ 3, 1 ],
+      [ 4, 2 ],
+      [ 7, 2 ],
+      [ 8, 3 ],
+      [ 15, 3 ],
+      [ 1024, 10 ],
+      [ 2047, 10 ],
+      [ 1 << 63, 63 ],
+      [ P99::UINT64_MAX, 63 ],
+    ]
+
+    cases.each do |value, bucket|
+
+      assert_equal bucket, P99.bucket_index(value), "value=#{value}"
+    end
+  end
+
+  def test_bucket_range
+
+    cases = [
+      [ 0, 0, 1 ],
+      [ 1, 2, 3 ],
+      [ 2, 4, 7 ],
+      [ 3, 8, 15 ],
+      [ 4, 16, 31 ],
+      [ 10, 1024, 2047 ],
+      [ 63, 1 << 63, P99::UINT64_MAX ],
+    ]
+
+    cases.each do |index, lower, upper|
+
+      assert_equal [ lower, upper ], P99.bucket_range(index)
+    end
+
+    assert_nil P99.bucket_range(64)
+    assert_nil P99.bucket_range(-1)
+  end
+
+  def test_bucket_placement
+
+    cases = [
+      [ 0, 0 ],
+      [ 1, 0 ],
+      [ 2, 1 ],
+      [ 3, 1 ],
+      [ 4, 2 ],
+      [ 7, 2 ],
+      [ 8, 3 ],
+      [ 15, 3 ],
+      [ 1024, 10 ],
+      [ 2047, 10 ],
+      [ 1 << 63, 63 ],
+      [ P99::UINT64_MAX, 63 ],
+    ]
+
+    cases.each do |value, bucket|
+
+      @h.clear
+
+      assert @h.push_event_time_ns(value)
+      assert_equal 1, @h.bucket_value(bucket), "value=#{value}"
+    end
+  end
+
+  def test_push_events
+
+    assert @h.push_event_time_ns(1)
+    assert @h.push_event_time_ns(3)
+    assert @h.push_event_time_us(10)
+    assert @h.push_event_time_ms(5)
+    assert @h.push_event_time_s(2)
+    assert @h.push_event_time_ns(100)
+
+    assert_equal 6, @h.event_count
+    assert_equal false, @h.has_overflowed?
+    assert_equal 1, @h.min_event_time
+    assert_equal 2_000_000_000, @h.max_event_time
+    assert_equal 2_005_010_104, @h.event_time_total
+
+    buckets = @h.buckets
+
+    assert_equal 1, buckets[0]
+    assert_equal 1, buckets[1]
+    assert_equal 1, buckets[6]
+    assert_equal 1, buckets[13]
+    assert_equal 1, buckets[22]
+    assert_equal 1, buckets[30]
+
+    @h.clear
+
+    assert_equal 0, @h.event_count
+    assert_equal 0, @h.event_time_total
+  end
+
+  def test_overflow
+
+    assert @h.push_event_time_ns(P99::UINT64_MAX)
+    assert_equal P99::UINT64_MAX, @h.event_time_total
+    assert_equal false, @h.has_overflowed?
+
+    assert_equal false, @h.push_event_time_ns(1)
+    assert_equal true, @h.has_overflowed?
+    assert_nil @h.event_time_total
+    assert_equal P99::UINT64_MAX, @h.event_time_total_raw
+  end
+
+  def test_percentiles_empty
+
+    assert_nil @h.value_at_percentile(50.0)
+    assert_nil @h.value_at_p50
+    assert_nil @h.value_at_p99
+    assert_nil @h.fixed_percentiles
+    assert_nil @h.values_at_percentiles([ 50.0 ])
+  end
+
+  def test_percentiles_single_event
+
+    assert @h.push_event_time_ns(100)
+
+    [ 0.0, 50.0, 99.0, 100.0 ].each do |percentile|
+
+      assert_equal 100, @h.value_at_percentile(percentile)
+    end
+
+    assert_equal 100, @h.value_at_p50
+    assert_equal 100, @h.value_at_p90
+    assert_equal 100, @h.value_at_p99
+    assert_equal 100, @h.value_at_p99_999_9
+  end
+
+  def test_percentiles_interpolation
+
+    assert @h.push_event_time_ns(100)
+    assert @h.push_event_time_ns(200)
+
+    p50 = @h.value_at_p50
+    p99 = @h.value_at_p99
+
+    assert_operator p50, :>=, 100
+    assert_operator p50, :<=, 200
+    assert_operator p99, :>=, 100
+    assert_operator p99, :<=, 200
+    assert_equal 100, @h.value_at_percentile(0.0)
+    assert_equal 200, @h.value_at_percentile(100.0)
+  end
+
+  def test_percentiles_wide_range
+
+    values = [
+      1,
+      10,
+      100,
+      1_000,
+      10_000,
+      100_000,
+      1_000_000,
+      10_000_000,
+      100_000_000,
+      1_000_000_000,
+      10_000_000_000,
+    ]
+
+    values.each do |value|
+
+      assert @h.push_event_time_ns(value)
+    end
+
+    assert_equal values.size, @h.event_count
+    assert_equal 1, @h.min_event_time
+    assert_equal 10_000_000_000, @h.max_event_time
+
+    fixed = @h.fixed_percentiles
+
+    refute_nil fixed
+
+    ordered = [
+      fixed['p50'],
+      fixed['p75'],
+      fixed['p90'],
+      fixed['p95'],
+      fixed['p99'],
+      fixed['p99.5'],
+      fixed['p99.9'],
+      fixed['p99.99'],
+      fixed['p99.999'],
+      fixed['p99.9999'],
+    ]
+
+    assert_equal ordered.sort, ordered
+    assert_operator ordered.first, :>=, 1
+    assert_operator ordered.last, :<=, 10_000_000_000
+  end
+
+  def test_percentiles_many_events
+
+    count = 100_000
+
+    (1..count).each do |i|
+
+      assert @h.push_event_time_ns(i)
+    end
+
+    assert_equal count, @h.event_count
+    assert_equal 1, @h.min_event_time
+    assert_equal count, @h.max_event_time
+    assert_equal 50_000, @h.value_at_p50
+    assert_equal 100_000, @h.value_at_p90
+    assert_equal 100_000, @h.value_at_p99
+    assert_equal 100_000, @h.value_at_p99_9
+  end
+
+  def test_compare_float_and_int_percentiles
+
+    (1..10_000).each do |i|
+
+      assert @h.push_event_time_ns((i * i) % 1_000_000)
+    end
+
+    pairs = [
+      [ 50.0, :value_at_p50 ],
+      [ 75.0, :value_at_p75 ],
+      [ 90.0, :value_at_p90 ],
+      [ 95.0, :value_at_p95 ],
+      [ 99.0, :value_at_p99 ],
+      [ 99.5, :value_at_p99_5 ],
+      [ 99.9, :value_at_p99_9 ],
+      [ 99.99, :value_at_p99_99 ],
+      [ 99.999, :value_at_p99_999 ],
+      [ 99.9999, :value_at_p99_999_9 ],
+    ]
+
+    pairs.each do |level, method_name|
+
+      float_value = @h.value_at_percentile(level)
+      int_value = @h.send(method_name)
+
+      refute_nil float_value
+      refute_nil int_value
+
+      tolerance = [ float_value.abs * 0.01, 1.0 ].max
+
+      assert_operator (float_value - int_value).abs, :<=, tolerance
+    end
+  end
+
+  def test_values_at_percentiles_empty_levels
+
+    assert @h.push_event_time_ns(100)
+    assert_equal [], @h.values_at_percentiles([])
+  end
+
+  def test_values_at_percentiles
+
+    assert @h.push_event_time_ns(100)
+    assert @h.push_event_time_ns(200)
+
+    results = @h.values_at_percentiles([ 0.0, 100.0 ])
+
+    assert_equal [ [ 0.0, 100 ], [ 100.0, 200 ] ], results
+  end
+
+  def test_clear_returns_self
+
+    assert_same @h, @h.clear
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: p99-ruby
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Matt Wilson
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: xqsr3
@@ -33,18 +33,39 @@ dependencies:
 description: |
   Low-cost generation of performance percentiles (p50, p90, p99, p99.9, etc.), for Ruby.
 
-  p99.Ruby is the Ruby implementation of the p99 family of libraries.
+  p99.Ruby is the Ruby implementation of the p99 family of libraries. This
+  release provides a pure-Ruby Histogram; a C-extension backend is planned.
 email:
 - matthew@synesis.com.au
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AUTHORS.md
+- CHANGES.md
+- CONTRIBUTING.md
+- EXAMPLES.md
+- FAQ.md
+- INSTALL.md
 - LICENSE
+- NEWS.md
 - README.md
 - Rakefile
+- SECURITY.md
+- TODO.md
+- docs/components/histogram.md
+- docs/guides/README.md
+- docs/guides/recording-and-reading-percentiles.md
+- docs/reference/README.md
+- examples/build_histogram.md
+- examples/build_histogram.rb
+- examples/measure_batch_latency.md
+- examples/measure_batch_latency.rb
 - lib/p99.rb
+- lib/p99/histogram.rb
+- lib/p99/histogram/pure.rb
 - lib/p99/version.rb
+- test/unit/tc_histogram.rb
 - test/unit/tc_version.rb
 - test/unit/ts_all.rb
 homepage: https://github.com/synesissoftware/p99.Ruby