1Test::Stream::IPC(3)  User Contributed Perl Documentation Test::Stream::IPC(3)
2
3
4

NAME

6       Test::Stream::IPC - Base class for Test::Stream IPC drivers.
7

DEPRECATED

9       This distribution is deprecated in favor of Test2, Test2::Suite, and
10       Test2::Workflow.
11
12       See Test::Stream::Manual::ToTest2 for a conversion guide.
13

SYNOPSIS

15           package Test::Stream::IPC::MyDriver;
16
17           use base 'Test::Stream::IPC';
18
19           ...
20

CLASS METHODS

22       @drivers = $class->drivers
23           Obtain the list of drivers that have been registered, in the order
24           they were registered. If no driver has been loaded this will load,
25           register, and return Test::Stream::IPC::Files.
26
27       $class->register_driver($DRIVER)
28           This is an alias to "register_driver"
29
30       $class->register_drivers($DRIVER1, $DRIVER2)
31           Use this to register an IPC driver. The driver shoudl already be
32           loaded.
33
34       $class->enable_polling
35           This turns on IPC polling. Essentially this adds a global callback
36           on context initialization. Every time a context is obtained from
37           Test::Stream::Context the IPC driver will have a chance to poll for
38           pending events.
39
40           This can only be turned on once, and it can not be turned off. The
41           effects are global.
42

INSTANCE METHODS

44       $self->abort($msg)
45           If an IPC encounters a fatal error it should use this. This will
46           print the message to STDERR with 'IPC Fatal Error: ' prefixed to
47           it, then it will forcefully exit 255. IPC errors may occur in
48           threads or processes other than the main one, this method provides
49           the best chance of the harness noticing the error.
50
51       $self->abort_trace($msg)
52           This is the same as "$ipc->abort($msg)" except that it uses
53           "Carp::longmess" to add a stack trace to the message.
54

LOADING DRIVERS

56       Test::Stream::IPC has an "import()" method. All drivers inherit this
57       import method. This import method registers the driver with the main
58       IPC module.
59
60       In most cases you just need to load the desired IPC driver to make it
61       work. You should load this driver as early as possible. A warning will
62       be issued if you load it too late for it to be effective.
63
64           use Test::Stream::IPC::MyDriver;
65           ...
66

WRITING DRIVERS

68           package Test::Stream::IPC::MyDriver;
69           use strict;
70           use warnings;
71
72           use base 'Test::Stream::IPC';
73
74           sub is_viable {
75               return 0 if $^O eq 'win32'; # Will not work on windows.
76               return 1;
77           }
78
79           sub add_hub {
80               my $self = shift;
81               my ($hid) = @_;
82
83               ... # Make it possible to contact the hub
84           }
85
86           sub drop_hub {
87               my $self = shift;
88               my ($hid) = @_;
89
90               ... # Nothing should try to reach the hub anymore.
91           }
92
93           sub send {
94               my $self = shift;
95               my ($hid, $e) = @_;
96
97               ... # Send the event to the proper hub.
98           }
99
100           sub cull {
101               my $self = shift;
102               my ($hid) = @_;
103
104               my @events = ...; # Here is where you get the events for the hub
105
106               return @events;
107           }
108
109           sub waiting {
110               my $self = shift;
111
112               ... # Notify all listening procs and threads that the main
113               ... # process/thread is waiting for them to finish.
114           }
115
116           1;
117
118   METHODS SUBCLASSES MUST IMPLEMENT
119       $ipc->is_viable
120           This should return true if the driver works in the current
121           environment. This should return false if it does not. This is a
122           CLASS method.
123
124       $ipc->add_hub($hid)
125           This is used to alert the driver that a new hub is expecting
126           events. The driver should keep track of the process and thread ids,
127           the hub should only be dropped by the proc+thread that started it.
128
129               sub add_hub {
130                   my $self = shift;
131                   my ($hid) = @_;
132
133                   ... # Make it possible to contact the hub
134               }
135
136       $ipc->drop_hub($hid)
137           This is used to alert the driver that a hub is no longer accepting
138           events. The driver should keep track of the process and thread ids,
139           the hub should only be dropped by the proc+thread that started it
140           (This is the drivers responsibility to enforce).
141
142               sub drop_hub {
143                   my $self = shift;
144                   my ($hid) = @_;
145
146                   ... # Nothing should try to reach the hub anymore.
147               }
148
149       $ipc->send($hid, $event);
150           Used to send events from the current process/thread to the
151           specified hub in its process+thread.
152
153               sub send {
154                   my $self = shift;
155                   my ($hid, $e) = @_;
156
157                   ... # Send the event to the proper hub.
158               }
159
160       @events = $ipc->cull($hid)
161           Used to collect events that have been sent to the specified hub.
162
163               sub cull {
164                   my $self = shift;
165                   my ($hid) = @_;
166
167                   my @events = ...; # Here is where you get the events for the hub
168
169                   return @events;
170               }
171
172       $ipc->waiting()
173           This is called in the parent process when it is complete and
174           waiting for all child processes and threads to complete.
175
176               sub waiting {
177                   my $self = shift;
178
179                   ... # Notify all listening procs and threads that the main
180                   ... # process/thread is waiting for them to finish.
181               }
182

SOURCE

184       The source code repository for Test::Stream can be found at
185       http://github.com/Test-More/Test-Stream/.
186

MAINTAINERS

188       Chad Granum <exodist@cpan.org>
189

AUTHORS

191       Chad Granum <exodist@cpan.org>
192
194       Copyright 2015 Chad Granum <exodist7@gmail.com>.
195
196       This program is free software; you can redistribute it and/or modify it
197       under the same terms as Perl itself.
198
199       See http://dev.perl.org/licenses/
200
201
202
203perl v5.34.0                      2022-01-21              Test::Stream::IPC(3)
Impressum