[/
 / Copyright (c) 2003-2024 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:cancellation Cancellation]

In Asio, many objects, such as sockets and timers, support object-wide
cancellation of outstanding asynchronous operations via their close or cancel
member functions. However, certain asynchronous operations also support
individual, targeted cancellation. This per-operation cancellation is enabled
by specifying that every asynchronous agent has an associated ['cancellation
slot].

To support cancellation, an asynchronous operation installs a cancellation
handler into the agent's slot. The cancellation handler is a function object
that will be invoked when a cancellation signal is emitted by the user into the
slot. Since a cancellation slot is associated with a single agent, the slot
holds at most one handler at a time, and installing a new handler will
overwrite any previously installed handler. Thus, the same slot is reused for
subsequent asynchronous operations within the agent.

Cancellation is particularly useful when an asynchronous operation contains
multiple child agents. For example, one child agent may be complete and the
other is then cancelled, as its side effects are no longer required.

[heading See Also]

[link asio.overview.core.cancellation Per-Operation Cancellation].

[endsect]
