.\" -*- 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 "Sys::Virt::EventImpl 3pm"
.TH Sys::Virt::EventImpl 3pm 2024-04-21 "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
Sys::Virt::EventImpl \- Event loop implementation parent class
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`Sys::Virt::EventImpl\*(C'\fR module represents the contract for integrating
libvirt with an event loop. This package is abstract and intended to
be subclassed to provide an actual implementation.
.PP
This module is new in 9.5.0. To use this module while also supporting pre\-9.5.0
versions, could may consider the code below to set up inheritance.
.PP
.Vb 1
\&  package YourImpl;
\&
\&  use strict;
\&  use warnings;
\&
\&  BEGIN {
\&    if (require Sys::Virt::EventImpl) {
\&       eval "use parent \*(AqSys::Virt::EventImpl\*(Aq;";
\&    }
\&    else {
\&       eval "use parent \*(AqSys::Virt::Event\*(Aq;";
\&    }
\&  }
.Ve
.SH "EVENT LOOP IMPLEMENTATION"
.IX Header "EVENT LOOP IMPLEMENTATION"
When implementing an event loop, the implementation must be a sub-class
of the \f(CW\*(C`Sys::Virt::EventImpl\*(C'\fR class.  It must override these functions:
.ie n .IP "my $watch_id = $self\->add_handle( $fd, $events, $callback, $opaque, $ff )" 4
.el .IP "my \f(CW$watch_id\fR = \f(CW$self\fR\->add_handle( \f(CW$fd\fR, \f(CW$events\fR, \f(CW$callback\fR, \f(CW$opaque\fR, \f(CW$ff\fR )" 4
.IX Item "my $watch_id = $self->add_handle( $fd, $events, $callback, $opaque, $ff )"
Registers \f(CW$callback\fR to be invoked for \f(CW$events\fR on \f(CW$fd\fR. Use
\&\f(CW\*(C`_run_handle_callback\*(C'\fR to do the actual invocation from the event
loop (see "Callback helpers" below).
.Sp
Next to the events explicitly indicated by \f(CW$events\fR,
\&\f(CW\*(C`Sys::Virt::Event::HANDLE_ERROR\*(C'\fR and \f(CW\*(C`Sys::Virt::Event::HANDLE_HANGUP\*(C'\fR
should \fIalways\fR trigger the callback.
.Sp
Returns a positive integer \f(CW$watch_id\fR or \f(CW\-1\fR on error.
.ie n .IP "$self\->update_handle($watch_id, $events)" 4
.el .IP "\f(CW$self\fR\->update_handle($watch_id, \f(CW$events\fR)" 4
.IX Item "$self->update_handle($watch_id, $events)"
Replaces the events currencly triggering \f(CW$watch_id\fR with \f(CW$events\fR.
.ie n .IP "my $ret = $self\->remove_handle($watch_id)" 4
.el .IP "my \f(CW$ret\fR = \f(CW$self\fR\->remove_handle($watch_id)" 4
.IX Item "my $ret = $self->remove_handle($watch_id)"
Removes the \f(CW$callback\fR from the \f(CW$fd\fR.
.Sp
Returns \f(CW0\fR on success or \f(CW\-1\fR on failure.
.Sp
\&\fBIMPORTANT\fR This should also make sure that \f(CW\*(C`_free_callback_opaque\*(C'\fR is
called \fIafter\fR this function has been executed: not doing so will prevent
the connection from being garbage collected.
.ie n .IP "my $timer_id = $self\->add_timeout($frequency, $callback, $opaque, $ff)" 4
.el .IP "my \f(CW$timer_id\fR = \f(CW$self\fR\->add_timeout($frequency, \f(CW$callback\fR, \f(CW$opaque\fR, \f(CW$ff\fR)" 4
.IX Item "my $timer_id = $self->add_timeout($frequency, $callback, $opaque, $ff)"
.PD 0
.ie n .IP "$self\->update_timeout($timer_id, $frequency)" 4
.el .IP "\f(CW$self\fR\->update_timeout($timer_id, \f(CW$frequency\fR)" 4
.IX Item "$self->update_timeout($timer_id, $frequency)"
.PD
Replaces the interval on the timer with \f(CW$frequency\fR.
.ie n .IP "my $ret = $self\->remove_timeout($timer_id)" 4
.el .IP "my \f(CW$ret\fR = \f(CW$self\fR\->remove_timeout($timer_id)" 4
.IX Item "my $ret = $self->remove_timeout($timer_id)"
Discards the timer.
.Sp
Returns \f(CW0\fR on success or \f(CW\-1\fR on failure.
.Sp
\&\fBIMPORTANT\fR This should also make sure that \f(CW\*(C`_free_callback_opaque\*(C'\fR is
called \fIafter\fR this function has been executed: not doing so will prevent
the connection from being garbage collected.
.SS "Callback helpers"
.IX Subsection "Callback helpers"
.ie n .IP "$self\->_run_handle_callback($watch_id, $fd, $events, $cb, $opaque)" 4
.el .IP "\f(CW$self\fR\->_run_handle_callback($watch_id, \f(CW$fd\fR, \f(CW$events\fR, \f(CW$cb\fR, \f(CW$opaque\fR)" 4
.IX Item "$self->_run_handle_callback($watch_id, $fd, $events, $cb, $opaque)"
A helper method for executing a callback in response to one of more
\&\f(CW$events\fR on the file handle \f(CW$fd\fR. The \f(CW$watch\fR number is the
unique identifier associated with the file descriptor. The \f(CW$cb\fR
and \f(CW$opaque\fR parameters are the callback and data registered for
the handle.
.ie n .IP "$self\->_run_timeout_callback($timer_id, $cb, $opaque)" 4
.el .IP "\f(CW$self\fR\->_run_timeout_callback($timer_id, \f(CW$cb\fR, \f(CW$opaque\fR)" 4
.IX Item "$self->_run_timeout_callback($timer_id, $cb, $opaque)"
A helper method for executing a callback in response to the
expiry of a timeout identified by \f(CW$timer\fR. The \f(CW$cb\fR
and \f(CW$opaque\fR parameters are the callback and data registered for
the timeout.
.ie n .IP "$self\->_free_callback_opaque($ff, $opaque)" 4
.el .IP "\f(CW$self\fR\->_free_callback_opaque($ff, \f(CW$opaque\fR)" 4
.IX Item "$self->_free_callback_opaque($ff, $opaque)"
A helper method for freeing the data associated with a callback.
The \f(CW$ff\fR and \f(CW$opaque\fR parameters are the callback and data
registered for the handle/timeout.
.Sp
\&\fBIMPORTANT\fR This helper must be called outside of any callbacks; that is
\&\fIafter\fR the \f(CW\*(C`remove_handle\*(C'\fR or \f(CW\*(C`remove_timeout\*(C'\fR callbacks complete.
.SH AUTHORS
.IX Header "AUTHORS"
Daniel P. Berrange <berrange@redhat.com>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (C) 2006\-2009 Red Hat
Copyright (C) 2006\-2009 Daniel P. Berrange
.SH LICENSE
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify
it under the terms of either the GNU General Public License as published
by the Free Software Foundation (either version 2 of the License, or at
your option any later version), or, the Artistic License, as specified
in the Perl README file.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sys::Virt,  \f(CW\*(C`http://libvirt.org\*(C'\fR