Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::AsyncSubtest.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::AsyncSubtest 3pm"
61 .TH Test2::AsyncSubtest 3pm 2026-03-09 "perl v5.42.1" "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::AsyncSubtest \- Object representing an async subtest.
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 Regular subtests have a limited scope, they start, events are generated, then
71 they close and send an Test2::Event::Subtest event. This is a problem if you
72 want the subtest to keep receiving events while other events are also being
73 generated. This class implements subtests that stay open until you decide to
74 close them.
75 .PP
76 This is mainly useful for tools that start a subtest in one process and then
77 spawn children. In many cases it is nice to let the parent process continue
78 instead of waiting on the children.
79 .SH SYNOPSIS
80 .IX Header "SYNOPSIS"
81 .Vb 1
82 \& use Test2::AsyncSubtest;
83 \&
84 \& my $ast = Test2::AsyncSubtest\->new(name => foo);
85 \&
86 \& $ast\->run(sub {
87 \& ok(1, "Event in parent" );
88 \& });
89 \&
90 \& ok(1, "Event outside of subtest");
91 \&
92 \& $ast\->run_fork(sub {
93 \& ok(1, "Event in child process");
94 \& });
95 \&
96 \& ...
97 \&
98 \& $ast\->finish;
99 \&
100 \& done_testing;
101 .Ve
102 .SH CONSTRUCTION
103 .IX Header "CONSTRUCTION"
104 .Vb 1
105 \& my $ast = Test2::AsyncSubtest\->new( ... );
106 .Ve
107 .ie n .IP "name => $name (required)" 4
108 .el .IP "name => \f(CW$name\fR (required)" 4
109 .IX Item "name => $name (required)"
110 Name of the subtest. This construction argument is required.
111 .ie n .IP "send_to => $hub (optional)" 4
112 .el .IP "send_to => \f(CW$hub\fR (optional)" 4
113 .IX Item "send_to => $hub (optional)"
114 Hub to which the final subtest event should be sent. This must be an instance
115 of Test2::Hub or a subclass. If none is specified then the current top hub
116 will be used.
117 .ie n .IP "trace => $trace (optional)" 4
118 .el .IP "trace => \f(CW$trace\fR (optional)" 4
119 .IX Item "trace => $trace (optional)"
120 File/Line to which errors should be attributed. This must be an instance of
121 Test2::Util::Trace. If none is specified then the file/line where the
122 constructor was called will be used.
123 .ie n .IP "hub => $hub (optional)" 4
124 .el .IP "hub => \f(CW$hub\fR (optional)" 4
125 .IX Item "hub => $hub (optional)"
126 Use this to specify a hub the subtest should use. By default a new hub is
127 generated. This must be an instance of Test2::AsyncSubtest::Hub.
128 .SH METHODS
129 .IX Header "METHODS"
130 .SS "SIMPLE ACCESSORS"
131 .IX Subsection "SIMPLE ACCESSORS"
132 .ie n .IP "$bool = $ast\->active" 4
133 .el .IP "\f(CW$bool\fR = \f(CW$ast\fR\->active" 4
134 .IX Item "$bool = $ast->active"
135 True if the subtest is active. The subtest is active if its hub appears in the
136 global hub stack. This is true when \f(CW\*(C`$ast\->run(...)\*(C'\fR us running.
137 .ie n .IP "$arrayref = $ast\->children" 4
138 .el .IP "\f(CW$arrayref\fR = \f(CW$ast\fR\->children" 4
139 .IX Item "$arrayref = $ast->children"
140 Get an arrayref of child processes/threads. Numerical items are PIDs, blessed
141 items are threads instances.
142 .ie n .IP "$arrayref = $ast\->events" 4
143 .el .IP "\f(CW$arrayref\fR = \f(CW$ast\fR\->events" 4
144 .IX Item "$arrayref = $ast->events"
145 Get an arrayref of events that have been sent to the subtests hub.
146 .ie n .IP "$bool = $ast\->finished" 4
147 .el .IP "\f(CW$bool\fR = \f(CW$ast\fR\->finished" 4
148 .IX Item "$bool = $ast->finished"
149 True if \f(CWfinished()\fR has already been called.
150 .ie n .IP "$hub = $ast\->hub" 4
151 .el .IP "\f(CW$hub\fR = \f(CW$ast\fR\->hub" 4
152 .IX Item "$hub = $ast->hub"
153 The hub created for the subtest.
154 .ie n .IP "$int = $ast\->id" 4
155 .el .IP "\f(CW$int\fR = \f(CW$ast\fR\->id" 4
156 .IX Item "$int = $ast->id"
157 Attach/Detach counter. Used internally, not useful to users.
158 .ie n .IP "$str = $ast\->name" 4
159 .el .IP "\f(CW$str\fR = \f(CW$ast\fR\->name" 4
160 .IX Item "$str = $ast->name"
161 Name of the subtest.
162 .ie n .IP "$pid = $ast\->pid" 4
163 .el .IP "\f(CW$pid\fR = \f(CW$ast\fR\->pid" 4
164 .IX Item "$pid = $ast->pid"
165 PID in which the subtest was created.
166 .ie n .IP "$tid = $ast\->tid" 4
167 .el .IP "\f(CW$tid\fR = \f(CW$ast\fR\->tid" 4
168 .IX Item "$tid = $ast->tid"
169 Thread ID in which the subtest was created.
170 .ie n .IP "$hub = $ast\->send_to" 4
171 .el .IP "\f(CW$hub\fR = \f(CW$ast\fR\->send_to" 4
172 .IX Item "$hub = $ast->send_to"
173 Hub to which the final subtest event should be sent.
174 .ie n .IP "$arrayref = $ast\->stack" 4
175 .el .IP "\f(CW$arrayref\fR = \f(CW$ast\fR\->stack" 4
176 .IX Item "$arrayref = $ast->stack"
177 Stack of async subtests at the time this one was created. This is mainly for
178 internal use.
179 .ie n .IP "$trace = $ast\->trace" 4
180 .el .IP "\f(CW$trace\fR = \f(CW$ast\fR\->trace" 4
181 .IX Item "$trace = $ast->trace"
182 Test2::Util::Trace instance used for error reporting.
183 .SS INTERFACE
184 .IX Subsection "INTERFACE"
185 .ie n .IP $ast\->attach($id) 4
186 .el .IP \f(CW$ast\fR\->attach($id) 4
187 .IX Item "$ast->attach($id)"
188 Attach a subtest in a child/process to the original.
189 .Sp
190 \&\fBNote:\fR \f(CW\*(C`my $id = $ast\->cleave\*(C'\fR must have been called in the parent
191 process/thread before the child was started, the id it returns must be used in
192 the call to \f(CW\*(C`$ast\->attach($id)\*(C'\fR
193 .ie n .IP "$id = $ast\->cleave" 4
194 .el .IP "\f(CW$id\fR = \f(CW$ast\fR\->cleave" 4
195 .IX Item "$id = $ast->cleave"
196 Prepare a slot for a child process/thread to attach. This must be called BEFORE
197 the child process or thread is started. The ID returned is used by \f(CWattach()\fR.
198 .Sp
199 This must only be called in the original process/thread.
200 .ie n .IP "$ctx = $ast\->context" 4
201 .el .IP "\f(CW$ctx\fR = \f(CW$ast\fR\->context" 4
202 .IX Item "$ctx = $ast->context"
203 Get an Test2::API::Context instance that can be used to send events to the
204 context in which the hub was created. This is not a canonical context, you
205 should not call \f(CW\*(C`$ctx\->release\*(C'\fR on it.
206 .ie n .IP $ast\->detach 4
207 .el .IP \f(CW$ast\fR\->detach 4
208 .IX Item "$ast->detach"
209 Detach from the parent in a child process/thread. This should be called just
210 before the child exits.
211 .ie n .IP $ast\->finish 4
212 .el .IP \f(CW$ast\fR\->finish 4
213 .IX Item "$ast->finish"
214 .PD 0
215 .ie n .IP $ast\->finish(%options) 4
216 .el .IP \f(CW$ast\fR\->finish(%options) 4
217 .IX Item "$ast->finish(%options)"
218 .PD
219 Finish the subtest, wait on children, and send the final subtest event.
220 .Sp
221 This must only be called in the original process/thread.
222 .Sp
223 \&\fBNote:\fR This calls \f(CW\*(C`$ast\->wait\*(C'\fR.
224 .Sp
225 These are the options:
226 .RS 4
227 .IP "collapse => 1" 4
228 .IX Item "collapse => 1"
229 This intelligently allows a subtest to be empty.
230 .Sp
231 If no events bump the test count then the subtest no final plan will be added.
232 The subtest will not be considered a failure (normally an empty subtest is a
233 failure).
234 .Sp
235 If there are no events at all the subtest will be collapsed into an
236 Test2::Event::Ok event.
237 .IP "silent => 1" 4
238 .IX Item "silent => 1"
239 This will prevent finish from generating a final Test2::Event::Subtest
240 event. This effectively ends the subtest without it affecting the parent
241 subtest (or top level test).
242 .IP "no_plan => 1" 4
243 .IX Item "no_plan => 1"
244 This will prevent a final plan from being added to the subtest for you when
245 none is directly specified.
246 .IP "skip => ""reason""" 4
247 .IX Item "skip => ""reason"""
248 This will issue an Test2::Event::Skip instead of a subtest. This will throw
249 an exception if any events have been seen, or if state implies events have
250 occurred.
251 .RE
252 .RS 4
253 .RE
254 .ie n .IP "$out = $ast\->fork" 4
255 .el .IP "\f(CW$out\fR = \f(CW$ast\fR\->fork" 4
256 .IX Item "$out = $ast->fork"
257 This is a slightly higher level interface to fork. Running it will fork your
258 code in\-place just like \f(CWfork()\fR. It will return a pid in the parent, and an
259 Test2::Util::Guard instance in the child. An exception will be thrown if
260 fork fails.
261 .Sp
262 It is recommended that you use \f(CW\*(C`$ast\->run_fork(sub { ... })\*(C'\fR instead.
263 .ie n .IP "$bool = $ast\->pending" 4
264 .el .IP "\f(CW$bool\fR = \f(CW$ast\fR\->pending" 4
265 .IX Item "$bool = $ast->pending"
266 True if there are child processes, threads, or subtests that depend on this
267 one.
268 .ie n .IP "$bool = $ast\->ready" 4
269 .el .IP "\f(CW$bool\fR = \f(CW$ast\fR\->ready" 4
270 .IX Item "$bool = $ast->ready"
271 This is essentially \f(CW\*(C`!$ast\->pending\*(C'\fR.
272 .ie n .IP "$ast\->run(sub { ... })" 4
273 .el .IP "\f(CW$ast\fR\->run(sub { ... })" 4
274 .IX Item "$ast->run(sub { ... })"
275 Run the provided codeblock inside the subtest. This will push the subtest hub
276 onto the stack, run the code, then pop the hub off the stack.
277 .ie n .IP "$pid = $ast\->run_fork(sub { ... })" 4
278 .el .IP "\f(CW$pid\fR = \f(CW$ast\fR\->run_fork(sub { ... })" 4
279 .IX Item "$pid = $ast->run_fork(sub { ... })"
280 Same as \f(CW\*(C`$ast\->run()\*(C'\fR, except that the codeblock is run in a child
281 process.
282 .Sp
283 You do not need to directly call \f(CWwait($pid)\fR, that will be done for you when
284 \&\f(CW\*(C`$ast\->wait\*(C'\fR, or \f(CW\*(C`$ast\->finish\*(C'\fR are called.
285 .ie n .IP "my $thr = $ast\->run_thread(sub { ... });" 4
286 .el .IP "my \f(CW$thr\fR = \f(CW$ast\fR\->run_thread(sub { ... });" 4
287 .IX Item "my $thr = $ast->run_thread(sub { ... });"
288 \&\fB** DISCOURAGED **\fR Threads cause problems. This method remains for anyone who
289 REALLY wants it, but it is no longer supported. Tests for this functionality do
290 not even run unless the AUTHOR_TESTING or T2_DO_THREAD_TESTS env vars are
291 enabled.
292 .Sp
293 Same as \f(CW\*(C`$ast\->run()\*(C'\fR, except that the codeblock is run in a child
294 thread.
295 .Sp
296 You do not need to directly call \f(CW\*(C`$thr\->join\*(C'\fR, that is done for you when
297 \&\f(CW\*(C`$ast\->wait\*(C'\fR, or \f(CW\*(C`$ast\->finish\*(C'\fR are called.
298 .ie n .IP "$passing = $ast\->start" 4
299 .el .IP "\f(CW$passing\fR = \f(CW$ast\fR\->start" 4
300 .IX Item "$passing = $ast->start"
301 Push the subtest hub onto the stack. Returns the current pass/fail status of
302 the subtest.
303 .ie n .IP $ast\->stop 4
304 .el .IP \f(CW$ast\fR\->stop 4
305 .IX Item "$ast->stop"
306 Pop the subtest hub off the stack. Returns the current pass/fail status of the
307 subtest.
308 .ie n .IP $ast\->wait 4
309 .el .IP \f(CW$ast\fR\->wait 4
310 .IX Item "$ast->wait"
311 Wait on all threads/processes that were started using \f(CW\*(C`$ast\->fork\*(C'\fR,
312 \&\f(CW\*(C`$ast\->run_fork\*(C'\fR, or \f(CW\*(C`$ast\->run_thread\*(C'\fR.
313 .SH SOURCE
314 .IX Header "SOURCE"
315 The source code repository for Test2\-AsyncSubtest can be found at
316 \&\fIhttps://github.com/Test\-More/test\-more/\fR.
317 .SH MAINTAINERS
318 .IX Header "MAINTAINERS"
319 .IP "Chad Granum <[email protected]>" 4
320 .IX Item "Chad Granum <[email protected]>"
321 .SH AUTHORS
322 .IX Header "AUTHORS"
323 .IP "Chad Granum <[email protected]>" 4
324 .IX Item "Chad Granum <[email protected]>"
325 .SH COPYRIGHT
326 .IX Header "COPYRIGHT"
327 Copyright Chad Granum <[email protected]>.
328 .PP
329 This program is free software; you can redistribute it and/or
330 modify it under the same terms as Perl itself.
331 .PP
332 See \fIhttp://dev.perl.org/licenses/\fR