asiolink.h 3.83 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14
// Copyright (C) 2010  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

15 16
#ifndef __ASIOLINK_H
#define __ASIOLINK_H 1
17

JINMEI Tatuya's avatar
JINMEI Tatuya committed
18 19
// IMPORTANT NOTE: only very few ASIO headers files can be included in
// this file.  In particular, asio.hpp should never be included here.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
20 21
// See the description of the namespace below.

22 23 24 25 26 27 28 29
#include <asiolink/io_service.h>
#include <asiolink/dns_service.h>
#include <asiolink/dns_server.h>
#include <asiolink/dns_lookup.h>
#include <asiolink/dns_answer.h>
#include <asiolink/simple_callback.h>
#include <asiolink/recursive_query.h>
#include <asiolink/interval_timer.h>
30

31 32 33 34
#include <asiolink/io_address.h>
#include <asiolink/io_endpoint.h>
#include <asiolink/io_message.h>
#include <asiolink/io_socket.h>
35
#include <asiolink/io_error.h>
36

37
/// \namespace asiolink
JINMEI Tatuya's avatar
JINMEI Tatuya committed
38 39
/// \brief A wrapper interface for the ASIO library.
///
40
/// The \c asiolink namespace is used to define a set of wrapper interfaces
JINMEI Tatuya's avatar
JINMEI Tatuya committed
41
/// for the ASIO library.
Evan Hunt's avatar
Evan Hunt committed
42 43 44
///
/// BIND 10 uses the non-Boost version of ASIO because it's header-only,
/// i.e., does not require a separate library object to be linked, and thus
JINMEI Tatuya's avatar
JINMEI Tatuya committed
45
/// lowers the bar for introduction.
Evan Hunt's avatar
Evan Hunt committed
46 47
///
/// But the advantage comes with its own costs: since the header-only version
JINMEI Tatuya's avatar
JINMEI Tatuya committed
48 49 50
/// includes more definitions in public header files, it tends to trigger
/// more compiler warnings for our own sources, and, depending on the
/// compiler options, may make the build fail.
Evan Hunt's avatar
Evan Hunt committed
51
///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
52 53
/// We also found it may be tricky to use ASIO and standard C++ libraries
/// in a single translation unit, i.e., a .cc file: depending on the order
Evan Hunt's avatar
Evan Hunt committed
54 55 56
/// of including header files, ASIO may or may not work on some platforms.
///
/// This wrapper interface is intended to centralize these
JINMEI Tatuya's avatar
JINMEI Tatuya committed
57
/// problematic issues in a single sub module.  Other BIND 10 modules should
58
/// simply include \c asiolink.h and use the wrapper API instead of
Evan Hunt's avatar
Evan Hunt committed
59
/// including ASIO header files and using ASIO-specific classes directly.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
60 61 62 63 64 65
///
/// This wrapper may be used for other IO libraries if and when we want to
/// switch, but generality for that purpose is not the primary goal of
/// this module.  The resulting interfaces are thus straightforward mapping
/// to the ASIO counterparts.
///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
66
/// Notes to developers:
67
/// Currently the wrapper interface is fairly specific to use by a
68
/// DNS server, i.e., b10-auth or b10-resolver.  But the plan is to
69
/// generalize it and have other modules use it as well.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
70
///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
71
/// One obvious drawback of this approach is performance overhead
JINMEI Tatuya's avatar
JINMEI Tatuya committed
72
/// due to the additional layer.  We should eventually evaluate the cost
Evan Hunt's avatar
Evan Hunt committed
73 74 75
/// of the wrapper abstraction in benchmark tests. Another drawback is
/// that the wrapper interfaces don't provide all features of ASIO
/// (at least for the moment).  We should also re-evaluate the
JINMEI Tatuya's avatar
JINMEI Tatuya committed
76 77
/// maintenance overhead of providing necessary wrappers as we develop
/// more.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
78 79 80 81
///
/// On the other hand, we may be able to exploit the wrapper approach to
/// simplify the interfaces (by limiting the usage) and unify performance
/// optimization points.
Evan Hunt's avatar
Evan Hunt committed
82
///
JINMEI Tatuya's avatar
JINMEI Tatuya committed
83 84 85
/// As for optimization, we may want to provide a custom allocator for
/// the placeholder of callback handlers:
/// http://think-async.com/Asio/asio-1.3.1/doc/asio/reference/asio_handler_allocate.html
JINMEI Tatuya's avatar
JINMEI Tatuya committed
86

87
#endif // __ASIOLINK_H