<!-- GENERATED by docs/sphinx/bin/20-reference (p5) from reference/bundled/Test2/Util.md. Do not edit. -->

```{index} single: Test2::Util
```

# Test2::Util

Tools used by Test2 and friends.

## DESCRIPTION

Collection of tools used by [Test2](../Test2.md) and friends.

## EXPORTS

All exports are optional. You must specify subs to import.

- ($success, $error) = try { ... }

    Eval the codeblock, return success or failure, and the error message. This code
    protects $@ and $!, they will be restored by the end of the run. This code also
    temporarily blocks $SIG{DIE} handlers.

- protect { ... }

    Similar to try, except that it does not catch exceptions. The idea here is to
    protect $@ 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

    This will return 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 ID's 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 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 systems process id's 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](https://metacpan.org/pod/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/](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/](https://dev.perl.org/licenses/)

## Modules

- [`Test2::Util::ExternalMeta`](Util/ExternalMeta.md) - Allow third party tools to safely attach meta-data to your instances.
- [`Test2::Util::Facets2Legacy`](Util/Facets2Legacy.md) - Convert facet data to the legacy event API.
- [`Test2::Util::Grabber`](Util/Grabber.md) - Object used to temporarily intercept all events.
- [`Test2::Util::Guard`](Util/Guard.md) - Inline copy of [Scope::Guard](https://metacpan.org/pod/Scope::Guard)
- [`Test2::Util::HashBase`](Util/HashBase.md) - Build hash based classes.
- [`Test2::Util::Importer`](Util/Importer.md) - Inline copy of [Importer](https://metacpan.org/pod/Importer).
- [`Test2::Util::Ref`](Util/Ref.md) - Tools for inspecting or manipulating references.
- [`Test2::Util::Sig`](Util/Sig.md) - Signal tools used by Test2 and friends.
- [`Test2::Util::Stash`](Util/Stash.md) - Utilities for manipulating stashes and globs.
- [`Test2::Util::Sub`](Util/Sub.md) - Tools for inspecting and manipulating subs.
- [`Test2::Util::Table`](Util/Table.md) - Format a header and rows into a table
- [`Test2::Util::Times`](Util/Times.md) - Format timing/benchmark information.
- [`Test2::Util::Trace`](Util/Trace.md) - Legacy wrapper for [Test2::EventFacet::Trace](EventFacet/Trace.md).

```{toctree}
:hidden:
:maxdepth: 1

Util/ExternalMeta
Util/Facets2Legacy
Util/Grabber
Util/Guard
Util/HashBase
Util/Importer
Util/Ref
Util/Sig
Util/Stash
Util/Sub
Util/Table
Util/Times
Util/Trace
```