1IO::Async::Resolver(3)User Contributed Perl DocumentationIO::Async::Resolver(3)
2
6 "IO::Async::Resolver" - performing name resolutions asynchronously
7
9 This object is used indirectly via an "IO::Async::Loop":
10 use IO::Async::Loop;
12 my $loop = IO::Async::Loop->new();
13 $loop->resolve( type => 'getpwuid', data => [ $< ],
15 on_resolved =>
16 sub { print "My passwd ent: " . join( "|", @_ ) . "\n" },
17 on_error =>
19 sub { print "Cannot look up my passwd ent - $_[0]\n" },
20 );
21 $loop->loop_forever;
23
25 This module extends an "IO::Async::Loop" to use the system's name
26 resolver functions asynchronously. It provides a number of named
27 resolvers, each one providing an asynchronous wrapper around a single
28 resolver function.
29 Because the system may not provide asynchronous versions of its
31 resolver functions, this class is implemented using a
32 "IO::Async::DetachedCode" object that wraps the normal (blocking)
33 functions. In this case, name resolutions will be performed
34 asynchronously from the rest of the program, but will likely be done by
35 a single background worker process, so will be processed in the order
36 they were requested; a single slow lookup will hold up the queue of
37 other requests behind it. To mitigate this, multiple worker processes
38 can be used; see the "workers" argument to the constructor.
39
41 $loop->resolve( %params )
42 Performs a single name resolution operation, as given by the keys in
43 the hash.
44 The %params hash keys the following keys:
46 type => STRING
48 Name of the resolution operation to perform. See BUILT-IN
49 RESOLVERS for the list of available operations.
50 data => ARRAY
52 Arguments to pass to the resolver function. Exact meaning
53 depends on the specific function chosen by the "type"; see
54 BUILT-IN RESOLVERS.
55 on_resolved => CODE
57 A continuation that is invoked when the resolver function
58 returns a successful result. It will be passed the array
59 returned by the resolver function.
60 on_error => CODE
62 A continuation that is invoked when the resolver function
63 fails. It will be passed the exception thrown by the function.
64
66 register_resolver( $name, $code )
67 Registers a new named resolver function that can be called by the
68 "resolve" method. All named resolvers must be registered before the
69 object is constructed.
70 $name The name of the resolver function; must be a plain string. This
72 name will be used by the "type" argument to the "resolve()"
73 method, to identify it.
74 $code A CODE reference to the resolver function body. It will be
76 called in list context, being passed the list of arguments
77 given in the "data" argument to the "resolve()" method. The
78 returned list will be passed to the "on_resolved" callback. If
79 the code throws an exception at call time, it will be passed to
80 the "on_error" continuation. If it returns normally, the list
81 of values it returns will be passed to "on_resolved".
82 The "IO::Async::DetachedCode" object underlying this class uses the
84 "storable" argument marshalling type, which means complex data
85 structures can be passed by reference. Because the resolver will run in
86 a separate process, the function should make sure to return all of the
87 result in the returned list; i.e. modifications to call arguments will
88 not be propagated back to the caller.
89
91 The following resolver names are implemented by the same-named perl
92 function, taking and returning a list of values exactly as the perl
93 function does:
94 getpwnam getpwuid
96 getgrnam getgrgid
97 getservbyname getservbyport
98 gethostbyname gethostbyaddr
99 getnetbyname getnetbyaddr
100 getprotobyname getprotobynumber
101 The following two resolver names are implemented using the same-named
103 functions from the "Socket::GetAddrInfo" module.
104 getaddrinfo getnameinfo
106 The "getaddrinfo" resolver mangles the result of the function, so that
108 the returned value is more useful to the caller. It splits up the list
109 of 5-tuples into a list of ARRAY refs, where each referenced array
110 contains one of the tuples of 5 values. The "getnameinfo" resolver
111 returns its result unchanged.
112
114 The following somewhat contrieved example shows how to implement a new
115 resolver function. This example just uses in-memory data, but a real
116 function would likely make calls to OS functions to provide an answer.
117 In traditional Unix style, a pair of functions are provided that each
118 look up the entity by either type of key, where both functions return
119 the same type of list. This is purely a convention, and is in no way
120 required or enforced by the "IO::Async::Resolver" itself.
121 @numbers = qw( zero one two three four
123 five six seven eight nine );
124 register_resolver( 'getnumberbyindex', sub {
126 my ( $index ) = @_;
127 die "Bad index $index" unless $index >= 0 and $index < @numbers;
128 return ( $index, $numbers[$index] );
129 } );
130 register_resolver( 'getnumberbyname', sub {
132 my ( $name ) = @_;
133 foreach my $index ( 0 .. $#numbers ) {
134 return ( $index, $name ) if $numbers[$index] eq $name;
135 }
136 die "Bad name $name";
137 } );
138
140 ยท Look into (system-specific) ways of accessing asynchronous
141 resolvers directly
142
144 Paul Evans <leonerd@leonerd.org.uk>
145perl v5.12.1 2010-06-09 IO::Async::Resolver(3)