.\" -*- 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 "Event::generic 3pm"
.TH Event::generic 3pm 2024-03-07 "perl v5.38.2" "User Contributed Perl Documentation"
.\" 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
Event::generic \- generic event handling
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& use Event::generic;
\&
\& $source = Event::generic::Source\->new;
\&
\& $w = Event\->generic(source => $source, ...);
\& $w = $source\->watch(...);
\&
\& $source = $w\->source;
\& $w\->source($source);
\&
\& $source\->event;
\& $source\->event($data);
\&
\& $data = $event\->data;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
This module provides a watcher type within the \f(CW\*(C`Event\*(C'\fR framework.
You must understand the architecture of the \f(CW\*(C`Event\*(C'\fR system in order to
understand this document.
.PP
This module provides a system of reified event sources and watchers
watching those sources.  Events are generated solely by a method on the
event source object.  The events may carry arbitrary data to the event
handler callbacks.  This module is intended for situations where the
events of interest are best determined by Perl code.
.SH CLASSES
.IX Header "CLASSES"
.IP Event::generic::Source 4
.IX Item "Event::generic::Source"
A reified event source.
.IP Event::generic 4
.IX Item "Event::generic"
A watcher that can watch \f(CW\*(C`Event::generic::Source\*(C'\fR event sources.
.IP Event::Event::Dataful 4
.IX Item "Event::Event::Dataful"
A (target) event that can carry arbitrary data.
.SH "EVENT SOURCE CLASS"
.IX Header "EVENT SOURCE CLASS"
.SS Constructor
.IX Subsection "Constructor"
.IP Event::generic::Source\->new 4
.IX Item "Event::generic::Source->new"
Creates and returns a new event source.
.SS Methods
.IX Subsection "Methods"
.ie n .IP $source\->event 4
.el .IP \f(CW$source\fR\->event 4
.IX Item "$source->event"
.PD 0
.ie n .IP $source\->event(DATA) 4
.el .IP \f(CW$source\fR\->event(DATA) 4
.IX Item "$source->event(DATA)"
.PD
The invocation of this method is a source event for watchers of the
event source.  When this method is called, each active watcher of the
event source generates a target event.  The \fIDATA\fR, if supplied, is
copied into the target event objects, from which it can be retrieved
using the \f(CWdata()\fR method.
.ie n .IP "$source\->watch(ATTR => VALUE, ...)" 4
.el .IP "\f(CW$source\fR\->watch(ATTR => VALUE, ...)" 4
.IX Item "$source->watch(ATTR => VALUE, ...)"
Generates and returns a new watcher, configured to watch this event
source.  The standard watcher attributes may be specified as arguments.
The watcher returned is an ordinary \f(CW\*(C`Event::generic\*(C'\fR, and may be
reconfigured to watch a different event source.
.SH "WATCHER CLASS"
.IX Header "WATCHER CLASS"
.SS "Type-specific attributes"
.IX Subsection "Type-specific attributes"
.ie n .IP "source => $source" 4
.el .IP "source => \f(CW$source\fR" 4
.IX Item "source => $source"
The event source to watch.  This must be either an
\&\f(CW\*(C`Event::generic::Source\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR.  When set to \f(CW\*(C`undef\*(C'\fR,
no source is being watched, and the watcher cannot be started.
.SH "EVENT CLASS"
.IX Header "EVENT CLASS"
.SS "Type-specific methods"
.IX Subsection "Type-specific methods"
.ie n .IP $event\->data 4
.el .IP \f(CW$event\fR\->data 4
.IX Item "$event->data"
Returns the data associated with the event, which may be any scalar.
This is read-only, and is set by the event source.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Event