Test2::Util(3)

💖 NAME 💖

Test2::Util — tools used by Test2 and friends. This is the Test2::Util(3) page from the User Contributed Perl Documentation, bestie, and we're gonna make it make sense. 💅

🌸 DESCRIPTION 🌸

Okay so this is a collection of tools used by Test2 and friends. That's the whole vibe: handy little utilities for the Test2 ecosystem. ✨

🧰 EXPORTS 🧰

All exports are optional. You must specify subs to import — no sneaky auto-import situation here, bestie. 🫶

• ($success, $error) = try { ... } — Eval the codeblock, then return success or failure plus the error message. This code protects $@ and $! — they get restored by the end of the run. It also temporarily blocks $SIG{DIE} handlers. 😭✨
• protect { ... } — Similar to try, except it does not catch exceptions. The whole idea is protecting $@ and $! from changes. $@ and $! will be restored to whatever they were before the run so long as it is successful. If the run fails, $! will still be restored, but $@ will contain the exception being thrown. 💀
• CAN_FORK — True if this system is capable of true or pseudo-fork. 🍓
• CAN_REALLY_FORK — True if the system can really fork. This will be false for systems where fork is emulated. 🙈
• CAN_THREAD — True if this system is capable of using threads. 🧵
• USE_THREADS — Returns true if threads are enabled, false if they are not. ✅
• get_tid — Returns the id of the current thread when threads are enabled. Otherwise it returns 0. 🪡
• my $file = pkg_to_file($package) — Convert a package name to a filename. 📁
• $string = ipc_separator() — Get the IPC separator. Currently this is always the string '~'. 🌈
• $string = gen_uid() — Generate a unique id (NOT A UUID). This will typically be the process id, the thread id, the time, and an incrementing integer all joined with the ipc_separator(). 🎀

These IDs are unique enough for most purposes. For identical ids to be generated, you must have 2 processes with the same PID generate IDs at the same time with the same current state of the incrementing integer. This is a perfectly reasonable thing to expect to happen across multiple machines, but it is quite unlikely to happen on one machine. 🫠

This can fail to be unique if a process generates an id, calls exec, and does it again after the exec, and it all happens in less than a second. It can also happen if the system's process ids cycle in less than a second, allowing 2 different programs that use this generator to run with the same PID in less than a second. Both these cases are sufficiently unlikely. If you need universally unique ids, or ids that are unique in these conditions, look at Data::UUID. 💜

• ($ok, $err) = do_rename($old_name, $new_name) — Rename a file. This wraps rename() in a way that makes it more reliable cross-platform when trying to rename files you recently altered. 🔁
• ($ok, $err) = do_unlink($filename) — Unlink a file. This wraps unlink() in a way that makes it more reliable cross-platform when trying to unlink files you recently altered. 🗑️

⚠️ NOTES && CAVEATS ⚠️

🐛 5.10.0 🐛

Perl 5.10.0 has a bug when compiled with newer gcc versions. This bug causes a segfault whenever a new thread is launched. Test2 will attempt to detect this, and note that the system is not capable of forking when it is detected. 😵‍💫

🙈 Devel::Cover 🙈

Devel::Cover does not support threads. CAN_THREAD will return false if Devel::Cover is loaded before the check is first run. 💅

🔗 SOURCE 🔗

The source code repository for Test2 can be found at https://github.com/Test-More/test-more/. 🌟

👑 MAINTAINERS 👑

• Chad Granum <exodist@cpan.org> 🫶

✨ AUTHORS ✨

• Chad Granum <exodist@cpan.org> 💖
• Kent Fredric <kentnl@cpan.org> 💖

📜 COPYRIGHT 📜

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

🫶 That's the whole page, bestie! Source/version vibes: perl v5.42.0, dated 2025-07-28 — and yes, this was the Test2::Util(3) manual. mwah 💋