NAME

       Test2::Manual::Anatomy::Hubs - Internals documentation for the hub stack, and hubs.

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.

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.

       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.

WHY DO WE HAVE A HUB STACK?

       There are cases where it makes sense to have more than one hub:

       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 "Test2::API::context" 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.

       testing your test tools
           "Test2::API::intercept()" is implemented using the hub stack. The
           "Test2::API::intercept()" function will add an Test2::Hub::Interceptor instance to the
           stack, any calls to Test2::API::context() 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.

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.

WHERE IS THE STACK?

       The stack is an instance of Test2::API::Stack. You can access the global hub stack using
       "Test2::API::test2_stack".

WHAT ABOUT THE ROOT HUB?

       The root hub is created automatically as needed. A call to
       "Test2::API::test2_stack->top()" will create the root hub if it does not already exist.

HOW DO HUBS HANDLE IPC?

       If the IPC system (Test2::IPC) was not loaded, then IPC is not handled at all. Forking or
       creating new threads without the IPC system can cause unexpected problems.

       All hubs track the PID and Thread ID 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 IPC system.

SEE ALSO

       Test2::Manual - Primary index of the manual.

SOURCE

       The source code repository for Test2-Manual can be found at
       https://github.com/Test-More/Test2-Suite/.

MAINTAINERS

       Chad Granum <exodist@cpan.org>

AUTHORS

       Chad Granum <exodist@cpan.org>

COPYRIGHT

       Copyright 2018 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 http://dev.perl.org/licenses/