README_ARESOLVER

async_resolver

A library that provides asynchronous dns lookups.

Author: Gunnar Zötl gz@tset.de, 2013-2023.
Released under the terms of the MIT license. See file LICENSE for details.

Introduction

Since version 1.2, lsocket comes with an additional library to do asynchronous dns lookups. It works by spawning a separate thread for each dns lookup and providing functions to check for completion and for fetching the results. This is experimental, and thus not an official part of lsocket, even though it comes with it. Since this is only one function, requiring this library will return a function instead of a table.

Building

As this is not an “official” part of lsocket, it can only be built by editing the Makefile. To build, cd to the src directory and open the Makefile in your favorite editor. Find this:

# swap the comments on the next 2 lines if you want the async resolver to be built and installed also
ALL=lsocket.so
#ALL=lsocket.so async_resolver.so

and change it to this:

# swap the comments on the next 2 lines if you want the async resolver to be built and installed also
#ALL=lsocket.so
ALL=lsocket.so async_resolver.so

then call make or luarocks make.

Using

Load the module with

async_resolve = require "async_resolver"

Constructor

• request = async_resolve(hostname)
  async_resolve here is the function returned by requiring async_resolver. Calling it with a hostname returns a request object, which you can poll and finally get your answer from, or nil + error message if an error occurred.

Resolver Methods

• ok = request:poll()
  checks whether the request is completed. Returns true if the request is completed, false if not, and nil + error message if an error occurred.
• ok = request:cancel()
  cancels an asynchronous dns lookup request. Returns true if the request has received the cancel, or nil + error message if an error occurred.
  Note that it is not guaranteed when the request will be canceled, it may be immediately or some time in the future. The cancel method returns immediately, though.
• addrs = request:finalize()
  fetch the results from an asynchronous dns request. Returns a table of ip addresses that the hostname resolves to. For each address, a record (subtable) is found in the result table with the fields:
  • family: IP protocol family, “inet” or “inet6”
  • addr: the ip address

  If an error occurred either in this method or in the course of the dns resolving, returns nil + error message. This is also true if the request has been canceled, in which case the error message will indicate that it has been cancelled.