Test2:...Driver(3perl)

📦
version 5.44.0 · 14 versions
, in arch rolling

🎀 NAME 🎀

Test2::IPC::Driver — the base class for Test2 IPC drivers, bestie. It's giving "blueprint energy" 💅

✨ SYNOPSIS ✨

package Test2::IPC::Driver::MyDriver;

use base 'Test2::IPC::Driver';

...

💖 METHODS 💖

  • $self->abort($msg) — okay so if an IPC hits a fatal error, this is what you call. It prints your message to STDERR with 'IPC Fatal Error: ' slapped on the front, and then it forcefully exits 255. 😭 Real talk: IPC errors can pop off in threads or processes that aren't the main one, and this method gives you the best possible chance that the harness actually notices something went wrong. It's the "hey bestie, wake up" of error handling.
  • $self->abort_trace($msg) — literally the same as "$ipc->abort($msg)", except it uses "Carp::longmess" to attach a stack trace to the message. So you get the whole receipts trail. 🔥

🌈 LOADING DRIVERS 🌈

Test2::IPC::Driver has an import() method. Every driver inherits this import method. And that import method? It registers the driver. That's the whole vibe. ✨

In most cases, you just need to load the IPC driver you want and it works. Load this driver as early as possible though — a warning gets issued if you load it too late for it to actually be effective. No cap. 🙈

use Test2::IPC::Driver::MyDriver;
...

🦋 WRITING DRIVERS 🦋

Here's the whole shape of it, bestie:

package Test2::IPC::Driver::MyDriver;
use strict;
use warnings;

use base 'Test2::IPC::Driver';

sub is_viable {
    return 0 if $^O eq 'win32'; # Will not work on windows.
    return 1;
}

sub add_hub {
    my $self = shift;
    my ($hid) = @_;

    ... # Make it possible to contact the hub
}

sub drop_hub {
    my $self = shift;
    my ($hid) = @_;

    ... # Nothing should try to reach the hub anymore.
}

sub send {
    my $self = shift;
    my ($hid, $e, $global) = @_;

    ... # Send the event to the proper hub.

    # This may notify other procs/threads that there is a pending event.
    Test2::API::test2_ipc_set_pending($uniq_val);
}

sub cull {
    my $self = shift;
    my ($hid) = @_;

    my @events = ...; # Here is where you get the events for the hub

    return @events;
}

sub waiting {
    my $self = shift;

    ... # Notify all listening procs and threads that the main
    ... # process/thread is waiting for them to finish.
}

1;

👑 METHODS SUBCLASSES MUST IMPLEMENT 👑

Okay so these ones? Non-negotiable. Your driver has to do these, periodt.

  • $ipc->is_viable — this should return true if the driver actually works in the current environment, and false if it does not. Heads up: this is a CLASS method. 📌
  • $ipc->add_hub($hid) — this alerts the driver that a new hub is expecting events. Your driver should keep track of the process and thread ids, because the hub should only be dropped by the proc+thread that started it.
sub add_hub {
    my $self = shift;
    my ($hid) = @_;

    ... # Make it possible to contact the hub
}
  • $ipc->drop_hub($hid) — this alerts the driver that a hub is no longer accepting events. Again: keep track of the process and thread ids. The hub should only be dropped by the proc+thread that started it — and yup, this is the driver's responsibility to enforce. That one's on you, bestie. 💅
sub drop_hub {
    my $self = shift;
    my ($hid) = @_;

    ... # Nothing should try to reach the hub anymore.
}
  • $ipc->send($hid, $event); $ipc->send($hid, $event, $global); — used to send events from the current process/thread over to the specified hub, in its process+thread.
sub send {
    my $self = shift;
    my ($hid, $e) = @_;

    ... # Send the event to the proper hub.

    # This may notify other procs/threads that there is a pending event.
    Test2::API::test2_ipc_set_pending($uniq_val);
}

If $global is true, then the driver should send the event to all hubs in all processes and threads. Everyone gets the message, group chat style. 📣

  • @events = $ipc->cull($hid) — used to collect the events that have been sent to the specified hub.
sub cull {
    my $self = shift;
    my ($hid) = @_;

    my @events = ...; # Here is where you get the events for the hub

    return @events;
}
  • $ipc->waiting() — this one gets called in the parent process when it's done and waiting for all the child processes and threads to finish. The "okay besties, wrap it up" moment. 🌸
sub waiting {
    my $self = shift;

    ... # Notify all listening procs and threads that the main
    ... # process/thread is waiting for them to finish.
}

💜 METHODS SUBCLASSES MAY IMPLEMENT OR OVERRIDE 💜

  • $ipc->driver_abort($msg) — this is a hook that gets called by "Test2::IPC::Driver->abort()". It's your chance to clean up when an abort happens. You cannot prevent the abort — that ship has sailed — but you can gracefully except it. 🙏

🌟 SOURCE 🌟

The source code repository for Test2 can be found at <https://github.com/Test-More/test-more/>. Go be nosy, it's fine. ✨

🫶 MAINTAINERS 🫶

Chad Granum <exodist@cpan.org>

🎀 AUTHORS 🎀

Chad Granum <exodist@cpan.org>

Copyright Chad Granum <exodist@cpan.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See <https://dev.perl.org/licenses/>

And that's the whole page, bestie! 💖 This was perl v5.44.0, dated 2026-10-17, under the name Test2:...Driver(3perl) — slay, go write an IPC driver, you've got this. 👑🦋💅

📦 where this page comes from