Where can I find Asio documentation? Official sources and repository guide

You can find Asio documentation on the official website at think-async.com, within the header files of the chriskohlhoff/asio repository, and by building the Doxygen reference locally using the provided build scripts.

Asio is a cross-platform C++ library for network and low-level I/O programming that provides a consistent asynchronous model. Whether you need API references, tutorials, or implementation details, the documentation is distributed across the official website, the GitHub repository, and inline source comments.

Official Online Documentation

The canonical reference for Asio lives at https://think-async.com/Asio/. This site hosts the complete Doxygen-generated API reference, tutorial series, and a searchable index of all symbols. It is the primary destination for learning about core concepts like io_context, executors, and completion tokens.

Documentation Inside the Repository

The chriskohlhoff/asio repository contains several documentation sources ranging from high-level overviews to detailed API specifications embedded in the source code.

The README File

The README file at the repository root provides a concise overview, build instructions, and status badges. It serves as the entry point for understanding project requirements, supported platforms, and basic setup procedures.

Inline Header Documentation

The definitive API documentation is embedded directly in the header files under include/asio/. Each public class and function is documented with Doxygen comments, usage patterns, and code-level examples.

Key headers to bookmark include:

• include/asio.hpp — The master header that pulls in the entire public API.
• include/asio/basic_socket.hpp — Core socket abstraction for TCP/UDP networking.
• include/asio/deadline_timer.hpp — Timer class for asynchronous timeouts and deadlines.
• include/asio/co_spawn.hpp — Coroutine-friendly spawn helper for C++20 async operations.
• include/asio/basic_random_access_file.hpp — Asynchronous random-access file I/O support.
• include/asio/awaitable.hpp — Definition of the awaitable type used by the coroutine API.

For implementation details, examine src/asio.cpp (core runtime) and src/asio_ssl.cpp (SSL support).

Building Documentation Locally

For offline access, generate the HTML documentation using the provided Doxygen configuration:

./autogen.sh
./configure
make doc

This creates HTML files in doc/html/ that mirror the structure and content of the online site, allowing you to browse the full reference without an internet connection.

Practical Code Examples

Below are complete, compilable examples demonstrating common Asio patterns. All examples use standalone Asio (no Boost dependency) and require C++17 or C++20.

Asynchronous TCP Echo Client (C++20 Coroutines)

This example demonstrates co_spawn, awaitable, and the use_awaitable completion token:

#include <asio.hpp>
#include <asio/experimental/co_spawn.hpp>
#include <asio/experimental/awaitable_operators.hpp>
#include <iostream>

using asio::awaitable;
using asio::co_spawn;
using asio::detached;
using asio::ip::tcp;
using asio::use_awaitable;

// Echo client that connects, sends a line, reads the response.
awaitable<void> echo_client(std::string host, std::string port, std::string msg)
{
    auto executor = co_await asio::this_coro::executor;
    tcp::resolver resolver(executor);
    tcp::socket sock(executor);

    // Resolve and connect
    auto endpoints = co_await resolver.async_resolve(host, port, use_awaitable);
    co_await asio::async_connect(sock, endpoints, use_awaitable);

    // Send the message
    co_await asio::async_write(sock, asio::buffer(msg), use_awaitable);

    // Receive the echo
    std::array<char, 128> data{};
    std::size_t n = co_await sock.async_read_some(asio::buffer(data), use_awaitable);
    std::cout << "Server replied: " << std::string(data.data(), n) << "\n";
}

int main()
{
    asio::io_context ctx;
    co_spawn(ctx, echo_client("localhost", "12345", "Hello Asio!\n"), detached);
    ctx.run();
}

The coroutine infrastructure is defined in include/asio/co_spawn.hpp and include/asio/awaitable.hpp.

Periodic Timer Task (C++17)

This example uses steady_timer and async_wait with lambda recursion:

#include <asio.hpp>
#include <iostream>

void periodic_task(asio::io_context& io, int interval_seconds)
{
    auto timer = std::make_shared<asio::steady_timer>(io,
                         std::chrono::seconds(interval_seconds));

    std::function<void()> handler;
    handler = [&, timer, interval_seconds, &handler]()
    {
        std::cout << "Tick at " << std::chrono::system_clock::now().time_since_epoch().count() << "\n";
        timer->expires_after(std::chrono::seconds(interval_seconds));
        timer->async_wait([&](const asio::error_code& ec)
        {
            if (!ec) handler();   // reschedule
        });
    };
    handler();   // start the loop
}

int main()
{
    asio::io_context io;
    periodic_task(io, 2);   // every 2 seconds
    io.run();
}

The timer implementation is located in include/asio/basic_waitable_timer.hpp (which defines steady_timer).

Asynchronous File Read (C++20 Coroutines)

This example demonstrates basic_random_access_file for file I/O:

#include <asio.hpp>
#include <asio/experimental/awaitable_operators.hpp>
#include <fstream>
#include <iostream>

using asio::awaitable;
using asio::use_awaitable;

// Reads an entire file using async I/O.
awaitable<void> async_file_read(const std::string& path)
{
    auto ex = co_await asio::this_coro::executor;
    asio::basic_random_access_file<asio::any_io_executor> file(ex);
    co_await file.async_open(path, asio::random_access_file::read_only, use_awaitable);

    std::vector<char> buffer(1024);
    std::size_t total = 0;
    while (true)
    {
        std::size_t n = co_await file.async_read_some(
            asio::buffer(buffer), use_awaitable);
        if (n == 0) break;
        std::cout.write(buffer.data(), n);
        total += n;
    }
    std::cout << "\n--- " << total << " bytes read ---\n";

    co_await file.async_close(use_awaitable);
}

int main()
{
    asio::io_context ctx;
    asio::co_spawn(ctx, async_file_read("example.txt"), asio::detached);
    ctx.run();
}

See include/asio/basic_random_access_file.hpp for the complete file API.

Summary

• The primary Asio documentation is hosted at think-async.com, offering comprehensive Doxygen-generated API references and tutorials.
• The chriskohlhoff/asio repository contains inline documentation in header files under include/asio/, with include/asio.hpp serving as the master entry point.
• You can build documentation locally by running ./autogen.sh, ./configure, and make doc to generate offline HTML reference in doc/html/.
• Core implementation details are found in src/asio.cpp and src/asio_ssl.cpp for the runtime and SSL support respectively.

Frequently Asked Questions

How do I generate Asio documentation for offline use?

Execute ./autogen.sh, ./configure, and make doc from the repository root. This produces HTML documentation in the doc/html/ directory using Doxygen, allowing you to browse the full API reference without internet access.

Where is the coroutine support documented in the source?

C++20 coroutine support is implemented in include/asio/co_spawn.hpp and include/asio/awaitable.hpp. These headers define co_spawn, awaitable, and the use_awaitable completion token used with asynchronous operations.

Can I find usage examples in the repository header files?

Yes. The headers under include/asio/ contain inline Doxygen comments with usage patterns and code snippets. For instance, include/asio/basic_socket.hpp documents the socket API, while include/asio/basic_random_access_file.hpp provides examples for asynchronous file I/O.

What is the difference between the repository README and the official website?

The repository README provides a concise project overview, build instructions, and quick links. The official website at think-async.com hosts the complete Doxygen-generated reference manual, detailed tutorials, and a searchable index of all symbols.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}