1Test2::Manual::Anatomy:U:sHeurbsC(o3n)tributed Perl DocuTmeesntt2a:t:iMoannual::Anatomy::Hubs(3)
2
3
4

NAME

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

DESCRIPTION

10       This document describes the hub stack, and the hubs it contains. It
11       explains why we have a stack, and when to add/remove hubs from it.
12

WHAT IS A HUB?

14       Test2 is an event system, tools generate events, those events are then
15       processed to modify the testing state (number of tests, number of
16       failures, etc). The hub is responsible for receiving and processing
17       events to record the change in state. All events should eventually
18       reach a destination hub.
19
20       The base hub is Test2::Hub. All hub classes should inherit from the
21       base hub class. The base hub class provides several hooks that allow
22       you to monitor or modify events. Hubs are also responsible for
23       forwarding events to the output formatter.
24

WHY DO WE HAVE A HUB STACK?

26       There are cases where it makes sense to have more than one hub:
27
28       subtests
29           In Test2 subtests are implemented using the hub stack. When you
30           start a subtest a new Test2::Hub::Subtest instance is created and
31           pushed to the stack. Once this is done all calls to
32           "Test2::API::context" will find the new hub and send all events to
33           it. When the subtest tool is complete it will remove the new hub,
34           and send a final subtest event to the parent hub.
35
36       testing your test tools
37           Test2::API::intercept() is implemented using the hub stack. The
38           Test2::API::intercept() function will add an
39           Test2::Hub::Interceptor instance to the stack, any calls to
40           Test2::API::context() will find the new hub, and send it all
41           events. The intercept hub is special in that is has no connection
42           to the parent hub, and usually does not have a formatter.
43

WHEN SHOULD I ADD A HUB TO THE STACK?

45       Any time you want to intercept or block events from effecting the test
46       state.  Adding a new hub is essentially a way to create a sandbox where
47       you have absolute control over what events do. Adding a new hub insures
48       that the main test state will not be effected.
49

WHERE IS THE STACK?

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

WHAT ABOUT THE ROOT HUB?

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

HOW DO HUBS HANDLE IPC?

60       If the IPC system (Test2::IPC) was not loaded, then IPC is not handled
61       at all. Forking or creating new threads without the IPC system can
62       cause unexpected problems.
63
64       All hubs track the PID and Thread ID that was current when they were
65       created.  If an event is sent to a hub in a new process/thread the hub
66       will detect this and try to forward the event along to the correct
67       process/thread. This is accomplished using the IPC system.
68

SEE ALSO

70       Test2::Manual - Primary index of the manual.
71

SOURCE

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

MAINTAINERS

77       Chad Granum <exodist@cpan.org>
78

AUTHORS

80       Chad Granum <exodist@cpan.org>
81

83       Copyright 2018 Chad Granum <exodist@cpan.org>.
84
85       This program is free software; you can redistribute it and/or modify it
86       under the same terms as Perl itself.
87
88       See http://dev.perl.org/licenses/
89
90
91
92perl v5.36.0                      2023-03-23   Test2::Manual::Anatomy::Hubs(3)
Impressum