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 $false = $self->use_shm
28 The base class always returns false for this method. You may
29 override it if you wish to use the SHM made available in
30 Test2::API/Test2::API::Instance.
31
33 Test2::IPC::Driver has an "import()" method. All drivers inherit this
34 import method. This import method registers the driver.
35 In most cases you just need to load the desired IPC driver to make it
37 work. You should load this driver as early as possible. A warning will
38 be issued if you load it too late for it to be effective.
39 use Test2::IPC::Driver::MyDriver;
41 ...
42
44 package Test2::IPC::Driver::MyDriver;
45 use strict;
46 use warnings;
47 use base 'Test2::IPC::Driver';
49 sub is_viable {
51 return 0 if $^O eq 'win32'; # Will not work on windows.
52 return 1;
53 }
54 sub add_hub {
56 my $self = shift;
57 my ($hid) = @_;
58 ... # Make it possible to contact the hub
60 }
61 sub drop_hub {
63 my $self = shift;
64 my ($hid) = @_;
65 ... # Nothing should try to reach the hub anymore.
67 }
68 sub send {
70 my $self = shift;
71 my ($hid, $e, $global) = @_;
72 ... # Send the event to the proper hub.
74 # If you are using the SHM you should notify other procs/threads that
76 # there is a pending event.
77 Test2::API::test2_ipc_set_pending($uniq_val);
78 }
79 sub cull {
81 my $self = shift;
82 my ($hid) = @_;
83 my @events = ...; # Here is where you get the events for the hub
85 return @events;
87 }
88 sub waiting {
90 my $self = shift;
91 ... # Notify all listening procs and threads that the main
93 ... # process/thread is waiting for them to finish.
94 }
95 1;
97 METHODS SUBCLASSES MUST IMPLEMENT
99 $ipc->is_viable
100 This should return true if the driver works in the current
101 environment. This should return false if it does not. This is a
102 CLASS method.
103 $ipc->add_hub($hid)
105 This is used to alert the driver that a new hub is expecting
106 events. The driver should keep track of the process and thread ids,
107 the hub should only be dropped by the proc+thread that started it.
108 sub add_hub {
110 my $self = shift;
111 my ($hid) = @_;
112 ... # Make it possible to contact the hub
114 }
115 $ipc->drop_hub($hid)
117 This is used to alert the driver that a hub is no longer accepting
118 events. The driver should keep track of the process and thread ids,
119 the hub should only be dropped by the proc+thread that started it
120 (This is the drivers responsibility to enforce).
121 sub drop_hub {
123 my $self = shift;
124 my ($hid) = @_;
125 ... # Nothing should try to reach the hub anymore.
127 }
128 $ipc->send($hid, $event);
130 $ipc->send($hid, $event, $global);
131 Used to send events from the current process/thread to the
132 specified hub in its process+thread.
133 sub send {
135 my $self = shift;
136 my ($hid, $e) = @_;
137 ... # Send the event to the proper hub.
139 # If you are using the SHM you should notify other procs/threads that
141 # there is a pending event.
142 Test2::API::test2_ipc_set_pending($uniq_val);
143 }
144 If $global is true then the driver should send the event to all
146 hubs in all processes and threads.
147 @events = $ipc->cull($hid)
149 Used to collect events that have been sent to the specified hub.
150 sub cull {
152 my $self = shift;
153 my ($hid) = @_;
154 my @events = ...; # Here is where you get the events for the hub
156 return @events;
158 }
159 $ipc->waiting()
161 This is called in the parent process when it is complete and
162 waiting for all child processes and threads to complete.
163 sub waiting {
165 my $self = shift;
166 ... # Notify all listening procs and threads that the main
168 ... # process/thread is waiting for them to finish.
169 }
170 METHODS SUBCLASSES MAY IMPLEMENT OR OVERRIDE
172 $ipc->driver_abort($msg)
173 This is a hook called by "Test2::IPC::Driver->abort()". This is
174 your chance to cleanup when an abort happens. You cannot prevent
175 the abort, but you can gracefully except it.
176 $bool = $ipc->use_shm()
178 True if you want to make use of the Test2::API/Test2::API::Instance
179 SHM.
180 $bites = $ipc->shm_size()
182 Use this to customize the size of the SHM space. There are no
183 guarantees about what the size will be if you do not implement
184 this.
185
187 The source code repository for Test2 can be found at
188 http://github.com/Test-More/test-more/.
189
191 Chad Granum <exodist@cpan.org>
192
194 Chad Granum <exodist@cpan.org>
195
197 Copyright 2018 Chad Granum <exodist@cpan.org>.
198 This program is free software; you can redistribute it and/or modify it
200 under the same terms as Perl itself.
201 See http://dev.perl.org/licenses/
203perl v5.28.0 2018-08-13 Test2::IPC::Driver(3)