E-MailRelay
gresolverfuture.h
Go to the documentation of this file.
1//
2// Copyright (C) 2001-2021 Graeme Walker <graeme_walker@users.sourceforge.net>
3//
4// This program is free software: you can redistribute it and/or modify
5// it under the terms of the GNU General Public License as published by
6// the Free Software Foundation, either version 3 of the License, or
7// (at your option) any later version.
8//
9// This program is distributed in the hope that it will be useful,
10// but WITHOUT ANY WARRANTY; without even the implied warranty of
11// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12// GNU General Public License for more details.
13//
14// You should have received a copy of the GNU General Public License
15// along with this program. If not, see <http://www.gnu.org/licenses/>.
16// ===
17///
18/// \file gresolverfuture.h
19///
20
21#ifndef G_NET_RESOLVER_FUTURE_H
22#define G_NET_RESOLVER_FUTURE_H
23
24#include "gdef.h"
25#include "gaddress.h"
26#include <utility>
27#include <vector>
28#include <string>
29
30namespace GNet
31{
32 class ResolverFuture ;
33}
34
35//| \class GNet::ResolverFuture
36/// A 'future' shared-state class for asynchronous name resolution that
37/// holds parameters and results of a call to getaddrinfo(), as performed
38/// by the run() method.
39///
40/// The run() method can be called from a worker thread and the results
41/// collected by the main thread using get() once the worker thread has
42/// signalled that it has finished. The signalling mechanism is outside
43/// the scope of this class (see GNet::FutureEvent).
44///
45/// Eg:
46/// \code
47///
48/// ResolverFuture f( "example.com" , "smtp" , AF_INET , false ) ;
49/// std::thread t( &ResolverFuture::run , f ) ;
50/// ...
51/// t.join() ;
52/// Address a = f.get().first ;
53/// if( f.error() ) throw std::runtime_error( f.reason() ) ;
54/// \endcode
55///
57{
58public:
59 using Pair = std::pair<Address,std::string> ;
60 using List = std::vector<Address> ;
61
62 ResolverFuture( const std::string & host , const std::string & service ,
63 int family , bool dgram , bool for_async_hint = false ) ;
64 ///< Constructor for resolving the given host and service names.
65
67 ///< Destructor.
68
69 ResolverFuture & run() noexcept ;
70 ///< Does the synchronous name resolution and stores the result.
71 ///< Returns *this.
72
73 Pair get() ;
74 ///< Returns the resolved address/name pair after run() has completed.
75 ///< Returns default values if an error().
76
77 void get( List & ) ;
78 ///< Returns the resolved addresses after run() has completed by
79 ///< appending to the given list. Appends nothing if an error().
80
81 bool error() const ;
82 ///< Returns true if name resolution failed or no suitable
83 ///< address was returned. Use after get().
84
85 std::string reason() const ;
86 ///< Returns the reason for the error().
87 ///< Precondition: error()
88
89public:
90 ResolverFuture( const ResolverFuture & ) = delete ;
91 ResolverFuture( ResolverFuture && ) = delete ;
92 void operator=( const ResolverFuture & ) = delete ;
93 void operator=( ResolverFuture && ) = delete ;
94
95private:
96 std::string failure() const ;
97 bool fetch( List & ) const ;
98 bool fetch( Pair & ) const ;
99 bool failed() const ;
100 std::string none() const ;
101 std::string ipvx() const ;
102
103private:
104 bool m_numeric_service ;
105 int m_socktype ;
106 std::string m_host ;
107 const char * m_host_p ;
108 std::string m_service ;
109 const char * m_service_p ;
110 int m_family ;
111 struct addrinfo m_ai_hint {} ;
112 bool m_test_mode ;
113 int m_rc ;
114 struct addrinfo * m_ai ;
115 std::string m_reason ;
116} ;
117
118#endif
A 'future' shared-state class for asynchronous name resolution that holds parameters and results of a...
bool error() const
Returns true if name resolution failed or no suitable address was returned.
std::string reason() const
Returns the reason for the error().
Pair get()
Returns the resolved address/name pair after run() has completed.
ResolverFuture(const std::string &host, const std::string &service, int family, bool dgram, bool for_async_hint=false)
Constructor for resolving the given host and service names.
ResolverFuture & run() noexcept
Does the synchronous name resolution and stores the result.
~ResolverFuture()
Destructor.
Network classes.
Definition: gdef.h:1115