HOME

sh-3ll 1.0
DIR:/home/.cpan/build/Test2-Suite-0.000148-0/blib/man3/
Current File : /home/.cpan/build/Test2-Suite-0.000148-0/blib/man3/Test2::Manual::Anatomy::Hubs.3pm
.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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::Manual::Anatomy::Hubs 3"
.TH Test2::Manual::Anatomy::Hubs 3 "2023-03-05" "perl v5.26.3" "User Contributed Perl Documentation"
.\" 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::Manual::Anatomy::Hubs \- Internals documentation for the hub stack, and
hubs.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This document describes the hub stack, and the hubs it contains. It explains
why we have a stack, and when to add/remove hubs from it.
.SH "WHAT IS A HUB?"
.IX Header "WHAT IS A HUB?"
Test2 is an event system, tools generate events, those events are then
processed to modify the testing state (number of tests, number of failures,
etc). The hub is responsible for receiving and processing events to record the
change in state. All events should eventually reach a destination hub.
.PP
The base hub is Test2::Hub. All hub classes should inherit from the base hub
class. The base hub class provides several hooks that allow you to monitor or
modify events. Hubs are also responsible for forwarding events to the output
formatter.
.SH "WHY DO WE HAVE A HUB STACK?"
.IX Header "WHY DO WE HAVE A HUB STACK?"
There are cases where it makes sense to have more than one hub:
.IP "subtests" 4
.IX Item "subtests"
In Test2 subtests are implemented using the hub stack. When you start a subtest
a new Test2::Hub::Subtest instance is created and pushed to the stack. Once
this is done all calls to \f(CW\*(C`Test2::API::context\*(C'\fR will find the new hub and send
all events to it. When the subtest tool is complete it will remove the new hub,
and send a final subtest event to the parent hub.
.IP "testing your test tools" 4
.IX Item "testing your test tools"
\&\f(CW\*(C`Test2::API::intercept()\*(C'\fR is implemented using the hub stack. The
\&\f(CW\*(C`Test2::API::intercept()\*(C'\fR function will add an Test2::Hub::Interceptor
instance to the stack, any calls to \fBTest2::API::context()\fR will find the new
hub, and send it all events. The intercept hub is special in that is has no
connection to the parent hub, and usually does not have a formatter.
.SH "WHEN SHOULD I ADD A HUB TO THE STACK?"
.IX Header "WHEN SHOULD I ADD A HUB TO THE STACK?"
Any time you want to intercept or block events from effecting the test state.
Adding a new hub is essentially a way to create a sandbox where you have
absolute control over what events do. Adding a new hub insures that the main
test state will not be effected.
.SH "WHERE IS THE STACK?"
.IX Header "WHERE IS THE STACK?"
The stack is an instance of Test2::API::Stack. You can access the global hub
stack using \f(CW\*(C`Test2::API::test2_stack\*(C'\fR.
.SH "WHAT ABOUT THE ROOT HUB?"
.IX Header "WHAT ABOUT THE ROOT HUB?"
The root hub is created automatically as needed. A call to
\&\f(CW\*(C`Test2::API::test2_stack\->top()\*(C'\fR will create the root hub if it does not
already exist.
.SH "HOW DO HUBS HANDLE IPC?"
.IX Header "HOW DO HUBS HANDLE IPC?"
If the \s-1IPC\s0 system (Test2::IPC) was not loaded, then \s-1IPC\s0 is not handled at
all. Forking or creating new threads without the \s-1IPC\s0 system can cause
unexpected problems.
.PP
All hubs track the \s-1PID\s0 and Thread \s-1ID\s0 that was current when they were created.
If an event is sent to a hub in a new process/thread the hub will detect this
and try to forward the event along to the correct process/thread. This is
accomplished using the \s-1IPC\s0 system.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Test2::Manual \- Primary index of the manual.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Test2\-Manual can be found at
\&\fIhttps://github.com/Test\-More/Test2\-Suite/\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 2018 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