NAME
    UV::Util - Some utility functions from libUV.

WARNING
    UV::Util is being released as a learning process that will hopefully be
    folded into a more complete set of modules allowing use of libUV with
    Perl later. In other words, this will be more useful later. If it
    happens to be useful now, that's awesome. If not, hopefully it will be
    soon. Until then, please let me know of any errors during installation
    or of anything I can do to make this better.

SYNOPSIS
      #!/usr/bin/env perl
      use strict;
      use warnings;
      use feature ':5.14';

      use Data::Dumper::Concise qw(Dumper);
      use UV::Util;
      use Syntax::Keyword::Try;

      my $res;
      try {
        $res = UV::Util::cpu_info();
      }
      catch {
        die "Aw, man. $@";
      }

DESCRIPTION
    This module provides access to a few of the functions in the
    miscellaneous libUV <http://docs.libuv.org/en/v1.x/misc.html> utilities.
    While it's extremely unlikely, all functions here can throw an exception
    on error unless specifically stated otherwise in the function's
    description.

CONSTANTS
    UV::Util makes the following constants available that represent
    different handle types
    <http://docs.libuv.org/en/latest/handle.html#c.uv_handle_type>.

  UV_UNKNOWN_HANDLE
  UV_ASYNC
  UV_CHECK
  UV_FS_EVENT
  UV_FS_POLL
  UV_HANDLE
  UV_IDLE
  UV_NAMED_PIPE
  UV_POLL
  UV_PREPARE
  UV_PROCESS
  UV_STREAM
  UV_TCP
  UV_TIMER
  UV_TTY
  UV_UDP
  UV_SIGNAL
  UV_FILE
  UV_HANDLE_TYPE_MAX
FUNCTIONS
    All functions provided here provide a Perl interface to their libUV
    <http://docs.libuv.org/en/latest/misc.html> equivalents.

  cpu_info
        use Data::Dumper;
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::cpu_info(); }
        catch { die "Aw, man. $@"; }
        say Dumper $res;
        # [
        #   {
        #     cpu_times => {
        #       idle => "1157161200",
        #       irq => 19912800,
        #       nice => 242400,
        #       sys => 8498700,
        #       user => 39428000
        #     },
        #     model => "Intel(R) Core(TM) i7-7700HQ CPU \@ 2.80GHz",
        #     speed => 1048
        #   },
        #   {
        #     cpu_times => {
        #       idle => 16922900,
        #       irq => 846300,
        #       nice => 371800,
        #       sys => 6491400,
        #       user => 34690000
        #     },
        #     model => "Intel(R) Core(TM) i7-7700HQ CPU \@ 2.80GHz",
        #     speed => 899
        #   }
        # ]

    This function <http://docs.libuv.org/en/v1.x/misc.html#c.uv_cpu_info>
    returns an array reference full of hashrefs. Each hashref represents an
    available CPU on your system. "cpu_times", "model", and "speed" will be
    supplied for each.

  get_free_memory
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::get_free_memory(); }
        catch { die "Aw, man. $@"; }
        say $res; # 23052402688

    This function returns an unsigned integer representing the number of
    bytes of free memory available.

  get_total_memory
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::get_total_memory(); }
        catch { die "Aw, man. $@"; }
        say $res; # 33452101632

    This function returns an unsigned integer representing the number of
    bytes of total memory in the system.

  getrusage
        use Data::Dumper;
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::getrusage(); }
        catch { die "Aw, man. $@"; }
        say Dumper $res;
        # {
        #   ru_idrss => 0,
        #   ru_inblock => 0,
        #   ru_isrss => 0,
        #   ru_ixrss => 0,
        #   ru_majflt => 0,
        #   ru_maxrss => 10132,
        #   ru_minflt => 1624,
        #   ru_msgrcv => 0,
        #   ru_msgsnd => 0,
        #   ru_nivcsw => 1,
        #   ru_nsignals => 0,
        #   ru_nswap => 0,
        #   ru_nvcsw => 1,
        #   ru_oublock => 0,
        #   ru_stime => "0.005963",
        #   ru_utime => "0.02801"
        # }

    This function <http://docs.libuv.org/en/v1.x/misc.html#c.uv_getrusage>
    returns a hash reference of resource metrics for the current process.

  guess_handle_type
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::guess_handle_type(\*STDIN); }
        catch { die "Aw, man. $@"; }
        say "yay!" if ($res == UV::Util::UV_TTY);

    This function
    <http://docs.libuv.org/en/latest/misc.html#c.uv_guess_handle> takes in a
    reference to a handle (e.g. "\*STDIN") and returns an integer that
    represents one of the CONSTANTS above.

  hrtime
        use UV::Util;

        # does not throw exceptions
        my $time = UV::Util::hrtime();

    This function <http://docs.libuv.org/en/latest/misc.html#c.uv_hrtime>
    returns the current high-resolution real time. This is expressed in
    nanoseconds. It is relative to an arbitrary time in the past. It is not
    related to the time of day and therefore not subject to clock drift. The
    primary use is for measuring performance between intervals.

    Not every platform can support nanosecond resolution; however, this
    value will always be in nanoseconds.

  interface_addresses
        use Data::Dumper qw(Dumper);
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::interface_addresses(); }
        catch { die "Aw, man. $@"; }
        say Dumper $res;
        # [
        #   {
        #     address => "127.0.0.1",
        #     is_internal => 1,
        #     mac => "00:00:00:00:00:00",
        #     name => "lo",
        #     netmask => "255.0.0.0"
        #   },
        # ]

    This function
    <http://docs.libuv.org/en/latest/misc.html#c.uv_interface_addresses>
    returns an array reference containing hash references representing each
    of your available interfaces.

  loadavg
        use Data::Dumper qw(Dumper);
        use UV::Util;

        # does not throw exceptions
        my $res = UV::Util::loadavg();
        say Dumper $res;
        # [
        #   "0.43212890625",
        #   "0.39599609375",
        #   "0.27880859375"
        # ]

    This function <http://docs.libuv.org/en/latest/misc.html#c.uv_loadavg>
    returns an array reference containing the load average
    <http://en.wikipedia.org/wiki/Load_(computing)>.

    On Windows, this will always return "[0,0,0]" as it's not implemented.

  resident_set_memory
        use Data::Dumper qw(Dumper);
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::resident_set_memory(); }
        catch { die "Aw, man. $@"; }
        say Dumper $res; # 10473472

    This function
    <http://docs.libuv.org/en/latest/misc.html#c.uv_resident_set_memory>
    returns an unsigned integer representing the resident set size (RSS) for
    the current process.

  uptime
        use Data::Dumper qw(Dumper);
        use UV::Util;
        use Syntax::Keyword::Try;

        my $res;
        try { $res = UV::Util::uptime(); }
        catch { die "Aw, man. $@"; }
        say Dumper $res; # 603468

    This function <http://docs.libuv.org/en/latest/misc.html#c.uv_uptime>
    returns a float representing the current system uptime.

  version
        use UV::Util;

        say UV::Util::version();
        # 1.9.1

    This function <http://docs.libuv.org/en/v1.x/version.html> returns the
    libUV version number as a string. Does not throw errors.

COPYRIGHT AND LICENSE
    Copyright 2017, Chase Whitener.

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

