1Test2::IPC::Driver(3) User Contributed Perl DocumentationTest2::IPC::Driver(3)
2
3
4

NAME

6       Test2::IPC::Driver - Base class for Test2 IPC drivers.
7

SYNOPSIS

9           package Test2::IPC::Driver::MyDriver;
10
11           use base 'Test2::IPC::Driver';
12
13           ...
14

METHODS

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
23       $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

LOADING DRIVERS

28       Test2::IPC::Driver has an import() method. All drivers inherit this
29       import method. This import method registers the driver.
30
31       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
35           use Test2::IPC::Driver::MyDriver;
36           ...
37

WRITING DRIVERS

39           package Test2::IPC::Driver::MyDriver;
40           use strict;
41           use warnings;
42
43           use base 'Test2::IPC::Driver';
44
45           sub is_viable {
46               return 0 if $^O eq 'win32'; # Will not work on windows.
47               return 1;
48           }
49
50           sub add_hub {
51               my $self = shift;
52               my ($hid) = @_;
53
54               ... # Make it possible to contact the hub
55           }
56
57           sub drop_hub {
58               my $self = shift;
59               my ($hid) = @_;
60
61               ... # Nothing should try to reach the hub anymore.
62           }
63
64           sub send {
65               my $self = shift;
66               my ($hid, $e, $global) = @_;
67
68               ... # Send the event to the proper hub.
69
70               # This may notify other procs/threads that there is a pending event.
71               Test2::API::test2_ipc_set_pending($uniq_val);
72           }
73
74           sub cull {
75               my $self = shift;
76               my ($hid) = @_;
77
78               my @events = ...; # Here is where you get the events for the hub
79
80               return @events;
81           }
82
83           sub waiting {
84               my $self = shift;
85
86               ... # Notify all listening procs and threads that the main
87               ... # process/thread is waiting for them to finish.
88           }
89
90           1;
91
92   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
98       $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
103               sub add_hub {
104                   my $self = shift;
105                   my ($hid) = @_;
106
107                   ... # Make it possible to contact the hub
108               }
109
110       $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
116               sub drop_hub {
117                   my $self = shift;
118                   my ($hid) = @_;
119
120                   ... # Nothing should try to reach the hub anymore.
121               }
122
123       $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
128               sub send {
129                   my $self = shift;
130                   my ($hid, $e) = @_;
131
132                   ... # Send the event to the proper hub.
133
134                   # This may notify other procs/threads that there is a pending event.
135                   Test2::API::test2_ipc_set_pending($uniq_val);
136               }
137
138           If $global is true then the driver should send the event to all
139           hubs in all processes and threads.
140
141       @events = $ipc->cull($hid)
142           Used to collect events that have been sent to the specified hub.
143
144               sub cull {
145                   my $self = shift;
146                   my ($hid) = @_;
147
148                   my @events = ...; # Here is where you get the events for the hub
149
150                   return @events;
151               }
152
153       $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
157               sub waiting {
158                   my $self = shift;
159
160                   ... # Notify all listening procs and threads that the main
161                   ... # process/thread is waiting for them to finish.
162               }
163
164   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

SOURCE

171       The source code repository for Test2 can be found at
172       http://github.com/Test-More/test-more/.
173

MAINTAINERS

175       Chad Granum <exodist@cpan.org>
176

AUTHORS

178       Chad Granum <exodist@cpan.org>
179
181       Copyright 2020 Chad Granum <exodist@cpan.org>.
182
183       This program is free software; you can redistribute it and/or modify it
184       under the same terms as Perl itself.
185
186       See http://dev.perl.org/licenses/
187
188
189
190perl v5.36.0                      2023-03-15             Test2::IPC::Driver(3)
Impressum