[ceph.git] / ceph / src / boost / libs / asio / doc / overview / threads.qbk

[/
 / Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
 /
 / Distributed under the Boost Software License, Version 1.0. (See accompanying
 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
 /]

[section:threads Threads and Boost.Asio]

[heading Thread Safety]

In general, it is safe to make concurrent use of distinct objects, but unsafe
to make concurrent use of a single object. However, types such as `io_service`
provide a stronger guarantee that it is safe to use a single object
concurrently.

[heading Thread Pools]

Multiple threads may call `io_service::run()` to set up a pool of threads from
which completion handlers may be invoked. This approach may also be used with
`io_service::post()` to use a means to perform any computational tasks across a
thread pool.

Note that all threads that have joined an `io_service`'s pool are considered
equivalent, and the `io_service` may distribute work across them in an
arbitrary fashion.

[heading Internal Threads]

The implementation of this library for a particular platform may make use of
one or more internal threads to emulate asynchronicity. As far as possible,
these threads must be invisible to the library user. In particular, the threads:

* must not call the user's code directly; and

* must block all signals.

This approach is complemented by the following guarantee:

* Asynchronous completion handlers will only be called from threads that are
  currently calling `io_service::run()`.

Consequently, it is the library user's responsibility to create and manage all
threads to which the notifications will be delivered.

The reasons for this approach include:

* By only calling `io_service::run()` from a single thread, the user's code can
  avoid the development complexity associated with synchronisation. For
  example, a library user can implement scalable servers that are
  single-threaded (from the user's point of view).

* A library user may need to perform initialisation in a thread shortly after
  the thread starts and before any other application code is executed. For
  example, users of Microsoft's COM must call `CoInitializeEx` before any other
  COM operations can be called from that thread.

* The library interface is decoupled from interfaces for thread creation and
  management, and permits implementations on platforms where threads are not
  available.

[heading See Also]

[link boost_asio.reference.io_service io_service].

[endsect]
Commit	Line	Data
7c673cae FG	1	[/
	2	/ Copyright (c) 2003-2016 Christopher M. Kohlhoff (chris at kohlhoff dot com)
	3	/
	4	/ Distributed under the Boost Software License, Version 1.0. (See accompanying
	5	/ file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
	6	/]
	7
	8	[section:threads Threads and Boost.Asio]
	9
	10	[heading Thread Safety]
	11
	12	In general, it is safe to make concurrent use of distinct objects, but unsafe
	13	to make concurrent use of a single object. However, types such as `io_service`
	14	provide a stronger guarantee that it is safe to use a single object
	15	concurrently.
	16
	17	[heading Thread Pools]
	18
	19	Multiple threads may call `io_service::run()` to set up a pool of threads from
	20	which completion handlers may be invoked. This approach may also be used with
	21	`io_service::post()` to use a means to perform any computational tasks across a
	22	thread pool.
	23
	24	Note that all threads that have joined an `io_service`'s pool are considered
	25	equivalent, and the `io_service` may distribute work across them in an
	26	arbitrary fashion.
	27
	28	[heading Internal Threads]
	29
	30	The implementation of this library for a particular platform may make use of
	31	one or more internal threads to emulate asynchronicity. As far as possible,
	32	these threads must be invisible to the library user. In particular, the threads:
	33
	34	* must not call the user's code directly; and
	35
	36	* must block all signals.
	37
	38	This approach is complemented by the following guarantee:
	39
	40	* Asynchronous completion handlers will only be called from threads that are
	41	currently calling `io_service::run()`.
	42
	43	Consequently, it is the library user's responsibility to create and manage all
	44	threads to which the notifications will be delivered.
	45
	46	The reasons for this approach include:
	47
	48	* By only calling `io_service::run()` from a single thread, the user's code can
	49	avoid the development complexity associated with synchronisation. For
	50	example, a library user can implement scalable servers that are
	51	single-threaded (from the user's point of view).
	52
	53	* A library user may need to perform initialisation in a thread shortly after
	54	the thread starts and before any other application code is executed. For
	55	example, users of Microsoft's COM must call `CoInitializeEx` before any other
	56	COM operations can be called from that thread.
	57
	58	* The library interface is decoupled from interfaces for thread creation and
	59	management, and permits implementations on platforms where threads are not
	60	available.
	61
	62	[heading See Also]
	63
	64	[link boost_asio.reference.io_service io_service].
65
66	[endsect]