Notes Tutorials

Concurrency basics

Doing several things at once makes programs faster and introduces a new kind of bug. Concurrency vs parallelism, why waiting is the usual reason to go concurrent, async in Python and JavaScript, race conditions you can reproduce, locks, Go's race detector, and the database version of the same bug.

7 min readAlso available in Bahasa Indonesia →

Everything in this series so far ran one step at a time: line after line, call after call. Real systems rarely work like that. A web server handles many requests at once. A page loads ten things in parallel. A checkout calls the payment API, the shipping API, and the email service. Doing several things at the same time makes software faster and more responsive. It also introduces a kind of bug that doesn’t exist in step-by-step code, and those bugs are among the hardest to find.

This part covers the basics: what concurrency is, when it helps, and the one bug everyone meets, the race condition.

Concurrency is not parallelism

Rob Pike’s talk on Go draws the distinction that most explanations start with: “Concurrency is about dealing with lots of things at once. Parallelism is about doing lots of things at once.” More formally, “concurrency is the composition of independently executing processes”, while parallelism is things literally running at the same moment, on different CPU cores.

A waiter with ten tables is concurrent: taking an order here, bringing a drink there, never standing still waiting for one table to finish eating. Ten waiters are parallel. You can have concurrency on a single core, by switching between tasks while each one waits. You need multiple cores for parallelism.

Most of the time, you’re waiting

The most common reason to go concurrent in everyday code isn’t heavy computation. It’s waiting: for the network, the database, the disk, an API. A request to a payment gateway might take 300 ms, and the CPU does nothing during that time.

Three calls of about one second each, one after the other, versus started together, with Python’s asyncio, “a library to write concurrent code using the async/await syntax”:

async def fetch(name, seconds):
    await asyncio.sleep(seconds)          # stands in for a network call
    return f"{name} done"

async def one_by_one():
    return [await fetch("rates", 1), await fetch("stock", 1), await fetch("email", 1)]

async def together():
    return await asyncio.gather(fetch("rates", 1), fetch("stock", 1), fetch("email", 1))
one by one 3.01 s  ['rates done', 'stock done', 'email done']
together   1.00 s  ['rates done', 'stock done', 'email done']

Same work, a third of the time, on one thread. Nothing ran in parallel; the program simply didn’t sit idle while waiting.

JavaScript works the same way, and it’s how the browser and Node handle everything. Promise.all “takes an iterable of promises as input and returns a single Promise” that fulfills when all of them do:

for (const n of ["rates", "stock", "email"]) await fetchFake(n, 1000);       // one by one
const all = await Promise.all([fetchFake("rates", 1000), fetchFake("stock", 1000), fetchFake("email", 1000)]);
one by one 3.00 s
together   1.00 s [ 'rates done', 'stock done', 'email done' ]

Note what MDN adds: the combined promise “rejects when any of the input’s promises rejects”. If one call fails, you need to decide what happens to the others, which is the error handling from part 13 again, now with several things in flight.

For work that’s CPU-heavy rather than waiting (image processing, big calculations), you need real parallelism: multiple processes, or a language and runtime that runs threads on several cores. In standard CPython, “due to the Global Interpreter Lock, only one thread can execute Python code at once”, though “threading is still an appropriate model if you want to run multiple I/O-bound tasks simultaneously.” Python 3.13 added optional free-threaded builds that remove that limit, but they’re not the default yet. Go, Java, and others run threads on multiple cores out of the box.

The race condition

Here’s where it gets dangerous. One book left in stock, and three customers press “buy” at the same moment. Each request runs in its own thread:

stock = 1
sold = []

def buy(customer):
    global stock
    if stock >= 1:            # check
        time.sleep(0.01)      # e.g. waiting for the payment API
        stock -= 1            # act
        sold.append(customer)
stock: -2 sold to: ['Ana', 'Budi', 'Cici']

One book, three sales, and the stock is negative. All three threads checked stock >= 1 while it was still 1, then all three waited, then all three subtracted. That’s a race condition: a system “where the system’s substantive behavior is dependent on the sequence or timing of uncontrollable events”, as Wikipedia describes it. The result depends on who gets there first.

The pattern is called check-then-act: you check a condition, and by the time you act on it, it’s no longer true. The sleep makes it happen every time here, but in real code the gap is whatever happens between the check and the act: a network call, a database round trip, or just the scheduler switching threads. Without the sleep, this code would pass every test and fail once a month in production. That’s the heisenbug from part 15.

Locks: one at a time

The fix is to make the check and the act happen as one step that no one else can interrupt. A lock (also called a mutex) lets only one thread into a block of code at a time:

lock = threading.Lock()

def buy(customer):
    global stock
    with lock:                # only one thread at a time in here
        if stock >= 1:
            time.sleep(0.01)
            stock -= 1
            sold.append(customer)
stock: 0 sold to: ['Ana']

One book, one sale. Locks come with their own cost: other threads wait, so keep the locked section small. And with more than one lock, two threads can each hold one and wait forever for the other. That’s a deadlock, “any situation in which no member of some group of entities can proceed”. The usual rule is to always take locks in the same order, or better, to need only one.

Even += 1 isn’t safe

The race doesn’t need a sleep or an if. In Go, a thousand goroutines each add one to a counter:

visits := 0
var wg sync.WaitGroup
for i := 0; i < 1000; i++ {
	wg.Add(1)
	go func() {
		defer wg.Done()
		visits++ // read, add, write: not atomic
	}()
}
wg.Wait()
fmt.Println("visits:", visits)

Three runs:

visits: 938
visits: 999
visits: 994

visits++ is really three steps: read the value, add one, write it back. Two goroutines can read the same value, and one update is lost. And the answer is different every run, which is exactly what makes these bugs so hard to catch.

Go ships a tool for this. Its documentation: “Data races are among the most common and hardest to debug types of bugs in concurrent systems. A data race occurs when two goroutines access the same variable concurrently and at least one of the accesses is a write.” Run with -race:

==================
WARNING: DATA RACE
Read at 0x00c000112078 by goroutine 8:
  main.main.func1()
      main.go:15 +0x84

Previous write at 0x00c000112078 by goroutine 13:
  main.main.func1()
      main.go:15 +0x96

It points at line 15, the visits++. With a sync.Mutex around the increment, the race detector is quiet and the answer is visits: 1000 every time. Go also offers sync/atomic for simple counters, and channels for passing data between goroutines instead of sharing it.

The same bug in your database

PHP code usually doesn’t share variables between requests: each request gets its own process or worker. So you might think races don’t apply. They do, one level down: the shared state is the database. Two requests buying the last book, simulated with two connections:

// Read-then-write: both requests read before either one writes.
$qtyA = $a->query("SELECT qty FROM stock WHERE product = 'book'")->fetchColumn();
$qtyB = $b->query("SELECT qty FROM stock WHERE product = 'book'")->fetchColumn();
if ($qtyA >= 1) { /* UPDATE stock SET qty = $qtyA - 1 */ }
if ($qtyB >= 1) { /* UPDATE stock SET qty = $qtyB - 1 */ }
A: sold
B: sold
stock now: 0

Two sales of one book, and this time the stock even looks fine: both wrote 0. A lost update with no error and no trace. The fix is to let the database do the check and the change in one atomic statement:

$sell = 'UPDATE stock SET qty = qty - 1 WHERE product = :p AND qty >= 1';
$stmt = $db->prepare($sell);
$stmt->execute(['p' => 'book']);
echo $stmt->rowCount() === 1 ? 'sold' : 'sold out';
A: sold
B: sold out
stock now: 0

The WHERE qty >= 1 is the check, inside the same statement as the change. If no row was updated, the book was already gone. Other tools for the same job: transactions with SELECT ... FOR UPDATE in MySQL and PostgreSQL to lock the row, unique constraints so the database rejects a duplicate, and the idempotency keys from part 20 for repeated requests.

Habits that keep concurrency safe

  • Prefer not sharing. Pass data in, return results out. Pure functions (part 7) have no races.
  • When you must share, protect it in one place. One lock, one owner, or one atomic database statement.
  • Watch for check-then-act. “If it’s free, take it”, “if it doesn’t exist, create it”, “if there’s stock, sell it”. Make the check and the act one operation.
  • Use the tools. Go’s -race, thread sanitizers in other languages, and load tests that send many requests at once.
  • Use concurrency for waiting first. Running independent API calls together is the easy, high-value win. Parallel CPU work is a bigger step; measure before taking it (part 10).

Why this matters day to day

  • Every web app is concurrent. Two users can always click at the same moment; double-submits and overselling are race conditions.
  • Speed for free. Independent API or database calls run together often cut response time in half or more.
  • Bugs that hide. Races pass tests and appear under load. Knowing the pattern is how you spot them in review.
  • AI-generated code frequently uses check-then-act (“find, then create”) and shared mutable state. Ask what happens if two requests run it at the same time.

Try it yourself

  1. Run the stock example without the lock several times, then with the lock. Try removing the sleep: how often does the bug still show?
  2. Run the Go counter with and without -race, then fix it with sync.Mutex and again with sync/atomic.
  3. Find a “check, then insert” in your code (for example, “if no user with this email, create one”). What stops two requests from both inserting? Would a unique constraint help?
  4. Take a page that makes several independent API or database calls and run them concurrently. Measure the difference.

Summary

  • Concurrency is dealing with many things at once; parallelism is doing them at the same moment.
  • Most everyday concurrency is about not sitting idle while waiting: asyncio.gather, Promise.all.
  • A race condition happens when the result depends on timing; check-then-act is the classic shape.
  • Locks make a block run one at a time; keep them small and avoid deadlocks.
  • Even x++ isn’t atomic; Go’s race detector finds data races.
  • In web apps, the shared state is the database: use atomic conditional updates, row locks, and constraints.
  • Prefer not sharing; when you must, protect shared state in one place.

References