Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
POE::Component::ResolvUser)Contributed Perl DocumenPOE::Component::Resolver(3)

NAME
       POE::Component::Resolver	- A non-blocking getaddrinfo() resolver

VERSION
       version 0.921

SYNOPSIS
	       #!/usr/bin/perl

	       use warnings;
	       use strict;

	       use POE;
	       use POE::Component::Resolver qw(AF_INET AF_INET6);

	       my $r = POE::Component::Resolver->new(
		       max_resolvers =>	8,
		       idle_timeout  =>	5,
		       af_order	     =>	[ AF_INET6, AF_INET ],
		       # sidecar_program => $path_to_program,
	       );

	       my @hosts = qw( ipv6-test.com );
	       my $tcp	 = getprotobyname("tcp");

	       POE::Session->create(
		       inline_states =>	{
			       _start => sub {
				       foreach my $host	(@hosts) {
					       $r->resolve(
						       host    => $host,
						       service => "http",
						       event   => "got_response",
						       hints   => { protocol =>	$tcp },
					       ) or die	$!;
				       }
			       },

			       _stop =>	sub { print "client session stopped\n" },

			       got_response => sub {
				       my ($error, $addresses, $request) = @_[ARG0..ARG2];
				       use YAML; print YAML::Dump(
					       {
						       error =>	$error,
						       addr => $addresses,
						       req => $request,
					       }
				       );
			       },
		       }
	       );

	       POE::Kernel->run();

DESCRIPTION
       POE::Component::Resolver	performs Socket::getaddrinfo() calls in
       subprocesses where they're permitted to block as	long as	necessary.

       By default it will run eight subprocesses and prefer address families
       in whatever order getaddrinfo() returns them.  These defaults can be
       overridden with constructor parameters.	getaddrinfo() delegates	to the
       operating system's resolver, which may be reconfigured according	to the
       usual conventions.

   PUBLIC METHODS
       new

       Create a	new resolver.  Returns an object that must be held and used to
       make requests.  See the synopsis.

       Accepts up to four optional named parameters.

       "af_order" may contain an arrayref with the address families to permit,
       in the order in which they're preferred.	 Without "af_order", the
       component will prefer IPv4 addresses over IPv6 for legacy
       compatibility.  This may	change in the future as	IPv6 gains more
       widespread acceptance.  See "ENVIRONMENT	VARIABLES" for a way to
       override	the default without hacking modules.

	       # Prefer	IPv6 addresses,	but also return	IPv4 ones.
	       my $r1 =	POE::Component::Resolver->new(
		       af_order	=> [ AF_INET6, AF_INET ]
	       );

	       # Only return IPv6 addresses,
	       # or nothing in cases where only	IPv4 addresses exist.
	       my $r2 =	POE::Component::Resolver->new(
		       af_order	=> [ AF_INET6 ]
	       );

       "idle_timeout" determines how long to keep idle resolver	subprocesses
       before cleaning them up,	in seconds.  It	defaults to 15.0 seconds.

       "max_resolvers" controls	the component's	parallelism by defining	the
       maximum number of sidecar processes to manage.  It defaults to 8, but
       fewer or	more processes can be configured depending on the resources
       you have	available and the amount of parallelism	you require.

	       # One at	a time,	but without the	pesky blocking.
	       my $r3 =	POE::Component::Resolver->new( max_resolvers =>	1 );

       "sidecar_program" contains the disk location of a program that will
       perform blocking	lookups	on standard input and print the	results	on
       standard	output.	 The sidecar program is	needed only in special
       environments where the bundling and execution of	extra utilities	is
       tricky.	PAR is one such	environment.

       The sidecar program needs to contain at least two statements:

	       use POE::Component::Resolver::Sidecar;
	       POE::Component::Resover::Sidecar->main();

       resolve

       resolve() begins	a new request to resolve a domain.  The	request	will
       be enqueued in the component until a sidecar process can	service	it.
       resolve() returns a request ID that may be used to cancel() a request
       before it has completed (or undef if the	request	couldn't begin,	such
       as during shutdown).  Resolve requires two parameters and accepts some
       additional optional ones.

       "host" and "service" are	required and contain the host (name or
       Internet	address) and service (name or numeric port) that will be
       passed verbatim to getaddrinfo().  See Socket for details.

       "event" is optional; it contains	the name of the	event that will
       contain the resolver response.  If omitted, it will default to
       "resolver_response"; you	may want to specify a shorter event name.

       "hints" is optional.  If	specified, it must contain a hashref of	hints
       exactly as getaddrinfo()	expects	them.  See Socket for details.

       "misc" is optional continuation data that will be passed	back in	the
       response.  It may contain any type of data the application requires.

       cancel

       Cancel a	request, given the request's ID.

	       my $request_id =	$resolver->resolve("poe.dyndns.org", "http");
	       $resolver->cancel($request_id);

       shutdown

       Shut down the resolver.	POE::Component::Resolver retains resources
       including child processes for up	to "idle_timeout" seconds.  This may
       keep programs running up	to "idle_timeout" seconds longer than they
       should.

       POE::Component::Resolver	will release its resources (including child
       processes) when its shutdown() method is	called.

       unpack_addr

       In scalar context, unpack_addr($response_addr_hashref) returns the addr
       element of $response_addr_hashref in a numeric form appropriate for the
       address family of the address.

	       sub handle_resolver_response {
		       my ($error, $addresses, $request) = @_[ARG0..ARG2];

		       foreach my $a (@$addresses) {
			       my $numeric_addr	= $resolver->unpack_addr($a);
			       print "$request->{host} = $numeric_addr\n";
		       }
	       }

       In list context,	it returns the numeric port and	address.

	       sub handle_resolver_response {
		       my ($error, $addresses, $request) = @_[ARG0..ARG2];

		       foreach my $a (@$addresses) {
			       my ($$numeric_addr, $port) = $resolver->unpack_addr($a);
			       print "$request->{host} = $numeric_addr\n";
		       }
	       }

       unpack_addr() is	a convenience wrapper around getnameinfo() from
       Socket.	You're certainly welcome to use	the discrete function instead.

       unpack_addr() returns bleak emptiness on	failure, regardless of
       context.	 You can check for undef return.

   PUBLIC EVENTS
       resolver_response

       The resolver response event includes three parameters.

       $_[ARG0]	and $_[ARG1] contain the retrn values from Socket's
       getaddrinfo() call.  These are an error message (if the call failed),
       and an arrayref of address structures if	the call succeeded.

       The component provides its own error message, 'component	shut down'.
       This response is	given for every	pending	request	at the time the	user
       shuts down the component.

       $_[ARG2]	contains a hashref of information provided to the resolve()
       method.	Specifically, the values of resolve()'s	"host",	"service" and
       "misc" parameters.

ENVIRONMENT VARIABLES
   POCO_RESOLVER_IPV
       The POCO_RESOLVER_IPV environment variable sets this component's
       default Internet	Protocol Version search	order.	If the variable
       exists, it should contain a string with the numbers 4 and/or 6.
       POE::Component::Resolver	will treate these as Internet Protocol
       versions	to consider, in	the order they are preferred.

       POE::Component::Resolver's new()	method accepts an "af_order" parameter
       that overrides this environment variable.

       Default to IPv4 addresses only:

	       export POCO_RESOLVER_IPV=4

       Default to IPv6 addresses only:

	       export POCO_RESOLVER_IPV=6

       Prefer IPv6, but	accept IPv4 if needed:

	       export POCO_RESOLVER_IPV=64

       Prefer IPv4, but	accept IPv6 if needed:

	       export POCO_RESOLVER_IPV=46

COMPATIBILITY ISSUES
   Microsoft Windows
       This module requires "Microsoft TCP/IP version 6" to be installed.
       Steps for Windows XP Pro	(the steps for your particular version of
       Windows may be subtly or	drastically different):

       o   Open	your Control Panel

       o   Open	your Network Connections

       o   Select your network connection from the available one(s)

       o   In the Local	Area Connection	Status dialog, click the Properties
	   button

       o   If "Microsoft TCP/IP	version	6" is listed as	an item	being used,
	   you are done.

       o   Otherwise click Install...

       o   Choose to add a Protocol

       o   And install "Microsoft TCP/IP version 6" from the list of network
	   protocols.

BUGS
       There is	no timeout on requests.

       There is	no way to cancel a pending request.

TROUBLESHOOTING
   programs linger for several seconds before exiting
       Programs	should shutdown() their	POE::Component::Resolver objects when
       they are	through	needing	asynchronous DNS resolution.  Programs should
       additionally destroy their resolvers if they intend to run awhile and
       want to reuse the memory	they consume.

       In some cases, it may be	necessary to shutdown components that perform
       asynchronous DNS	using POE::Component::Resolver... such as
       POE::Component::IRC, POE::Component::Client::Keepalive and
       POE::Component::Client::HTTP.

       By default, the resolver	subprocesses hang around for idle_timeout,
       which defaults to 15.0 seconds.	Destroying the Resolver	object will
       clean up	the process pool.  Assuming only that is keeping the event
       loop active, the	program	will then exit cleanly.

       Alternatively, reduce idle_timeout to a more manageable number, such as
       5.0 seconds.

       Otherwise something else	may also be keeping the	event loop active.

LICENSE
       Except where otherwise noted, this distribution is Copyright 2011 by
       Rocco Caputo.  All rights reserved.  This distribution is free
       software; you may redistribute it and/or	modify it under	the same terms
       as Perl itself.

perl v5.24.1			  2012-08-15	   POE::Component::Resolver(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | ENVIRONMENT VARIABLES | COMPATIBILITY ISSUES | BUGS | TROUBLESHOOTING | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=POE::Component::Resolver&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help