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

LOADING DRIVERS

33       Test2::IPC::Driver has an "import()" method. All drivers inherit this
34       import method. This import method registers the driver.
35
36       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
40           use Test2::IPC::Driver::MyDriver;
41           ...
42

WRITING DRIVERS

44           package Test2::IPC::Driver::MyDriver;
45           use strict;
46           use warnings;
47
48           use base 'Test2::IPC::Driver';
49
50           sub is_viable {
51               return 0 if $^O eq 'win32'; # Will not work on windows.
52               return 1;
53           }
54
55           sub add_hub {
56               my $self = shift;
57               my ($hid) = @_;
58
59               ... # Make it possible to contact the hub
60           }
61
62           sub drop_hub {
63               my $self = shift;
64               my ($hid) = @_;
65
66               ... # Nothing should try to reach the hub anymore.
67           }
68
69           sub send {
70               my $self = shift;
71               my ($hid, $e, $global) = @_;
72
73               ... # Send the event to the proper hub.
74
75               # 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
80           sub cull {
81               my $self = shift;
82               my ($hid) = @_;
83
84               my @events = ...; # Here is where you get the events for the hub
85
86               return @events;
87           }
88
89           sub waiting {
90               my $self = shift;
91
92               ... # Notify all listening procs and threads that the main
93               ... # process/thread is waiting for them to finish.
94           }
95
96           1;
97
98   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
104       $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
109               sub add_hub {
110                   my $self = shift;
111                   my ($hid) = @_;
112
113                   ... # Make it possible to contact the hub
114               }
115
116       $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
122               sub drop_hub {
123                   my $self = shift;
124                   my ($hid) = @_;
125
126                   ... # Nothing should try to reach the hub anymore.
127               }
128
129       $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
134               sub send {
135                   my $self = shift;
136                   my ($hid, $e) = @_;
137
138                   ... # Send the event to the proper hub.
139
140                   # 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
145           If $global is true then the driver should send the event to all
146           hubs in all processes and threads.
147
148       @events = $ipc->cull($hid)
149           Used to collect events that have been sent to the specified hub.
150
151               sub cull {
152                   my $self = shift;
153                   my ($hid) = @_;
154
155                   my @events = ...; # Here is where you get the events for the hub
156
157                   return @events;
158               }
159
160       $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
164               sub waiting {
165                   my $self = shift;
166
167                   ... # Notify all listening procs and threads that the main
168                   ... # process/thread is waiting for them to finish.
169               }
170
171   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
177       $bool = $ipc->use_shm()
178           True if you want to make use of the Test2::API/Test2::API::Instance
179           SHM.
180
181       $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

SOURCE

187       The source code repository for Test2 can be found at
188       http://github.com/Test-More/test-more/.
189

MAINTAINERS

191       Chad Granum <exodist@cpan.org>
192

AUTHORS

194       Chad Granum <exodist@cpan.org>
195
197       Copyright 2018 Chad Granum <exodist@cpan.org>.
198
199       This program is free software; you can redistribute it and/or modify it
200       under the same terms as Perl itself.
201
202       See http://dev.perl.org/licenses/
203
204
205
206perl v5.28.0                      2018-08-13             Test2::IPC::Driver(3)
Impressum