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.
alloc
$handle->on("alloc", sub { say "We are allocating!"});
$handle->on("alloc", sub {
# the handle instance this event fired on and the buffer size in use
my ($invocant, $buffer_size) = @_;
say "A buffer of size $buffer_size was just allocated for us!";
});The alloc callback fires when a $handle->read_start() or $handle->recv_start() method gets called.
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. Since libuv does not make use of this attribute in any way, you're free to use it 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.
type
# read-only attribute
my $int = $handle->type();
if ($int == UV::Handle::UV_TIMER) {
say "This handle is a timer";
}The type attribute is a read-only attribute that returns the corresponding libuv handle type constant.
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.
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.
has_ref
my $int = $handle->has_ref();The has_ref method returns non-zero if the handle is referenced, zero otherwise.
See Reference Counting.
is_active
# simply a synonym for ->active()
my $int = $handle->is_active();A synonym for "active" in UV::Handle.
is_closing
# simply a synonym for ->closing()
my $int = $handle->is_closing();A synonym for "closing" in UV::Handle.
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.
ref
$handle->ref();The ref method references the given handle. References are idempotent, that is, if a handle is already referenced, then calling this function again will have no effect.
See Reference Counting.
unref
$handle->unref();The unref method un-references the given handle. References are idempotent, that is, if a handle is not referenced, then calling this function again will have no effect.
See Reference Counting.
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.