View source for Net::DBus::Reactor Methods

{{dbtut_header}}

= new =

Usage:
<source lang="perl">my $reactor=Net::DBus::Reactor->new();</source>

This creates a new event loop that is ready to monitor filehandles and timeouts.

However, you should not use this method, but instead you should use the '[[Net::DBus::Reactor Methods#main|main]]' method. Using this directly will mean that the handle returned to you will be available within the scope of your module only, requiring you to pass it around as needed.

= main =

Usage:
<source lang="perl">my $reactor=Net::DBus::Reactor->main;</source>

This creates a handle to the main event loop.

This is the prefered method for creating a new event loop as it removes the need for modules to pass around handles to their privately created reactors. When this is called, it checks if there is a pre-existing reactor loop. If not, it starts one. If so, it returns it directly.

= manage =

Usage:
<source lang="perl">
use Net::DBus;
my $bus=Net::DBus->find();
my $connection=$bus->get_connection;  # You could use the connection below, if
                                      # not using a well known bus.
#my $connection=Net::DBus::Binding::Connection->new(address => "unix:path=/path/to/socket");
$reactor->manage($connection);
</source>
Or
<source lang="perl">
use Net::DBus;
my $server = Net::DBus::Binding::Server->new(address => "unix:path=/path/to/socket");
$reactor->manage($server);
</source>

This registers a handle to the '<span class="code">Net::DBus::Binding::Connection</span>' or '<span class="code">Net::DBus::Binding::Server</span>' object with the main reactor event loop.

Generally you will not need to call this directly, as the [[Net::DBus Methods#new|Net::DBus->new]] call will handle this.

= run =

Usage:
<source lang="perl">$reactor->run();</source>

Once you have registered at least one filehandle with the reactor, you can call this method to start the event loop. Calling this without a registered filehandle will cause it to immediately exit.

This reactor will run until all registered filehandles and timeouts have been removed or disabled, or until the '[[Net::DBus::Reactor Methods#shutdown|shutdown]]' method is called.

= shutdown =

Usage:
<source lang="perl">$reactor->shutdown();</source>

This shuts down the reactor as soon as all events currently being processed have finished.

= step =

<source lang="perl">$reactor->step();</source>

This steps through one iteration of the reactor loop. Generally you should not need to call this.

= add_read =

Usage:
<source lang="perl">
use Net::DBus;
my $bus=Net::DBus->find;
my $service=$bus->get_service("org.freedesktop.DBus");
my $object=$service->get_object("/org/freedesktop/DBus");
my $name="SomeMethod";
$callback=Net::DBus::Callback->new(
        object => $object,
        method => $name);
my $filehandle=""; # I need an example of where this might come from. IO::Handle->new, likely but what about objects?
$status="1";       # Optional boolean value, set to '1' to monitor this event
                   # right away, '0' to disable initially. Default is '1'.
$reactor->add_read($filehandle, $callback[, $status]);
</source>

This registers the '<span class="code">$filehandle</span>' with the reactor event loop which will react to read events. When ever a read event is detected, the '<span class="code">$callback</span>' will be invoked. The optional '<span class="code">$status</span>' value is a [[boolean]] value that tells the reactor loop whether the filehandle is initially watched ('<span class="code">1</span>') or not ('<span class="code">0</span>'). By default, it is.

= add_write =

Usage:
<source lang="perl">
use Net::DBus;
my $bus=Net::DBus->find;
my $service=$bus->get_service("org.freedesktop.DBus");
my $object=$service->get_object("/org/freedesktop/DBus");
my $name="SomeMethod";
$callback=Net::DBus::Callback->new(
        object => $object,
        method => $name);
my $filehandle="";
$status="1";       # Optional boolean value, set to '1' to monitor this event
                   # right away, '0' to disable initially. Default is '1'.
$reactor->add_write($filehandle, $callback[, $status]);
</source>

This registers the '<span class="code">$filehandle</span>' with the reactor event loop which will react to write events. When ever a write event is detected, the '<span class="code">$callback</span>' will be invoked. The optional '<span class="code">$status</span>' value is a [[boolean]] value that tells the reactor loop whether the filehandle is initially watched ('<span class="code">1</span>') or not ('<span class="code">0</span>'). By default, it is.

= add_exception =

Usage:
<source lang="perl">
use Net::DBus;
my $bus=Net::DBus->find;
my $service=$bus->get_service("org.freedesktop.DBus");
my $object=$service->get_object("/org/freedesktop/DBus");
my $name="SomeMethod";
$callback=Net::DBus::Callback->new(
        object => $object,
        method => $name);
my $filehandle="";
$status="1";       # Optional boolean value, set to '1' to monitor this event
                   # right away, '0' to disable initially. Default is '1'.
$reactor->add_exception($filehandle, $callback[, $status]);
</source>

This registers the '<span class="code">$filehandle</span>' with the reactor event loop which will react to exceptions raised by this file handle. When ever an exception event is detected, the '<span class="code">$callback</span>' will be invoked. The optional '<span class="code">$status</span>' value is a [[boolean]] value that tells the reactor loop whether the filehandle is initially watched ('<span class="code">1</span>') or not ('<span class="code">0</span>'). By default, it is.

= add_timeout =

Usage:
<source lang="perl">
use Net::DBus;
my $bus=Net::DBus->find;
my $service=$bus->get_service("org.freedesktop.DBus");
my $object=$service->get_object("/org/freedesktop/DBus");
my $name="SomeMethod";
$callback=Net::DBus::Callback->new(
        object => $object,
        method => $name);
my $timeout=1000;    # Will loop every 1 second.
$status="1";
my $id=$reactor->add_timeout($timeout, $callback[, $status]);
</source>

This registers a timeout with the reactor loop that triggers a [[Net::DBus::Reactos#step|step]] every '<span class="code">$timeout</span>' milliseconds. This call returns an '<span class="code">$id</span>' that can later be used to disable this loop. The optional '<span class="code">$status</span>' value is a [[boolean]] value that tells the reactor loop whether this timeout loop is initially watched ('<span class="code">1</span>') or not ('<span class="code">0</span>'). By default, it is.

= remove_timeout =

Usage:
<source lang="perl">$reactor->remove_timeout($id);</source>

This removes the registered timeout loop with the given '<span class="code">$id</span>' from the reactor loop.

= toggle_timeout =

Usage:
<source lang="perl">
my $status=1;
my $new_timeout=5000;
$reactor->toggle_timeout($id, $status[, $new_timeout]);
</source>

This changes the registered timeout event with the given '<span class="code">$id</span>'. The '<span class="code">$status</span>' value is a [[boolean]], with '<span class="code">1</span>' (re)enabling the loop and '<span class="code">0</span>' pausing it. Optionally, you can pass a '<span class="code">$new_timeout</span>' value which will change the timeout period to the set number of milliseconds.

= add_hook =

Usage:
<source lang="perl">
my $service=$bus->get_service("org.freedesktop.DBus");
my $object=$service->get_object("/org/freedesktop/DBus");
my $name="SomeMethod";
$callback=Net::DBus::Callback->new(
        object => $object,
        method => $name);
my $id=$reactor->add_hook($callback[, $status]);
</source>

This registers a '<span class="code">$callback</span>' with the '<span class="code">$reactor</span>' event loop that is triggered on every iteration of the loop. This call returns an '<span class="code">$id</span>' that can later be used to disable this hook. The optional '<span class="code">$status</span>' value is a [[boolean]] value that tells the reactor loop whether this hook is initially watched ('<span class="code">1</span>') or not ('<span class="code">0</span>'). By default, it is.

= remove_hook =

Usage:
<source lang="perl">$reactor->remove_hook($id);</source>

This removes the registered hook with the given '<span class="code">$id</span>' from the reactor loop.

= toggle_hook =

Usage:
<source lang="perl">
my $status=1;
$reactor->toggle_timeout($id, $status);
</source>

This changes the registered timeout event with the given '<span class="code">$id</span>'. The '<span class="code">$status</span>' value is a [[boolean]], with '<span class="code">1</span>' (re)enabling the loop and '<span class="code">0</span>' pausing it. Optionally, you can pass a '<span class="code">$new_timeout</span>' value which will change the timeout period to the set number of milliseconds.

= remove_read =

Usage:
<source lang="perl">$reactor->remove_read($filehandle);</source>

This removes the registered '<span class="code">$filehandle</span>' read events from the reactor loop.

= remove_write =

Usage:
<source lang="perl">$reactor->remove_write($filehandle);</source>

This removes the registered '<span class="code">$filehandle</span>' write events from the reactor loop.

= remove_exception =

Usage:
<source lang="perl">$reactor->remove_exception($filehandle);</source>

This removes the registered '<span class="code">$filehandle</span>' exception events from the reactor loop.

= toggle_read =

Usage:
<source lang="perl">
my $status=0;
$reactor->toggle_read($filehandle, $status);
</source>

This enables or pauses the registered '<span class="code">$filehandle</span>' read events in the '<span class="code">$reactor</span>' loop. Setting '<span class="code">$status</span>' to '<span class="code">1</span>' will (re)enable it and '<span class="code">0</span>' will pause it.

= toggle_write =

Usage:
<source lang="perl">
my $status=0;
$reactor->toggle_write($filehandle, $status);
</source>

This enables or pauses the registered '<span class="code">$filehandle</span>' write events in the '<span class="code">$reactor</span>' loop. Setting '<span class="code">$status</span>' to '<span class="code">1</span>' will (re)enable it and '<span class="code">0</span>' will pause it.

= toggle_exception =

Usage:
<source lang="perl">
my $status=0;
$reactor->toggle_exception($filehandle, $status);
</source>

This enables or pauses the registered '<span class="code">$filehandle</span>' exception events in the '<span class="code">$reactor</span>' loop. Setting '<span class="code">$status</span>' to '<span class="code">1</span>' will (re)enable it and '<span class="code">0</span>' will pause it.

{{footer}}