1Test2::IPC::Driver(3) User Contributed Perl DocumentationTest2::IPC::Driver(3)
2
6 Test2::IPC::Driver - Base class for Test2 IPC drivers.
7
9 package Test2::IPC::Driver::MyDriver;
10 use base 'Test2::IPC::Driver';
12 ...
14
16 $self->abort($msg)
17 If an IPC encounters a fatal error it should use this. This will
18 print the message to STDERR with 'IPC Fatal Error: ' prefixed to
19 it, then it will forcefully exit 255. IPC errors may occur in
20 threads or processes other than the main one, this method provides
21 the best chance of the harness noticing the error.
22 $self->abort_trace($msg)
24 This is the same as "$ipc->abort($msg)" except that it uses
25 "Carp::longmess" to add a stack trace to the message.
26
28 Test2::IPC::Driver has an import() method. All drivers inherit this
29 import method. This import method registers the driver.
30 In most cases you just need to load the desired IPC driver to make it
32 work. You should load this driver as early as possible. A warning will
33 be issued if you load it too late for it to be effective.
34 use Test2::IPC::Driver::MyDriver;
36 ...
37
39 package Test2::IPC::Driver::MyDriver;
40 use strict;
41 use warnings;
42 use base 'Test2::IPC::Driver';
44 sub is_viable {
46 return 0 if $^O eq 'win32'; # Will not work on windows.
47 return 1;
48 }
49 sub add_hub {
51 my $self = shift;
52 my ($hid) = @_;
53 ... # Make it possible to contact the hub
55 }
56 sub drop_hub {
58 my $self = shift;
59 my ($hid) = @_;
60 ... # Nothing should try to reach the hub anymore.
62 }
63 sub send {
65 my $self = shift;
66 my ($hid, $e, $global) = @_;
67 ... # Send the event to the proper hub.
69 # This may notify other procs/threads that there is a pending event.
71 Test2::API::test2_ipc_set_pending($uniq_val);
72 }
73 sub cull {
75 my $self = shift;
76 my ($hid) = @_;
77 my @events = ...; # Here is where you get the events for the hub
79 return @events;
81 }
82 sub waiting {
84 my $self = shift;
85 ... # Notify all listening procs and threads that the main
87 ... # process/thread is waiting for them to finish.
88 }
89 1;
91 METHODS SUBCLASSES MUST IMPLEMENT
93 $ipc->is_viable
94 This should return true if the driver works in the current
95 environment. This should return false if it does not. This is a
96 CLASS method.
97 $ipc->add_hub($hid)
99 This is used to alert the driver that a new hub is expecting
100 events. The driver should keep track of the process and thread ids,
101 the hub should only be dropped by the proc+thread that started it.
102 sub add_hub {
104 my $self = shift;
105 my ($hid) = @_;
106 ... # Make it possible to contact the hub
108 }
109 $ipc->drop_hub($hid)
111 This is used to alert the driver that a hub is no longer accepting
112 events. The driver should keep track of the process and thread ids,
113 the hub should only be dropped by the proc+thread that started it
114 (This is the drivers responsibility to enforce).
115 sub drop_hub {
117 my $self = shift;
118 my ($hid) = @_;
119 ... # Nothing should try to reach the hub anymore.
121 }
122 $ipc->send($hid, $event);
124 $ipc->send($hid, $event, $global);
125 Used to send events from the current process/thread to the
126 specified hub in its process+thread.
127 sub send {
129 my $self = shift;
130 my ($hid, $e) = @_;
131 ... # Send the event to the proper hub.
133 # This may notify other procs/threads that there is a pending event.
135 Test2::API::test2_ipc_set_pending($uniq_val);
136 }
137 If $global is true then the driver should send the event to all
139 hubs in all processes and threads.
140 @events = $ipc->cull($hid)
142 Used to collect events that have been sent to the specified hub.
143 sub cull {
145 my $self = shift;
146 my ($hid) = @_;
147 my @events = ...; # Here is where you get the events for the hub
149 return @events;
151 }
152 $ipc->waiting()
154 This is called in the parent process when it is complete and
155 waiting for all child processes and threads to complete.
156 sub waiting {
158 my $self = shift;
159 ... # Notify all listening procs and threads that the main
161 ... # process/thread is waiting for them to finish.
162 }
163 METHODS SUBCLASSES MAY IMPLEMENT OR OVERRIDE
165 $ipc->driver_abort($msg)
166 This is a hook called by "Test2::IPC::Driver->abort()". This is
167 your chance to cleanup when an abort happens. You cannot prevent
168 the abort, but you can gracefully except it.
169
171 The source code repository for Test2 can be found at
172 http://github.com/Test-More/test-more/.
173
175 Chad Granum <exodist@cpan.org>
176
178 Chad Granum <exodist@cpan.org>
179
181 Copyright 2020 Chad Granum <exodist@cpan.org>.
182 This program is free software; you can redistribute it and/or modify it
184 under the same terms as Perl itself.
185 See http://dev.perl.org/licenses/
187perl v5.38.0 2023-07-21 Test2::IPC::Driver(3)