Golang Concurrent Port Scanner Tutorial: Semaphore vs Worker Pool

Photo by Josh Sorenson on Pexels

If you built the sequential and semaphore-based port scanner in the previous article, you have a working concurrent tool. What this tutorial adds is architectural perspective: there are two common ways to implement concurrency for this kind of task in Go, each with different trade-offs around extensibility, performance, and debuggability. Understanding both patterns — and when to reach for each — is more useful than just having a working scanner.

We’re also going to cover two topics that most port scanner tutorials skip: context cancellation (how to stop all goroutines cleanly when a user presses Ctrl+C or a timeout fires) and the Go race detector (a built-in tool that finds data races in concurrent code). These are worth understanding before you start writing larger concurrent programs.

Two Concurrency Architectures

At a high level, both architectures solve the same problem — run many TCP connection attempts concurrently without overwhelming the network stack. The difference is in how they manage which goroutines are running:

• Semaphore pattern: Spawn a goroutine per task. Use a buffered channel as a gate — goroutines must acquire a slot before starting, release it when done. Maximum concurrency = channel capacity.
• Worker pool pattern: Spawn a fixed number of goroutines upfront (the “pool”). Push all tasks into a job channel. Workers pull jobs until the channel is closed and empty, then exit.

Both patterns are idiomatic Go. They appear throughout production code and open source tools. The choice between them is more about what comes next in your codebase than about raw performance — though there are differences there too.

Architecture A: Semaphore Pattern

The semaphore implementation is covered in depth in the prerequisite article, but a quick anatomy before the comparison is useful.

package main

import (
	"fmt"
	"net"
	"sort"
	"sync"
	"time"
)

func scanPort(host string, port int, timeout time.Duration) bool {
	conn, err := net.DialTimeout("tcp", fmt.Sprintf("%s:%d", host, port), timeout)
	if err != nil {
		return false
	}
	conn.Close()
	return true
}

func main() {
	host := "scanme.nmap.org"
	timeout := 3 * time.Second
	concurrency := 100

	var mu sync.Mutex
	var openPorts []int
	sem := make(chan struct{}, concurrency)
	var wg sync.WaitGroup

	for port := 1; port <= 1024; port++ {
		wg.Add(1)
		sem <- struct{}{}
		go func(p int) {
			defer wg.Done()
			defer func() { <-sem }()
			if scanPort(host, p, timeout) {
				mu.Lock()
				openPorts = append(openPorts, p)
				mu.Unlock()
			}
		}(port)
	}

	wg.Wait()
	sort.Ints(openPorts)
	for _, p := range openPorts {
		fmt.Printf("  %d/tcp  OPEN\n", p)
	}
}

Anatomy of the Semaphore Pattern

Main goroutine drives the loop. The main function both dispatches work and waits for completion. It spawns one goroutine per port, but blocks on sem <- struct{}{} when the concurrency limit is reached.

Goroutines manage their own lifecycle. Each goroutine acquires a semaphore slot on entry, releases it on exit. They’re independent — they don’t know about each other.

Shared state via mutex. The openPorts slice is shared across goroutines. The sync.Mutex prevents concurrent writes from causing a data race.

This works correctly and is easy to read. The limitation is extensibility: adding context cancellation, error handling, or more complex coordination requires patching a lot of independent goroutine bodies. The worker pool trades some simplicity for better structure.

Architecture B: Worker Pool Pattern

The worker pool pattern inverts the relationship between goroutines and tasks. Instead of one goroutine per task, you create a fixed pool of goroutines and feed them tasks through a channel.

package main

import (
	"fmt"
	"net"
	"sort"
	"sync"
	"time"
)

type Job struct {
	Host string
	Port int
}

type Result struct {
	Port int
	Open bool
}

// worker processes jobs from the jobs channel until it's closed.
func worker(jobs <-chan Job, results chan<- Result, timeout time.Duration, wg *sync.WaitGroup) {
	defer wg.Done()
	for job := range jobs {
		address := fmt.Sprintf("%s:%d", job.Host, job.Port)
		conn, err := net.DialTimeout("tcp", address, timeout)
		open := err == nil
		if open {
			conn.Close()
		}
		results <- Result{Port: job.Port, Open: open}
	}
}

func main() {
	host := "scanme.nmap.org"
	timeout := 3 * time.Second
	numWorkers := 100
	startPort, endPort := 1, 1024
	total := endPort - startPort + 1

	jobs := make(chan Job, total)
	results := make(chan Result, total)

	// Start the worker pool
	var wg sync.WaitGroup
	for i := 0; i < numWorkers; i++ {
		wg.Add(1)
		go worker(jobs, results, timeout, &wg)
	}

	// Send all jobs, then close to signal no more work
	for port := startPort; port <= endPort; port++ {
		jobs <- Job{Host: host, Port: port}
	}
	close(jobs)

	// Close results after all workers finish
	go func() {
		wg.Wait()
		close(results)
	}()

	// Collect results
	var openPorts []int
	for r := range results {
		if r.Open {
			openPorts = append(openPorts, r.Port)
		}
	}

	sort.Ints(openPorts)
	fmt.Printf("Open ports on %s:\n", host)
	for _, p := range openPorts {
		fmt.Printf("  %d/tcp  OPEN\n", p)
	}
}

How the Worker Pool Works

Typed structs for jobs and results. Job and Result are explicit types. This is more readable than passing loose primitives through a channel, and makes it straightforward to add fields later — a priority, a timeout override, a protocol selection — without changing function signatures throughout the codebase.

for job := range jobs in each worker. This is the key idiom. A range over a channel blocks waiting for the next value, processes it, then blocks again. When the channel is closed and empty, the range loop exits and the worker goroutine returns. Closing jobs is the signal that no more work is coming — it’s a clean, push-based shutdown.

No mutex needed. Results go into a buffered channel, one per port. Channel sends are goroutine-safe — no mutex required. The semaphore version needed a mutex because multiple goroutines were writing to a shared slice. Here, the channel takes that role.

The coordinator goroutine closes results. wg.Wait() ensures all workers have finished (which means all results have been sent), then close(results) signals the consumer that it can stop reading. The consumer’s for r := range results exits when the channel is closed.

Side-by-Side Comparison

Property	Semaphore Pattern	Worker Pool Pattern
Goroutine count	One per task (up to concurrency limit)	Fixed pool size
Goroutine creation overhead	Higher (new goroutine per task)	Lower (goroutines reused)
Code complexity	Lower (fewer moving parts)	Slightly higher (separate types, channel coordination)
Context cancellation	Requires patching each goroutine body	Naturally fits in worker function
Shared state	Mutex required for shared slice	No mutex needed (results via channel)
Extensibility	Harder to add per-task logic (retry, error, priority)	Job struct is easy to extend
Best for	Simple fan-out tasks, quick scripts	Production tools, extensible pipelines

For a port scanner you’re writing once and running locally, the semaphore version is fine. For a scanner that’s part of a larger toolchain, feeds into a logging system, or needs clean interruption support, the worker pool is the better starting point.

Adding Context Cancellation

Context cancellation lets you stop all in-progress scans cleanly — for example, when a user presses Ctrl+C, or when a timeout fires, or when you’ve found enough results. The worker pool pattern integrates naturally with Go’s context package.

The key change is replacing net.DialTimeout with net.Dialer.DialContext, which accepts a context and respects cancellation:

package main

import (
	"context"
	"fmt"
	"net"
	"os"
	"os/signal"
	"sort"
	"sync"
	"syscall"
	"time"
)

type Job struct {
	Host string
	Port int
}

type Result struct {
	Port int
	Open bool
}

func worker(
	ctx context.Context,
	jobs <-chan Job,
	results chan<- Result,
	timeout time.Duration,
	wg *sync.WaitGroup,
) {
	defer wg.Done()
	dialer := &net.Dialer{}

	for job := range jobs {
		// Check for cancellation before each dial
		select {
		case <-ctx.Done():
			return
		default:
		}

		dialCtx, cancel := context.WithTimeout(ctx, timeout)
		conn, err := dialer.DialContext(dialCtx, "tcp", fmt.Sprintf("%s:%d", job.Host, job.Port))
		cancel() // Always release the timeout context

		open := err == nil
		if open {
			conn.Close()
		}
		results <- Result{Port: job.Port, Open: open}
	}
}

func main() {
	host := "scanme.nmap.org"
	timeout := 3 * time.Second
	numWorkers := 100
	startPort, endPort := 1, 1024
	total := endPort - startPort + 1

	// Root context — cancelled on Ctrl+C or SIGTERM
	ctx, cancel := context.WithCancel(context.Background())
	defer cancel()

	// Signal handling: cancel context on interrupt
	sigs := make(chan os.Signal, 1)
	signal.Notify(sigs, syscall.SIGINT, syscall.SIGTERM)
	go func() {
		<-sigs
		fmt.Println("\nInterrupt received — cancelling scan...")
		cancel()
	}()

	jobs := make(chan Job, total)
	results := make(chan Result, total)

	var wg sync.WaitGroup
	for i := 0; i < numWorkers; i++ {
		wg.Add(1)
		go worker(ctx, jobs, results, timeout, &wg)
	}

	for port := startPort; port <= endPort; port++ {
		select {
		case jobs <- Job{Host: host, Port: port}:
		case <-ctx.Done():
			break
		}
	}
	close(jobs)

	go func() {
		wg.Wait()
		close(results)
	}()

	var openPorts []int
	for r := range results {
		if r.Open {
			openPorts = append(openPorts, r.Port)
		}
	}

	sort.Ints(openPorts)
	fmt.Printf("Open ports on %s:\n", host)
	for _, p := range openPorts {
		fmt.Printf("  %d/tcp  OPEN\n", p)
	}
}

What Changed

context.WithCancel at the top. Creates a root context and its cancellation function. Calling cancel() closes the context’s Done() channel, which all downstream code watches.

Signal handling goroutine. signal.Notify routes Ctrl+C (SIGINT) and SIGTERM into a channel. When the signal arrives, the goroutine calls cancel(). Every worker goroutine will exit when it next checks ctx.Done().

select check before each dial. Before starting a new connection, workers check whether the context has been cancelled. If it has, they return immediately rather than starting unnecessary work. This is what “cooperative cancellation” means in Go — code checks for cancellation at natural points rather than being forcibly killed.

context.WithTimeout per-dial. context.WithTimeout(ctx, timeout) creates a child context that is cancelled either when timeout expires or when the parent ctx is cancelled — whichever comes first. The cancel returned by WithTimeout must always be called to release resources, hence the immediate defer cancel() after the dial.

The Race Detector (go run -race)

Go ships with a built-in data race detector. It instruments your binary at build time to track all memory accesses and detect cases where two goroutines access the same memory location concurrently, with at least one writing, without synchronization.

Run the semaphore scanner without the mutex to see a race in action:

// Remove mu.Lock() / mu.Unlock() from the semaphore version
// Then run:
go run -race scanner_semaphore.go

You’ll see output like this:

The race detector tells you exactly which line the race is on, and which goroutines are involved. This is invaluable for debugging concurrent code — especially when races only manifest under specific timing conditions that make them hard to reproduce with testing alone.

Run it on both the correct semaphore version (with the mutex) and the worker pool version to verify no races exist:

go run -race scanner_workerpool.go

No race report means the synchronization is correct. The -race flag is worth running periodically during development — it adds a performance overhead (typical 5–20x slower), so it’s not for production binaries, but it’s worth using during any development phase involving concurrency.

Goroutine Leaks — What They Are and How to Avoid Them

A goroutine leak is a goroutine that’s started but never terminates. In a long-running program, leaking goroutines gradually exhaust memory. In a port scanner, leaks are usually caused by one of two things:

A full results channel. If the results channel is buffered but workers generate more results than the buffer can hold before the consumer starts reading, worker goroutines block on results <-. If the consumer never starts (maybe it’s waiting for all workers to finish in the wrong order), you have a deadlock.

The fix: ensure the results channel is large enough to hold all results without blocking, or start the consumer goroutine before feeding jobs. In the worker pool implementation, the results buffer is sized to total — the maximum number of results possible — which prevents this scenario.

A context that’s never cancelled. If workers check ctx.Done() but the context is never cancelled and no more jobs arrive, workers waiting on range jobs will exit cleanly when the channel is closed. This is fine — but if close(jobs) is never called (maybe because a panic interrupted the job-feeding loop), workers block forever.

The fix: use defer close(jobs) immediately after creating the jobs channel, and ensure the job-feeding loop always terminates. With context cancellation, the job-feeding loop exits via case <-ctx.Done(): break, and then close(jobs) runs.

Frequently Asked Questions

What to Build Next

The concurrent port scanner covers the core patterns. Natural extensions from here:

• CIDR range input: Parse 192.168.1.0/24 as a target, scan all hosts in range — adds a host enumeration layer above the port scanning loop
• Rate limiting: Use time.Tick or golang.org/x/time/rate to cap connections per second, useful for staying below IDS thresholds during authorized tests
• JSON output: Extend the Result struct and use encoding/json to produce structured output for integration with logging or SIEM systems
• UDP scanning: A fundamentally different approach — UDP doesn’t complete handshakes, so absence of a response doesn’t mean the port is closed