Debian Codegraph @

upstream/debian-unstable/man3/Test2::API::Instance.3perl

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