Getting started with ASIO C++: creating a TCP server

Our idea here is to create a very simple server application using the ASIO C++ library whose purpose is to accept connections, write "Hello World" and close the connection. I have choose to make use of simple organization for the code that you should not replicate on your real application -- specially nesting lambdas which can be very confusion as you code grows.

Let try to be clear one more time: this is not a guide on how you should design your application with ASIO. It's a guide for you to undertand how it works at a very basic level.

Let's go quickly through the basics of using ASIO as a server. We first need to create a few setup objects like the io_service, the endpoint and the acceptor:

asio::io_service service;

This creates a new io_service instance that will be used to dispatch all IO async taksks -- think of it like something that looks like a thread.

Having created a io_service we now have to setup our server configuration: what should our server listen to? Any not used port would do, in this example I choose to use 2000. Feel free to use whatever port you want.

asio::ip::tcp::endpoint endpoint(asio::ip::tcp::v4(), 2000);

There's nothing fancy here, we just set a asio::ip::tcp::endpoint that will listen to any IPv4 address on port 2000.

Whenever a new client tries to connect to your server you have to accept the connection and this should be done using an asio::ip::tcp::acceptor class. We will start accepting connections in a second, but before that we need to instantiate a new acceptor instance:

asio::ip::tcp::acceptor acceptor(service, endpoint);

Notice that asio::ip::tcp::acceptor constructor takes two arguments: service and endpoint -- this is really simple to explain: tasks are going to be run on the io_service and acceptor should bind to address pointed by the endpoint.

asio::io_service service;
asio::ip::tcp::endpoint endpoint(asio::ip::tcp::v4(), 2000);
asio::ip::tcp::acceptor acceptor(service, endpoint);

Okay, now we are done with setting up. Every configuration you need is done and now you can to start accepting connections and handling them. Each connection in ASIO is represented by a asio::ip::tcp::socket -- the socket class it where you will be doing most of your work: receiving data and writing data.

// alias to reduce verbosity
using socket_ptr = std::shared_ptr<asio::ip::tcp::socket>;
socket_ptr socket = std::make_shared<asio::ip::tcp::socket>(service);
acceptor.async_accept(*socket, [socket](std::error_code error) {
    std::cout << "New connection from " << socket->remote_endpoint().address() << std::endl;
});

To simplify and reduce the need of typing the socket complete class name we setup an alias using the new C++11's using syntax. Then we are allocating a new std::shared_ptr for the socket. async_acept will place a new task on io_service io queue that will accept the first socket that tried to connect to your server. The second argument -- a lambda -- on async_accept is a handler that will be called once a new connection has been accepted.

If you compile and run your code now you will be surpised that nothing has happened - the program will return immediatly. That's because io_service was never started! To run io_service on the main thread all we need to do is invoke run:

service.run();

Running your program now will accept one connection to the server. After the first connection is accepted it is closed and the program terminates. This is due to an important behaviour on ASIO: io_service::run() will only block if there are pending tasks on the queue, returning once the queue is or becomes empty.

asio::io_service service;
asio::ip::tcp::endpoint endpoint(asio::ip::tcp::v4(), 2000);
asio::ip::tcp::acceptor acceptor(service, endpoint);

using socket_ptr = std::shared_ptr;
socket_ptr socket = std::make_shared(service);

acceptor.async_accept(*socket, [socket](std::error_code error) {
    std::cout << "New connection from " << socket->remote_endpoint().address() << std::endl;
});

service.run();

To keep acepting more connection we need to call acceptor::async_accept again inside our handler. To do this we need to change a certain number of things:

• The socket cannot be passed through the capture group: every connection has to have a new socket
• The lambda has to be passed to itself through the capture group

A possible implementation to this would be:

using socket_ptr = std::shared_ptr<asio::ip::tcp::socket>;

// the handler lambda takes two arguments: the socket and the error code. handler, service and acceptor are taked by the capture group and are used to schedule the next accept.
std::function<void(socket_ptr, std::error_code)> handler = [&handler, &service, &acceptor](socket_ptr socket, std::error_code error) {
    std::cout << "New connection from " << socket->remote_endpoint().address() << std::endl;

    // accepts the next connection -- creates a new socket and gives it to the acceptor
    socket_ptr newSocket = std::make_shared<asio::ip::tcp::socket>(service);
    acceptor.async_accept(*newSocket, std::bind1st(handler, newSocket));
};
socket_ptr socket = std::make_shared<asio::ip::tcp::socket>(service);
acceptor.async_accept(*socket, std::bind1st(handler, socket));

We are accepting multiple connections already the only thing that remains on our server is to send our "Hello World" message to the client connecting. Sending data is really easy all you need to do is issue a socket::async_write_some and your done.

Let's go in more details: upon accepting the connection, inside the handler, we should issue a socket::async_write_some call with our hello message and a write completion handler that should close the connection after sending.

std::function<void(socket_ptr, std::error_code)> handler = [&handler, &service, &acceptor](socket_ptr socket, std::error_code error) {
    std::cout << "New connection from " << socket->remote_endpoint().address() << std::endl;

    // writes data to the client
    socket->async_write_some(asio::buffer("Hello World\n"), [socket](std::error_code error, size_t bytes) {
        socket->close();
    });

    // accepts the next connection -- creates a new socket and gives it to the acceptor
    socket_ptr newSocket = std::make_shared<asio::ip::tcp::socket>(service);
    acceptor.async_accept(*newSocket, std::bind1st(handler, newSocket));
};

Note the use of the asio::buffer class: it is a small class that will act as a wrapper around a std::string, const char* and many other data types.

If you want to see your server in action you can open a Terminal window (Application > Utilities > Terminal on the Mac or Command Prompt on Windows) and type the following:

$ telnet 127.0.0.1 2000
    Trying 127.0.0.1...
    Connected to localhost.
    Escape character is '^]'.
    Hello World
    Connection closed by foreign host.

Something that I have not covered here is receiving data from the client which works in a analogous way to writing. I think it is worth mentining that socket::async_read_some suffers from the same issues as socket::async_write_some -- it might not fill buffer and you will have to accumulate the data you are receiving on each event.

And remember: ASIO's documentation is your friend! Good luck!

Complete code with Xcode project is on GitHub.