Description
Resolves host names with nonblocking DNS transports and a bounded cache.
Example:
Addresses := Flyology.IO.DNS.Resolve ("example.net", Timeout => 2.0);
Address_Array
type Address_Array is array (Positive range <>) of Flyology.IO.Sockets.IP_Address;
Nonempty or null array of resolved internet addresses.
Clear_Cache
procedure Clear_Cache
Atomically remove all process-local positive and negative cache entries. The cache owns no descriptors or background tasks and is safe to use concurrently with resolution calls.
Family_Preference
type Family_Preference is (Any_Family, IPv4_Only, IPv6_Only);
Address families returned by the resolver.
Enumeration literals
- Any_Family
Return available IPv6 and IPv4 addresses
- IPv4_Only
Query or accept only IPv4 addresses
- IPv6_Only
Query or accept only IPv6 addresses
Finish
function Finish (Operation : in out Resolve_Operation) return Address_Array
Consume one terminal scoped DNS result. Provider failures are retained until this call and use the same exception classes as synchronous DNS.
Parameters
- Operation
Terminal resolve operation
Return value
Resolved addresses in resolver response order
Raised exceptions
- Name_Not_Found
No address exists for the selected family
- Resolution_Failed
Input or resolver policy is unusable
- Malformed_Response
No valid response can be obtained
- Name_Server_Failure
Every candidate ends in server failure
- Operation_Cancelled
Token or explicit cancellation wins
- Timeout_Error
The absolute deadline expires
- Device_Error
Readiness polling fails
- Socket_Error
Flyology.IO.Sockets.Socket_Error is retained
Load_Configuration
function Load_Configuration
(Configuration_Path : String := "/etc/resolv.conf") return Resolver_Configuration
Load numeric servers, search domains, ndots, attempts, retry interval, and rotation from one resolver configuration file. The returned value owns no descriptor, task, or heap allocation and may be shared by concurrent operations after initialization.
Parameters
- Configuration_Path
Resolver configuration file
Return value
Immutable bounded resolver configuration snapshot
Raised exceptions
- Resolution_Failed
The configuration is too large or has no usable numeric name server
- File_Error
Flyology.IO.Files reports a file operation error
Malformed_Response
Malformed_Response : exception;
Raised when no valid result can be obtained from malformed responses.
Name_Not_Found
Name_Not_Found : exception;
Raised for a valid negative DNS answer or family mismatch.
Name_Server_Array
type Name_Server_Array is array (Positive range <>) of Flyology.IO.Sockets.Endpoint;
Caller-supplied numeric DNS endpoints for Resolve_Using.
Name_Server_Failure
Name_Server_Failure : exception;
Raised when every name server answers with a failure response code. Unlike Timeout_Error this outcome leaves the caller's deadline unspent.
Operation_Cancelled
Operation_Cancelled : exception;
Raised when a member of the resolver's interrupt set becomes readable.
Resolution_Failed
Resolution_Failed : exception;
Raised for invalid resolver input or unusable resolver configuration.
Resolve
function Resolve
(Set : not null access Flyology.Operations.Completion_Set'Class;
Name : String;
Configuration : not null access constant Resolver_Configuration;
Family : Family_Preference := Any_Family;
Deadline : Ada.Real_Time.Time := Ada.Real_Time.Time_Last;
Token : access Flyology.Cancellation.Token := null) return Resolve_Operation
Start scoped resolution using a preloaded configuration snapshot. Deadline is one absolute monotonic deadline across search expansion, family queries, retries, and UDP-to-TCP fallback. Time_Last is unlimited. Token is borrowed until terminal publication; its readable wake source is passed through every pending socket child. Configuration is copied synchronously and need not outlive the returned operation. An already-requested Token or expired Deadline completes without a socket. Starting a network query needs one additional hidden set slot. Failure to reserve a child during initial Start transactionally rolls back the root operation. Exhaustion when a later driver transition starts a child terminalizes the root as Failed, closes temporary sockets, and is reported by Finish as Resolution_Failed.
Parameters
- Set
Completion set that owns the root and hidden child slots
- Name
Host name, numeric address, or localhost copied at start
- Configuration
Preloaded resolver configuration copied at start
- Family
Requested result family
- Deadline
Absolute monotonic deadline
- Token
Optional cancellation source that outlives the operation
Return value
Started limited resolve operation
Raised exceptions
- Capacity_Error
The root or a hidden child started during initial Start cannot reserve a completion-set slot
Resolve
function Resolve
(Name : String;
Family : Family_Preference := Any_Family;
Timeout : Duration := 5.0;
Interrupts : Interrupt_Set := No_Interrupts;
Configuration_Path : String := "/etc/resolv.conf") return Address_Array
Resolve through numeric servers in Configuration_Path. Search domains, ndots, retries, rotation, and bounded positive/negative caching are supported without libc name services. Numeric and localhost names bypass the file. Negative Timeout means no limit and zero is immediate; one deadline spans search candidates, family queries, retries, and transport fallback. A negative answer or a server-failure response code moves on to the next search candidate. Lightweight tasks suspend on socket readiness; native tasks block their threads. Reading Configuration_Path is a direct metadata operation and can block the underlying thread.
Parameters
- Name
Host name, numeric address, or localhost
- Family
Requested result family
- Timeout
Overall deadline interval in seconds
- Interrupts
Readable cancellation sources owned by the caller
- Configuration_Path
Resolver configuration file
Return value
Resolved addresses in resolver response order
Raised exceptions
- Name_Not_Found
No address exists for Name and Family
- Resolution_Failed
Input or resolver configuration is unusable
- Malformed_Response
Responses are malformed or inconsistent
- Name_Server_Failure
Every candidate ends in a server failure
- Operation_Cancelled
An interrupt descriptor is readable
- Timeout_Error
The overall deadline expires or every transport fails without an answer
- Device_Error
Descriptor polling or transport setup fails
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when a socket operation fails
Resolve
procedure Resolve
(Name : String;
Configuration : not null access constant Resolver_Configuration;
Family : Family_Preference := Any_Family;
Deadline : Ada.Real_Time.Time := Ada.Real_Time.Time_Last;
Token : access Flyology.Cancellation.Token := null;
Operation : in out Resolve_Operation)
Start or restart scoped resolution in an established operation object. This form lets a parent provider compose DNS through Continue_After. A Capacity_Error from child admission during initial Start leaves Operation fresh and releases every token borrow and socket resource. Exhaustion when a later driver transition starts a child terminalizes Operation as Failed and is reported by Finish as Resolution_Failed.
Parameters
- Name
Host name, numeric address, or localhost copied at start
- Configuration
Preloaded resolver configuration copied at start
- Family
Requested result family
- Deadline
Absolute monotonic deadline
- Token
Optional cancellation source that outlives the operation
- Operation
Fresh, released, or consumed resolve operation
Raised exceptions
- Capacity_Error
The root or a hidden child started during initial Start cannot reserve a completion-set slot
Resolve_Operation
type Resolve_Operation (Owner : not null access Flyology.Operations.Completion_Set'Class) is
new Flyology.Operations.Operation (Owner)
with record
State : Resolve_Operation_State (Owner);
end record;
Scoped DNS resolution result. The operation copies its host name and selected configuration into bounded storage. Internal socket children consume hidden completion-set slots while Continue_After keeps their identities out of user batches and gates.
Record fields
- Owner
Completion set that owns the root and hidden child slots
- State
Opaque build-in-place resolver and child storage
Resolve_Operation_State
type Resolve_Operation_State (Owner : not null access Flyology.Operations.Completion_Set'Class) is
limited private;
Opaque build-in-place storage for a scoped resolver and its socket child. @exclude
Record fields
- Owner
Completion set shared with the child operation
Resolve_Using
function Resolve_Using
(Set : not null access Flyology.Operations.Completion_Set'Class;
Name : String;
Name_Servers : Name_Server_Array;
Family : Family_Preference := Any_Family;
Deadline : Ada.Real_Time.Time := Ada.Real_Time.Time_Last;
Attempts : Positive := 2;
Retry_Interval : Duration := 1.0;
Token : access Flyology.Cancellation.Token := null) return Resolve_Operation
Start scoped resolution through explicit numeric DNS endpoints without search-domain expansion. Endpoints and retry policy are copied at start. An already-requested Token or expired Deadline completes without a socket. A network query requires one hidden completion-set slot. Failure to reserve a child during initial Start transactionally rolls back the root operation. Exhaustion when a later driver transition starts a child terminalizes the root as Failed, closes temporary sockets, and is reported by Finish as Resolution_Failed.
Parameters
- Set
Completion set that owns the root and hidden child slots
- Name
Host name, numeric address, or localhost copied at start
- Name_Servers
Numeric UDP/TCP DNS endpoints copied at start
- Family
Requested result family
- Deadline
Absolute monotonic deadline
- Attempts
Attempts made for each query kind
- Retry_Interval
Maximum seconds allocated per attempt
- Token
Optional cancellation source that outlives the operation
Return value
Started limited resolve operation
Raised exceptions
- Capacity_Error
The root or a hidden child started during initial Start cannot reserve a completion-set slot
Resolve_Using
function Resolve_Using
(Name : String;
Name_Servers : Name_Server_Array;
Family : Family_Preference := Any_Family;
Timeout : Duration := 5.0;
Attempts : Positive := 2;
Retry_Interval : Duration := 1.0;
Interrupts : Interrupt_Set := No_Interrupts) return Address_Array
Resolve through explicit numeric DNS endpoints without search-domain expansion. Timeout is one deadline across family queries, Attempts, and transports. Retry_Interval is the per-attempt interval. Lane and interrupt behavior match Resolve.
Parameters
- Name
Host name, numeric address, or localhost
- Name_Servers
Numeric UDP/TCP DNS endpoints
- Family
Requested result family
- Timeout
Overall deadline interval in seconds
- Attempts
Attempts made for each query kind
- Retry_Interval
Maximum seconds allocated per attempt
- Interrupts
Readable cancellation sources owned by the caller
Return value
Resolved addresses in resolver response order
Raised exceptions
- Name_Not_Found
No address exists for Name and Family
- Resolution_Failed
Servers or retry interval are unusable
- Malformed_Response
Responses are malformed or inconsistent
- Name_Server_Failure
Every name server reports a failure
- Operation_Cancelled
An interrupt descriptor is readable
- Timeout_Error
The overall deadline expires or every transport fails without an answer
- Device_Error
Descriptor polling or transport setup fails
- Socket_Error
Flyology.IO.Sockets.Socket_Error is raised when a socket operation fails
Resolve_Using
procedure Resolve_Using
(Name : String;
Name_Servers : Name_Server_Array;
Family : Family_Preference := Any_Family;
Deadline : Ada.Real_Time.Time := Ada.Real_Time.Time_Last;
Attempts : Positive := 2;
Retry_Interval : Duration := 1.0;
Token : access Flyology.Cancellation.Token := null;
Operation : in out Resolve_Operation)
Start or restart explicit-server scoped resolution in an established operation object. A Capacity_Error from child admission during initial Start rolls back every resource and leaves Operation fresh. Exhaustion when a later driver transition starts a child terminalizes Operation as Failed and is reported by Finish as Resolution_Failed.
Parameters
- Name
Host name, numeric address, or localhost copied at start
- Name_Servers
Numeric UDP/TCP DNS endpoints copied at start
- Family
Requested result family
- Deadline
Absolute monotonic deadline
- Attempts
Attempts made for each query kind
- Retry_Interval
Maximum seconds allocated per attempt
- Token
Optional cancellation source that outlives the operation
- Operation
Fresh, released, or consumed resolve operation
Raised exceptions
- Capacity_Error
The root or a hidden child started during initial Start cannot reserve a completion-set slot
Resolver_Configuration
type Resolver_Configuration is limited private;
Immutable bounded resolver configuration loaded before scoped DNS work starts. Loading may perform synchronous filesystem metadata and data operations; resolving from a snapshot performs no configuration I/O.