Test2::IPC::Driver(3)

📦 version 1.302214, in opensuse-leap 16.0

hi bestie 💖 welcome to the Test2::IPC::Driver(3) page — it's part of User Contributed Perl Documentation. buckle up, because this is the base-class tea for Test2 IPC drivers, and it's lowkey iconic.

✨ NAME ✨

Test2::IPC::Driver — the base class for Test2 IPC drivers. periodt. 👑

🌸 SYNOPSIS 🌸

okay so if you're making your own driver, the starter shape is literally this:

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

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

...

slay, that's the vibe. 💅

💅 METHODS 💅

  • $self->abort($msg) — bestie, this is the emergency button 🚨. If an IPC hits a fatal error, it should call this. It prints your message to STDERR with the exact prefix 'IPC Fatal Error: ' stuck in front, then it forcefully exits with status 255. IPC drama can happen in threads or processes that are not the main one, and this method gives the harness the best chance of noticing the error. no cap.
  • $self->abort_trace($msg) — same energy as "$ipc->abort($msg)", except it uses "Carp::longmess" to add a stack trace to the message. so you get the receipts 📜✨.

🦋 LOADING DRIVERS 🦋

Test2::IPC::Driver has an import() method, and all drivers inherit it. That import() method is the thing that registers the driver. iykyk.

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

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

🎀 WRITING DRIVERS 🎀

here's the full skeleton, bestie — this is giving starter pack and it ate:

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 🫶

  • $ipc->is_viable — this one is a CLASS method, bestie, don't forget. It should return true if the driver actually works in the current environment, and false if it doesn't. vibe check for the whole driver. ✅
  • $ipc->add_hub($hid) — tells the driver that a shiny new hub is expecting events. The driver should keep track of the process and thread ids, because the hub should only be dropped by the proc+thread that started it. main character boundary rules. 👑
sub add_hub {
    my $self = shift;
    my ($hid) = @_;

    ... # Make it possible to contact the hub
}
  • $ipc->drop_hub($hid) — tells the driver that a hub is no longer accepting events. Again, the driver should keep track of the process and thread ids, and the hub should only be dropped by the proc+thread that started it. enforcing that is the driver's responsibility, fr fr.
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 to the specified hub, in its process+thread. here's the shape:
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. that's the "everybody gets a notification" moment 💌.

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

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

    return @events;
}
  • $ipc->waiting() — called in the parent process when it's complete and waiting for all child processes and threads to complete. so everyone knows the main process/thread is in its waiting era. ⏳
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 called by "Test2::IPC::Driver->abort()". It's your chance to clean up when an abort happens. You cannot prevent the abort, but you can gracefully except it. (yes, that's the wording — keep it cute, keep it accurate 🫶)

🌈 SOURCE 🌈

The source code repository for Test2 lives at <https://github.com/Test-More/test-more/>. go be nosy, bestie. 🔍✨

⭐ 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/>.

byeee bestie 💖 this page is from perl v5.42.0, dated 2025-07-28, and it's the Test2::IPC::Driver(3) page. mwah 💋✨

📦 where this page comes from