Debian Codegraph @

upstream/mageia-cauldron/man3pm/Test2::IPC::Driver.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Test2::IPC::Driver 3pm"
61 .TH Test2::IPC::Driver 3pm 2025-06-24 "perl v5.42.0" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Test2::IPC::Driver \- Base class for Test2 IPC drivers.
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& package Test2::IPC::Driver::MyDriver;
72 \&
73 \& use base \*(AqTest2::IPC::Driver\*(Aq;
74 \&
75 \& ...
76 .Ve
77 .SH METHODS
78 .IX Header "METHODS"
79 .ie n .IP $self\->abort($msg) 4
80 .el .IP \f(CW$self\fR\->abort($msg) 4
81 .IX Item "$self->abort($msg)"
82 If an IPC encounters a fatal error it should use this. This will print the
83 message to STDERR with \f(CW\*(AqIPC Fatal Error: \*(Aq\fR prefixed to it, then it will
84 forcefully exit 255. IPC errors may occur in threads or processes other than
85 the main one, this method provides the best chance of the harness noticing the
86 error.
87 .ie n .IP $self\->abort_trace($msg) 4
88 .el .IP \f(CW$self\fR\->abort_trace($msg) 4
89 .IX Item "$self->abort_trace($msg)"
90 This is the same as \f(CW\*(C`$ipc\->abort($msg)\*(C'\fR except that it uses
91 \&\f(CW\*(C`Carp::longmess\*(C'\fR to add a stack trace to the message.
92 .SH "LOADING DRIVERS"
93 .IX Header "LOADING DRIVERS"
94 Test2::IPC::Driver has an \f(CWimport()\fR method. All drivers inherit this import
95 method. This import method registers the driver.
96 .PP
97 In most cases you just need to load the desired IPC driver to make it work. You
98 should load this driver as early as possible. A warning will be issued if you
99 load it too late for it to be effective.
100 .PP
101 .Vb 2
102 \& use Test2::IPC::Driver::MyDriver;
103 \& ...
104 .Ve
105 .SH "WRITING DRIVERS"
106 .IX Header "WRITING DRIVERS"
107 .Vb 3
108 \& package Test2::IPC::Driver::MyDriver;
109 \& use strict;
110 \& use warnings;
111 \&
112 \& use base \*(AqTest2::IPC::Driver\*(Aq;
113 \&
114 \& sub is_viable {
115 \& return 0 if $^O eq \*(Aqwin32\*(Aq; # Will not work on windows.
116 \& return 1;
117 \& }
118 \&
119 \& sub add_hub {
120 \& my $self = shift;
121 \& my ($hid) = @_;
122 \&
123 \& ... # Make it possible to contact the hub
124 \& }
125 \&
126 \& sub drop_hub {
127 \& my $self = shift;
128 \& my ($hid) = @_;
129 \&
130 \& ... # Nothing should try to reach the hub anymore.
131 \& }
132 \&
133 \& sub send {
134 \& my $self = shift;
135 \& my ($hid, $e, $global) = @_;
136 \&
137 \& ... # Send the event to the proper hub.
138 \&
139 \& # This may notify other procs/threads that there is a pending event.
140 \& Test2::API::test2_ipc_set_pending($uniq_val);
141 \& }
142 \&
143 \& sub cull {
144 \& my $self = shift;
145 \& my ($hid) = @_;
146 \&
147 \& my @events = ...; # Here is where you get the events for the hub
148 \&
149 \& return @events;
150 \& }
151 \&
152 \& sub waiting {
153 \& my $self = shift;
154 \&
155 \& ... # Notify all listening procs and threads that the main
156 \& ... # process/thread is waiting for them to finish.
157 \& }
158 \&
159 \& 1;
160 .Ve
161 .SS "METHODS SUBCLASSES MUST IMPLEMENT"
162 .IX Subsection "METHODS SUBCLASSES MUST IMPLEMENT"
163 .ie n .IP $ipc\->is_viable 4
164 .el .IP \f(CW$ipc\fR\->is_viable 4
165 .IX Item "$ipc->is_viable"
166 This should return true if the driver works in the current environment. This
167 should return false if it does not. This is a CLASS method.
168 .ie n .IP $ipc\->add_hub($hid) 4
169 .el .IP \f(CW$ipc\fR\->add_hub($hid) 4
170 .IX Item "$ipc->add_hub($hid)"
171 This is used to alert the driver that a new hub is expecting events. The driver
172 should keep track of the process and thread ids, the hub should only be dropped
173 by the proc+thread that started it.
174 .Sp
175 .Vb 3
176 \& sub add_hub {
177 \& my $self = shift;
178 \& my ($hid) = @_;
179 \&
180 \& ... # Make it possible to contact the hub
181 \& }
182 .Ve
183 .ie n .IP $ipc\->drop_hub($hid) 4
184 .el .IP \f(CW$ipc\fR\->drop_hub($hid) 4
185 .IX Item "$ipc->drop_hub($hid)"
186 This is used to alert the driver that a hub is no longer accepting events. The
187 driver should keep track of the process and thread ids, the hub should only be
188 dropped by the proc+thread that started it (This is the drivers responsibility
189 to enforce).
190 .Sp
191 .Vb 3
192 \& sub drop_hub {
193 \& my $self = shift;
194 \& my ($hid) = @_;
195 \&
196 \& ... # Nothing should try to reach the hub anymore.
197 \& }
198 .Ve
199 .ie n .IP "$ipc\->send($hid, $event);" 4
200 .el .IP "\f(CW$ipc\fR\->send($hid, \f(CW$event\fR);" 4
201 .IX Item "$ipc->send($hid, $event);"
202 .PD 0
203 .ie n .IP "$ipc\->send($hid, $event, $global);" 4
204 .el .IP "\f(CW$ipc\fR\->send($hid, \f(CW$event\fR, \f(CW$global\fR);" 4
205 .IX Item "$ipc->send($hid, $event, $global);"
206 .PD
207 Used to send events from the current process/thread to the specified hub in its
208 process+thread.
209 .Sp
210 .Vb 3
211 \& sub send {
212 \& my $self = shift;
213 \& my ($hid, $e) = @_;
214 \&
215 \& ... # Send the event to the proper hub.
216 \&
217 \& # This may notify other procs/threads that there is a pending event.
218 \& Test2::API::test2_ipc_set_pending($uniq_val);
219 \& }
220 .Ve
221 .Sp
222 If \f(CW$global\fR is true then the driver should send the event to all hubs in all
223 processes and threads.
224 .ie n .IP "@events = $ipc\->cull($hid)" 4
225 .el .IP "\f(CW@events\fR = \f(CW$ipc\fR\->cull($hid)" 4
226 .IX Item "@events = $ipc->cull($hid)"
227 Used to collect events that have been sent to the specified hub.
228 .Sp
229 .Vb 3
230 \& sub cull {
231 \& my $self = shift;
232 \& my ($hid) = @_;
233 \&
234 \& my @events = ...; # Here is where you get the events for the hub
235 \&
236 \& return @events;
237 \& }
238 .Ve
239 .ie n .IP $ipc\->\fBwaiting()\fR 4
240 .el .IP \f(CW$ipc\fR\->\fBwaiting()\fR 4
241 .IX Item "$ipc->waiting()"
242 This is called in the parent process when it is complete and waiting for all
243 child processes and threads to complete.
244 .Sp
245 .Vb 2
246 \& sub waiting {
247 \& my $self = shift;
248 \&
249 \& ... # Notify all listening procs and threads that the main
250 \& ... # process/thread is waiting for them to finish.
251 \& }
252 .Ve
253 .SS "METHODS SUBCLASSES MAY IMPLEMENT OR OVERRIDE"
254 .IX Subsection "METHODS SUBCLASSES MAY IMPLEMENT OR OVERRIDE"
255 .ie n .IP $ipc\->driver_abort($msg) 4
256 .el .IP \f(CW$ipc\fR\->driver_abort($msg) 4
257 .IX Item "$ipc->driver_abort($msg)"
258 This is a hook called by \f(CW\*(C`Test2::IPC::Driver\->abort()\*(C'\fR. This is your
259 chance to cleanup when an abort happens. You cannot prevent the abort, but you
260 can gracefully except it.
261 .SH SOURCE
262 .IX Header "SOURCE"
263 The source code repository for Test2 can be found at
264 <https://github.com/Test\-More/test\-more/>.
265 .SH MAINTAINERS
266 .IX Header "MAINTAINERS"
267 .IP "Chad Granum <[email protected]>" 4
268 .IX Item "Chad Granum <[email protected]>"
269 .SH AUTHORS
270 .IX Header "AUTHORS"
271 .IP "Chad Granum <[email protected]>" 4
272 .IX Item "Chad Granum <[email protected]>"
273 .SH COPYRIGHT
274 .IX Header "COPYRIGHT"
275 Copyright Chad Granum <[email protected]>.
276 .PP
277 This program is free software; you can redistribute it and/or
278 modify it under the same terms as Perl itself.
279 .PP
280 See <https://dev.perl.org/licenses/>