Lesson 13 of 18 Concurrency and I/O

poll(): Serving Many Clients

Handle many TCP clients in one thread with poll(): pollfd, events and revents, a growable watch list, and a complete chat server in C.

50-60 min intermediate 0/18 lessons done
Course contents Lesson 13 of 18 · 0 done
On this page (9 sections)
  1. What you will learn
  2. The idea
  3. The API
  4. A chat server
  5. Honest limitations
  6. poll() vs epoll and kqueue
  7. Key takeaways
  8. Exercises
  9. Quiz

What you will learn

  • What synchronous I/O multiplexing means and why it scales better than a process per client.
  • The poll() API: struct pollfd, events, revents and the timeout.
  • How to add and remove sockets from the watch list safely while iterating.
  • A complete single-threaded chat server.

The idea

Instead of blocking on one socket, you give the kernel a list of descriptors and ask: “Sleep until any of these is ready, then tell me which.” Your program then performs only the calls that won’t block. One thread can juggle hundreds of connections this way.

The API

#include <poll.h>

struct pollfd {
    int   fd;        /* descriptor to watch (negative = ignore this entry) */
    short events;    /* what you're interested in */
    short revents;   /* what actually happened (filled in by poll) */
};

int poll(struct pollfd fds[], nfds_t nfds, int timeout_ms);
FlagIn eventsMeaning in revents
POLLINYesData to read, or a connection to accept(), or end-of-stream
POLLOUTYesRoom to write (or a non-blocking connect finished)
POLLERRNo (always reported)Error condition on the socket
POLLHUPNo (always reported)Peer hung up
POLLNVALNo (always reported)The fd isn’t open; a bug in your list

timeout_ms is -1 to wait forever, 0 to check and return immediately, or a number of milliseconds. poll() returns the number of entries with non-zero revents, 0 on timeout, or -1 on error (handle EINTR by retrying).

A listening socket becomes readable when a new connection is waiting, so the same POLLIN check covers both accept() and recv().

A chat server

Every line a client sends is relayed to every other client, tagged with the sender’s descriptor number. Slot 0 of the watch list is the listening socket.

/* poll_chat.c - a chat room: every line a client sends is relayed to the others.
 * Single process, single thread, poll(). Usage: ./poll_chat 7070 */
#include <errno.h>
#include <poll.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>

static int open_listener(const char *port)
{
    struct addrinfo hints, *res, *ai;
    memset(&hints, 0, sizeof hints);
    hints.ai_family = AF_UNSPEC;
    hints.ai_socktype = SOCK_STREAM;
    hints.ai_flags = AI_PASSIVE;
    if (getaddrinfo(NULL, port, &hints, &res) != 0)
        return -1;

    int fd = -1;
    for (ai = res; ai != NULL; ai = ai->ai_next) {
        fd = socket(ai->ai_family, ai->ai_socktype, ai->ai_protocol);
        if (fd == -1)
            continue;
        int on = 1;
        setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &on, sizeof on);
        if (bind(fd, ai->ai_addr, ai->ai_addrlen) == 0)
            break;
        close(fd);
        fd = -1;
    }
    freeaddrinfo(res);
    if (fd != -1 && listen(fd, 16) == -1) {
        close(fd);
        fd = -1;
    }
    return fd;
}

/* A growable array of pollfd entries. Slot 0 is always the listener. */
struct watch_list {
    struct pollfd *fds;
    int count;
    int capacity;
};

static void watch_add(struct watch_list *w, int fd)
{
    if (w->count == w->capacity) {
        w->capacity *= 2;
        w->fds = realloc(w->fds, sizeof *w->fds * (size_t)w->capacity);
        if (w->fds == NULL) {
            perror("realloc");
            exit(1);
        }
    }
    w->fds[w->count].fd = fd;
    w->fds[w->count].events = POLLIN;
    w->fds[w->count].revents = 0;
    w->count++;
}

/* Remove slot i by moving the last entry into it (order doesn't matter). */
static void watch_remove(struct watch_list *w, int i)
{
    w->fds[i] = w->fds[w->count - 1];
    w->count--;
}

static void relay(struct watch_list *w, int from_fd, const char *msg, size_t len)
{
    for (int i = 1; i < w->count; i++) {
        int fd = w->fds[i].fd;
        if (fd == from_fd)
            continue;
        if (send(fd, msg, len, MSG_NOSIGNAL) == -1)
            perror("send");
    }
}

int main(int argc, char *argv[])
{
    const char *port = argc > 1 ? argv[1] : "7070";
    int listener = open_listener(port);
    if (listener == -1) {
        fprintf(stderr, "cannot listen on port %s\n", port);
        return 1;
    }

    struct watch_list w = { malloc(sizeof(struct pollfd) * 8), 0, 8 };
    watch_add(&w, listener);
    printf("chat room open on port %s\n", port);

    for (;;) {
        if (poll(w.fds, (nfds_t)w.count, -1) == -1) {
            if (errno == EINTR)
                continue;
            perror("poll");
            return 1;
        }

        for (int i = 0; i < w.count; i++) {
            if (w.fds[i].revents == 0)
                continue;

            if (w.fds[i].fd == listener) {
                int client = accept(listener, NULL, NULL);
                if (client == -1) {
                    perror("accept");
                    continue;
                }
                watch_add(&w, client);
                printf("fd %d joined (%d in room)\n", client, w.count - 1);
                continue;
            }

            char buf[512];
            ssize_t n = recv(w.fds[i].fd, buf, sizeof buf, 0);
            if (n <= 0) {              /* 0 = hung up, -1 = error */
                printf("fd %d left\n", w.fds[i].fd);
                close(w.fds[i].fd);
                watch_remove(&w, i);
                i--;                   /* re-check the entry moved into slot i */
                continue;
            }

            char line[600];
            int len = snprintf(line, sizeof line, "[%d] %.*s", w.fds[i].fd, (int)n, buf);
            if (len > (int)sizeof line - 1)
                len = (int)sizeof line - 1;
            relay(&w, w.fds[i].fd, line, (size_t)len);
        }
    }
}

How it works

  1. poll() sleeps until at least one descriptor is ready.
  2. We scan the list. Entries with revents == 0 are skipped.
  3. Listener ready → accept() won’t block, so we accept and append the new client.
  4. Client ready → recv() won’t block. If it returns data, relay it. If it returns 0 or -1 (POLLHUP/POLLERR lead here too), the client is gone: close it and remove it.
  5. Removal while iterating: we move the last entry into slot i and decrement i, so the moved entry gets checked in this same pass. Order in the list doesn’t matter to poll().
  6. Adding while iterating is safe: the new entry is appended with revents = 0, so it’s simply skipped until the next poll().

MSG_NOSIGNAL on the relay send() stops one vanished client from killing the whole server with SIGPIPE.

Try it

gcc -Wall -o poll_chat poll_chat.c
./poll_chat 7070
# open two or three more terminals:
nc localhost 7070

Type in one nc window and the others show [4] your text.

Honest limitations

This server is correct for learning but cuts two corners real servers can’t:

  • Blocking relay sends. If one client stops reading, its send buffer fills and send() blocks the whole server. Production code makes client sockets non-blocking, keeps a per-client outgoing queue, and watches POLLOUT to drain it.
  • No line framing. A recv() might return half a line or two lines; we relay chunks as they come. Lesson 15 introduces a per-connection buffer that fixes this.

poll() vs epoll and kqueue

poll() copies the whole list into the kernel on every call and you scan the whole list afterwards, so cost grows with the number of connections, ready or not. Fine for hundreds. For tens of thousands, Linux offers epoll and BSD/macOS offer kqueue: you register descriptors once and get back only the ready ones. The program structure stays the same, so poll() is the right place to learn the pattern. Libraries such as libuv and libevent wrap these for you.

Key takeaways

  • poll() waits on many descriptors at once and reports which are ready.
  • Set events, read revents; errors and hang-ups are always reported.
  • A readable listener means a pending connection; a readable client means data or end-of-stream.
  • Remove entries carefully while iterating; protect relays against SIGPIPE and slow readers.

Exercises

  1. Add nicknames: the first line a client sends becomes its name, and messages are tagged [name] instead of [fd].
  2. Add a 60-second poll() timeout that prints how many clients are connected when nothing happens.
  3. Make client sockets non-blocking and give each client an outgoing buffer drained on POLLOUT, so a stalled client can’t block the others.

Quiz

  1. What does POLLIN on the listening socket mean?
  2. Why does the server decrement i after removing a client?
  3. Name one reason to move from poll() to epoll on Linux.
Show answers
  1. A new connection is waiting, so accept() will return without blocking.
  2. The last entry was moved into slot i; decrementing makes the loop examine that moved entry instead of skipping it.
  3. With many connections, poll() re-sends and re-scans the whole list each time; epoll registers descriptors once and returns only ready ones, so cost tracks activity rather than total connections.

Finished this lesson?

Mark it complete to track your progress (saved in this browser).