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

> Find official Asio documentation at think-async.com or explore the chriskohlhoff/asio repository. Learn to build local Doxygen references for in-depth guidance.

- Repository: [chriskohlhoff/asio](https://github.com/chriskohlhoff/asio)
- Tags: api-reference
- Published: 2026-07-16

---

**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`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp) — The master header that pulls in the entire public API.
- [`include/asio/basic_socket.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/basic_socket.hpp) — Core socket abstraction for TCP/UDP networking.
- [`include/asio/deadline_timer.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/deadline_timer.hpp) — Timer class for asynchronous timeouts and deadlines.
- [`include/asio/co_spawn.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/co_spawn.hpp) — Coroutine-friendly spawn helper for C++20 async operations.
- [`include/asio/basic_random_access_file.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/basic_random_access_file.hpp) — Asynchronous random-access file I/O support.
- [`include/asio/awaitable.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/awaitable.hpp) — Definition of the `awaitable` type used by the coroutine API.

For implementation details, examine [`src/asio.cpp`](https://github.com/chriskohlhoff/asio/blob/main/src/asio.cpp) (core runtime) and [`src/asio_ssl.cpp`](https://github.com/chriskohlhoff/asio/blob/main/src/asio_ssl.cpp) (SSL support).

## Building Documentation Locally

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

```bash
./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:

```cpp
#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`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/co_spawn.hpp) and [`include/asio/awaitable.hpp`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/awaitable.hpp).

### Periodic Timer Task (C++17)

This example uses `steady_timer` and `async_wait` with lambda recursion:

```cpp
#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`](https://github.com/chriskohlhoff/asio/blob/main/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:

```cpp
#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`](https://github.com/chriskohlhoff/asio/blob/main/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`](https://github.com/chriskohlhoff/asio/blob/main/include/asio.hpp) serving as the master entry point.
- You can **build documentation locally** by running [`./autogen.sh`](https://github.com/chriskohlhoff/asio/blob/main/./autogen.sh), `./configure`, and `make doc` to generate offline HTML reference in `doc/html/`.
- Core implementation details are found in [`src/asio.cpp`](https://github.com/chriskohlhoff/asio/blob/main/src/asio.cpp) and [`src/asio_ssl.cpp`](https://github.com/chriskohlhoff/asio/blob/main/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`](https://github.com/chriskohlhoff/asio/blob/main/./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`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/co_spawn.hpp) and [`include/asio/awaitable.hpp`](https://github.com/chriskohlhoff/asio/blob/main/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`](https://github.com/chriskohlhoff/asio/blob/main/include/asio/basic_socket.hpp) documents the socket API, while [`include/asio/basic_random_access_file.hpp`](https://github.com/chriskohlhoff/asio/blob/main/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.