/ 
UV-2.002
River stage one • 3 direct dependents • 3 total dependents
⭐ Starred 10 GitHub stars
/ README.md

NAME

UV - Perl interface to libuv

SYNOPSIS

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

use UV;
use UV::Loop;

# hi-resolution time
my $hi_res_time = UV::hrtime();

# A new loop
my $loop = UV::Loop->new();

# default loop
my $loop = UV::Loop->default_loop(); # convenience singleton constructor
my $loop = UV::Loop->default(); # convenience singleton constructor

# run a loop with one of three options:
# UV_RUN_DEFAULT, UV_RUN_ONCE, UV_RUN_NOWAIT
$loop->run(); # runs with UV_RUN_DEFAULT
$loop->run(UV::Loop::UV_RUN_DEFAULT); # explicitly state UV_RUN_DEFAULT
$loop->run(UV::Loop::UV_RUN_ONCE);
$loop->run(UV::Loop::UV_RUN_NOWAIT);

DESCRIPTION

This module provides an interface to libuv. 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.

Event loops that work properly on all platforms. YAY!

FUNCTIONS

The following functions are available:

check

my $handle = UV::check(); # uses the default loop
my $handle = UV::check(loop => $some_other_loop); # non-default loop

Returns a new UV::Check Handle object.

default_loop

my $loop = UV::default_loop();
# You can also get it with the UV::Loop methods below:
my $loop = UV::Loop->default_loop();
my $loop = UV::Loop->default();
# Passing a true value as the first arg to the UV::Loop constructor
# will also return the default loop
my $loop = UV::Loop->new(1);

Returns the default loop (which is a singleton object). This module already creates the default loop and you get access to it with this method.

err_name

my $error_name = UV::err_name(UV::UV_EAI_BADFLAGS);
say $error_name; # EAI_BADFLAGS

The err_name function returns the error name for the given error code. Leaks a few bytes of memory when you call it with an unknown error code.

In libuv errors are negative numbered constants. As a rule of thumb, whenever there is a status parameter, or an API functions returns an integer, a negative number will imply an error.

When a function which takes a callback returns an error, the callback will never be called.

hrtime

my $uint64_t = UV::hrtime();

Get the current Hi-Res time; a value given in nanoseconds since some arbitrary point in the past. On 64bit-capable perls this will be represented by an integer with full precision. On perls unable to represent a 64bit integer this will be given as a floating-point value so may lose some precision if the value is large enough.

idle

my $handle = UV::idle(); # uses the default loop
my $handle = UV::idle(loop => $some_other_loop); # non-default loop

Returns a new UV::Idle Handle object.

loop

my $loop = UV::loop();
# You can also get it with the UV::Loop methods below:
my $loop = UV::Loop->default_loop();
my $loop = UV::Loop->default();

Returns the default loop (which is a singleton object). This module already creates the default loop and you get access to it with this method.

poll

my $handle = UV::poll(); # uses the default loop
my $handle = UV::poll(loop => $some_other_loop); # non-default loop

Returns a new UV::Poll Handle object.

prepare

my $handle = UV::prepare(); # uses the default loop
my $handle = UV::prepare(loop => $some_other_loop); # non-default loop

Returns a new UV::Prepare Handle object.

signal

my $handle = UV::signal(POSIX::SIGHUP); # uses the default loop

my $handle = UV::signal(loop => $some_other_loop, signal => POSIX::SIGHUP);
    # non-default loop

Returns a new UV::Signal Handle object.

strerror

my $error = UV::strerror(UV::UV_EAI_BADFLAGS);
say $error; # bad ai_flags value

The strerror function returns the error message for the given error code. Leaks a few bytes of memory when you call it with an unknown error code.

In libuv errors are negative numbered constants. As a rule of thumb, whenever there is a status parameter, or an API functions returns an integer, a negative number will imply an error.

When a function which takes a callback returns an error, the callback will never be called.

tcp

my $tcp = UV::tcp();

Returns a new UV::TCP object.

timer

my $timer = UV::timer(); # uses the default loop
my $timer = UV::timer(loop => $some_other_loop); # non-default loop

Returns a new UV::Timer object.

tty

my $tty = UV::tty(fd => 0);

Returns a new UV::TTY object.

udp

my $udp = UV::udp();

Returns a new UV::UDP object.

version

my $int = UV::version();

The version function returns UV::UV_VERSION_HEX, the libuv version packed into a single integer. 8 bits are used for each component, with the patch number stored in the 8 least significant bits. E.g. for libuv 1.2.3 this would be 0x010203.

version_string

say UV::version_string();
# 1.13.1

The version_string function returns the libuv version number as a string. For non-release versions the version suffix is included.

EXCEPTIONS

If any call to libuv fails, an exception will be thrown. The exception will be a blessed object having a code method which returns the numerical error code (which can be compared to one of the UV::UV_E* error constants), and a message method which returns a human-readable string describing the failure.

try { ... }
catch my $e {
    if(blessed $e and $e->isa("UV::Exception")) {
        print "The failure was ", $e->message, " of code ", $e->code;
    }
}

The exception class provides stringify overload to call the message method, so the normal Perl behaviour of just printing the exception will print the message from it, as expected.

Exceptions are blessed into a subclass of UV::Exception named after the type of the failure code. This allows type-based testing of error types.

try { ... }
catch my $e {
    if(blessed $e and $e->isa("UV::Exception::ECANCELED") {
        # ignore
    }
    else ...
}

CONSTANTS

VERSION CONSTANTS

ERROR CONSTANTS

AUTHOR

Paul Evans leonerd@leonerd.org.uk

AUTHORS EMERITUS

Daisuke Murase <typester@cpan.org>, Chase Whitener <capoeirab@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.