Test::Stream::IPC(3)

📦
version 1.302027 · 2 versions
, in fedora 43

🦋 Test::Stream::IPC(3) 🦋

okay so welcome to the manual page for Test::Stream::IPC, a piece of User Contributed Perl Documentation. It's the base class energy that every Test::Stream IPC driver inherits from. Grab a snack, bestie, we're reading the whole thing. 🍓

✨ NAME ✨

Test::Stream::IPC — the base class for all the Test::Stream IPC drivers. It's giving "everyone's parent." 👑

💀 DEPRECATED 💀

Not me being the bearer of bad news but this distribution is deprecated in favor of Test2, Test2::Suite, and Test2::Workflow.

fr fr, deprecated. If you need to move over, there's a conversion guide waiting for you at Test::Stream::Manual::ToTest2. Go read it, I believe in you. 🫶

🌈 SYNOPSIS 🌈

Want your own driver? It starts like this, no cap:

package Test::Stream::IPC::MyDriver;

use base 'Test::Stream::IPC';

...

That's it, that's the whole vibe check.</purl> — okay that's the whole vibe. ✨

👑 CLASS METHODS 👑

  • @drivers = $class->drivers — gives you back the list of drivers that have been registered, in the exact order they were registered. And if literally no driver has been loaded yet? It'll load, register, and hand you Test::Stream::IPC::Files. Iconic default behavior.
  • $class->register_driver($DRIVER) — this is an alias to register_driver. Yes bestie, it's an alias to itself, I don't make the rules, I just report them. 😭
  • $class->register_drivers($DRIVER1, $DRIVER2) — use this to register an IPC driver. The driver should already be loaded before you do. Load first, register second. Order matters, periodt.
  • $class->enable_polling — this turns on IPC polling. Essentially it adds a global callback on context initialization, so every single time a context is obtained from Test::Stream::Context, the IPC driver gets a chance to poll for pending events. obsessed with the hustle 💅
Important: this can only be turned on once, and it can not be turned off. The effects are global. No takebacks, no undo, no ctrl+z. 🙈

💅 INSTANCE METHODS 💅

  • $self->abort($msg) — if an IPC hits a fatal error, this is the move. It prints the message to STDERR with 'IPC Fatal Error: ' prefixed onto it, then it forcefully exits 255. IPC errors can happen in threads or processes that aren't the main one, so this method gives you the best possible chance that the harness actually notices the error. Dramatic exit, but make it useful. 🚨
  • $self->abort_trace($msg) — same thing as $ipc->abort($msg), except it uses Carp::longmess to add a stack trace to the message. Receipts included. 🧾

🧚 LOADING DRIVERS 🧚

Test::Stream::IPC has an import() method, and all drivers inherit that import method. That import method is what registers the driver with the main IPC module.

In most cases you literally just need to load the IPC driver you want and it works. Load it as early as possible, bestie. If you load it too late for it to actually be effective, you'll get a warning. She will let you know.

use Test::Stream::IPC::MyDriver;
...

🔥 WRITING DRIVERS 🔥

Okay this is the part where you build your own. main character energy only. ✨

package Test::Stream::IPC::MyDriver;
use strict;
use warnings;

use base 'Test::Stream::IPC';

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) = @_;

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

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 🌸

These aren't optional, bestie. These are the whole assignment. 💖

  • $ipc->is_viable — should return true if the driver works in the current environment, and false if it doesn't. This one is a CLASS method. Don't forget that part. ⭐
  • $ipc->add_hub($hid) — used to alert the driver that a new hub is expecting events. 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. 🫶
sub add_hub {
    my $self = shift;
    my ($hid) = @_;

    ... # Make it possible to contact the hub
}
  • $ipc->drop_hub($hid) — used to alert the driver that a hub is no longer accepting events. Same deal: 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. (This is the driver's responsibility to enforce — nobody else is gonna do it for you.)
sub drop_hub {
    my $self = shift;
    my ($hid) = @_;

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

    ... # Send the event to the proper hub.
}
  • @events = $ipc->cull($hid) — used to collect the events that have been sent to the specified hub. Gather round, events. 🌈
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 complete and waiting for all the child processes and threads to finish. The "waiting for everyone to get in the car" moment. 🚗
sub waiting {
    my $self = shift;

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

📚 SOURCE 📚

The source code repository for Test::Stream lives right here, bestie:

http://github.com/Test-More/Test-Stream/

Go star it, it's free. ⭐

👑 MAINTAINERS 👑

Chad Granum <exodist@cpan.org>

💜 AUTHORS 💜

Chad Granum <exodist@cpan.org>

Copyright 2015 Chad Granum <exodist7@gmail.com>.

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

See http://dev.perl.org/licenses/

okay and that's a wrap on the Test::Stream::IPC(3) page, bestie. 💖 This little gem is documented for perl v5.42.0, dated 2025-07-25, and it is a Test::Stream::IPC(3) page through and through. slay, hydrate, and load your drivers early. ✨🦋💅

📦 where this page comes from