NAME

UV::Handle - Handles in libuv

SYNOPSIS

  #!/usr/bin/env perl
  use strict;
  use warnings;

  use UV;

  # Handle is just a base-class for all types of Handles in libuv

  # For example, a UV::Timer
  # A new timer will give initialize against the default loop
  my $timer = UV::Timer->new();

DESCRIPTION

This module provides an interface to libuv's handle. We will try to document things here as best as we can, but we also suggest you look at the libuv docs directly for more details on how things work.

You will likely never use this class directly. You will use the different handle sub-classes directly. Some of these methods or events will be called or fired from those sub-classes.

CONSTANTS

HANDLE TYPE CONSTANTS

UV_ASYNC

UV_CHECK

UV_FILE

UV_FS_EVENT

UV_FS_POLL

UV_IDLE

UV_NAMED_PIPE

UV_POLL

UV_PREPARE

UV_PROCESS

UV_SIGNAL

UV_STREAM

UV_TCP

UV_TIMER

UV_TTY

UV_UDP

EVENTS

UV::Handle makes the following extra events available.

close

    $handle->on("close", sub { say "We are closing!"});
    $handle->on("close", sub {
        # the handle instance this event fired on
        my $invocant = shift;
        say "The handle is closing";
    });

The close callback fires when a $handle->close() method gets called.

ATTRIBUTES

UV::Handle implements the following attributes.

data

    $handle = $handle->data(23); # allows for method chaining.
    $handle = $handle->data("Some stringy stuff");
    $handle = $handle->data(Foo::Bar->new());
    $handle = $handle->data(undef);
    my $data = $handle->data();

The data attribute allows you to store some information along with your UV::Handle object that you can for your own purposes.

loop

    # read-only attribute
    my $loop = $handle->loop();

The loop attribute is a read-only attribute that returns the UV::Loop object this handle was initialized with.

METHODS

UV::Handle makes the following methods available.

active

    my $int = $handle->active();

The active method returns non-zero if the handle is active, zero if it's inactive. What "active" means depends on the type of handle:

• A UV::Async handle is always active and cannot be deactivated, except by closing it with $handle->close().

• A UV::Pipe, UV::TCP, UV::UDP, etc. handle - basically any handle that deals with i/o - is active when it is doing something that involves i/o, like reading, writing, connecting, accepting new connections, etc.

• A UV::Check, UV::Idle, UV::Timer, etc. handle is active when it has been started with a call to $handle->start(), etc.

* Rule of thumb: if a handle of type foo has a $foo->start() function, then it's active from the moment that function is called. Likewise, $foo->stop() deactivates the handle again.

close

    $handle->close();
    $handle->close(sub {say "we're closing"});

The close method requests that the handle be closed. The close event will be fired asynchronously after this call. This MUST be called on each handle before memory is released.

Handles that wrap file descriptors are closed immediately but the close event will still be deferred to the next iteration of the event loop. It gives you a chance to free up any resources associated with the handle.

In-progress requests, like $handle->connect() or $handle->write, are canceled and have their callbacks called asynchronously with status = UV::UV_ECANCELED.

closed

    # are we officially closed?
    my $int = $handle->closed();

Read-only method to let us know if the handle is closed.

closing

    my $int = $handle->closing();

The closing method returns non-zero if the handle is closing or closed, zero otherwise.

* Note: This function should only be used between the initialization of the handle and the arrival of the close callback.

on

    # set a close event callback to print the handle's data attribute
    $handle->on('close', sub {
        my $hndl = shift;
        say $hndl->data();
        say "closing!"
    });

    # clear out the close event callback for the handle
    $handle->on(close => undef);
    $handle->on(close => sub {});

The on method allows you to subscribe to "EVENTS" in UV::Handle emitted by any UV::Handle or subclass.

AUTHOR

Chase Whitener <capoeirab@cpan.org>

AUTHOR EMERITUS

Daisuke Murase <typester@cpan.org>

COPYRIGHT AND LICENSE

Copyright 2012, Daisuke Murase.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm UV

perl -MCPAN -e shell
install UV