diff options
Diffstat (limited to 'upstream/mageia-cauldron/man3pm/Test2::API::Instance.3pm')
| -rw-r--r-- | upstream/mageia-cauldron/man3pm/Test2::API::Instance.3pm | 311 |
1 files changed, 311 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man3pm/Test2::API::Instance.3pm b/upstream/mageia-cauldron/man3pm/Test2::API::Instance.3pm new file mode 100644 index 00000000..1b31c599 --- /dev/null +++ b/upstream/mageia-cauldron/man3pm/Test2::API::Instance.3pm @@ -0,0 +1,311 @@ +.\" -*- 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::API::Instance 3pm" +.TH Test2::API::Instance 3pm 2023-11-28 "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::API::Instance \- Object used by Test2::API under the hood +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This object encapsulates the global shared state tracked by +Test2. A single global instance of this package is stored (and +obscured) by the Test2::API package. +.PP +There is no reason to directly use this package. This package is documented for +completeness. This package can change, or go away completely at any time. +Directly using, or monkeypatching this package is not supported in any way +shape or form. +.SH SYNOPSIS +.IX Header "SYNOPSIS" +.Vb 1 +\& use Test2::API::Instance; +\& +\& my $obj = Test2::API::Instance\->new; +.Ve +.ie n .IP "$pid = $obj\->pid" 4 +.el .IP "\f(CW$pid\fR = \f(CW$obj\fR\->pid" 4 +.IX Item "$pid = $obj->pid" +PID of this instance. +.ie n .IP $obj\->tid 4 +.el .IP \f(CW$obj\fR\->tid 4 +.IX Item "$obj->tid" +Thread ID of this instance. +.ie n .IP $obj\->\fBreset()\fR 4 +.el .IP \f(CW$obj\fR\->\fBreset()\fR 4 +.IX Item "$obj->reset()" +Reset the object to defaults. +.ie n .IP $obj\->\fBload()\fR 4 +.el .IP \f(CW$obj\fR\->\fBload()\fR 4 +.IX Item "$obj->load()" +Set the internal state to loaded, and run and stored post-load callbacks. +.ie n .IP "$bool = $obj\->loaded" 4 +.el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->loaded" 4 +.IX Item "$bool = $obj->loaded" +Check if the state is set to loaded. +.ie n .IP "$arrayref = $obj\->post_load_callbacks" 4 +.el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->post_load_callbacks" 4 +.IX Item "$arrayref = $obj->post_load_callbacks" +Get the post-load callbacks. +.ie n .IP "$obj\->add_post_load_callback(sub { ... })" 4 +.el .IP "\f(CW$obj\fR\->add_post_load_callback(sub { ... })" 4 +.IX Item "$obj->add_post_load_callback(sub { ... })" +Add a post-load callback. If \f(CWload()\fR has already been called then the callback will +be immediately executed. If \f(CWload()\fR has not been called then the callback will be +stored and executed later when \f(CWload()\fR is called. +.ie n .IP "$hashref = $obj\->\fBcontexts()\fR" 4 +.el .IP "\f(CW$hashref\fR = \f(CW$obj\fR\->\fBcontexts()\fR" 4 +.IX Item "$hashref = $obj->contexts()" +Get a hashref of all active contexts keyed by hub id. +.ie n .IP "$arrayref = $obj\->context_acquire_callbacks" 4 +.el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->context_acquire_callbacks" 4 +.IX Item "$arrayref = $obj->context_acquire_callbacks" +Get all context acquire callbacks. +.ie n .IP "$arrayref = $obj\->context_init_callbacks" 4 +.el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->context_init_callbacks" 4 +.IX Item "$arrayref = $obj->context_init_callbacks" +Get all context init callbacks. +.ie n .IP "$arrayref = $obj\->context_release_callbacks" 4 +.el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->context_release_callbacks" 4 +.IX Item "$arrayref = $obj->context_release_callbacks" +Get all context release callbacks. +.ie n .IP "$arrayref = $obj\->pre_subtest_callbacks" 4 +.el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->pre_subtest_callbacks" 4 +.IX Item "$arrayref = $obj->pre_subtest_callbacks" +Get all pre-subtest callbacks. +.ie n .IP "$obj\->add_context_init_callback(sub { ... })" 4 +.el .IP "\f(CW$obj\fR\->add_context_init_callback(sub { ... })" 4 +.IX Item "$obj->add_context_init_callback(sub { ... })" +Add a context init callback. Subs are called every time a context is created. Subs +get the newly created context as their only argument. +.ie n .IP "$obj\->add_context_release_callback(sub { ... })" 4 +.el .IP "\f(CW$obj\fR\->add_context_release_callback(sub { ... })" 4 +.IX Item "$obj->add_context_release_callback(sub { ... })" +Add a context release callback. Subs are called every time a context is released. Subs +get the released context as their only argument. These callbacks should not +call release on the context. +.ie n .IP "$obj\->add_pre_subtest_callback(sub { ... })" 4 +.el .IP "\f(CW$obj\fR\->add_pre_subtest_callback(sub { ... })" 4 +.IX Item "$obj->add_pre_subtest_callback(sub { ... })" +Add a pre-subtest callback. Subs are called every time a subtest is +going to be run. Subs get the subtest name, coderef, and any +arguments. +.ie n .IP $obj\->\fBset_exit()\fR 4 +.el .IP \f(CW$obj\fR\->\fBset_exit()\fR 4 +.IX Item "$obj->set_exit()" +This is intended to be called in an \f(CW\*(C`END { ... }\*(C'\fR block. This will look at +test state and set $?. This will also call any end callbacks, and wait on child +processes/threads. +.ie n .IP $obj\->set_ipc_pending($val) 4 +.el .IP \f(CW$obj\fR\->set_ipc_pending($val) 4 +.IX Item "$obj->set_ipc_pending($val)" +Tell other processes and threads there is a pending event. \f(CW$val\fR should be a +unique value no other thread/process will generate. +.Sp +\&\fBNote:\fR This will also make the current process see a pending event. +.ie n .IP "$pending = $obj\->\fBget_ipc_pending()\fR" 4 +.el .IP "\f(CW$pending\fR = \f(CW$obj\fR\->\fBget_ipc_pending()\fR" 4 +.IX Item "$pending = $obj->get_ipc_pending()" +This returns \-1 if it is not possible to know. +.Sp +This returns 0 if there are no pending events. +.Sp +This returns 1 if there are pending events. +.ie n .IP "$timeout = $obj\->ipc_timeout;" 4 +.el .IP "\f(CW$timeout\fR = \f(CW$obj\fR\->ipc_timeout;" 4 +.IX Item "$timeout = $obj->ipc_timeout;" +.PD 0 +.ie n .IP $obj\->set_ipc_timeout($timeout); 4 +.el .IP \f(CW$obj\fR\->set_ipc_timeout($timeout); 4 +.IX Item "$obj->set_ipc_timeout($timeout);" +.PD +How long to wait for child processes and threads before aborting. +.ie n .IP "$drivers = $obj\->ipc_drivers" 4 +.el .IP "\f(CW$drivers\fR = \f(CW$obj\fR\->ipc_drivers" 4 +.IX Item "$drivers = $obj->ipc_drivers" +Get the list of IPC drivers. +.ie n .IP $obj\->add_ipc_driver($DRIVER_CLASS) 4 +.el .IP \f(CW$obj\fR\->add_ipc_driver($DRIVER_CLASS) 4 +.IX Item "$obj->add_ipc_driver($DRIVER_CLASS)" +Add an IPC driver to the list. The most recently added IPC driver will become +the global one during initialization. If a driver is added after initialization +has occurred a warning will be generated: +.Sp +.Vb 1 +\& "IPC driver $driver loaded too late to be used as the global ipc driver" +.Ve +.ie n .IP "$bool = $obj\->ipc_polling" 4 +.el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->ipc_polling" 4 +.IX Item "$bool = $obj->ipc_polling" +Check if polling is enabled. +.ie n .IP $obj\->enable_ipc_polling 4 +.el .IP \f(CW$obj\fR\->enable_ipc_polling 4 +.IX Item "$obj->enable_ipc_polling" +Turn on polling. This will cull events from other processes and threads every +time a context is created. +.ie n .IP $obj\->disable_ipc_polling 4 +.el .IP \f(CW$obj\fR\->disable_ipc_polling 4 +.IX Item "$obj->disable_ipc_polling" +Turn off IPC polling. +.ie n .IP "$bool = $obj\->no_wait" 4 +.el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->no_wait" 4 +.IX Item "$bool = $obj->no_wait" +.PD 0 +.ie n .IP "$bool = $obj\->set_no_wait($bool)" 4 +.el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->set_no_wait($bool)" 4 +.IX Item "$bool = $obj->set_no_wait($bool)" +.PD +Get/Set no_wait. This option is used to turn off process/thread waiting at exit. +.ie n .IP "$arrayref = $obj\->exit_callbacks" 4 +.el .IP "\f(CW$arrayref\fR = \f(CW$obj\fR\->exit_callbacks" 4 +.IX Item "$arrayref = $obj->exit_callbacks" +Get the exit callbacks. +.ie n .IP "$obj\->add_exit_callback(sub { ... })" 4 +.el .IP "\f(CW$obj\fR\->add_exit_callback(sub { ... })" 4 +.IX Item "$obj->add_exit_callback(sub { ... })" +Add an exit callback. This callback will be called by \f(CWset_exit()\fR. +.ie n .IP "$bool = $obj\->finalized" 4 +.el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->finalized" 4 +.IX Item "$bool = $obj->finalized" +Check if the object is finalized. Finalization happens when either \f(CWipc()\fR, +\&\f(CWstack()\fR, or \f(CWformat()\fR are called on the object. Once finalization happens +these fields are considered unchangeable (not enforced here, enforced by +Test2). +.ie n .IP "$ipc = $obj\->ipc" 4 +.el .IP "\f(CW$ipc\fR = \f(CW$obj\fR\->ipc" 4 +.IX Item "$ipc = $obj->ipc" +Get the one true IPC instance. +.ie n .IP $obj\->ipc_disable 4 +.el .IP \f(CW$obj\fR\->ipc_disable 4 +.IX Item "$obj->ipc_disable" +Turn IPC off +.ie n .IP "$bool = $obj\->ipc_disabled" 4 +.el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->ipc_disabled" 4 +.IX Item "$bool = $obj->ipc_disabled" +Check if IPC is disabled +.ie n .IP "$stack = $obj\->stack" 4 +.el .IP "\f(CW$stack\fR = \f(CW$obj\fR\->stack" 4 +.IX Item "$stack = $obj->stack" +Get the one true hub stack. +.ie n .IP "$formatter = $obj\->formatter" 4 +.el .IP "\f(CW$formatter\fR = \f(CW$obj\fR\->formatter" 4 +.IX Item "$formatter = $obj->formatter" +Get the global formatter. By default this is the \f(CW\*(AqTest2::Formatter::TAP\*(Aq\fR +package. This could be any package that implements the \f(CWwrite()\fR method. This +can also be an instantiated object. +.ie n .IP "$bool = $obj\->\fBformatter_set()\fR" 4 +.el .IP "\f(CW$bool\fR = \f(CW$obj\fR\->\fBformatter_set()\fR" 4 +.IX Item "$bool = $obj->formatter_set()" +Check if a formatter has been set. +.ie n .IP $obj\->add_formatter($class) 4 +.el .IP \f(CW$obj\fR\->add_formatter($class) 4 +.IX Item "$obj->add_formatter($class)" +.PD 0 +.ie n .IP $obj\->add_formatter($obj) 4 +.el .IP \f(CW$obj\fR\->add_formatter($obj) 4 +.IX Item "$obj->add_formatter($obj)" +.PD +Add a formatter. The most recently added formatter will become the global one +during initialization. If a formatter is added after initialization has occurred +a warning will be generated: +.Sp +.Vb 1 +\& "Formatter $formatter loaded too late to be used as the global formatter" +.Ve +.ie n .IP "$obj\->set_add_uuid_via(sub { ... })" 4 +.el .IP "\f(CW$obj\fR\->set_add_uuid_via(sub { ... })" 4 +.IX Item "$obj->set_add_uuid_via(sub { ... })" +.PD 0 +.ie n .IP "$sub = $obj\->\fBadd_uuid_via()\fR" 4 +.el .IP "\f(CW$sub\fR = \f(CW$obj\fR\->\fBadd_uuid_via()\fR" 4 +.IX Item "$sub = $obj->add_uuid_via()" +.PD +This allows you to provide a UUID generator. If provided UUIDs will be attached +to all events, hubs, and contexts. This is useful for storing, tracking, and +linking these objects. +.Sp +The sub you provide should always return a unique identifier. Most things will +expect a proper UUID string, however nothing in Test2::API enforces this. +.Sp +The sub will receive exactly 1 argument, the type of thing being tagged +\&'context', 'hub', or 'event'. In the future additional things may be tagged, in +which case new strings will be passed in. These are purely informative, you can +(and usually should) ignore them. +.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 |