/ 
Algorithm-EventsPerSecond-0.0.1
/ Algorithm::EventsPerSecond

NAME

Algorithm::EventsPerSecond - A sliding-window events-per-second rate counter with a optional XS backend for additional zoomies.

VERSION

Version 0.0.1

SYNOPSIS

use Algorithm::EventsPerSecond;

my $meter = Algorithm::EventsPerSecond->new( window => 10 );  # 10-second window

while (my $event = get_next_event()) {
    $meter->mark;                 # record one event
    # $meter->mark(5);            # or record several at once

    printf "current rate: %.2f events/sec\n", $meter->rate;
}

print "events seen in window: ", $meter->count, "\n";
print "lifetime total:        ", $meter->total, "\n";

DESCRIPTION

Algorithm::EventsPerSecond keeps per-second counts in a fixed-size ring buffer and reports the average event rate over the most recent N seconds (the "window"). Memory use is constant regardless of event volume, and both mark and rate are O(1) averaged out over time.

METHODS

new( window => $seconds )

Construct a meter. window is the length of the averaging window in seconds and defaults to 60.

mark( [$count] )

Record one event, or $count events. Returns the meter object, so calls can be chained.

count

Number of events recorded within the current window.

rate

Average events per second over the window. If the meter has been alive for less time than the window, the elapsed lifetime is used instead, so early readings are not artificially deflated.

total

Lifetime count of all events ever recorded, regardless of window.

window

The configured window length in seconds.

reset

Clear all counts and restart the clock. Returns the meter object.

backend

Returns 'XS' when the accelerated backend is in use, 'PP' for the pure Perl fallback. May be called as a class or instance method.

simd

Returns which SIMD flavor the XS backend was compiled with: 'AVX2', 'SSE4.2', or 'scalar' (plain C, left to the compiler's auto-vectorizer). Returns undef when the pure Perl backend is in use.

ACCELERATION

If a working C compiler is available at install time, an accelerated XS backend, Algorithm::EventsPerSecond::XS, is built and loaded automatically. It keeps the ring buffer in packed int64_t buffers and scans the window in C, using SIMD (AVX2 or SSE4.2) when the compiler targets a CPU that has it. If the backend cannot be loaded for any reason (not built, no compiler at install time), a pure Perl implementation with identical behavior is used instead.

The following control this.

IF_OPT

Environment variable read by Makefile.PL: the -O optimization value used when compiling the XS backend during install. IF_OPT=2 (or IF_OPT=-O2) compiles with -O2. The default is -O3.

IF_ARCH

Environment variable read by Makefile.PL: optionally sets the architecture used for the build during the install. IF_ARCH=native (or IF_ARCH=-march=native) compiles with -march=native, enabling the SIMD paths the build host supports. When unset the compiler's baseline architecture is used.

PUREPERL_ONLY

perl Makefile.PL PUREPERL_ONLY=1 skips building the XS backend.

ALGORITHM_EVENTSPERSECOND_PP

Environment variable read at runtime: when true, skip the XS backend entirely and use pure Perl.

Which backend is in use can be checked via "backend" and "simd".

AUTHOR

Zane C. Bowers-Hadley, <vvelox at vvelox.net>

BUGS

Please report any bugs or feature requests to bug-algorithm-eventspersecond at rt.cpan.org, or through the web interface at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=Algorithm-EventsPerSecond. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Algorithm::EventsPerSecond

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

This software is Copyright (c) 2026 by Zane C. Bowers-Hadley.

This is free software, licensed under:

The GNU Lesser General Public License, Version 2.1, February 1999