Commit e183d8b7 authored by Francis Dupont's avatar Francis Dupont
Browse files

[#996] Added MT considerations

parent 1a0d168d
......@@ -108,7 +108,10 @@
* - @subpage perfdhcpInternals
*
* @section libraries Kea libraries
* - @subpage libutil
* - @subpage libasiolink
* - @subpage libcc
* - @subpage libdatabase
* - @subpage libdhcp
* - @subpage libdhcpIntro
* - @subpage libdhcpRelay
......@@ -116,6 +119,7 @@
* - @subpage libdhcpPktFilter
* - @subpage libdhcpPktFilter6
* - @subpage libdhcpErrorLogging
* - @subpage libstats
* - @subpage libdhcp_ddns
* - @subpage libdhcpsrv
* - @subpage leasemgr
......@@ -132,6 +136,7 @@
* - @subpage cpl
* - @subpage cplSignals
* - @subpage libyang
* - @subpage libhttp
*
* @section miscellaneousTopics Miscellaneous Topics
* - @subpage terminology
......
......@@ -5,6 +5,8 @@ AM_CPPFLAGS += $(BOOST_INCLUDES)
AM_CXXFLAGS = $(KEA_CXXFLAGS) -Wno-non-virtual-dtor
EXTRA_DIST = asiolink.dox
CLEANFILES = *.gcno *.gcda
# This is a wrapper library.
......
// 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.
*/
......@@ -96,4 +96,12 @@ ParamsList is a simple vector<string>. There will be more specific
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
......@@ -175,5 +175,14 @@ main loop must contain calls to @ref isc::asiolink::IOService::run or
@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.
*/
......@@ -6,7 +6,7 @@ AM_CPPFLAGS += $(BOOST_INCLUDES)
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
......
// 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
......@@ -260,4 +260,18 @@ error string as an argument. The handler function may use its logging
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
......@@ -51,4 +51,11 @@ and isc::dhcp_ddns::NameChangeUDPListener. The implementation is strictly
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
......@@ -198,4 +198,28 @@
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
......@@ -461,5 +461,21 @@ is used by DHCPv4 and DHCPv6 components.
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
......@@ -176,4 +176,10 @@ instantiated with the appropriate value and put onto the expression vector.
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.
*/
......@@ -1649,7 +1649,22 @@ Some other Kea APIs are intrinsically thread safe because they do not
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
*/
......@@ -4,8 +4,10 @@ AM_CPPFLAGS = -I$(top_builddir)/src/lib -I$(top_srcdir)/src/lib
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
......
// 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
......@@ -682,4 +682,17 @@ loggers. As the loggers are independent and the severity levels
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
......@@ -173,4 +173,9 @@ during startup and the subsequent receipt of a SIGHUP:
@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.
*/
......@@ -17,6 +17,8 @@ libkea_stats_la_LIBADD += $(top_builddir)/src/lib/util/libkea-util.la
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 \
......
// 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).
*/
......@@ -48,6 +48,8 @@ libkea_util_la_LIBADD = $(top_builddir)/src/lib/exceptions/libkea-exceptions.la
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.
......
// 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
......@@ -181,4 +181,10 @@ to verify that your environment is ready. If there is anything
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.
*/
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment