[/
 / Copyright (c) 2003-2025 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:async_ops Asynchronous Operations]

[$async_op_model.png [width 421px]]

An ['asynchronous operation] is the basic unit of composition in the Asio
asynchronous model. Asynchronous operations represent work that is launched and
performed in the background, while the user's code that initiated the work can
continue with other things.

Conceptually, the lifecycle of an asynchronous operation can be described in
terms of the following events and phases:

[$async_op_phases.png [width 861px]]

An ['initiating function] is a function which may be called by the user to
start an asynchronous operation.

A ['completion handler] is a user-provided, move-only function object that will
be invoked, at most once, with the result of the asynchronous operation. The
invocation of the completion handler tells the user about something that has
already happened: the operation completed, and the side effects of the
operation were established.

The initiating function and completion handler are incorporated into the user's
code as follows:

[$async_op_init_complete.png [width 496px]]

Synchronous operations, being embodied as single functions, have several
inherent semantic properties as a consequence. Asynchronous operations adopt
some of these semantic properties from their synchronous counterparts, in order
to facilitate flexible and efficient composition.

[table
  [
    [Property of synchronous operations]
    [Equivalent property of asynchronous operations]
  ]
  [
    [
      When a synchronous operation is generic (i.e. a template) the return type
      is deterministically derived from the function and its arguments.
    ]
    [
      When an asynchronous operation is generic, the completion handler's
      arguments' types and order are deterministically derived from the
      initiating function and its arguments.
    ]
  ]
  [
    [
      If a synchronous operation requires a temporary resource (such as memory,
      a file descriptor, or a thread), this resource is released before
      returning from the function.
    ]
    [
      If an asynchronous operation requires a temporary resource (such as
      memory, a file descriptor, or a thread), this resource is released before
      calling the completion handler.
    ]
  ]
]

The latter is an important property of asynchronous operations, in that it
allows a completion handler to initiate further asynchronous operations without
overlapping resource usage. Consider the trivial (and relatively common) case
of the same operation being repeated over and over in a chain:

[$async_op_trivial_chain.png [width 375px]]

By ensuring that resources are released before the completion handler runs, we
avoid doubling the peak resource usage of the chain of operations.

[endsect]
