* - @subpage perfdhcpInternals
*
* @section libraries Kea libraries
+ * - @subpage libutil
+ * - @subpage libasiolink
* - @subpage libcc
+ * - @subpage libdatabase
* - @subpage libdhcp
* - @subpage libdhcpIntro
* - @subpage libdhcpRelay
* - @subpage libdhcpPktFilter
* - @subpage libdhcpPktFilter6
* - @subpage libdhcpErrorLogging
+ * - @subpage libstats
* - @subpage libdhcp_ddns
* - @subpage libdhcpsrv
* - @subpage leasemgr
* - @subpage cpl
* - @subpage cplSignals
* - @subpage libyang
+ * - @subpage libhttp
*
* @section miscellaneousTopics Miscellaneous Topics
* - @subpage terminology
AM_CXXFLAGS = $(KEA_CXXFLAGS) -Wno-non-virtual-dtor
+EXTRA_DIST = asiolink.dox
+
CLEANFILES = *.gcno *.gcda
# This is a wrapper library.
--- /dev/null
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libasiolink libkea-asiolink - Kea Boost ASIO Library
+
+@section asiolinkUtilities Boost ASIO Utilities
+
+The asiolink library (libkea-asiolink) encapsulates Boost ASIO tools:
+
+ - addr utilities: prefix (IOAddress and length pair) tools.
+
+ - dummy I/O callback.
+
+ - interval timer.
+
+ - I/O acceptor: asynchronous server ASIO socket (base class).
+
+ - I/O address: ASIO IP address.
+
+ - I/O ASIO socket (derived from I/O socket).
+
+ - I/O endpoint: ASIO IP endpoint (abstraction of a socket address).
+
+ - I/O error: @c isc::asiolink::IOError exception declaration.
+
+ - I/O service: ASIO I/O service (named I/O context in recent versions).
+
+ - I/O socket: ASIO I/O socket base class.
+
+ - TCP acceptor: TCP derivation of I/O acceptor.
+
+ - TCP endpoint: TCP derivation of I/O endpoint.
+
+ - TCP socket: TCP derivation of I/O socket.
+
+ - UDP endpoint: UDP derivation of I/O endpoint.
+
+ - UDP socket: UDP derivation of I/O socket.
+
+ - Unix domain socket: Unix socket (AF_LOCAL) derivation of I/O socket.
+
+ - Unix domain acceptor: Unix socket (AF_LOCAL) derivation of I/O acceptor.
+
+ - Unix domain endpoint: Unix socket (AF_LOCAL) derivation of I/O endpoint.
+
+@section asiolinkMTConsiderations Multi-Threading Consideration for Boost ASIO Utilities
+
+By default Boost ASIO utilities are not thread safe even Boost ASIO tools
+themselves are. When there is no state and the encapsulation is direct
+the thread safety property is preserved. Exceptions to the by default
+no thread safe are:
+
+ - I/O address (direct encapsulation) is thread safe.
+
+ - interval timer setup and cancel methods are thread safe.
+
+*/
methods implemented in the future, but for the time being only
@ref isc::data::SimpleParser::deriveParams is implemented.
+@subsection ccMTConsiderations Multi-Threading Consideration for Configuration Utilities
+
+No configuration utility is thread safe. For instance stamped values are
+not thread safe so any read access must be done in a context where write
+access at the same time is not possible. Note that configuration is
+performed by the main thread with service threads stopped so this constraint
+is fulfilled.
+
*/
-// Copyright (C) 2015-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2015-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
@ref isc::asiolink::IOService::poll or their variants to invoke Command
Manager's handlers as required for processing control requests.
+@section ctrlSocketMTConsiderations Multi-Threading Consideration for Control Channel
+
+The control channel utilities are not thread safe but they are used only
+by the main thread so in most cases it does not matter. For instance
+the assumption that only at most one command can be executed at a given
+time can be done. Of course this has its limit: when the command changes
+the configuration or is incompatible with a simultaneous packet
+processing the multi-threading mode must be checked and service threads
+stopped.
*/
AM_CXXFLAGS = $(KEA_CXXFLAGS)
# Ensure that the message file is included in the distribution
-EXTRA_DIST = db_messages.mes
+EXTRA_DIST = database.dox db_messages.mes
CLEANFILES = *.gcno *.gcda
--- /dev/null
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libdatabase libkea-database - Kea Database Library
+
+@section databaseMTConsiderations Multi-Threading Consideration for Database
+
+MySQL and PostgreSQL provide connection pools which is used to make
+lease, host and legal log backends thread safe. Cassandra/CQL is
+thread safe by design.
+
+MySQL and PostgreSQL are inter-process safe only when transactions are used
+(including the MySQL auto-transaction mode which includes queries into
+a transaction). For MySQL this means that transactions must be supported
+by the database engine (the engine selection is done in the schema).
+
+Note the InnoDB engine used by Kea for MySQL databases cancels a transaction
+when a deadlock is detected (rare but possible event) and leaves the charge
+to retry the transaction to the caller.
+
+*/
-// Copyright (C) 2012-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
mechanism to log this error message. In particular, the DHCP server
will use BINDX logger to log the error message.
+@section libdhcpMTConsiderations Multi-Threading Consideration for DHCP library
+
+By default APIs provided by the DHCP library are not thread safe.
+For instance packets or options are not thread safe. Exception are:
+
+ - external sockets are thread safe (the container used to manage external
+ socket is thread safe so one can for instance delete an external socket
+ at any time).
+
+ - interface send method is thread safe (mainly because it does not change
+ any internal state).
+
+ - packet queue ring is thread safe.
+
*/
-// Copyright (C) 2013-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
unidirectional: there is no explicit acknowledgment of receipt of a
request so, as it is UDP, no guarantee of delivery.
+@section libdhcp_ddnsMTConsiderations Multi-Threading Consideration for DHCP_DDNS Request I/O Library
+
+By default this library is not thread safe (it uses asynchronous I/O) at
+the exception of the Name Change Request sender class (@c
+isc::dhcp_ddns::NameChangeSender) which is Kea thread safe (i.e. it is
+thread safe when the multi-threading mode is true).
+
*/
-// Copyright (C) 2012-2019 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
this property should not be used because it limits negative cache
addition to only be performed by the host manager.
+@section dhcpDatabaseBackendsMTConsiderations Multi-Threading Consideration for DHCP Database Backends
+
+Lease and host database backends including the memfile for leases are Kea
+(i.e. when the multi-threading mode is true) thread safe. This extends
+to legal / forensic log backends but not to config backends which is
+used only for configuration by the main thread with packet processing
+threads stopped so has no thread safety requirements.
+
+There are exceptions:
+
+ - memfile constructor (including loading of leases from files) is not
+ thread safe.
+
+ - lfc handling in memfile is not thread safe: instead it is required
+ to be called from the main thread.
+
+ - wipe lease methods are either not thread safe or not implemented.
+
+Note for statistics queries it does not make sense to call them with
+running packet processing threads so they have no thread safety guarantees.
+
+Note too the memfile backend is not inter-process safe so must be kept
+private to the Kea server using it.
+
*/
-// Copyright (C) 2012-2018 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
DHCPv4-over-DHCPv6 which are relayed by a DHCPv6 relay are not yet supported.
+@section libdhcpsrvMTConsiderations Multi-Threading Consideration for Server DHCP Library
+
+Note that for backends specific consideration is in @ref
+dhcpDatabaseBackendsMTConsiderations.
+
+Below Kea thread safe means thread safe when the multi-threading mode is
+true (when it is false packets are processed by the main thread).
+
+By default this library is not thread safe, in particular all classes used
+for configuration are not thread safe. Exceptions are:
+
+ - allocation engine allocator is Kea thread safe.
+
+ - resource handler is thread safe.
+
+ - last allocated members of subnets are Kea thread safe.
*/
-// Copyright (C) 2015-2018 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2015-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
More operators are expected to be implemented in upcoming releases.
+@section dhcpEvalMTConsiderations Multi-Threading Consideration for Expression Evaluation Library
+
+This library is not thread safe, for instance @ref isc::dhcp::evaluateBool
+or @ref isc::dhcp::evaluateString must not be called in different threads
+on the same packet.
+
*/
involve a shared structure so for instance despite of its name the
interface manager send methods are generic thread safe.
-Per library documentation will be updated to detail thread safety to help
-hooks writers and to provide an exhaustive list of Kea thread safe APIs.
+Per library documentation details thread safety to help hooks writers
+and to provide an exhaustive list of Kea thread safe APIs:
+ - @ref utilMTConsiderations
+ - @ref logMTConsiderations
+ - @ref asiolinkMTConsiderations
+ - @ref ccMTConsiderations
+ - @ref databaseMTConsiderations
+ - @ref ctrlSocketMTConsiderations
+ - @ref libdhcpMTConsiderations
+ - @ref statsMTConsiderations
+ - @ref yangMTConsiderations
+ - @ref libdhcp_ddnsMTConsiderations
+ - @ref dhcpEvalMTConsiderations
+ - @ref cplMTConsiderations
+ - @ref dhcpDatabaseBackendsMTConsiderations
+ - @ref libdhcpsrvMTConsiderations
+ - @ref httpMTConsiderations
*/
AM_CPPFLAGS += $(BOOST_INCLUDES)
AM_CXXFLAGS = $(KEA_CXXFLAGS)
+EXTRA_DIST = http.dox
+
# Ensure that the message file is included in the distribution
-EXTRA_DIST = http_messages.mes
+EXTRA_DIST += http_messages.mes
CLEANFILES = *.gcno *.gcda
--- /dev/null
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libhttp libkea-http - Kea HTTP Library
+
+@section httpMTConsiderations Multi-Threading Consideration for HTTP Library
+
+By default this library is not thread safe, for instance HTTP listeners
+and HTTP messages are not thread safe. Exceptions are:
+
+ - HTTP client is Kea (i.e. when the multi-threading mode is treu)
+ thread safe.
+
+ - date time is thread safe (mainly because its encapsulated POSIX time
+ is private and read-only, or because all methods are instance const methods
+ or class methods).
+
+ - URL is thread safe (all public methods are const methods).
+
+*/
-// Copyright (C) 2013-2019 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
independent, fine-tuning of what and what is not recorded can be achieved.</li>
</ol>
+
+@section logMTConsiderations Multi-Threading Consideration for Logging
+
+Logging is thread safe: messages emitted at the same time do not mix.
+
+When the KEA_LOCKFILE_DIR environment variable is not set to none
+Logging to files is multi-process safe too: for instance two servers
+can be configured to put log messages in the same file.
+
+The @c isc::log::Logger class initializes its implementation in a lazy
+(i.e. on demand) but thread safe way so it is always initialized at most
+once even in a multi-threaded environment.
+
*/
-// Copyright (C) 2016-2017 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2016-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
@image html cpl_signal_sequence.svg "CPL Signal Handling Sequence"
+@section cplMTConsiderations Multi-Threading Consideration for Controllable Process Layer
+
+By default this library is not thread safe and currently there is no known
+exception.
+
*/
libkea_stats_la_LIBADD += $(top_builddir)/src/lib/exceptions/libkea-exceptions.la
libkea_stats_la_LIBADD += $(BOOST_LIBS)
+EXTRA_DIST = stats.dox
+
libkea_stats_includedir = $(pkgincludedir)/stats
libkea_stats_include_HEADERS = \
context.h \
--- /dev/null
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libstats libkea-stats - Kea Statistics Library
+
+@section statsMTConsiderations Multi-Threading Consideration for Statistics
+
+The statistic manager (@c isc::stats::StatsMgr singleton) is Kea thread safe
+i.e. it is thread safe when the multi-threading mode is true (when the
+multi-threading mode is false Kea main thread processes packets).
+
+*/
libkea_util_la_LDFLAGS = -no-undefined -version-info 14:0:0
+EXTRA_DIST = util.dox
+
CLEANFILES = *.gcno *.gcda
# Specify the headers for copying into the installation directory tree.
--- /dev/null
+// Copyright (C) 2020 Internet Systems Consortium, Inc. ("ISC")
+//
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+/**
+ @page libutil libkea-util - Kea Utilities Library
+
+@section utilUtilities Utilities
+
+The utilities library (libkea-util) provides generic and Kea utilities:
+
+ - boost time: boost Posix time and duration to text conversions.
+
+ - buffer (header only): input and output buffers.
+
+ - csv file: comma-separated values (CSV) files.
+
+ - double: test utility for checking double equivalence (vs. strict
+ equality).
+
+ - encode: base16, base32, base64 and hexadecimal conversions.
+
+ - filename: filename manipulation (avoid dependency on boost).
+
+ - hash: Fowler-Noll-Vo 64 bit hash function.
+
+ - io: test utils for file descriptors and sockets.
+
+ - io utilities (header only): reads and writes integers from / to buffers.
+
+ - labeled values: labeled constants and label constant sets.
+
+ - multi threading manager (in the util library to be available in the
+ whole Kea code).
+
+ - optional: optional values.
+
+ - pid file: process id files.
+
+ - pointer util: test utility to compare smart pointers.
+
+ - process spawn.
+
+ - random: pseudo-random number generator for query ids (please use
+ the cryptolink random generator when security matters).
+
+ - range utilities.
+
+ - read-write mutex (header only).
+
+ - signal set: signal handling (please @c isc::process::IOSignalSet instead).
+
+ - staged values.
+
+ - state model: event-driven deterministic finite state automaton
+ (to accept a regular language).
+
+ - stop watch: to measure code execution time.
+
+ - string util: various string common tools.
+
+ - thread pool.
+
+ - time utilities: DNSSEC time conversions from and to text.
+
+ - unittests (directory): tools for google test unit tests.
+
+ - unlock guard: RAII helper to unlock a mutex in a limited scope.
+
+ - versioned csv file: csv files with multiple versions of file schema.
+
+ - watched socket (required as select() or poll() do not support condition
+ variables).
+
+ - watched threads: threads using ready, error and terminate watched socket.
+
+@section utilMTConsiderations Multi-Threading Consideration for Utilities
+
+By default utilities are not thread safe, for instance CSV files and
+qid random generators are not thread safe. Exceptions are:
+
+ - multi threading manager is thread safe.
+
+ - read-write mutex is thread safe.
+
+ - state model is thread safe.
+
+ - thread pool is thread safe.
+
+ - unlock guard is thread safe.
+
+ - watched threads are thread safe.
+
+*/
-// Copyright (C) 2018-2019 Internet Systems Consortium, Inc. ("ISC")
+K// Copyright (C) 2018-2020 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
wrong, it will enumerate the problems and will suggest how to solve
them.
+@section yangMTConsiderations Multi-Threading Consideration for YANG Utilities
+
+The YANG utilities are not thread safe. Note as they are used only in a
+configuration context it is not a problem, and the yang / sysrepo libraries
+are multi-threaded so their APIs are thread safe.
+
*/
projects / thirdparty / kea.git / commitdiff
