diff options
Diffstat (limited to 'upstream/debian-unstable/man3/Test2::EventFacet::Trace.3perl')
| -rw-r--r-- | upstream/debian-unstable/man3/Test2::EventFacet::Trace.3perl | 291 |
1 files changed, 291 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man3/Test2::EventFacet::Trace.3perl b/upstream/debian-unstable/man3/Test2::EventFacet::Trace.3perl new file mode 100644 index 00000000..d76cda26 --- /dev/null +++ b/upstream/debian-unstable/man3/Test2::EventFacet::Trace.3perl @@ -0,0 +1,291 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "Test2::EventFacet::Trace 3perl" +.TH Test2::EventFacet::Trace 3perl 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +Test2::EventFacet::Trace \- Debug information for events +.SH DESCRIPTION +.IX Header "DESCRIPTION" +The Test2::API::Context object, as well as all Test2::Event types need to +have access to information about where they were created. This object +represents that information. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Test2::EventFacet::Trace; +\& +\& my $trace = Test2::EventFacet::Trace\->new( +\& frame => [$package, $file, $line, $subname], +\& ); +.Ve +.SH "FACET FIELDS" +.IX Header "FACET FIELDS" +.ie n .IP "$string = $trace\->{details}" 4 +.el .IP "\f(CW$string\fR = \f(CW$trace\fR\->{details}" 4 +.IX Item "$string = $trace->{details}" +.PD 0 +.ie n .IP "$string = $trace\->\fBdetails()\fR" 4 +.el .IP "\f(CW$string\fR = \f(CW$trace\fR\->\fBdetails()\fR" 4 +.IX Item "$string = $trace->details()" +.PD +Used as a custom trace message that will be used INSTEAD of +\&\f(CW\*(C`at <FILE> line <LINE>\*(C'\fR when calling \f(CW\*(C`$trace\->debug\*(C'\fR. +.ie n .IP "$frame = $trace\->{frame}" 4 +.el .IP "\f(CW$frame\fR = \f(CW$trace\fR\->{frame}" 4 +.IX Item "$frame = $trace->{frame}" +.PD 0 +.ie n .IP "$frame = $trace\->\fBframe()\fR" 4 +.el .IP "\f(CW$frame\fR = \f(CW$trace\fR\->\fBframe()\fR" 4 +.IX Item "$frame = $trace->frame()" +.PD +Get the call frame arrayref. +.Sp +.Vb 1 +\& [$package, $file, $line, $subname] +.Ve +.ie n .IP "$int = $trace\->{pid}" 4 +.el .IP "\f(CW$int\fR = \f(CW$trace\fR\->{pid}" 4 +.IX Item "$int = $trace->{pid}" +.PD 0 +.ie n .IP "$int = $trace\->\fBpid()\fR" 4 +.el .IP "\f(CW$int\fR = \f(CW$trace\fR\->\fBpid()\fR" 4 +.IX Item "$int = $trace->pid()" +.PD +The process ID in which the event was generated. +.ie n .IP "$int = $trace\->{tid}" 4 +.el .IP "\f(CW$int\fR = \f(CW$trace\fR\->{tid}" 4 +.IX Item "$int = $trace->{tid}" +.PD 0 +.ie n .IP "$int = $trace\->\fBtid()\fR" 4 +.el .IP "\f(CW$int\fR = \f(CW$trace\fR\->\fBtid()\fR" 4 +.IX Item "$int = $trace->tid()" +.PD +The thread ID in which the event was generated. +.ie n .IP "$id = $trace\->{cid}" 4 +.el .IP "\f(CW$id\fR = \f(CW$trace\fR\->{cid}" 4 +.IX Item "$id = $trace->{cid}" +.PD 0 +.ie n .IP "$id = $trace\->\fBcid()\fR" 4 +.el .IP "\f(CW$id\fR = \f(CW$trace\fR\->\fBcid()\fR" 4 +.IX Item "$id = $trace->cid()" +.PD +The ID of the context that was used to create the event. +.ie n .IP "$uuid = $trace\->{uuid}" 4 +.el .IP "\f(CW$uuid\fR = \f(CW$trace\fR\->{uuid}" 4 +.IX Item "$uuid = $trace->{uuid}" +.PD 0 +.ie n .IP "$uuid = $trace\->\fBuuid()\fR" 4 +.el .IP "\f(CW$uuid\fR = \f(CW$trace\fR\->\fBuuid()\fR" 4 +.IX Item "$uuid = $trace->uuid()" +.PD +The UUID of the context that was used to create the event. (If uuid tagging was +enabled) +.ie n .IP "($pkg, $file, $line, $subname) = $trace\->call" 4 +.el .IP "($pkg, \f(CW$file\fR, \f(CW$line\fR, \f(CW$subname\fR) = \f(CW$trace\fR\->call" 4 +.IX Item "($pkg, $file, $line, $subname) = $trace->call" +Get the basic call info as a list. +.ie n .IP "@caller = $trace\->full_call" 4 +.el .IP "\f(CW@caller\fR = \f(CW$trace\fR\->full_call" 4 +.IX Item "@caller = $trace->full_call" +Get the full caller(N) results. +.ie n .IP "$warning_bits = $trace\->warning_bits" 4 +.el .IP "\f(CW$warning_bits\fR = \f(CW$trace\fR\->warning_bits" 4 +.IX Item "$warning_bits = $trace->warning_bits" +Get index 9 from the full caller info. This is the warnings_bits field. +.Sp +The value of this is not portable across perl versions or even processes. +However it can be used in the process that generated it to reproduce the +warnings settings in a new scope. +.Sp +.Vb 4 +\& eval <<EOT; +\& BEGIN { ${^WARNING_BITS} = $trace\->warning_bits }; +\& ... context\*(Aqs warning settings apply here ... +\& EOT +.Ve +.SS "DISCOURAGED HUB RELATED FIELDS" +.IX Subsection "DISCOURAGED HUB RELATED FIELDS" +These fields were not always set properly by tools. These are \fBMOSTLY\fR +deprecated by the Test2::EventFacet::Hub facets. These fields are not +required, and may only reflect the hub that was current when the event was +created, which is not necessarily the same as the hub the event was sent +through. +.PP +Some tools did do a good job setting these to the correct hub, but you cannot +always rely on that. Use the 'hubs' facet list instead. +.ie n .IP "$hid = $trace\->{hid}" 4 +.el .IP "\f(CW$hid\fR = \f(CW$trace\fR\->{hid}" 4 +.IX Item "$hid = $trace->{hid}" +.PD 0 +.ie n .IP "$hid = $trace\->\fBhid()\fR" 4 +.el .IP "\f(CW$hid\fR = \f(CW$trace\fR\->\fBhid()\fR" 4 +.IX Item "$hid = $trace->hid()" +.PD +The ID of the hub that was current when the event was created. +.ie n .IP "$huuid = $trace\->{huuid}" 4 +.el .IP "\f(CW$huuid\fR = \f(CW$trace\fR\->{huuid}" 4 +.IX Item "$huuid = $trace->{huuid}" +.PD 0 +.ie n .IP "$huuid = $trace\->\fBhuuid()\fR" 4 +.el .IP "\f(CW$huuid\fR = \f(CW$trace\fR\->\fBhuuid()\fR" 4 +.IX Item "$huuid = $trace->huuid()" +.PD +The UUID of the hub that was current when the event was created. (If uuid +tagging was enabled). +.ie n .IP "$int = $trace\->{nested}" 4 +.el .IP "\f(CW$int\fR = \f(CW$trace\fR\->{nested}" 4 +.IX Item "$int = $trace->{nested}" +.PD 0 +.ie n .IP "$int = $trace\->\fBnested()\fR" 4 +.el .IP "\f(CW$int\fR = \f(CW$trace\fR\->\fBnested()\fR" 4 +.IX Item "$int = $trace->nested()" +.PD +How deeply nested the event is. +.ie n .IP "$bool = $trace\->{buffered}" 4 +.el .IP "\f(CW$bool\fR = \f(CW$trace\fR\->{buffered}" 4 +.IX Item "$bool = $trace->{buffered}" +.PD 0 +.ie n .IP "$bool = $trace\->\fBbuffered()\fR" 4 +.el .IP "\f(CW$bool\fR = \f(CW$trace\fR\->\fBbuffered()\fR" 4 +.IX Item "$bool = $trace->buffered()" +.PD +True if the event was buffered and not sent to the formatter independent of a +parent (This should never be set when nested is \f(CW0\fR or \f(CW\*(C`undef\*(C'\fR). +.SH METHODS +.IX Header "METHODS" +\&\fBNote:\fR All facet frames are also methods. +.ie n .IP $trace\->set_detail($msg) 4 +.el .IP \f(CW$trace\fR\->set_detail($msg) 4 +.IX Item "$trace->set_detail($msg)" +.PD 0 +.ie n .IP "$msg = $trace\->detail" 4 +.el .IP "\f(CW$msg\fR = \f(CW$trace\fR\->detail" 4 +.IX Item "$msg = $trace->detail" +.PD +Used to get/set a custom trace message that will be used INSTEAD of +\&\f(CW\*(C`at <FILE> line <LINE>\*(C'\fR when calling \f(CW\*(C`$trace\->debug\*(C'\fR. +.Sp +\&\f(CWdetail()\fR is an alias to the \f(CW\*(C`details\*(C'\fR facet field for backwards +compatibility. +.ie n .IP "$str = $trace\->debug" 4 +.el .IP "\f(CW$str\fR = \f(CW$trace\fR\->debug" 4 +.IX Item "$str = $trace->debug" +Typically returns the string \f(CW\*(C`at <FILE> line <LINE>\*(C'\fR. If \f(CW\*(C`detail\*(C'\fR is set +then its value will be returned instead. +.ie n .IP $trace\->alert($MESSAGE) 4 +.el .IP \f(CW$trace\fR\->alert($MESSAGE) 4 +.IX Item "$trace->alert($MESSAGE)" +This issues a warning at the frame (filename and line number where +errors should be reported). +.ie n .IP $trace\->throw($MESSAGE) 4 +.el .IP \f(CW$trace\fR\->throw($MESSAGE) 4 +.IX Item "$trace->throw($MESSAGE)" +This throws an exception at the frame (filename and line number where +errors should be reported). +.ie n .IP "($package, $file, $line, $subname) = $trace\->\fBcall()\fR" 4 +.el .IP "($package, \f(CW$file\fR, \f(CW$line\fR, \f(CW$subname\fR) = \f(CW$trace\fR\->\fBcall()\fR" 4 +.IX Item "($package, $file, $line, $subname) = $trace->call()" +Get the caller details for the debug-info. This is where errors should be +reported. +.ie n .IP "$pkg = $trace\->package" 4 +.el .IP "\f(CW$pkg\fR = \f(CW$trace\fR\->package" 4 +.IX Item "$pkg = $trace->package" +Get the debug-info package. +.ie n .IP "$file = $trace\->file" 4 +.el .IP "\f(CW$file\fR = \f(CW$trace\fR\->file" 4 +.IX Item "$file = $trace->file" +Get the debug-info filename. +.ie n .IP "$line = $trace\->line" 4 +.el .IP "\f(CW$line\fR = \f(CW$trace\fR\->line" 4 +.IX Item "$line = $trace->line" +Get the debug-info line number. +.ie n .IP "$subname = $trace\->subname" 4 +.el .IP "\f(CW$subname\fR = \f(CW$trace\fR\->subname" 4 +.IX Item "$subname = $trace->subname" +Get the debug-info subroutine name. +.ie n .IP "$sig = trace\->signature" 4 +.el .IP "\f(CW$sig\fR = trace\->signature" 4 +.IX Item "$sig = trace->signature" +Get a signature string that identifies this trace. This is used to check if +multiple events are related. The signature includes pid, tid, file, line +number, and the cid. +.SH SOURCE +.IX Header "SOURCE" +The source code repository for Test2 can be found at +\&\fIhttp://github.com/Test\-More/test\-more/\fR. +.SH MAINTAINERS +.IX Header "MAINTAINERS" +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.SH AUTHORS +.IX Header "AUTHORS" +.PD 0 +.IP "Chad Granum <exodist@cpan.org>" 4 +.IX Item "Chad Granum <exodist@cpan.org>" +.PD +.SH COPYRIGHT +.IX Header "COPYRIGHT" +Copyright 2020 Chad Granum <exodist@cpan.org>. +.PP +This program is free software; you can redistribute it and/or +modify it under the same terms as Perl itself. +.PP +See \fIhttp://dev.perl.org/licenses/\fR |