In this post, we’ll explore both concepts through relatable analogies and practical Go examples. By the end, you’ll have a clear understanding of when to reach for a mutex versus a semaphore.

Mutex: The Library Book

A mutex (short for “mutual exclusion“) is like a popular library book with only one copy. Only one person can check it out at a time, and they must return it before the next person can borrow it. When they’re done reading, they return the book to the library, and the next person in line can check it out.

In Go, a sync.Mutex ensures that only one goroutine can access a critical section of code at a time. It’s binary: locked or unlocked. There’s no middle ground.

package main

import (
    "fmt"
    "sync"
    "time"
)

var (
    counter int
    mutex   sync.Mutex
)

func increment() {
    mutex.Lock()         // Check out the book
    defer mutex.Unlock() // Always return the book, even if panic occurs

    // Critical section: only one goroutine can be here at a time
    temp := counter
    time.Sleep(1 * time.Millisecond) // Simulate reading the book
    counter = temp + 1
}

func main() {
    var wg sync.WaitGroup

    // Launch 10 goroutines trying to increment
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            increment()
        }()
    }

    wg.Wait()
    fmt.Printf("Final counter: %d\n", counter) // Will always prints 10
}

The mutex is the librarian managing the book checkout. It doesn't matter how many people want to read the book, only one person can have it at a time. Simple, predictable, and perfect when you need exclusive access.

Semaphore: The Computer Lab

A semaphore, on the other hand, is like a computer lab with 5 computers available. The lab monitor keeps track of how many computers are free. When a computer becomes available, the next student can use it. If all 5 computers are in use, new students must wait.

In Go, semaphores can be implemented using buffered channels (for educational purposes) or using the official golang.org/x/sync/semaphore package (for production use). They allow a specified number of goroutines to access a resource simultaneously, not just one.

Understanding Semaphores: The Simple Way

Here's a simple semaphore implementation using a buffered channel to illustrate the concept. This example limits concurrent computer usage to manage lab resources:

package main

import (
    "fmt"
    "sync"
    "time"
)

// A semaphore implemented with a buffered channel
type Semaphore struct {
    tokens chan struct{}
}

func NewSemaphore(capacity int) *Semaphore {
    return &Semaphore{
        tokens: make(chan struct{}, capacity),
    }
}

func (s *Semaphore) Acquire() {
    s.tokens <- struct{}{} // Take a token
}

func (s *Semaphore) Release() {
    <-s.tokens // Return the token
}

var sem = NewSemaphore(3) // // Limit to 3 concurrent computer users

// Simulate using a computer in the lab
func useComputer(id int) {
    sem.Acquire()         // Get permission to use a computer
    defer sem.Release()   // Return the computer when done

    fmt.Printf("Student %d: Using computer...\n", id)
    time.Sleep(100 * time.Millisecond) // // Simulate work time
    fmt.Printf("Student %d: Finished using computer\n", id)
}

func main() {
    var wg sync.WaitGroup

    // Tell 10 students to use computers
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            useComputer(id)
        }(i)
    }

    wg.Wait()
    fmt.Println("All students finished using computers")
}

Notice how the semaphore controls the concurrency without needing a mutex? This is because we’re limiting access to an external resource (computers), not protecting shared mutable state. Only 3 students can use computers simultaneously, while the others wait.

Production-Ready: Using the Official Package

For production code, you should use the official golang.org/x/sync/semaphore package, which provides a weighted semaphore with context support and better performance:

package main

import (
    "context"
    "fmt"
    "sync"
    "time"

    "golang.org/x/sync/semaphore"
)

var sem = semaphore.NewWeighted(3) // Limit to 3 concurrent computer users

// Simulate using a computer in the lab
func useComputer(ctx context.Context, id int) error {
    if err := sem.Acquire(ctx, 1); err != nil {
        return err // Context cancelled or timeout
    }
    defer sem.Release(1)

    fmt.Printf("Student %d: Using computer...\n", id)
    time.Sleep(100 * time.Millisecond) // Simulate work time
    fmt.Printf("Student %d: Finished using computer\n", id)
    return nil
}

func main() {
    ctx := context.Background()
    var wg sync.WaitGroup

    // Tell 10 students to use computers
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go func(id int) {
            defer wg.Done()
            if err := useComputer(ctx, id); err != nil {
                fmt.Printf("Student %d: failed: %v\n", id, err)
            }
        }(i)
    }

    wg.Wait()
    fmt.Println("All students finished using computers")
}

The official package offers additional benefits like context cancellation support (so you can timeout or cancel semaphore acquisition) and weighted acquisition (allowing different goroutines to request different amounts of capacity). This is perfect for rate limiting, connection pooling, or controlling access to resource pools.

The Moral of the Story

Both mutexes and semaphores are tools in your concurrency toolkit, each serving different purposes:

• Mutex: “Only one at a time, please.”

• Semaphore: “We have N computers available, but no more.”

Understanding when to use each is key to writing safe, efficient concurrent Go programs. The mutex is your strict bouncer, ensuring exclusive access. The semaphore is your capacity manager, controlling the flow while allowing controlled concurrency.

In the world of Go concurrency, both have their place. Choose wisely, and your programs will thank you with predictable behavior and optimal performance.

Why the heck not?

Enjoy my crap drawing LOL

When you have two frameworks, they both force you to fill in a specific hole. Usually, there is no way to fit one framework inside another. With packages, the situation is different. You are in control, so go crazy!

How do I handle URL parameters and methods?

While Go's net/http package is comprehensive, the one thing it truly sucks at is handling URL parameters and providing an easy way to create handlers for specific methods. But hey, that is not the case anymore!

In Go 1.22, Go team introduced two enhancements to the net/http package: method matching and wildcards. Yay!

Instead of writing this verbose code:

m := http.NewServeMux()
m.HandleFunc("/items/", func(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodGet {
        w.WriteHeader(http.StatusMethodNotAllowed)
        return
    }

    if r.URL.Path == "/items/" {
        w.WriteHeader(http.StatusNotFound)
        return
    }

    w.Write([]byte(strings.TrimPrefix(r.URL.Path, "/items/")))
})

You will get this pretty code instead :)

m := http.NewServeMux()
m.HandleFunc("GET /items/{id}", func(w http.ResponseWriter, r *http.Request) {
    w.Write([]byte(r.PathValue("id")))
})

I heard that X is faster, so why shouldn't I learn it?!

Fiber (based on FastHTTP), and many other alternatives, have numerous tradeoffs that make it hard for people to recommend their usage.

• You are locked into their ecosystem, as there is no standard library compatibility.

• Too much magic involved to gain speed that no one will ever notice.

• To get the full benefits, you will be forced to write in an unidiomatic and advanced style of Go.

Summary (TL;DR)

Go has a comprehensive standard library that takes care of almost everything necessary for the vast majority of web applications. If you have a choice, it is unnecessary to use a framework just to build an API service.