Debian Codegraph @

upstream/debian-unstable/man3/Test2::EventFacet::Trace.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::EventFacet::Trace 3perl"
58 .TH Test2::EventFacet::Trace 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::EventFacet::Trace \- Debug information for events
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 The Test2::API::Context object, as well as all Test2::Event types need to
68 have access to information about where they were created. This object
69 represents that information.
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 1
73 \& use Test2::EventFacet::Trace;
74 \&
75 \& my $trace = Test2::EventFacet::Trace\->new(
76 \& frame => [$package, $file, $line, $subname],
77 \& );
78 .Ve
79 .SH "FACET FIELDS"
80 .IX Header "FACET FIELDS"
81 .ie n .IP "$string = $trace\->{details}" 4
82 .el .IP "\f(CW$string\fR = \f(CW$trace\fR\->{details}" 4
83 .IX Item "$string = $trace->{details}"
84 .PD 0
85 .ie n .IP "$string = $trace\->\fBdetails()\fR" 4
86 .el .IP "\f(CW$string\fR = \f(CW$trace\fR\->\fBdetails()\fR" 4
87 .IX Item "$string = $trace->details()"
88 .PD
89 Used as a custom trace message that will be used INSTEAD of
90 \&\f(CW\*(C`at <FILE> line <LINE>\*(C'\fR when calling \f(CW\*(C`$trace\->debug\*(C'\fR.
91 .ie n .IP "$frame = $trace\->{frame}" 4
92 .el .IP "\f(CW$frame\fR = \f(CW$trace\fR\->{frame}" 4
93 .IX Item "$frame = $trace->{frame}"
94 .PD 0
95 .ie n .IP "$frame = $trace\->\fBframe()\fR" 4
96 .el .IP "\f(CW$frame\fR = \f(CW$trace\fR\->\fBframe()\fR" 4
97 .IX Item "$frame = $trace->frame()"
98 .PD
99 Get the call frame arrayref.
100 .Sp
101 .Vb 1
102 \& [$package, $file, $line, $subname]
103 .Ve
104 .ie n .IP "$int = $trace\->{pid}" 4
105 .el .IP "\f(CW$int\fR = \f(CW$trace\fR\->{pid}" 4
106 .IX Item "$int = $trace->{pid}"
107 .PD 0
108 .ie n .IP "$int = $trace\->\fBpid()\fR" 4
109 .el .IP "\f(CW$int\fR = \f(CW$trace\fR\->\fBpid()\fR" 4
110 .IX Item "$int = $trace->pid()"
111 .PD
112 The process ID in which the event was generated.
113 .ie n .IP "$int = $trace\->{tid}" 4
114 .el .IP "\f(CW$int\fR = \f(CW$trace\fR\->{tid}" 4
115 .IX Item "$int = $trace->{tid}"
116 .PD 0
117 .ie n .IP "$int = $trace\->\fBtid()\fR" 4
118 .el .IP "\f(CW$int\fR = \f(CW$trace\fR\->\fBtid()\fR" 4
119 .IX Item "$int = $trace->tid()"
120 .PD
121 The thread ID in which the event was generated.
122 .ie n .IP "$id = $trace\->{cid}" 4
123 .el .IP "\f(CW$id\fR = \f(CW$trace\fR\->{cid}" 4
124 .IX Item "$id = $trace->{cid}"
125 .PD 0
126 .ie n .IP "$id = $trace\->\fBcid()\fR" 4
127 .el .IP "\f(CW$id\fR = \f(CW$trace\fR\->\fBcid()\fR" 4
128 .IX Item "$id = $trace->cid()"
129 .PD
130 The ID of the context that was used to create the event.
131 .ie n .IP "$uuid = $trace\->{uuid}" 4
132 .el .IP "\f(CW$uuid\fR = \f(CW$trace\fR\->{uuid}" 4
133 .IX Item "$uuid = $trace->{uuid}"
134 .PD 0
135 .ie n .IP "$uuid = $trace\->\fBuuid()\fR" 4
136 .el .IP "\f(CW$uuid\fR = \f(CW$trace\fR\->\fBuuid()\fR" 4
137 .IX Item "$uuid = $trace->uuid()"
138 .PD
139 The UUID of the context that was used to create the event. (If uuid tagging was
140 enabled)
141 .ie n .IP "($pkg, $file, $line, $subname) = $trace\->call" 4
142 .el .IP "($pkg, \f(CW$file\fR, \f(CW$line\fR, \f(CW$subname\fR) = \f(CW$trace\fR\->call" 4
143 .IX Item "($pkg, $file, $line, $subname) = $trace->call"
144 Get the basic call info as a list.
145 .ie n .IP "@caller = $trace\->full_call" 4
146 .el .IP "\f(CW@caller\fR = \f(CW$trace\fR\->full_call" 4
147 .IX Item "@caller = $trace->full_call"
148 Get the full caller(N) results.
149 .ie n .IP "$warning_bits = $trace\->warning_bits" 4
150 .el .IP "\f(CW$warning_bits\fR = \f(CW$trace\fR\->warning_bits" 4
151 .IX Item "$warning_bits = $trace->warning_bits"
152 Get index 9 from the full caller info. This is the warnings_bits field.
153 .Sp
154 The value of this is not portable across perl versions or even processes.
155 However it can be used in the process that generated it to reproduce the
156 warnings settings in a new scope.
157 .Sp
158 .Vb 4
159 \& eval <<EOT;
160 \& BEGIN { ${^WARNING_BITS} = $trace\->warning_bits };
161 \& ... context\*(Aqs warning settings apply here ...
162 \& EOT
163 .Ve
164 .SS "DISCOURAGED HUB RELATED FIELDS"
165 .IX Subsection "DISCOURAGED HUB RELATED FIELDS"
166 These fields were not always set properly by tools. These are \fBMOSTLY\fR
167 deprecated by the Test2::EventFacet::Hub facets. These fields are not
168 required, and may only reflect the hub that was current when the event was
169 created, which is not necessarily the same as the hub the event was sent
170 through.
171 .PP
172 Some tools did do a good job setting these to the correct hub, but you cannot
173 always rely on that. Use the 'hubs' facet list instead.
174 .ie n .IP "$hid = $trace\->{hid}" 4
175 .el .IP "\f(CW$hid\fR = \f(CW$trace\fR\->{hid}" 4
176 .IX Item "$hid = $trace->{hid}"
177 .PD 0
178 .ie n .IP "$hid = $trace\->\fBhid()\fR" 4
179 .el .IP "\f(CW$hid\fR = \f(CW$trace\fR\->\fBhid()\fR" 4
180 .IX Item "$hid = $trace->hid()"
181 .PD
182 The ID of the hub that was current when the event was created.
183 .ie n .IP "$huuid = $trace\->{huuid}" 4
184 .el .IP "\f(CW$huuid\fR = \f(CW$trace\fR\->{huuid}" 4
185 .IX Item "$huuid = $trace->{huuid}"
186 .PD 0
187 .ie n .IP "$huuid = $trace\->\fBhuuid()\fR" 4
188 .el .IP "\f(CW$huuid\fR = \f(CW$trace\fR\->\fBhuuid()\fR" 4
189 .IX Item "$huuid = $trace->huuid()"
190 .PD
191 The UUID of the hub that was current when the event was created. (If uuid
192 tagging was enabled).
193 .ie n .IP "$int = $trace\->{nested}" 4
194 .el .IP "\f(CW$int\fR = \f(CW$trace\fR\->{nested}" 4
195 .IX Item "$int = $trace->{nested}"
196 .PD 0
197 .ie n .IP "$int = $trace\->\fBnested()\fR" 4
198 .el .IP "\f(CW$int\fR = \f(CW$trace\fR\->\fBnested()\fR" 4
199 .IX Item "$int = $trace->nested()"
200 .PD
201 How deeply nested the event is.
202 .ie n .IP "$bool = $trace\->{buffered}" 4
203 .el .IP "\f(CW$bool\fR = \f(CW$trace\fR\->{buffered}" 4
204 .IX Item "$bool = $trace->{buffered}"
205 .PD 0
206 .ie n .IP "$bool = $trace\->\fBbuffered()\fR" 4
207 .el .IP "\f(CW$bool\fR = \f(CW$trace\fR\->\fBbuffered()\fR" 4
208 .IX Item "$bool = $trace->buffered()"
209 .PD
210 True if the event was buffered and not sent to the formatter independent of a
211 parent (This should never be set when nested is \f(CW0\fR or \f(CW\*(C`undef\*(C'\fR).
212 .SH METHODS
213 .IX Header "METHODS"
214 \&\fBNote:\fR All facet frames are also methods.
215 .ie n .IP $trace\->set_detail($msg) 4
216 .el .IP \f(CW$trace\fR\->set_detail($msg) 4
217 .IX Item "$trace->set_detail($msg)"
218 .PD 0
219 .ie n .IP "$msg = $trace\->detail" 4
220 .el .IP "\f(CW$msg\fR = \f(CW$trace\fR\->detail" 4
221 .IX Item "$msg = $trace->detail"
222 .PD
223 Used to get/set a custom trace message that will be used INSTEAD of
224 \&\f(CW\*(C`at <FILE> line <LINE>\*(C'\fR when calling \f(CW\*(C`$trace\->debug\*(C'\fR.
225 .Sp
226 \&\f(CWdetail()\fR is an alias to the \f(CW\*(C`details\*(C'\fR facet field for backwards
227 compatibility.
228 .ie n .IP "$str = $trace\->debug" 4
229 .el .IP "\f(CW$str\fR = \f(CW$trace\fR\->debug" 4
230 .IX Item "$str = $trace->debug"
231 Typically returns the string \f(CW\*(C`at <FILE> line <LINE>\*(C'\fR. If \f(CW\*(C`detail\*(C'\fR is set
232 then its value will be returned instead.
233 .ie n .IP $trace\->alert($MESSAGE) 4
234 .el .IP \f(CW$trace\fR\->alert($MESSAGE) 4
235 .IX Item "$trace->alert($MESSAGE)"
236 This issues a warning at the frame (filename and line number where
237 errors should be reported).
238 .ie n .IP $trace\->throw($MESSAGE) 4
239 .el .IP \f(CW$trace\fR\->throw($MESSAGE) 4
240 .IX Item "$trace->throw($MESSAGE)"
241 This throws an exception at the frame (filename and line number where
242 errors should be reported).
243 .ie n .IP "($package, $file, $line, $subname) = $trace\->\fBcall()\fR" 4
244 .el .IP "($package, \f(CW$file\fR, \f(CW$line\fR, \f(CW$subname\fR) = \f(CW$trace\fR\->\fBcall()\fR" 4
245 .IX Item "($package, $file, $line, $subname) = $trace->call()"
246 Get the caller details for the debug-info. This is where errors should be
247 reported.
248 .ie n .IP "$pkg = $trace\->package" 4
249 .el .IP "\f(CW$pkg\fR = \f(CW$trace\fR\->package" 4
250 .IX Item "$pkg = $trace->package"
251 Get the debug-info package.
252 .ie n .IP "$file = $trace\->file" 4
253 .el .IP "\f(CW$file\fR = \f(CW$trace\fR\->file" 4
254 .IX Item "$file = $trace->file"
255 Get the debug-info filename.
256 .ie n .IP "$line = $trace\->line" 4
257 .el .IP "\f(CW$line\fR = \f(CW$trace\fR\->line" 4
258 .IX Item "$line = $trace->line"
259 Get the debug-info line number.
260 .ie n .IP "$subname = $trace\->subname" 4
261 .el .IP "\f(CW$subname\fR = \f(CW$trace\fR\->subname" 4
262 .IX Item "$subname = $trace->subname"
263 Get the debug-info subroutine name.
264 .ie n .IP "$sig = trace\->signature" 4
265 .el .IP "\f(CW$sig\fR = trace\->signature" 4
266 .IX Item "$sig = trace->signature"
267 Get a signature string that identifies this trace. This is used to check if
268 multiple events are related. The signature includes pid, tid, file, line
269 number, and the cid.
270 .SH SOURCE
271 .IX Header "SOURCE"
272 The source code repository for Test2 can be found at
273 <https://github.com/Test\-More/test\-more/>.
274 .SH MAINTAINERS
275 .IX Header "MAINTAINERS"
276 .IP "Chad Granum <[email protected]>" 4
277 .IX Item "Chad Granum <[email protected]>"
278 .SH AUTHORS
279 .IX Header "AUTHORS"
280 .PD 0
281 .IP "Chad Granum <[email protected]>" 4
282 .IX Item "Chad Granum <[email protected]>"
283 .PD
284 .SH COPYRIGHT
285 .IX Header "COPYRIGHT"
286 Copyright 2020 Chad Granum <[email protected]>.
287 .PP
288 This program is free software; you can redistribute it and/or
289 modify it under the same terms as Perl itself.
290 .PP
291 See <https://dev.perl.org/licenses/>