Heap::PQ — A Binary Heap (Priority Queue) Implementation for Perl

dev.to #perl by LNATION Tuesday 07 April 2026 07:09

So What Is A Binary Heap?

A binary heap is really just an sorted array pretending to be a tree. Each element has a parent and children, but instead of pointers you find them with simple array indexes. The trick is that every parent follows one rule relative to its children, and that rule decides what kind of heap you get:

Min heap - every parent is less than or equal to its children. The smallest element always lives at the root/top.
Max heap - every parent is greater than or equal to its children. The largest element always lives at the root/top.

Because the tree is complete, the parent of element at index i sits at index floor((i−1)/2), and its children sit at 2i+1 and 2i+2. No pointers, no linked lists — just arithmetic on array indices. That cache friendly layout is one reason heaps are so fast in practice.

The key operations:

Operation	Time	What it does
push	O(log n)	Insert a value, then sift it up to restore order
pop	O(log n)	Remove the root, move the last element up, sift down
peek	O(1)	Read the root without removing it
make_heap	O(n)	Turn an existing unsorted array into a valid heap (`make_heap_min` / `make_heap_max`, `new('min')`, `new('max')`)

This makes a heap the natural backbone of a priority queue — a collection where you always want the next most important item and you need insertions to stay fast.

Why Heap::PQ?

Heap::PQ brings binary heaps to Perl as a C extension. Where a pure Perl heap tops out around 300 operations per second, Heap::PQ's functional interface clocks over 11,000 when pushing a 1000 random integers — and if you are just handling plain integers then there is an optimised NV heap implementation that squeezes out 50% more performance. It ships with three interfaces (object oriented, functional custom ops or a raw array) so you can trade readability for throughput depending on what your code needs.

Installation

cpanm Heap::PQ

Getting Started

Create a heap, push values in, and they come back out in priority order:

use Heap::PQ;

my $pq = Heap::PQ::new('min');

$pq->push(5);
$pq->push(1);
$pq->push(3);

print $pq->peek, "\n";  # 1 — the smallest value is always at the root

while (!$pq->is_empty) {
    print $pq->pop, "\n";  # 1, 3, 5
}

Switch to 'max' and the largest element comes out first instead.

Three Ways to Use It

OO Interface

The object oriented API is the clearest to read if you're a traditional perl developer that likes OO. push returns the heap so calls can be chained:

my $heap = Heap::PQ::new('min');
$heap->push(10)->push(20)->push(5);
$heap->push_all(8, 2, 15);

my $top = $heap->pop;    # 2
my $size = $heap->size;  # 5

Functional Interface

Import with 'import' and Heap::PQ installs heap_push, heap_pop, heap_peek, heap_size, and heap_is_empty as custom ops. Perl compiles them down to optimised opcodes so there is no method dispatch overhead at runtime:

use Heap::PQ 'import';

my $h = Heap::PQ::new('min');

heap_push($h, 42);
heap_push($h, 7);

my $val  = heap_pop($h);      # 7
my $size = heap_size($h);     # 1
my $top  = heap_peek($h);     # 42

This is the fastest path as stated functional custom ops removes the method->dispatch overhead.

Raw Array Interface

You can also operate directly on a Perl array. Import with 'raw' to get make_heap_min, push_heap_min, pop_heap_min (and their _max counterparts). This skips the object entirely but the functional interface is still faster thanks to custom op optimisation:

use Heap::PQ 'raw';

my @data = (9, 4, 7, 1, 3);
Heap::PQ::make_heap_min(\@data);  # O(n) heapify in place

my $min = Heap::PQ::pop_heap_min(\@data);   # 1
Heap::PQ::push_heap_min(\@data, 2);

No object, no opaque struct — just an array whose layout satisfies the heap property. Useful when you already have data in an array and want to avoid copying it.

Custom Comparators

By default the heap compares values numerically. Pass a code reference as a second argument to new and you can heap order anything — hash references, objects, strings:

my $tasks = Heap::PQ::new('min', sub {
    $a->{due} <=> $b->{due}
});

$tasks->push({ name => 'Write tests',  due => 3 });
$tasks->push({ name => 'Ship release', due => 5 });
$tasks->push({ name => 'Fix bug',      due => 1 });

while (!$tasks->is_empty) {
    my $t = $tasks->pop;
    print "$t->{name}\n";
}
# Fix bug
# Write tests
# Ship release

The comparator receives two elements in $a and $b — exactly like Perl's sort — and should return a negative, zero, or positive value. String ordering works the same way:

my $alpha = Heap::PQ::new('min', sub { $a cmp $b });
$alpha->push_all('banana', 'apple', 'cherry');
print $alpha->pop, "\n";  # apple

Key Path Comparators

When your heap contains hash references and you just want to compare by a numeric field, pass the field name as a string instead of a code reference. The comparison happens entirely in C — no Perl callback overhead at all:

my $tasks = Heap::PQ::new('min', 'priority');

$tasks->push({ name => 'Write tests',  priority => 3 });
$tasks->push({ name => 'Ship release', priority => 5 });
$tasks->push({ name => 'Fix bug',      priority => 1 });

while (!$tasks->is_empty) {
    my $t = $tasks->pop;
    print "$t->{name}\n";
}
# Fix bug
# Write tests
# Ship release

Dot separated paths reach into nested hashes:

my $heap = Heap::PQ::new('min', 'meta.score');
$heap->push({ id => 'a', meta => { score => 42 } });
$heap->push({ id => 'b', meta => { score => 17 } });
print $heap->pop->{id};  # 'b'

The key is extracted once when you push, so sift operations run at the same speed as a plain numeric heap. In benchmarks, key path heaps match the no-comparator path (~6,400/s) while custom Perl comparators top out around ~1,200/s — a 5× difference.

NV Heaps — Native Doubles, No SV Overhead

When every value is a number, new_nv stores them as raw C doubles instead of Perl scalars. That eliminates SV allocation and reference counting entirely:

my $h = Heap::PQ::new_nv('min');
$h->push_all(3.14, 2.71, 1.41, 1.73);
print $h->pop, "\n";  # 1.41

In benchmarks the NV heap runs roughly 1.5× faster than the functional interface for push heavy workloads, and nearly 57× faster than pure Perl.

Searching and Deleting

Both search and delete accept a callback that receives each element in $_. search returns matching elements; delete removes them and returns how many were dropped:

my $pq = Heap::PQ::new('min');
$pq->push_all(1, 5, 10, 15, 20, 25);

# Find all elements greater than 12
my @big = $pq->search(sub { $_ > 12 });
# @big = (15, 20, 25)

# Remove them from the heap
my $removed = $pq->delete(sub { $_ > 12 });
# $removed = 3, heap now contains (1, 5, 10)

After a delete, Heap::PQ rebuilds the heap in O(n) with Floyd's algorithm so the ordering invariant is always intact.

Peeking at the Top N

peek_n returns the top N elements in sorted order without removing them:

my $scores = Heap::PQ::new('max');
$scores->push_all(88, 95, 72, 99, 84, 91);

my @top3 = $scores->peek_n(3);  # (99, 95, 91)
# Heap is unchanged — still has all 6 elements

peek_n works with the heap's built-in numeric comparison, so it is best suited to plain numeric heaps. For heaps that use a custom comparator, pop and re-push to inspect the top N.

Putting It Together: An Event Scheduler

A priority queue is a natural fit for an event loop — push events with a timestamp, pop them in chronological order:

use Heap::PQ 'import';

my $scheduler = Heap::PQ::new('min', 'time'); # compare by the 'time' key in C

heap_push($scheduler, { time => 1712500800, action => 'start_server' });
heap_push($scheduler, { time => 1712497200, action => 'load_config' });
heap_push($scheduler, { time => 1712504400, action => 'open_connections' });
heap_push($scheduler, { time => 1712502600, action => 'warm_cache' });

while (!heap_is_empty($scheduler)) {
    my $event = heap_pop($scheduler);
    printf "t=%d  %s\n", $event->{time}, $event->{action};
}

# t=1712497200  load_config
# t=1712500800  start_server
# t=1712502600  warm_cache
# t=1712504400  open_connections

Benchmarks

All numbers below are from pushing 1,000 random integers then popping them all, measured with Benchmark:

Implementation	Rate	vs Pure Perl
Pure Perl	305/s	—
Custom comparator	1,194/s	4x
Array::Heap	6,087/s	20x
Heap::PQ OO key path	6,359/s	21x
Heap::PQ OO	6,685/s	22x
Heap::PQ raw	8,665/s	28x
Heap::PQ func	11,416/s	37x
Heap::PQ NV	16,747/s	55x

The custom op overhead reduction is clearly visible in the functional row, and the NV heap's custom op implementation plus avoidance of SV allocation pushes throughput higher still.

If you have any questions please do comment.

A Side note: I'm currently on look out for a new contract or permanent opportunity. If you know of any relevant openings, I'd appreciate hearing from you - email@lnation.org

Yet Another CLI framework

IncludeIf: A digital space written in pencil Tuesday 07 April 2026 01:34

TL;DR

Searching for CLI modules on MetaCPAN returns 1690 results. And still I wrote another, Yet Another CLI framework. This is about why mine is the one you want to use.

Introduction

CLI clients, we all write them, we all want them, but the boilerplate is just horrible. I wanted to get rid of it: Burn it with 🔥.

At my previous dayjob we had something I wrote, or co-wrote, my boss wanted a sort of chef like API. It became zsknife, but had a huge downside. You needed to register each command in the main module and I didn’t like that at all. I forked the concept internally, made it so you didn’t needed to register, but it lacked discovery.

This week in PSC (220) | 2026-04-06

blogs.perl.org by Perl Steering Council Monday 06 April 2026 21:44

We were all present.

We noted that core team membership votes are concluding on this day.
We are waiting for voting to conclude before we kick off the discussion about an LLM policy.
Release blocker triage continues. We are now fully caught up and marked a few more issues as blockers – all of them minor.
We unmarked several issues as blockers and marked #23131 as such instead, because it was the root cause for them all. We then spent a long time deliberating what to do about it and debating approaches. We have not reached a conclusion yet and will be keeping an eye on it.

[P5P posting of this summary]

Sync Pod-Simple-1.48 into blead

Perl commits on GitHub by khwilliamson Monday 06 April 2026 15:38

Sync Pod-Simple-1.48 into blead

From Changelog:

3.48 2026-04-05
        - Add sections to manpage URLs  Peter Oliver++
        - Better fallback when no HTML::Entities  Tomasz Konojacki++
        - Don't call each on an anonymous hash  Niko Tyni++
        - Fix encoding of Unicode URL fragments  Graham Knop++

Fix documentation: specify when foreach iterates an array directly

Perl commits on GitHub Monday 06 April 2026 15:17

Fix documentation: specify when foreach iterates an array directly

If the list contains more than a single array, it copies the values,
so no confusion happens.

what's a good functional language for someone coming from perl?

Perl questions on StackOverflow by tungstengmd Monday 06 April 2026 12:06

We're avid Perl programmers but we have been really wanting to get into Haskell or Erlang or something similar, though we don't know where to start. Any languages you guys recommend? if so, send some good tutorials [or give us a rundown yourself :>]

We must add that we're looking for pure-ish functional languages. Lisp syntax doesn't really sit right with us either so we don't really wish to use those.

edit [2026-04-05]: clarified why we don't accept lisp languages as suggestions

Perlweekly #767 - Rust and Perl

r/perl by /u/Itcharlie Monday 06 April 2026 11:39

https://perlweekly.com/archive/767.html

submitted by /u/Itcharlie
[link] [comments]

Learning XS - Sharing Reusable C Headers Between Perl XS Distributions

r/perl by /u/briandfoy Monday 06 April 2026 11:31

Learning XS - Sharing Reusable C Headers Between Perl XS Distributions

submitted by /u/briandfoy
[link] [comments]

Perl 🐪 Weekly #767 - Rust and Perl

dev.to #perl by Gabor Szabo Monday 06 April 2026 05:55

Originally published at Perl Weekly 767

Hi there!

It was interesting to see how Rust started to eat Python from the inside out. Several Python modules and stand-alone tools were rewritten in Rust. Now as I can see there started to be a movement in Perl as well to rewrite some parts in Rust (e.g. PDL). Very interesting.

People quite often ask me how could they find a job? Given that I have been self-employed providing training and contract development work, I don't have a lot of experience in job-hunting, but it seems if you can show your programming, creative, and learning capabilities then you will have a better chance landing a new job. So I recommend that people build some interesting open source project or contribute to some projects. I am mentioning this as I just saw an article about Chandra: Cross-Platform Desktop GUIs in Perl by Robert Acock and at the end of the article he mentions that he is looking for new opportunities. IMHO building new stuff and talking (or writing) about it creates a lot more opportunities in getting a job than only complaining about the lack of jobs. Good luck!

If talking about contribution, probably one of the easiest thing to contribute is a test. It is also way more valuable than many people might think. If you'd like to contribute to an open source Perl project: 1. clone its source code; 2. Generate test coverage report; 3. Find the holes in the tests and write a test. Then repeat. If you are unsure how to do this, luckily the "Testing in Perl" course I am teaching these days will help you. Last time we saw how to generate and interpret test coverage reports. Next time we'll also see how to do mutation testing. You can watch the recordings from the previous sessions (free of charge for 10 more days) and you can join our next live session.

Enjoy Passover, Easter and the rest of your week!

--
Your editor: Gabor Szabo.

Articles

PDL in Rust -- A Native Reimplementation of the Perl Data Language

Very interesting that more of Perl gets a Rust reimplementation.

Chandra: Cross-Platform Desktop GUIs in Perl

"Chandra is a Perl module that lets you build cross-platform desktop applications using the web technologies you already know - HTML, CSS, and JavaScript - while keeping your application logic in Perl.". Sounds interesting to see where it goes.

Introducing Object::Proto — A Prototype Object System for Perl

Manage the health of your CLI tools at scale

"Your services have dashboards, tracing, and alerting. Your CLI tools print to STDOUT and exit. When something breaks, debugging starts at the API gateway -- everything upstream is a black box. This makes no sense."

Discussion

Activity streams library/module for Perl

Perl

This week in PSC (219) | 2026-03-30

The Weekly Challenge

The Weekly Challenge by Mohammad Sajid Anwar will help you step out of your comfort-zone. You can even win prize money of $50 by participating in the weekly challenge. We pick one champion at the end of the month from among all of the contributors during the month, thanks to the sponsor Marc Perry.

The Weekly Challenge - 368

Welcome to a new week with a couple of fun tasks "Make it Bigger" and "Big and Little Omega". If you are new to the weekly challenge then why not join us and have fun every week. For more information, please read the FAQ.

RECAP - The Weekly Challenge - 367

Enjoy a quick recap of last week's contributions by Team PWC dealing with the "Max Odd Binary" and "Conflict Events" tasks in Perl and Raku. You will find plenty of solutions to keep you busy.

Max Conflict

Arne demonstrates how Raku can help with the "Max Conflict" problem using Raku's built-in support for intervals and sets. By using Raku's expressive syntax (like ranges and Bags), Raku has created an easy-to-read and mathematically intuitive way to solve problems that involve overlapping data.

Overlapping Oddities

The post contains an excellent technical breakdown of both terms using Perl programming language, along with the associated edge cases, such as how to handle timings that cross over midnight using modular arithmetic to resolve them. Additionally, his benchmark testing for different ways to manipulate binary strings provides measurable, statistical data on the efficiency of these algorithms.

Odd Events

The post explores time-interval logic and complexities of "wrap-around" (i.e., time zone?) events in a mathematically rigorous and fascinating way. Specifically, by introducing the idea of "complementary" events and making use of an ingenious duration-sum inequality, he presents an elegant, universal formula for simplifying conflict detection across the Perl and J programming languages.

The Weekly Challenge 367

The post provides a very pragmatic and functional dual language reference to assist in solving PWC 367. He uses string replication to solve the binary operation task and provides a simple mathematical overlap condition $max(start1, start2) < min(end1, end2)$ for the scheduling task. Therefore his post shows readers how to write readable, fast and efficient code in Perl and Python.

overlapping intervals

The article provides a flexible technical overview of PWC 367: Solutions to the two tasks implemented in both Raku and PL/Perl for PostgreSQL (PostgreSQL's Procedural Language/Perl). He presents Raku as a convenient and efficient way of working with high-level string and array operations to concisely solve the binary and interval task while at the same time illustrating how database-level functions can be written using the same logical patterns as the ones he used for both the Raku and PL/Perl implementations of the two tasks.

Perl Weekly Challenge 367

This is a perspective piece reviewing the problems faced in physics, providing elegant one-liners using Perl and/or robust scripts. In particular, solution to events happening at "Conflicting Events" is unique in that he treats time as a circular interval and takes offsets of + or -1440 minutes so that he can accurately determine whether two events overlap even if one of the events crosses the boundary of midnight by using the degree of circularity. This demonstrates an extensive application of mathematics to derive the proper ways to schedule events over time.

Odd Conflicts

The post demonstrates his focus on maintaining clean code and code maintainability. The use of meaningful variable names and decomposing the time conversion into logical sub-steps allowed him to take a potentially complicated problem of overlapping time zones and present it in a clear and concise manner via a mathematically sound Perl implementation.

Conflicting Every Odd

The post offers a great demonstration of multi-language support for PWC 367, using Raku, Perl, Python, and Elixir to provide solutions. The technical review is particularly good at comparing different programming language techniques and how each can be uniquely applied to provide elegant and precise solutions for string manipulation and scheduling conflicts using Elixir's pattern matching and Raku's dynamic coercion as examples of differences between the languages.

Bits of conflicts

The post features a very well thought out, extensive solution in Perl that uses string multiplication to create the largest odd binary number. He gives us a lin2dec utility that helps validate his solutions. He also provides an excellent explanation of the underlying mathematical principles behind the task he has undertaken.

The Weekly Challenge - 367: Max Odd Binary

The post gives a very complete and well supported solution to the "Max Odd Binary" challenge using Perl, using the principles of defensive programming, through good input validation. The way he technically describes his solution is very helpful since he is able to explain perl specific idioms such as tr///, and also provide good alternatives to count bits when using safe and/or optimised methods so that your code will not fail.

The Weekly Challenge - 367: Conflict Events

The second task solution provides a consistent, well-understood and detailed Perl implementation for identifying conflicting events by accentuating how to process time-based intervals that cross midnight boundaries. The use of a simple mathematical representation (normalisation of times to minutes), and an efficient "shift" loop to address the next day results in an exceptional algorithm that greatly simplifies complex overlapping logic.

The Weekly Challenge #367

The thoughtful way Robbie highlights some of the ambiguity surrounding date-less times in the "Conflict Events" task. By specifically stating what the assumption of "next-day" means for events that occur before a reference time, he offered a reasonable basis upon which to solve for overlaps between intervals of time that is both mathematically accurate and practically viable.

Binary Conflict

The includes solutions in both the Raku and Crystal languages. The way he solves Task#2 is particularly interesting because of how he looks at quantising time; by looking at events as ranges of minutes and splitting events that span midnight into two spans, he has developed a very mathematically sound and clean way to check for non-emptiness of intersecting intervals.

Maximum conflict

Simon Green used the Perl and Python programming language to produce solutions for Task 1 and Task 2. One of Simon's solutions was for the "Conflict Events" problem and it is very good because he used the range objects provided in Python, and generated individual minutes using sets, to determine where there are overlaps by tracking through time; his method provides a good way of handling events that cross over to another day.

Weekly collections

NICEPERL's lists

Great CPAN modules released last week;
MetaCPAN weekly report.

Event reports

Koha Hackfest 2026 in Marseille

Events

Perl Maven online: Testing in Perl - part 3

April 9, 2026

Perl Maven online: Testing in Perl - part 4

April 16, 2026

Perl Toolchain Summit 2026

April 23-26, 2026

The Perl and Raku Conference 2026

June 26-29, 2026, Greenville, SC, USA

You joined the Perl Weekly to get weekly e-mails about the Perl programming language and related topics.

Want to see more? See the archives of all the issues.

Not yet subscribed to the newsletter? Join us free of charge!

(C) Copyright Gabor Szabo
The articles are copyright the respective authors.

Writing Maintainable Perl: Breaking the "Write-Only" Stereotype

r/perl by /u/swe129 Monday 06 April 2026 03:27