Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Test2::API::Instance.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::API::Instance 3pm"
61 .TH Test2::API::Instance 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::API::Instance \- Object used by Test2::API under the hood
68 .SH DESCRIPTION
69 .IX Header "DESCRIPTION"
70 This object encapsulates the global shared state tracked by
71 Test2. A single global instance of this package is stored (and
72 obscured) by the Test2::API package.
73 .PP
74 There is no reason to directly use this package. This package is documented for
75 completeness. This package can change, or go away completely at any time.
76 Directly using, or monkeypatching this package is not supported in any way
77 shape or form.
78 .SH SYNOPSIS
79 .IX Header "SYNOPSIS"
80 .Vb 1
81 \& use Test2::API::Instance;
82 \&
83 \& my $obj = Test2::API::Instance\->new;
84 .Ve
85 .ie n .IP "$pid = $obj\->pid" 4
86 .el .IP "\f(CW$pid\fR = \f(CW$obj\fR\->pid" 4
87 .IX Item "$pid = $obj->pid"
88 PID of this instance.
89 .ie n .IP $obj\->tid 4
90 .el .IP \f(CW$obj\fR\->tid 4
91 .IX Item "$obj->tid"
92 Thread ID of this instance.
93 .ie n .IP $obj\->\fBreset()\fR 4
94 .el .IP \f(CW$obj\fR\->\fBreset()\fR 4
95 .IX Item "$obj->reset()"
96 Reset the object to defaults.
97 .ie n .IP $obj\->\fBload()\fR 4
98 .el .IP \f(CW$obj\fR\->\fBload()\fR 4
99 .IX Item "$obj->load()"
100 Set the internal state to loaded, and run and stored post\-load callbacks.
101 .ie n .IP "$bool = $obj\->loaded" 4
102 .el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->loaded" 4
103 .IX Item "$bool = $obj->loaded"
104 Check if the state is set to loaded.
105 .ie n .IP "$arrayref = $obj\->post_load_callbacks" 4
106 .el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->post_load_callbacks" 4
107 .IX Item "$arrayref = $obj->post_load_callbacks"
108 Get the post\-load callbacks.
109 .ie n .IP "$obj\->add_post_load_callback(sub { ... })" 4
110 .el .IP "\f(CW$obj\fR\->add_post_load_callback(sub { ... })" 4
111 .IX Item "$obj->add_post_load_callback(sub { ... })"
112 Add a post\-load callback. If \f(CWload()\fR has already been called then the callback will
113 be immediately executed. If \f(CWload()\fR has not been called then the callback will be
114 stored and executed later when \f(CWload()\fR is called.
115 .ie n .IP "$hashref = $obj\->\fBcontexts()\fR" 4
116 .el .IP "\f(CW$hashref\fR = \f(CW$obj\fR\->\fBcontexts()\fR" 4
117 .IX Item "$hashref = $obj->contexts()"
118 Get a hashref of all active contexts keyed by hub id.
119 .ie n .IP "$arrayref = $obj\->context_acquire_callbacks" 4
120 .el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->context_acquire_callbacks" 4
121 .IX Item "$arrayref = $obj->context_acquire_callbacks"
122 Get all context acquire callbacks.
123 .ie n .IP "$arrayref = $obj\->context_init_callbacks" 4
124 .el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->context_init_callbacks" 4
125 .IX Item "$arrayref = $obj->context_init_callbacks"
126 Get all context init callbacks.
127 .ie n .IP "$arrayref = $obj\->context_release_callbacks" 4
128 .el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->context_release_callbacks" 4
129 .IX Item "$arrayref = $obj->context_release_callbacks"
130 Get all context release callbacks.
131 .ie n .IP "$arrayref = $obj\->pre_subtest_callbacks" 4
132 .el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->pre_subtest_callbacks" 4
133 .IX Item "$arrayref = $obj->pre_subtest_callbacks"
134 Get all pre\-subtest callbacks.
135 .ie n .IP "$obj\->add_context_init_callback(sub { ... })" 4
136 .el .IP "\f(CW$obj\fR\->add_context_init_callback(sub { ... })" 4
137 .IX Item "$obj->add_context_init_callback(sub { ... })"
138 Add a context init callback. Subs are called every time a context is created. Subs
139 get the newly created context as their only argument.
140 .ie n .IP "$obj\->add_context_release_callback(sub { ... })" 4
141 .el .IP "\f(CW$obj\fR\->add_context_release_callback(sub { ... })" 4
142 .IX Item "$obj->add_context_release_callback(sub { ... })"
143 Add a context release callback. Subs are called every time a context is released. Subs
144 get the released context as their only argument. These callbacks should not
145 call release on the context.
146 .ie n .IP "$obj\->add_pre_subtest_callback(sub { ... })" 4
147 .el .IP "\f(CW$obj\fR\->add_pre_subtest_callback(sub { ... })" 4
148 .IX Item "$obj->add_pre_subtest_callback(sub { ... })"
149 Add a pre\-subtest callback. Subs are called every time a subtest is
150 going to be run. Subs get the subtest name, coderef, and any
151 arguments.
152 .ie n .IP $obj\->\fBset_exit()\fR 4
153 .el .IP \f(CW$obj\fR\->\fBset_exit()\fR 4
154 .IX Item "$obj->set_exit()"
155 This is intended to be called in an \f(CW\*(C`END { ... }\*(C'\fR block. This will look at
156 test state and set $?. This will also call any end callbacks, and wait on child
157 processes/threads.
158 .ie n .IP $obj\->set_ipc_pending($val) 4
159 .el .IP \f(CW$obj\fR\->set_ipc_pending($val) 4
160 .IX Item "$obj->set_ipc_pending($val)"
161 Tell other processes and threads there is a pending event. \f(CW$val\fR should be a
162 unique value no other thread/process will generate.
163 .Sp
164 \&\fBNote:\fR This will also make the current process see a pending event.
165 .ie n .IP "$pending = $obj\->\fBget_ipc_pending()\fR" 4
166 .el .IP "\f(CW$pending\fR = \f(CW$obj\fR\->\fBget_ipc_pending()\fR" 4
167 .IX Item "$pending = $obj->get_ipc_pending()"
168 This returns \-1 if it is not possible to know.
169 .Sp
170 This returns 0 if there are no pending events.
171 .Sp
172 This returns 1 if there are pending events.
173 .ie n .IP "$timeout = $obj\->ipc_timeout;" 4
174 .el .IP "\f(CW$timeout\fR = \f(CW$obj\fR\->ipc_timeout;" 4
175 .IX Item "$timeout = $obj->ipc_timeout;"
176 .PD 0
177 .ie n .IP $obj\->set_ipc_timeout($timeout); 4
178 .el .IP \f(CW$obj\fR\->set_ipc_timeout($timeout); 4
179 .IX Item "$obj->set_ipc_timeout($timeout);"
180 .PD
181 How long to wait for child processes and threads before aborting.
182 .ie n .IP "$drivers = $obj\->ipc_drivers" 4
183 .el .IP "\f(CW$drivers\fR = \f(CW$obj\fR\->ipc_drivers" 4
184 .IX Item "$drivers = $obj->ipc_drivers"
185 Get the list of IPC drivers.
186 .ie n .IP $obj\->add_ipc_driver($DRIVER_CLASS) 4
187 .el .IP \f(CW$obj\fR\->add_ipc_driver($DRIVER_CLASS) 4
188 .IX Item "$obj->add_ipc_driver($DRIVER_CLASS)"
189 Add an IPC driver to the list. The most recently added IPC driver will become
190 the global one during initialization. If a driver is added after initialization
191 has occurred a warning will be generated:
192 .Sp
193 .Vb 1
194 \& "IPC driver $driver loaded too late to be used as the global ipc driver"
195 .Ve
196 .ie n .IP "$bool = $obj\->ipc_polling" 4
197 .el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->ipc_polling" 4
198 .IX Item "$bool = $obj->ipc_polling"
199 Check if polling is enabled.
200 .ie n .IP $obj\->enable_ipc_polling 4
201 .el .IP \f(CW$obj\fR\->enable_ipc_polling 4
202 .IX Item "$obj->enable_ipc_polling"
203 Turn on polling. This will cull events from other processes and threads every
204 time a context is created.
205 .ie n .IP $obj\->disable_ipc_polling 4
206 .el .IP \f(CW$obj\fR\->disable_ipc_polling 4
207 .IX Item "$obj->disable_ipc_polling"
208 Turn off IPC polling.
209 .ie n .IP "$bool = $obj\->no_wait" 4
210 .el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->no_wait" 4
211 .IX Item "$bool = $obj->no_wait"
212 .PD 0
213 .ie n .IP "$bool = $obj\->set_no_wait($bool)" 4
214 .el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->set_no_wait($bool)" 4
215 .IX Item "$bool = $obj->set_no_wait($bool)"
216 .PD
217 Get/Set no_wait. This option is used to turn off process/thread waiting at exit.
218 .ie n .IP "$arrayref = $obj\->exit_callbacks" 4
219 .el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->exit_callbacks" 4
220 .IX Item "$arrayref = $obj->exit_callbacks"
221 Get the exit callbacks.
222 .ie n .IP "$obj\->add_exit_callback(sub { ... })" 4
223 .el .IP "\f(CW$obj\fR\->add_exit_callback(sub { ... })" 4
224 .IX Item "$obj->add_exit_callback(sub { ... })"
225 Add an exit callback. This callback will be called by \f(CWset_exit()\fR.
226 .ie n .IP "$bool = $obj\->finalized" 4
227 .el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->finalized" 4
228 .IX Item "$bool = $obj->finalized"
229 Check if the object is finalized. Finalization happens when either \f(CWipc()\fR,
230 \&\f(CWstack()\fR, or \f(CWformat()\fR are called on the object. Once finalization happens
231 these fields are considered unchangeable (not enforced here, enforced by
232 Test2).
233 .ie n .IP "$ipc = $obj\->ipc" 4
234 .el .IP "\f(CW$ipc\fR = \f(CW$obj\fR\->ipc" 4
235 .IX Item "$ipc = $obj->ipc"
236 Get the one true IPC instance.
237 .ie n .IP $obj\->ipc_disable 4
238 .el .IP \f(CW$obj\fR\->ipc_disable 4
239 .IX Item "$obj->ipc_disable"
240 Turn IPC off
241 .ie n .IP "$bool = $obj\->ipc_disabled" 4
242 .el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->ipc_disabled" 4
243 .IX Item "$bool = $obj->ipc_disabled"
244 Check if IPC is disabled
245 .ie n .IP "$stack = $obj\->stack" 4
246 .el .IP "\f(CW$stack\fR = \f(CW$obj\fR\->stack" 4
247 .IX Item "$stack = $obj->stack"
248 Get the one true hub stack.
249 .ie n .IP "$formatter = $obj\->formatter" 4
250 .el .IP "\f(CW$formatter\fR = \f(CW$obj\fR\->formatter" 4
251 .IX Item "$formatter = $obj->formatter"
252 Get the global formatter. By default this is the \f(CW\*(AqTest2::Formatter::TAP\*(Aq\fR
253 package. This could be any package that implements the \f(CWwrite()\fR method. This
254 can also be an instantiated object.
255 .ie n .IP "$bool = $obj\->\fBformatter_set()\fR" 4
256 .el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->\fBformatter_set()\fR" 4
257 .IX Item "$bool = $obj->formatter_set()"
258 Check if a formatter has been set.
259 .ie n .IP $obj\->add_formatter($class) 4
260 .el .IP \f(CW$obj\fR\->add_formatter($class) 4
261 .IX Item "$obj->add_formatter($class)"
262 .PD 0
263 .ie n .IP $obj\->add_formatter($obj) 4
264 .el .IP \f(CW$obj\fR\->add_formatter($obj) 4
265 .IX Item "$obj->add_formatter($obj)"
266 .PD
267 Add a formatter. The most recently added formatter will become the global one
268 during initialization. If a formatter is added after initialization has occurred
269 a warning will be generated:
270 .Sp
271 .Vb 1
272 \& "Formatter $formatter loaded too late to be used as the global formatter"
273 .Ve
274 .ie n .IP "$obj\->set_add_uuid_via(sub { ... })" 4
275 .el .IP "\f(CW$obj\fR\->set_add_uuid_via(sub { ... })" 4
276 .IX Item "$obj->set_add_uuid_via(sub { ... })"
277 .PD 0
278 .ie n .IP "$sub = $obj\->\fBadd_uuid_via()\fR" 4
279 .el .IP "\f(CW$sub\fR = \f(CW$obj\fR\->\fBadd_uuid_via()\fR" 4
280 .IX Item "$sub = $obj->add_uuid_via()"
281 .PD
282 This allows you to provide a UUID generator. If provided UUIDs will be attached
283 to all events, hubs, and contexts. This is useful for storing, tracking, and
284 linking these objects.
285 .Sp
286 The sub you provide should always return a unique identifier. Most things will
287 expect a proper UUID string, however nothing in Test2::API enforces this.
288 .Sp
289 The sub will receive exactly 1 argument, the type of thing being tagged
290 \&\*(Aqcontext\*(Aq, \*(Aqhub\*(Aq, or \*(Aqevent\*(Aq. In the future additional things may be tagged, in
291 which case new strings will be passed in. These are purely informative, you can
292 (and usually should) ignore them.
293 .SH SOURCE
294 .IX Header "SOURCE"
295 The source code repository for Test2 can be found at
296 <https://github.com/Test\-More/test\-more/>.
297 .SH MAINTAINERS
298 .IX Header "MAINTAINERS"
299 .IP "Chad Granum <[email protected]>" 4
300 .IX Item "Chad Granum <[email protected]>"
301 .SH AUTHORS
302 .IX Header "AUTHORS"
303 .IP "Chad Granum <[email protected]>" 4
304 .IX Item "Chad Granum <[email protected]>"
305 .SH COPYRIGHT
306 .IX Header "COPYRIGHT"
307 Copyright Chad Granum <[email protected]>.
308 .PP
309 This program is free software; you can redistribute it and/or
310 modify it under the same terms as Perl itself.
311 .PP
312 See <https://dev.perl.org/licenses/>