Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 929 insertions, 0 deletions

diff --git a/upstream/archlinux/man3/Test2::API.3perl b/upstream/archlinux/man3/Test2::API.3perl
new file mode 100644
index 00000000..c790e72f
--- /dev/null
+++ b/upstream/archlinux/man3/Test2::API.3perl
@@ -0,0 +1,929 @@
+.\" -*- mode: troff; coding: utf-8 -*-
+.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
+.ie n \{\
+.    ds C` ""
+.    ds C' ""
+'br\}
+.el\{\
+.    ds C`
+.    ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+.    if \nF \{\
+.        de IX
+.        tm Index:\\$1\t\\n%\t"\\$2"
+..
+.        if !\nF==2 \{\
+.            nr % 0
+.            nr F 2
+.        \}
+.    \}
+.\}
+.rr rF
+.\" ========================================================================
+.\"
+.IX Title "Test2::API 3perl"
+.TH Test2::API 3perl 2024-02-11 "perl v5.38.2" "Perl Programmers Reference Guide"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH NAME
+Test2::API \- Primary interface for writing Test2 based testing tools.
+.SH "***INTERNALS NOTE***"
+.IX Header "***INTERNALS NOTE***"
+\&\fBThe internals of this package are subject to change at any time!\fR The public
+methods provided will not change in backwards-incompatible ways (once there is
+a stable release), but the underlying implementation details might.
+\&\fBDo not break encapsulation here!\fR
+.PP
+Currently the implementation is to create a single instance of the
+Test2::API::Instance Object. All class methods defer to the single
+instance. There is no public access to the singleton, and that is intentional.
+The class methods provided by this package provide the only functionality
+publicly exposed.
+.PP
+This is done primarily to avoid the problems Test::Builder had by exposing its
+singleton. We do not want anyone to replace this singleton, rebless it, or
+directly muck with its internals. If you need to do something and cannot
+because of the restrictions placed here, then please report it as an issue. If
+possible, we will create a way for you to implement your functionality without
+exposing things that should not be exposed.
+.SH DESCRIPTION
+.IX Header "DESCRIPTION"
+This package exports all the functions necessary to write and/or verify testing
+tools. Using these building blocks you can begin writing test tools very
+quickly. You are also provided with tools that help you to test the tools you
+write.
+.SH SYNOPSIS
+.IX Header "SYNOPSIS"
+.SS "WRITING A TOOL"
+.IX Subsection "WRITING A TOOL"
+The \f(CWcontext()\fR method is your primary interface into the Test2 framework.
+.PP
+.Vb 2
+\&    package My::Ok;
+\&    use Test2::API qw/context/;
+\&
+\&    our @EXPORT = qw/my_ok/;
+\&    use base \*(AqExporter\*(Aq;
+\&
+\&    # Just like ok() from Test::More
+\&    sub my_ok($;$) {
+\&        my ($bool, $name) = @_;
+\&        my $ctx = context(); # Get a context
+\&        $ctx\->ok($bool, $name);
+\&        $ctx\->release; # Release the context
+\&        return $bool;
+\&    }
+.Ve
+.PP
+See Test2::API::Context for a list of methods available on the context object.
+.SS "TESTING YOUR TOOLS"
+.IX Subsection "TESTING YOUR TOOLS"
+The \f(CW\*(C`intercept { ... }\*(C'\fR tool lets you temporarily intercept all events
+generated by the test system:
+.PP
+.Vb 1
+\&    use Test2::API qw/intercept/;
+\&
+\&    use My::Ok qw/my_ok/;
+\&
+\&    my $events = intercept {
+\&        # These events are not displayed
+\&        my_ok(1, "pass");
+\&        my_ok(0, "fail");
+\&    };
+.Ve
+.PP
+As of version 1.302178 this now returns an arrayref that is also an instance of
+Test2::API::InterceptResult. See the Test2::API::InterceptResult
+documentation for details on how to best use it.
+.SS "OTHER API FUNCTIONS"
+.IX Subsection "OTHER API FUNCTIONS"
+.Vb 10
+\&    use Test2::API qw{
+\&        test2_init_done
+\&        test2_stack
+\&        test2_set_is_end
+\&        test2_get_is_end
+\&        test2_ipc
+\&        test2_formatter_set
+\&        test2_formatter
+\&        test2_is_testing_done
+\&    };
+\&
+\&    my $init  = test2_init_done();
+\&    my $stack = test2_stack();
+\&    my $ipc   = test2_ipc();
+\&
+\&    test2_formatter_set($FORMATTER)
+\&    my $formatter = test2_formatter();
+\&
+\&    ... And others ...
+.Ve
+.SH "MAIN API EXPORTS"
+.IX Header "MAIN API EXPORTS"
+All exports are optional. You must specify subs to import.
+.PP
+.Vb 1
+\&    use Test2::API qw/context intercept run_subtest/;
+.Ve
+.PP
+This is the list of exports that are most commonly needed. If you are simply
+writing a tool, then this is probably all you need. If you need something and
+you cannot find it here, then you can also look at "OTHER API EXPORTS".
+.PP
+These exports lack the 'test2_' prefix because of how important/common they
+are. Exports in the "OTHER API EXPORTS" section have the 'test2_' prefix to
+ensure they stand out.
+.SS context(...)
+.IX Subsection "context(...)"
+Usage:
+.ie n .IP "$ctx = \fBcontext()\fR" 4
+.el .IP "\f(CW$ctx\fR = \fBcontext()\fR" 4
+.IX Item "$ctx = context()"
+.PD 0
+.ie n .IP "$ctx = context(%params)" 4
+.el .IP "\f(CW$ctx\fR = context(%params)" 4
+.IX Item "$ctx = context(%params)"
+.PD
+.PP
+The \f(CWcontext()\fR function will always return the current context. If
+there is already a context active, it will be returned. If there is not an
+active context, one will be generated. When a context is generated it will
+default to using the file and line number where the currently running sub was
+called from.
+.PP
+Please see "CRITICAL DETAILS" in Test2::API::Context for important rules about
+what you can and cannot do with a context once it is obtained.
+.PP
+\&\fBNote\fR This function will throw an exception if you ignore the context object
+it returns.
+.PP
+\&\fBNote\fR On perls 5.14+ a depth check is used to insure there are no context
+leaks. This cannot be safely done on older perls due to
+<https://rt.perl.org/Public/Bug/Display.html?id=127774>
+You can forcefully enable it either by setting \f(CW\*(C`$ENV{T2_CHECK_DEPTH} = 1\*(C'\fR or
+\&\f(CW\*(C`$Test2::API::DO_DEPTH_CHECK = 1\*(C'\fR \fBBEFORE\fR loading Test2::API.
+.PP
+\fIOPTIONAL PARAMETERS\fR
+.IX Subsection "OPTIONAL PARAMETERS"
+.PP
+All parameters to \f(CW\*(C`context\*(C'\fR are optional.
+.ie n .IP "level => $int" 4
+.el .IP "level => \f(CW$int\fR" 4
+.IX Item "level => $int"
+If you must obtain a context in a sub deeper than your entry point you can use
+this to tell it how many EXTRA stack frames to look back. If this option is not
+provided the default of \f(CW0\fR is used.
+.Sp
+.Vb 6
+\&    sub third_party_tool {
+\&        my $sub = shift;
+\&        ... # Does not obtain a context
+\&        $sub\->();
+\&        ...
+\&    }
+\&
+\&    third_party_tool(sub {
+\&        my $ctx = context(level => 1);
+\&        ...
+\&        $ctx\->release;
+\&    });
+.Ve
+.ie n .IP "wrapped => $int" 4
+.el .IP "wrapped => \f(CW$int\fR" 4
+.IX Item "wrapped => $int"
+Use this if you need to write your own tool that wraps a call to \f(CWcontext()\fR
+with the intent that it should return a context object.
+.Sp
+.Vb 7
+\&    sub my_context {
+\&        my %params = ( wrapped => 0, @_ );
+\&        $params{wrapped}++;
+\&        my $ctx = context(%params);
+\&        ...
+\&        return $ctx;
+\&    }
+\&
+\&    sub my_tool {
+\&        my $ctx = my_context();
+\&        ...
+\&        $ctx\->release;
+\&    }
+.Ve
+.Sp
+If you do not do this, then tools you call that also check for a context will
+notice that the context they grabbed was created at the same stack depth, which
+will trigger protective measures that warn you and destroy the existing
+context.
+.ie n .IP "stack => $stack" 4
+.el .IP "stack => \f(CW$stack\fR" 4
+.IX Item "stack => $stack"
+Normally \f(CWcontext()\fR looks at the global hub stack. If you are maintaining
+your own Test2::API::Stack instance you may pass it in to be used
+instead of the global one.
+.ie n .IP "hub => $hub" 4
+.el .IP "hub => \f(CW$hub\fR" 4
+.IX Item "hub => $hub"
+Use this parameter if you want to obtain the context for a specific hub instead
+of whatever one happens to be at the top of the stack.
+.IP "on_init => sub { ... }" 4
+.IX Item "on_init => sub { ... }"
+This lets you provide a callback sub that will be called \fBONLY\fR if your call
+to \f(CWcontext()\fR generated a new context. The callback \fBWILL NOT\fR be called if
+\&\f(CWcontext()\fR is returning an existing context. The only argument passed into
+the callback will be the context object itself.
+.Sp
+.Vb 2
+\&    sub foo {
+\&        my $ctx = context(on_init => sub { \*(Aqwill run\*(Aq });
+\&
+\&        my $inner = sub {
+\&            # This callback is not run since we are getting the existing
+\&            # context from our parent sub.
+\&            my $ctx = context(on_init => sub { \*(Aqwill NOT run\*(Aq });
+\&            $ctx\->release;
+\&        }
+\&        $inner\->();
+\&
+\&        $ctx\->release;
+\&    }
+.Ve
+.IP "on_release => sub { ... }" 4
+.IX Item "on_release => sub { ... }"
+This lets you provide a callback sub that will be called when the context
+instance is released. This callback will be added to the returned context even
+if an existing context is returned. If multiple calls to context add callbacks,
+then all will be called in reverse order when the context is finally released.
+.Sp
+.Vb 2
+\&    sub foo {
+\&        my $ctx = context(on_release => sub { \*(Aqwill run second\*(Aq });
+\&
+\&        my $inner = sub {
+\&            my $ctx = context(on_release => sub { \*(Aqwill run first\*(Aq });
+\&
+\&            # Neither callback runs on this release
+\&            $ctx\->release;
+\&        }
+\&        $inner\->();
+\&
+\&        # Both callbacks run here.
+\&        $ctx\->release;
+\&    }
+.Ve
+.SS release($;$)
+.IX Subsection "release($;$)"
+Usage:
+.ie n .IP "release $ctx;" 4
+.el .IP "release \f(CW$ctx\fR;" 4
+.IX Item "release $ctx;"
+.PD 0
+.ie n .IP "release $ctx, ...;" 4
+.el .IP "release \f(CW$ctx\fR, ...;" 4
+.IX Item "release $ctx, ...;"
+.PD
+.PP
+This is intended as a shortcut that lets you release your context and return a
+value in one statement. This function will get your context, and an optional
+return value. It will release your context, then return your value. Scalar
+context is always assumed.
+.PP
+.Vb 3
+\&    sub tool {
+\&        my $ctx = context();
+\&        ...
+\&
+\&        return release $ctx, 1;
+\&    }
+.Ve
+.PP
+This tool is most useful when you want to return the value you get from calling
+a function that needs to see the current context:
+.PP
+.Vb 4
+\&    my $ctx = context();
+\&    my $out = some_tool(...);
+\&    $ctx\->release;
+\&    return $out;
+.Ve
+.PP
+We can combine the last 3 lines of the above like so:
+.PP
+.Vb 2
+\&    my $ctx = context();
+\&    release $ctx, some_tool(...);
+.Ve
+.SS context_do(&;@)
+.IX Subsection "context_do(&;@)"
+Usage:
+.PP
+.Vb 3
+\&    sub my_tool {
+\&        context_do {
+\&            my $ctx = shift;
+\&
+\&            my (@args) = @_;
+\&
+\&            $ctx\->ok(1, "pass");
+\&
+\&            ...
+\&
+\&            # No need to call $ctx\->release, done for you on scope exit.
+\&        } @_;
+\&    }
+.Ve
+.PP
+Using this inside your test tool takes care of a lot of boilerplate for you. It
+will ensure a context is acquired. It will capture and rethrow any exception. It
+will insure the context is released when you are done. It preserves the
+subroutine call context (array, scalar, void).
+.PP
+This is the safest way to write a test tool. The only two downsides to this are a
+slight performance decrease, and some extra indentation in your source. If the
+indentation is a problem for you then you can take a peek at the next section.
+.SS no_context(&;$)
+.IX Subsection "no_context(&;$)"
+Usage:
+.IP "no_context { ... };" 4
+.IX Item "no_context { ... };"
+.PD 0
+.ie n .IP "no_context { ... } $hid;" 4
+.el .IP "no_context { ... } \f(CW$hid\fR;" 4
+.IX Item "no_context { ... } $hid;"
+.PD
+.Vb 4
+\&    sub my_tool(&) {
+\&        my $code = shift;
+\&        my $ctx = context();
+\&        ...
+\&
+\&        no_context {
+\&            # Things in here will not see our current context, they get a new
+\&            # one.
+\&
+\&            $code\->();
+\&        };
+\&
+\&        ...
+\&        $ctx\->release;
+\&    };
+.Ve
+.PP
+This tool will hide a context for the provided block of code. This means any
+tools run inside the block will get a completely new context if they acquire
+one. The new context will be inherited by tools nested below the one that
+acquired it.
+.PP
+This will normally hide the current context for the top hub. If you need to
+hide the context for a different hub you can pass in the optional \f(CW$hid\fR
+parameter.
+.SS intercept(&)
+.IX Subsection "intercept(&)"
+Usage:
+.PP
+.Vb 5
+\&    my $events = intercept {
+\&        ok(1, "pass");
+\&        ok(0, "fail");
+\&        ...
+\&    };
+.Ve
+.PP
+This function takes a codeblock as its only argument, and it has a prototype.
+It will execute the codeblock, intercepting any generated events in the
+process. It will return an array reference with all the generated event
+objects. All events should be subclasses of Test2::Event.
+.PP
+As of version 1.302178 the events array that is returned is blssed as an
+Test2::API::InterceptResult instance. Test2::API::InterceptResult
+Provides a helpful interface for filtering and/or inspecting the events list
+overall, or individual events within the list.
+.PP
+This is intended to help you test your test code. This is not intended for
+people simply writing tests.
+.SS run_subtest(...)
+.IX Subsection "run_subtest(...)"
+Usage:
+.PP
+.Vb 1
+\&    run_subtest($NAME, \e&CODE, $BUFFERED, @ARGS)
+\&
+\&    # or
+\&
+\&    run_subtest($NAME, \e&CODE, \e%PARAMS, @ARGS)
+.Ve
+.PP
+This will run the provided codeblock with the args in \f(CW@args\fR. This codeblock
+will be run as a subtest. A subtest is an isolated test state that is condensed
+into a single Test2::Event::Subtest event, which contains all events
+generated inside the subtest.
+.PP
+\fIARGUMENTS:\fR
+.IX Subsection "ARGUMENTS:"
+.ie n .IP $NAME 4
+.el .IP \f(CW$NAME\fR 4
+.IX Item "$NAME"
+The name of the subtest.
+.IP \e&CODE 4
+.IX Item "&CODE"
+The code to run inside the subtest.
+.ie n .IP "$BUFFERED or \e%PARAMS" 4
+.el .IP "\f(CW$BUFFERED\fR or \e%PARAMS" 4
+.IX Item "$BUFFERED or %PARAMS"
+If this is a simple scalar then it will be treated as a boolean for the
+\&'buffered' setting. If this is a hash reference then it will be used as a
+parameters hash. The param hash will be used for hub construction (with the
+specified keys removed).
+.Sp
+Keys that are removed and used by run_subtest:
+.RS 4
+.ie n .IP "'buffered' => $bool" 4
+.el .IP "'buffered' => \f(CW$bool\fR" 4
+.IX Item "'buffered' => $bool"
+Toggle buffered status.
+.ie n .IP "'inherit_trace' => $bool" 4
+.el .IP "'inherit_trace' => \f(CW$bool\fR" 4
+.IX Item "'inherit_trace' => $bool"
+Normally the subtest hub is pushed and the sub is allowed to generate its own
+root context for the hub. When this setting is turned on a root context will be
+created for the hub that shares the same trace as the current context.
+.Sp
+Set this to true if your tool is producing subtests without user-specified
+subs.
+.ie n .IP "'no_fork' => $bool" 4
+.el .IP "'no_fork' => \f(CW$bool\fR" 4
+.IX Item "'no_fork' => $bool"
+Defaults to off. Normally forking inside a subtest will actually fork the
+subtest, resulting in 2 final subtest events. This parameter will turn off that
+behavior, only the original process/thread will return a final subtest event.
+.RE
+.RS 4
+.RE
+.ie n .IP @ARGS 4
+.el .IP \f(CW@ARGS\fR 4
+.IX Item "@ARGS"
+Any extra arguments you want passed into the subtest code.
+.PP
+\fIBUFFERED VS UNBUFFERED (OR STREAMED)\fR
+.IX Subsection "BUFFERED VS UNBUFFERED (OR STREAMED)"
+.PP
+Normally all events inside and outside a subtest are sent to the formatter
+immediately by the hub. Sometimes it is desirable to hold off sending events
+within a subtest until the subtest is complete. This usually depends on the
+formatter being used.
+.IP "Things not effected by this flag" 4
+.IX Item "Things not effected by this flag"
+In both cases events are generated and stored in an array. This array is
+eventually used to populate the \f(CW\*(C`subevents\*(C'\fR attribute on the
+Test2::Event::Subtest event that is generated at the end of the subtest.
+This flag has no effect on this part, it always happens.
+.Sp
+At the end of the subtest, the final Test2::Event::Subtest event is sent to
+the formatter.
+.IP "Things that are effected by this flag" 4
+.IX Item "Things that are effected by this flag"
+The \f(CW\*(C`buffered\*(C'\fR attribute of the Test2::Event::Subtest event will be set to
+the value of this flag. This means any formatter, listener, etc which looks at
+the event will know if it was buffered.
+.IP "Things that are formatter dependant" 4
+.IX Item "Things that are formatter dependant"
+Events within a buffered subtest may or may not be sent to the formatter as
+they happen. If a formatter fails to specify then the default is to \fBNOT SEND\fR
+the events as they are generated, instead the formatter can pull them from the
+\&\f(CW\*(C`subevents\*(C'\fR attribute.
+.Sp
+A formatter can specify by implementing the \f(CWhide_buffered()\fR method. If this
+method returns true then events generated inside a buffered subtest will not be
+sent independently of the final subtest event.
+.PP
+An example of how this is used is the Test2::Formatter::TAP formatter. For
+unbuffered subtests the events are rendered as they are generated. At the end
+of the subtest, the final subtest event is rendered, but the \f(CW\*(C`subevents\*(C'\fR
+attribute is ignored. For buffered subtests the opposite occurs, the events are
+NOT rendered as they are generated, instead the \f(CW\*(C`subevents\*(C'\fR attribute is used
+to render them all at once. This is useful when running subtests tests in
+parallel, since without it the output from subtests would be interleaved
+together.
+.SH "OTHER API EXPORTS"
+.IX Header "OTHER API EXPORTS"
+Exports in this section are not commonly needed. These all have the 'test2_'
+prefix to help ensure they stand out. You should look at the "MAIN API
+EXPORTS" section before looking here. This section is one where "Great power
+comes with great responsibility". It is possible to break things badly if you
+are not careful with these.
+.PP
+All exports are optional. You need to list which ones you want at import time:
+.PP
+.Vb 1
+\&    use Test2::API qw/test2_init_done .../;
+.Ve
+.SS "STATUS AND INITIALIZATION STATE"
+.IX Subsection "STATUS AND INITIALIZATION STATE"
+These provide access to internal state and object instances.
+.ie n .IP "$bool = \fBtest2_init_done()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_init_done()\fR" 4
+.IX Item "$bool = test2_init_done()"
+This will return true if the stack and IPC instances have already been
+initialized. It will return false if they have not. Init happens as late as
+possible. It happens as soon as a tool requests the IPC instance, the
+formatter, or the stack.
+.ie n .IP "$bool = \fBtest2_load_done()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_load_done()\fR" 4
+.IX Item "$bool = test2_load_done()"
+This will simply return the boolean value of the loaded flag. If Test2 has
+finished loading this will be true, otherwise false. Loading is considered
+complete the first time a tool requests a context.
+.IP \fBtest2_set_is_end()\fR 4
+.IX Item "test2_set_is_end()"
+.PD 0
+.IP test2_set_is_end($bool) 4
+.IX Item "test2_set_is_end($bool)"
+.PD
+This is used to toggle Test2's belief that the END phase has already started.
+With no arguments this will set it to true. With arguments it will set it to
+the first argument's value.
+.Sp
+This is used to prevent the use of \f(CWcaller()\fR in END blocks which can cause
+segfaults. This is only necessary in some persistent environments that may have
+multiple END phases.
+.ie n .IP "$bool = \fBtest2_get_is_end()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_get_is_end()\fR" 4
+.IX Item "$bool = test2_get_is_end()"
+Check if Test2 believes it is the END phase.
+.ie n .IP "$stack = \fBtest2_stack()\fR" 4
+.el .IP "\f(CW$stack\fR = \fBtest2_stack()\fR" 4
+.IX Item "$stack = test2_stack()"
+This will return the global Test2::API::Stack instance. If this has not
+yet been initialized it will be initialized now.
+.ie n .IP "$bool = \fBtest2_is_testing_done()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_is_testing_done()\fR" 4
+.IX Item "$bool = test2_is_testing_done()"
+This will return true if testing is complete and no other events should be
+sent. This is useful in things like warning handlers where you might want to
+turn warnings into events, but need them to start acting like normal warnings
+when testing is done.
+.Sp
+.Vb 2
+\&    $SIG{_\|_WARN_\|_} = sub {
+\&        my ($warning) = @_;
+\&
+\&        if (test2_is_testing_done()) {
+\&            warn @_;
+\&        }
+\&        else {
+\&            my $ctx = context();
+\&            ...
+\&            $ctx\->release
+\&        }
+\&    }
+.Ve
+.IP test2_ipc_disable 4
+.IX Item "test2_ipc_disable"
+Disable IPC.
+.ie n .IP "$bool = test2_ipc_diabled" 4
+.el .IP "\f(CW$bool\fR = test2_ipc_diabled" 4
+.IX Item "$bool = test2_ipc_diabled"
+Check if IPC is disabled.
+.IP \fBtest2_ipc_wait_enable()\fR 4
+.IX Item "test2_ipc_wait_enable()"
+.PD 0
+.IP \fBtest2_ipc_wait_disable()\fR 4
+.IX Item "test2_ipc_wait_disable()"
+.ie n .IP "$bool = \fBtest2_ipc_wait_enabled()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_ipc_wait_enabled()\fR" 4
+.IX Item "$bool = test2_ipc_wait_enabled()"
+.PD
+These can be used to turn IPC waiting on and off, or check the current value of
+the flag.
+.Sp
+Waiting is turned on by default. Waiting will cause the parent process/thread
+to wait until all child processes and threads are finished before exiting. You
+will almost never want to turn this off.
+.ie n .IP "$bool = \fBtest2_no_wait()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_no_wait()\fR" 4
+.IX Item "$bool = test2_no_wait()"
+.PD 0
+.IP test2_no_wait($bool) 4
+.IX Item "test2_no_wait($bool)"
+.PD
+\&\fBDISCOURAGED\fR: This is a confusing interface, it is better to use
+\&\f(CWtest2_ipc_wait_enable()\fR, \f(CWtest2_ipc_wait_disable()\fR and
+\&\f(CWtest2_ipc_wait_enabled()\fR.
+.Sp
+This can be used to get/set the no_wait status. Waiting is turned on by
+default. Waiting will cause the parent process/thread to wait until all child
+processes and threads are finished before exiting. You will almost never want
+to turn this off.
+.ie n .IP "$fh = \fBtest2_stdout()\fR" 4
+.el .IP "\f(CW$fh\fR = \fBtest2_stdout()\fR" 4
+.IX Item "$fh = test2_stdout()"
+.PD 0
+.ie n .IP "$fh = \fBtest2_stderr()\fR" 4
+.el .IP "\f(CW$fh\fR = \fBtest2_stderr()\fR" 4
+.IX Item "$fh = test2_stderr()"
+.PD
+These functions return the filehandles that test output should be written to.
+They are primarily useful when writing a custom formatter and code that turns
+events into actual output (TAP, etc.).  They will return a dupe of the original
+filehandles that formatted output can be sent to regardless of whatever state
+the currently running test may have left STDOUT and STDERR in.
+.IP \fBtest2_reset_io()\fR 4
+.IX Item "test2_reset_io()"
+Re-dupe the internal filehandles returned by \f(CWtest2_stdout()\fR and
+\&\f(CWtest2_stderr()\fR from the current STDOUT and STDERR.  You shouldn't need to do
+this except in very peculiar situations (for example, you're testing a new
+formatter and you need control over where the formatter is sending its output.)
+.SS "BEHAVIOR HOOKS"
+.IX Subsection "BEHAVIOR HOOKS"
+These are hooks that allow you to add custom behavior to actions taken by Test2
+and tools built on top of it.
+.IP "test2_add_callback_exit(sub { ... })" 4
+.IX Item "test2_add_callback_exit(sub { ... })"
+This can be used to add a callback that is called after all testing is done. This
+is too late to add additional results, the main use of this callback is to set the
+exit code.
+.Sp
+.Vb 6
+\&    test2_add_callback_exit(
+\&        sub {
+\&            my ($context, $exit, \e$new_exit) = @_;
+\&            ...
+\&        }
+\&    );
+.Ve
+.Sp
+The \f(CW$context\fR passed in will be an instance of Test2::API::Context. The
+\&\f(CW$exit\fR argument will be the original exit code before anything modified it.
+\&\f(CW$$new_exit\fR is a reference to the new exit code. You may modify this to
+change the exit code. Please note that \f(CW$$new_exit\fR may already be different
+from \f(CW$exit\fR
+.IP "test2_add_callback_post_load(sub { ... })" 4
+.IX Item "test2_add_callback_post_load(sub { ... })"
+Add a callback that will be called when Test2 is finished loading. This
+means the callback will be run once, the first time a context is obtained.
+If Test2 has already finished loading then the callback will be run immediately.
+.IP "test2_add_callback_testing_done(sub { ... })" 4
+.IX Item "test2_add_callback_testing_done(sub { ... })"
+This adds your coderef as a follow-up to the root hub after Test2 is finished loading.
+.Sp
+This is essentially a helper to do the following:
+.Sp
+.Vb 4
+\&    test2_add_callback_post_load(sub {
+\&        my $stack = test2_stack();
+\&        $stack\->top; # Insure we have a hub
+\&        my ($hub) = Test2::API::test2_stack\->all;
+\&
+\&        $hub\->set_active(1);
+\&
+\&        $hub\->follow_up(sub { ... }); # <\-\- Your coderef here
+\&    });
+.Ve
+.IP "test2_add_callback_context_acquire(sub { ... })" 4
+.IX Item "test2_add_callback_context_acquire(sub { ... })"
+Add a callback that will be called every time someone tries to acquire a
+context. This will be called on EVERY call to \f(CWcontext()\fR. It gets a single
+argument, a reference to the hash of parameters being used the construct the
+context. This is your chance to change the parameters by directly altering the
+hash.
+.Sp
+.Vb 4
+\&    test2_add_callback_context_acquire(sub {
+\&        my $params = shift;
+\&        $params\->{level}++;
+\&    });
+.Ve
+.Sp
+This is a very scary API function. Please do not use this unless you need to.
+This is here for Test::Builder and backwards compatibility. This has you
+directly manipulate the hash instead of returning a new one for performance
+reasons.
+.IP "test2_add_callback_context_init(sub { ... })" 4
+.IX Item "test2_add_callback_context_init(sub { ... })"
+Add a callback that will be called every time a new context is created. The
+callback will receive the newly created context as its only argument.
+.IP "test2_add_callback_context_release(sub { ... })" 4
+.IX Item "test2_add_callback_context_release(sub { ... })"
+Add a callback that will be called every time a context is released. The
+callback will receive the released context as its only argument.
+.IP "test2_add_callback_pre_subtest(sub { ... })" 4
+.IX Item "test2_add_callback_pre_subtest(sub { ... })"
+Add a callback that will be called every time a subtest is going to be
+run. The callback will receive the subtest name, coderef, and any
+arguments.
+.ie n .IP "@list = \fBtest2_list_context_acquire_callbacks()\fR" 4
+.el .IP "\f(CW@list\fR = \fBtest2_list_context_acquire_callbacks()\fR" 4
+.IX Item "@list = test2_list_context_acquire_callbacks()"
+Return all the context acquire callback references.
+.ie n .IP "@list = \fBtest2_list_context_init_callbacks()\fR" 4
+.el .IP "\f(CW@list\fR = \fBtest2_list_context_init_callbacks()\fR" 4
+.IX Item "@list = test2_list_context_init_callbacks()"
+Returns all the context init callback references.
+.ie n .IP "@list = \fBtest2_list_context_release_callbacks()\fR" 4
+.el .IP "\f(CW@list\fR = \fBtest2_list_context_release_callbacks()\fR" 4
+.IX Item "@list = test2_list_context_release_callbacks()"
+Returns all the context release callback references.
+.ie n .IP "@list = \fBtest2_list_exit_callbacks()\fR" 4
+.el .IP "\f(CW@list\fR = \fBtest2_list_exit_callbacks()\fR" 4
+.IX Item "@list = test2_list_exit_callbacks()"
+Returns all the exit callback references.
+.ie n .IP "@list = \fBtest2_list_post_load_callbacks()\fR" 4
+.el .IP "\f(CW@list\fR = \fBtest2_list_post_load_callbacks()\fR" 4
+.IX Item "@list = test2_list_post_load_callbacks()"
+Returns all the post load callback references.
+.ie n .IP "@list = \fBtest2_list_pre_subtest_callbacks()\fR" 4
+.el .IP "\f(CW@list\fR = \fBtest2_list_pre_subtest_callbacks()\fR" 4
+.IX Item "@list = test2_list_pre_subtest_callbacks()"
+Returns all the pre-subtest callback references.
+.IP "test2_add_uuid_via(sub { ... })" 4
+.IX Item "test2_add_uuid_via(sub { ... })"
+.PD 0
+.ie n .IP "$sub = \fBtest2_add_uuid_via()\fR" 4
+.el .IP "\f(CW$sub\fR = \fBtest2_add_uuid_via()\fR" 4
+.IX Item "$sub = test2_add_uuid_via()"
+.PD
+This allows you to provide a UUID generator. If provided UUIDs will be attached
+to all events, hubs, and contexts. This is useful for storing, tracking, and
+linking these objects.
+.Sp
+The sub you provide should always return a unique identifier. Most things will
+expect a proper UUID string, however nothing in Test2::API enforces this.
+.Sp
+The sub will receive exactly 1 argument, the type of thing being tagged
+\&'context', 'hub', or 'event'. In the future additional things may be tagged, in
+which case new strings will be passed in. These are purely informative, you can
+(and usually should) ignore them.
+.SS "IPC AND CONCURRENCY"
+.IX Subsection "IPC AND CONCURRENCY"
+These let you access, or specify, the IPC system internals.
+.ie n .IP "$bool = \fBtest2_has_ipc()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_has_ipc()\fR" 4
+.IX Item "$bool = test2_has_ipc()"
+Check if IPC is enabled.
+.ie n .IP "$ipc = \fBtest2_ipc()\fR" 4
+.el .IP "\f(CW$ipc\fR = \fBtest2_ipc()\fR" 4
+.IX Item "$ipc = test2_ipc()"
+This will return the global Test2::IPC::Driver instance. If this has not yet
+been initialized it will be initialized now.
+.IP test2_ipc_add_driver($DRIVER) 4
+.IX Item "test2_ipc_add_driver($DRIVER)"
+Add an IPC driver to the list. This will add the driver to the start of the
+list.
+.ie n .IP "@drivers = \fBtest2_ipc_drivers()\fR" 4
+.el .IP "\f(CW@drivers\fR = \fBtest2_ipc_drivers()\fR" 4
+.IX Item "@drivers = test2_ipc_drivers()"
+Get the list of IPC drivers.
+.ie n .IP "$bool = \fBtest2_ipc_polling()\fR" 4
+.el .IP "\f(CW$bool\fR = \fBtest2_ipc_polling()\fR" 4
+.IX Item "$bool = test2_ipc_polling()"
+Check if polling is enabled.
+.IP \fBtest2_ipc_enable_polling()\fR 4
+.IX Item "test2_ipc_enable_polling()"
+Turn on polling. This will cull events from other processes and threads every
+time a context is created.
+.IP \fBtest2_ipc_disable_polling()\fR 4
+.IX Item "test2_ipc_disable_polling()"
+Turn off IPC polling.
+.IP \fBtest2_ipc_enable_shm()\fR 4
+.IX Item "test2_ipc_enable_shm()"
+Legacy, this is currently a no-op that returns 0;
+.IP test2_ipc_set_pending($uniq_val) 4
+.IX Item "test2_ipc_set_pending($uniq_val)"
+Tell other processes and events that an event is pending. \f(CW$uniq_val\fR should
+be a unique value no other thread/process will generate.
+.Sp
+\&\fBNote:\fR After calling this \f(CWtest2_ipc_get_pending()\fR will return 1. This is
+intentional, and not avoidable.
+.ie n .IP "$pending = \fBtest2_ipc_get_pending()\fR" 4
+.el .IP "\f(CW$pending\fR = \fBtest2_ipc_get_pending()\fR" 4
+.IX Item "$pending = test2_ipc_get_pending()"
+This returns \-1 if there is no way to check (assume yes)
+.Sp
+This returns 0 if there are (most likely) no pending events.
+.Sp
+This returns 1 if there are (likely) pending events. Upon return it will reset,
+nothing else will be able to see that there were pending events.
+.ie n .IP "$timeout = \fBtest2_ipc_get_timeout()\fR" 4
+.el .IP "\f(CW$timeout\fR = \fBtest2_ipc_get_timeout()\fR" 4
+.IX Item "$timeout = test2_ipc_get_timeout()"
+.PD 0
+.IP test2_ipc_set_timeout($timeout) 4
+.IX Item "test2_ipc_set_timeout($timeout)"
+.PD
+Get/Set the timeout value for the IPC system. This timeout is how long the IPC
+system will wait for child processes and threads to finish before aborting.
+.Sp
+The default value is \f(CW30\fR seconds.
+.SS "MANAGING FORMATTERS"
+.IX Subsection "MANAGING FORMATTERS"
+These let you access, or specify, the formatters that can/should be used.
+.ie n .IP "$formatter = test2_formatter" 4
+.el .IP "\f(CW$formatter\fR = test2_formatter" 4
+.IX Item "$formatter = test2_formatter"
+This will return the global formatter class. This is not an instance. By
+default the formatter is set to Test2::Formatter::TAP.
+.Sp
+You can override this default using the \f(CW\*(C`T2_FORMATTER\*(C'\fR environment variable.
+.Sp
+Normally 'Test2::Formatter::' is prefixed to the value in the
+environment variable:
+.Sp
+.Vb 2
+\&    $ T2_FORMATTER=\*(AqTAP\*(Aq perl test.t     # Use the Test2::Formatter::TAP formatter
+\&    $ T2_FORMATTER=\*(AqFoo\*(Aq perl test.t     # Use the Test2::Formatter::Foo formatter
+.Ve
+.Sp
+If you want to specify a full module name you use the '+' prefix:
+.Sp
+.Vb 1
+\&    $ T2_FORMATTER=\*(Aq+Foo::Bar\*(Aq perl test.t     # Use the Foo::Bar formatter
+.Ve
+.IP test2_formatter_set($class_or_instance) 4
+.IX Item "test2_formatter_set($class_or_instance)"
+Set the global formatter class. This can only be set once. \fBNote:\fR This will
+override anything specified in the 'T2_FORMATTER' environment variable.
+.ie n .IP "@formatters = \fBtest2_formatters()\fR" 4
+.el .IP "\f(CW@formatters\fR = \fBtest2_formatters()\fR" 4
+.IX Item "@formatters = test2_formatters()"
+Get a list of all loaded formatters.
+.IP test2_formatter_add($class_or_instance) 4
+.IX Item "test2_formatter_add($class_or_instance)"
+Add a formatter to the list. Last formatter added is used at initialization. If
+this is called after initialization a warning will be issued.
+.SH "OTHER EXAMPLES"
+.IX Header "OTHER EXAMPLES"
+See the \f(CW\*(C`/Examples/\*(C'\fR directory included in this distribution.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+Test2::API::Context \- Detailed documentation of the context object.
+.PP
+Test2::IPC \- The IPC system used for threading/fork support.
+.PP
+Test2::Formatter \- Formatters such as TAP live here.
+.PP
+Test2::Event \- Events live in this namespace.
+.PP
+Test2::Hub \- All events eventually funnel through a hub. Custom hubs are how
+\&\f(CWintercept()\fR and \f(CWrun_subtest()\fR are implemented.
+.SH MAGIC
+.IX Header "MAGIC"
+This package has an END block. This END block is responsible for setting the
+exit code based on the test results. This end block also calls the callbacks that
+can be added to this package.
+.SH SOURCE
+.IX Header "SOURCE"
+The source code repository for Test2 can be found at
+\&\fIhttp://github.com/Test\-More/test\-more/\fR.
+.SH MAINTAINERS
+.IX Header "MAINTAINERS"
+.IP "Chad Granum <exodist@cpan.org>" 4
+.IX Item "Chad Granum <exodist@cpan.org>"
+.SH AUTHORS
+.IX Header "AUTHORS"
+.PD 0
+.IP "Chad Granum <exodist@cpan.org>" 4
+.IX Item "Chad Granum <exodist@cpan.org>"
+.PD
+.SH COPYRIGHT
+.IX Header "COPYRIGHT"
+Copyright 2020 Chad Granum <exodist@cpan.org>.
+.PP
+This program is free software; you can redistribute it and/or
+modify it under the same terms as Perl itself.
+.PP
+See \fIhttp://dev.perl.org/licenses/\fR