p99-ruby 0.0.1 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da3930d99a75f03beaf92509ba1f074b1b12587937a82ec6f5abdd8ee68f2d65
-  data.tar.gz: 57d5fbbcf56edfebe4ffdabc8b10378dcd6660688855bb975f13a54c20fbacb1
+  metadata.gz: 8bdde9c07f1b5d11d8e2d57e1fbc021d3115c5f574ac0b21cb9326cfa3c0f1db
+  data.tar.gz: 0b3123844e720c310a7599a0c44bcec319bbdc9ea3e23668eea825138bd4bf11
 SHA512:
-  metadata.gz: db0d21d44fb05142aa260cb5696b3f5d53dbdf6c696d09e8804b4122805337ee8e199d8215cb7690aefb4e32efccd4f30ecc2407e14cae0a9f16ac355a3854a6
-  data.tar.gz: 58eb910c50c6f7a380d30ae935421e79e31184f3ae455d3a554e75527c8740255494e14238c0da0729feaaf7d4e96b431caf72c74922cb583d43204c282949c4
+  metadata.gz: 3d38cc27f0a13cf6786940b5925d41c37cd9d509fe3bf86a72fece9112e1420b593c1321f1d1d8ec0cc895506e6cea96ccc09de733f4f82edbe4f06a4339033c
+  data.tar.gz: 80170c0a7d40cab847c2a21644c117aca97da7bc18f24b4dc2770e59e07d1b954d7f5e3a7751c094ce0f31da04e6d4936e0ca6e3dcc39181b81ff160c3d40b13

data/AUTHORS.md

@@ -0,0 +1,21 @@
+# p99.Ruby - Authors <!-- omit in toc -->
+
+
+## Major Contributors
+
+| Name        | GitHub                            |
+| ----------- | --------------------------------- |
+| Matt Wilson | [mwsis](https://github.com/mwsis) |
+
+
+## Defect reports, fixes and suggestions (for which we are very grateful)
+
+| Name        | GitHub                            |
+| ----------- | --------------------------------- |
+| \<none>     |                                   |
+
+
+Contributions are welcomed.
+
+
+<!-- ########################### end of file ########################### -->

data/CHANGES.md

@@ -0,0 +1,35 @@
+# p99.Ruby - Changes <!-- omit in toc -->
+
+
+## 0.1.0 - 30th August 2026
+
+* added pure-Ruby **P99::Histogram** (log2 buckets, push helpers, percentile queries);
+* added unit tests for Histogram behaviour;
+* added **examples/build_histogram** runnable example;
+* added **EXAMPLES.md** catalogue;
+
+
+## 0.0.1 - 28th August 2026
+
+* added `# frozen_string_literal: true` to all **lib/** sources;
+* added **AUTHORS.md**, **CONTRIBUTING.md**, **EXAMPLES.md**, **FAQ.md**,
+  **INSTALL.md**, and **SECURITY.md**;
+* added Ruby 2.0 and MinGW CI coverage, warning-mode tests, and gem
+  build/install smoke tests to **.github/workflows/ruby.yml**;
+* improved gem metadata, URL handling, and bounded the **xqsr3** development
+  dependency;
+* modernised the test runner's argument handling, library loading, and
+  Ruby-version support;
+* documented the currently available root module and version metadata in
+  **README.md**;
+* added Windows helpers and shared editor, Git, Vim, and project configuration;
+* updated **Gemfile**, **Rakefile**, and RDoc configuration for the revised
+  development workflow;
+
+
+## 0.0.0 - 4th August 2026
+
+* initial project scaffolding;
+
+
+<!-- ########################### end of file ########################### -->

data/CONTRIBUTING.md

@@ -0,0 +1,36 @@
+# p99.Ruby - Contributing <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Defects and features](#defects-and-features)
+- [Pull requests](#pull-requests)
+- [Tests](#tests)
+- [License](#license)
+
+
+## Defects and features
+
+Open an issue on https://github.com/synesissoftware/p99.Ruby/issues.
+
+
+## Pull requests
+
+Pull requests are welcome on https://github.com/synesissoftware/p99.Ruby. Keep diffs local to the change; match existing indentation (2 spaces in Ruby) and the Synesis markdown set (**README.md**, **CHANGES.md**, **NEWS.md**, **TODO.md**, **INSTALL.md**, **CONTRIBUTING.md**, **SECURITY.md**).
+
+
+## Tests
+
+```
+bundle exec rake test
+```
+
+or `./run_all_unit_tests.sh`.
+
+
+## License
+
+Contributions are accepted under the 3-clause BSD license. See [LICENSE](./LICENSE).
+
+
+<!-- ########################### end of file ########################### -->

data/EXAMPLES.md

@@ -0,0 +1,9 @@
+# p99.Ruby Examples <!-- omit in toc -->
+
+| Name | Source & Description | Summary |
+| --- | --- | --- |
+| **build_histogram** | [examples/build_histogram.rb](./examples/build_histogram.rb)<br/>[examples/build_histogram.md](./examples/build_histogram.md) | Records timed `sleep` delays under a simple PRNG into `P99::Histogram`, then prints a summary and percentile approximations (`P99_TRIES` controls iteration count) |
+| **measure_batch_latency** | [examples/measure_batch_latency.rb](./examples/measure_batch_latency.rb)<br/>[examples/measure_batch_latency.md](./examples/measure_batch_latency.md) | Measures simulated batch-operation latency with a monotonic clock, records nanoseconds, and prints fixed percentile results |
+
+
+<!-- ########################### end of file ########################### -->

data/FAQ.md

@@ -0,0 +1,28 @@
+# p99.Ruby - FAQ <!-- omit in toc -->
+
+The FAQ list is under (constant) development. If you post a question on the
+[Issues](https://github.com/synesissoftware/p99.Ruby/issues) forum
+it will be used to create one.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Q1: "How do I install this library?"](#q1-how-do-i-install-this-library)
+
+
+# FAQs: <!-- omit in toc -->
+
+
+## Q1: "How do I install this library?"
+
+Install via **gem**:
+
+```
+gem install p99-ruby
+```
+
+See [README.md](./README.md) for usage.
+
+
+
+<!-- ########################### end of file ########################### -->

data/INSTALL.md

@@ -0,0 +1,41 @@
+# p99.Ruby - Installation and Use <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Install the gem](#install-the-gem)
+- [From a source checkout](#from-a-source-checkout)
+- [Using the library](#using-the-library)
+
+
+## Install the gem
+
+```
+gem install p99-ruby
+```
+
+or add to a **Gemfile**:
+
+```Ruby
+gem 'p99-ruby'
+```
+
+then `bundle install`.
+
+
+## From a source checkout
+
+```
+bundle install
+bundle exec rake test
+```
+
+
+## Using the library
+
+```Ruby
+require 'p99'
+```
+
+
+<!-- ########################### end of file ########################### -->

data/NEWS.md

@@ -0,0 +1,10 @@
+# p99.Ruby - News <!-- omit in toc -->
+
+| Date             | News Item                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------ |
+| 30th August 2026 | [**p99.Ruby** 0.1.0](https://github.com/synesissoftware/p99.Ruby/releases/tag/0.1.0) |
+| 28th August 2026 | [**p99.Ruby** 0.0.1](https://github.com/synesissoftware/p99.Ruby/releases/tag/0.0.1) |
+| 4th August 2026  | [**p99.Ruby** 0.0.0](https://github.com/synesissoftware/p99.Ruby/releases/tag/0.0.0) |
+
+
+<!-- ########################### end of file ########################### -->

data/README.md

@@ -15,13 +15,15 @@ Low-cost generation of performance percentiles (p50, p90, p99, p99.9, etc.), for
 - [Introduction](#introduction)
 - [Installation](#installation)
 - [Components](#components)
+  - [`P99::Histogram`](#p99histogram)
+- [Examples](#examples)
 - [Project Information](#project-information)
-	- [Where to get help](#where-to-get-help)
-	- [Contribution guidelines](#contribution-guidelines)
-	- [Dependencies](#dependencies)
-		- [Development Dependencies](#development-dependencies)
-	- [Related projects](#related-projects)
-	- [License](#license)
+  - [Where to get help](#where-to-get-help)
+  - [Contribution guidelines](#contribution-guidelines)
+  - [Dependencies](#dependencies)
+    - [Development Dependencies](#development-dependencies)
+  - [Related projects](#related-projects)
+  - [License](#license)
 
 
 ## Introduction
@@ -50,7 +52,53 @@ require 'p99'
 
 ## Components
 
-**p99.Ruby** currently ships the **`P99`** root module and version metadata (`require 'p99'`). The low-overhead logarithmic histogram / percentile query surface present in the sibling **p99** libraries (fixed-size buckets, push duration, query p50 / p90 / p99 / …) is not yet implemented in this Ruby tree; see the **Related projects** links for the mature C and other-language APIs this gem is intended to mirror.
+
+### `P99::Histogram`
+
+Low-cost, fixed-size histogram for recording event durations (nanoseconds and
+common larger units) and querying high-resolution percentiles (p50, p90, p99,
+and beyond).
+
+This release provides a **pure-Ruby** implementation. A C-extension backend
+(with automatic fallback) is planned.
+
+See the [Histogram component guide](./docs/components/histogram.md) for
+loading, recording, statistics, percentile, and backend details. The
+[generated API reference](./docs/reference/README.md) provides the complete
+source-level method documentation.
+
+The [task-oriented guides](./docs/guides/README.md) provide practical
+workflows for recording and reading percentiles.
+
+```Ruby
+require 'p99'
+
+h = P99::Histogram.new
+h.push_event_time_ns(150)
+h.push_event_time_us(5)
+h.push_event_time_ms(10)
+
+h.event_count          # => 3
+h.value_at_p99         # => approximated duration in nanoseconds
+P99::IMPLEMENTATION    # => "ruby" (or "c" when a native backend is present)
+```
+
+Force the pure-Ruby backend (for debugging or CI):
+
+```bash
+P99_PURE_RUBY=1 ruby -e "require 'p99'; puts P99::IMPLEMENTATION"
+```
+
+
+## Examples
+
+See [**EXAMPLES.md**](./EXAMPLES.md) for the full list. The primary
+demonstration is [**build_histogram**](./examples/build_histogram.md):
+
+```bash
+ruby examples/build_histogram.rb
+P99_TRIES=1000 ruby examples/build_histogram.rb
+```
 
 
 ## Project Information

data/SECURITY.md

@@ -0,0 +1,22 @@
+# p99.Ruby - Security <!-- omit in toc -->
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Reporting a vulnerability](#reporting-a-vulnerability)
+- [Supported versions](#supported-versions)
+
+
+## Reporting a vulnerability
+
+Please report security issues privately via GitHub Security Advisories on https://github.com/synesissoftware/p99.Ruby/security, or by opening an issue if an advisory cannot be filed. Do not attach exploit proofs of concept against third-party systems.
+
+
+## Supported versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.0.x   | ✅        |
+
+
+<!-- ########################### end of file ########################### -->

data/TODO.md

@@ -0,0 +1,20 @@
+# p99.Ruby - TODO <!-- omit in toc -->
+
+
+## Functional improvements
+
+* [ ] C extension backend (vendored **p99**) with pure-Ruby fallback;
+
+
+## Performance improvements
+
+* \<none>
+
+
+## Packaging improvements
+
+* [ ] Optional precompiled platform gems for the C extension;
+* [x] Rename gemspec so the filename stem matches `spec.name` (`p99.gemspec` → **p99-ruby.gemspec**);
+
+
+<!-- ########################### end of file ########################### -->

data/docs/components/histogram.md

@@ -0,0 +1,116 @@
+# p99.Ruby Histogram <!-- omit in toc -->
+
+`P99::Histogram` is a fixed-size histogram for recording event durations and
+estimating high percentiles such as p50, p90, p99, and p99.9. The current
+release uses a pure-Ruby backend and stores durations in nanoseconds.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Loading](#loading)
+- [Recording durations](#recording-durations)
+- [Reading statistics](#reading-statistics)
+- [Reading percentiles](#reading-percentiles)
+- [Overflow handling](#overflow-handling)
+- [Backend selection](#backend-selection)
+
+
+## Loading
+
+Load the public entry point:
+
+```Ruby
+require 'p99'
+```
+
+This loads `P99::Histogram` and selects the available implementation. The
+active backend is available through `P99::IMPLEMENTATION`.
+
+
+## Recording durations
+
+Create an empty histogram and record durations in the supported units:
+
+```Ruby
+histogram = P99::Histogram.new
+
+histogram.push_event_time_ns(150)
+histogram.push_event_time_us(5)
+histogram.push_event_time_ms(10)
+histogram.push_event_time_s(1)
+```
+
+All recorded durations are converted to nanoseconds. Each `push_event_time_*`
+method returns `true` when the duration is accepted and `false` when it cannot
+be recorded.
+Pass an integer in the selected unit; fractional values are truncated during
+conversion.
+
+Use `clear` to reset the histogram:
+
+```Ruby
+histogram.clear
+```
+
+
+## Reading statistics
+
+The histogram exposes the number of recorded events and aggregate duration
+statistics:
+
+```Ruby
+histogram.event_count
+histogram.event_time_total
+histogram.event_time_total_raw
+histogram.min_event_time
+histogram.max_event_time
+histogram.has_overflowed?
+```
+
+The duration values are expressed in nanoseconds. The raw total is useful when
+the normal total has entered the overflow state.
+
+
+## Reading percentiles
+
+Use the named methods for common percentiles:
+
+```Ruby
+histogram.value_at_p50
+histogram.value_at_p90
+histogram.value_at_p99
+histogram.value_at_p99_9
+```
+
+For other percentile values, use `value_at_percentile` or query several
+percentiles at once with `values_at_percentiles`. `fixed_percentiles` provides
+the library's standard percentile set.
+
+The result is an approximation in nanoseconds. The implementation uses 64
+logarithmic power-of-two buckets and linearly interpolates within the selected
+bucket, so results should be treated as estimates rather than exact samples.
+
+
+## Overflow handling
+
+The histogram tracks whether the running event-time total has overflowed.
+Once an addition cannot be represented safely, subsequent duration pushes are
+rejected and `has_overflowed?` reports `true`.
+
+Call `clear` to return the histogram to its initial empty state.
+
+
+## Backend selection
+
+The loader prefers a native backend when one is available. Set
+`P99_PURE_RUBY` to force the pure-Ruby implementation:
+
+```Shell
+P99_PURE_RUBY=1 ruby -e "require 'p99'; puts P99::IMPLEMENTATION"
+```
+
+The current release reports `"ruby"` through `P99::IMPLEMENTATION`. A
+compatible C-extension backend is planned for a future release.
+
+
+<!-- ########################### end of file ########################### -->

data/docs/guides/README.md

@@ -0,0 +1,18 @@
+# p99.Ruby Guides <!-- omit in toc -->
+
+Task-oriented guidance for using **p99.Ruby**.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Guides](#guides)
+
+
+## Guides
+
+* [Recording and reading percentiles](./recording-and-reading-percentiles.md)
+  explains time units, common and custom percentile queries, approximation,
+  and empty or overflowing histograms;
+
+
+<!-- ########################### end of file ########################### -->

data/docs/guides/recording-and-reading-percentiles.md

@@ -0,0 +1,134 @@
+# p99.Ruby - Recording and Reading Percentiles <!-- omit in toc -->
+
+This guide shows how to record event durations with `P99::Histogram` and
+interpret its percentile results.
+
+
+## Table of Contents <!-- omit in toc -->
+
+- [Create a histogram](#create-a-histogram)
+- [Record event durations](#record-event-durations)
+- [Choose a time unit](#choose-a-time-unit)
+- [Read common percentiles](#read-common-percentiles)
+- [Read custom percentiles](#read-custom-percentiles)
+- [Interpret approximate values](#interpret-approximate-values)
+- [Handle empty and overflowing histograms](#handle-empty-and-overflowing-histograms)
+
+
+## Create a histogram
+
+Require the library and create an empty histogram:
+
+```Ruby
+require 'p99'
+
+histogram = P99::Histogram.new
+```
+
+The histogram has a fixed 64-bucket storage model, so its memory use does not
+grow with the number of recorded events.
+
+
+## Record event durations
+
+Record each completed operation as an event. Select the method whose suffix
+matches the unit of the duration:
+
+```Ruby
+histogram.push_event_time_ns(database_time_ns)
+histogram.push_event_time_us(cache_time_us)
+histogram.push_event_time_ms(request_time_ms)
+histogram.push_event_time_s(batch_time_s)
+```
+
+Each method converts its argument to nanoseconds. A successful push returns
+`true`; an invalid duration or a duration rejected after overflow returns
+`false`.
+
+
+## Choose a time unit
+
+Use the unit that matches the value already produced by the measuring code:
+
+* Use nanoseconds for APIs that already report high-resolution monotonic time;
+* Use microseconds or milliseconds when those are the native measurement units;
+* Use seconds for coarse-grained operations or externally supplied durations;
+
+The stored and returned values are always nanoseconds, regardless of the input
+method used.
+
+
+## Read common percentiles
+
+Read the percentile that matches the question being asked:
+
+```Ruby
+p50  = histogram.value_at_p50
+p90  = histogram.value_at_p90
+p99  = histogram.value_at_p99
+p999 = histogram.value_at_p99_9
+```
+
+For example, p99 is useful when the slowest one percent of observations
+matters. A percentile result is expressed in nanoseconds.
+
+The fixed set can be read as a hash:
+
+```Ruby
+histogram.fixed_percentiles
+# => { "p50" => ..., "p75" => ..., "p90" => ..., "p99" => ... }
+```
+
+
+## Read custom percentiles
+
+Use `value_at_percentile` for one custom level:
+
+```Ruby
+histogram.value_at_percentile(99.5)
+```
+
+Use `values_at_percentiles` when several levels are needed:
+
+```Ruby
+histogram.values_at_percentiles([ 50.0, 90.0, 99.0, 99.9 ])
+# => [ [50.0, ...], [90.0, ...], [99.0, ...], [99.9, ...] ]
+```
+
+Percentiles are expressed as values from 0.0 to 100.0. Values outside that
+range are clamped to the nearest endpoint.
+
+
+## Interpret approximate values
+
+`P99::Histogram` uses 64 logarithmic power-of-two buckets and linearly
+interpolates within the bucket containing the requested rank. Results are
+therefore estimates, not exact values from a retained sample set.
+
+Use the histogram for stable operational summaries and comparisons. If exact
+sample retrieval or arbitrary quantile algorithms are required, use a data
+structure designed to retain or sort the individual observations.
+
+
+## Handle empty and overflowing histograms
+
+Percentile and minimum/maximum queries return `nil` for an empty histogram:
+
+```Ruby
+histogram.value_at_p99       # => nil
+histogram.min_event_time     # => nil
+histogram.max_event_time     # => nil
+```
+
+`event_time_total` returns `nil` after the running total overflows. Use
+`event_time_total_raw` to inspect the accumulated value and
+`has_overflowed?` to check the overflow state. Rejected pushes return `false`.
+
+Call `clear` to reset the histogram and begin a new measurement interval:
+
+```Ruby
+histogram.clear
+```
+
+
+<!-- ########################### end of file ########################### -->

data/docs/reference/README.md

@@ -0,0 +1,39 @@
+# p99.Ruby Generated API Reference <!-- omit in toc -->
+
+The generated API reference is produced by RDoc from the Ruby source
+documentation comments. It complements the authored Histogram documentation:
+
+* [`docs/components/histogram.md`](../components/histogram.md) explains the
+  component's loading, recording, statistics, percentile, and backend APIs;
+* generated `doc/` explains the complete public Ruby API;
+
+
+## Generate the reference
+
+From the project directory, run:
+
+```Shell
+./generate_rdoc.sh
+```
+
+The script removes previous generated output and writes the new reference to
+`doc/` by default. Use `--pwd` to operate in the caller's current directory,
+or set `SIS_RDOC_DOC_DIR` to choose another generated-document directory.
+Generated files are build output and should not be edited by hand.
+
+To check that every documentable API entity has RDoc documentation, run:
+
+```Shell
+./generate_rdoc.sh --coverage-report
+```
+
+
+## Reading the reference
+
+Use the generated namespace and method pages for exact signatures and
+source-level API details. Start with the authored component documentation when
+deciding how to use `P99::Histogram`, then use RDoc to inspect the complete
+method surface.
+
+
+<!-- ########################### end of file ########################### -->

data/examples/build_histogram.md

@@ -0,0 +1,57 @@
+# p99.Ruby Example - **build_histogram**
+
+## Summary
+
+Example illustrating use of `P99::Histogram` to record event durations
+generated by `sleep` delays under a simple PRNG, then print a histogram
+summary and percentile values.
+
+
+## Source
+
+See [build_histogram.rb](./build_histogram.rb).
+
+
+## Execution
+
+The number of iterations can be configured via the `P99_TRIES` environment
+variable:
+
+```bash
+# Run with the default of 100 tries
+ruby examples/build_histogram.rb
+
+# Run with 1000 tries
+P99_TRIES=1000 ruby examples/build_histogram.rb
+```
+
+
+## Representative output
+
+The timing values vary by machine and scheduler. A short run produces output
+like:
+
+```text
+Running Histogram example with 3 tries...
+(backend: ruby)
+
+Histogram summary:
+Histogram{
+  implementation:   ruby
+  event_count:      3
+  event_time_total: 1713000
+  has_overflowed:   false
+  min_event_time:   319000
+  max_event_time:   782000
+  buckets:          {18: 1, 19: 2}
+}
+
+Percentiles (approximated):
+  p50 (f64):         655360 ns
+  p50 (integer):     524287 ns
+  p75 (integer):     782000 ns
+  p99 (integer):     782000 ns
+```
+
+
+<!-- ########################### end of file ########################### -->