Creation Reuse, ownership, and cleanup

Object pool

Borrow it. Use it. Return it ready.

Your image service has eight thumbnails to prepare. Each job uses a processing session with its own working state. Creating a fresh session for every image is easy to understand. When setup becomes costly, or the service needs a firm resource limit, you start looking for something reusable.

Keep three sessions. Lend each to one thumbnail at a time. The interesting part comes afterward: how do you know a session is ready for the next thumbnail?

TypeScriptGoPython One borrowing contract · across the comparison

01 / Notice the repeated setup

The next thumbnail could use the same session.

Creating, using, and closing a resource per operation is a sensible first design. Its lifetime follows the work, and each thumbnail starts fresh. The pressure appears when repeated setup matters or too many simultaneous resources compete for limited capacity.

An object pool keeps reusable objects and lends an available one to a caller, which returns it when its work is finished. This lesson uses a bounded pool with exclusive leases: at most three thumbnails can hold our three sessions at once.

A fourth thumbnail gets no lease. That is an expected outcome, not permission to silently create a fourth session. Its caller must decide whether to wait, retry later, or refuse the request.

We model one retained setting: whether to flip the image horizontally. The programs return that setting with each thumbnail result instead of writing image files, and the small arrow picture makes the flag visible.

02 / Give borrowing a boundary

The session survives. This lease does not.

The pool owns the sessions. A successful checkout creates a lease: one caller’s temporary right to use one session. Session 1 can serve A now and B later, but B receives a new lease. A’s old handle must stop working.

1 / Acquire → borrower

Reserve an idle session.

The pool records an owner before returning the lease. Other checkouts skip that session.

2 / Borrower → thumbnail

Use it exclusively.

The thumbnail can change the session’s setting. Another thumbnail cannot borrow it during this lease.

3 / Release → pool

Reset, then make available.

The lease ends. Successful cleanup clears the flip setting before the session can be borrowed again.

Two separate mistakes can break this lifecycle. A thumbnail can finish and forget to return its lease, leaving a perfectly usable session unavailable. Or it can return the session without restoring its baseline, making the previous thumbnail’s setting someone else’s problem.

Our clean return does both jobs. If cleanup reports failure, the pool retires that slot instead of offering it again. The configured pool still has three slots, but fewer usable sessions until an owner provides a replacement policy.

03 / See the shape

Ask for a lease. End it in the same scope.

The basic form constructs the sessions once and finds the first idle, usable slot. The useful version adds the lease: rendering, checking that this is still the current owner, and returning the session after cleanup.

The produce helper shows the central calling rule. Acquire a lease, handle exhaustion, and arrange its return before work can fail. The full dispatcher admits thumbnails in batches of up to three, then finishes each thumbnail. Batch admission is visible; these source programs perform their model renders synchronously.

Read in

Compare with

Create a fixed set of sessions and lend an idle one. Checkout returns no lease immediately when all usable sessions are busy. The lease’s behavior appears in the next view; supporting types are in the complete file.

TypeScriptReading

sessions.ts

export class SessionPool {
	#slots: Slot[];
	#reset: Reset;
	constructor(capacity: number, reset: Reset = (session) => session.reset()) {
		if (!Number.isInteger(capacity) || capacity < 0 || capacity > 8) {
			throw new RangeError('Capacity must be an integer from 0 through 8');
		}
		this.#slots = Array.from({ length: capacity }, (_, i) => ({
			session: new Session(i + 1),
			owner: null,
			retired: false
		}));
		this.#reset = reset;
	}
	tryAcquire(): Lease | null {
		const slot = this.#slots.find((slot) => slot.owner === null && !slot.retired);
		if (!slot) return null; // The caller decides whether to wait, retry, or refuse work.
		const token = Symbol();
		slot.owner = token;
		return new Lease(slot, token, this.#reset);
	}
	snapshot(): Snapshot[] {
		return this.#slots.map((slot) => ({
			id: slot.session.id,
			busy: slot.owner !== null,
			flipX: slot.session.flipX,
			retired: slot.retired
		}));
	}
}

GoAlongside

sessions.go

type SessionPool struct {
	mu    sync.Mutex
	slots []slot
	reset Reset
}

func NewPool(capacity int, reset Reset) (*SessionPool, error) {
	if capacity < 0 || capacity > 8 {
		return nil, errCapacity
	}
	if reset == nil {
		reset = func(s *Session) bool { return s.Reset() }
	}
	p := &SessionPool{slots: make([]slot, capacity), reset: reset}
	for i := range p.slots {
		p.slots[i].session.id = i + 1
	}
	return p, nil
}
func (p *SessionPool) TryAcquire() *Lease {
	p.mu.Lock()
	defer p.mu.Unlock()
	for i := range p.slots {
		if p.slots[i].owner == nil && !p.slots[i].retired {
			lease := &Lease{pool: p, index: i}
			p.slots[i].owner = lease
			return lease
		}
	}
	return nil // Waiting or refusing belongs to the caller.
}
func (p *SessionPool) Snapshot() []Snapshot {
	p.mu.Lock()
	defer p.mu.Unlock()
	result := make([]Snapshot, len(p.slots))
	for i, s := range p.slots {
		result[i] = Snapshot{ID: s.session.id, Busy: s.owner != nil, FlipX: s.session.flipX, Retired: s.retired}
	}
	return result
}

Read complete examples without JavaScript

sessions.ts

export type Thumbnail = Readonly<{ name: string; flipX?: boolean; fail?: boolean }>;
export type Rendered = Readonly<{ name: string; sessionId: number; flipX: boolean }>;
export type Release = 'released' | 'inactive' | 'discarded';
export type Snapshot = Readonly<{
	id: number;
	busy: boolean;
	flipX: boolean;
	retired: boolean;
}>;

// Models a retained horizontal-flip setting; it does not process image files.
export class Session {
	readonly id: number;
	flipX = false;
	constructor(id: number) {
		this.id = id;
	}
	reset(): boolean {
		this.flipX = false;
		return true;
	}
}
type Reset = (session: Session) => boolean;
type Slot = { session: Session; owner: symbol | null; retired: boolean };

export class SessionPool {
	#slots: Slot[];
	#reset: Reset;
	constructor(capacity: number, reset: Reset = (session) => session.reset()) {
		if (!Number.isInteger(capacity) || capacity < 0 || capacity > 8) {
			throw new RangeError('Capacity must be an integer from 0 through 8');
		}
		this.#slots = Array.from({ length: capacity }, (_, i) => ({
			session: new Session(i + 1),
			owner: null,
			retired: false
		}));
		this.#reset = reset;
	}
	tryAcquire(): Lease | null {
		const slot = this.#slots.find((slot) => slot.owner === null && !slot.retired);
		if (!slot) return null; // The caller decides whether to wait, retry, or refuse work.
		const token = Symbol();
		slot.owner = token;
		return new Lease(slot, token, this.#reset);
	}
	snapshot(): Snapshot[] {
		return this.#slots.map((slot) => ({
			id: slot.session.id,
			busy: slot.owner !== null,
			flipX: slot.session.flipX,
			retired: slot.retired
		}));
	}
}

export class Lease {
	#slot: Slot;
	#token: symbol;
	#reset: Reset;
	constructor(slot: Slot, token: symbol, reset: Reset) {
		this.#slot = slot;
		this.#token = token;
		this.#reset = reset;
	}
	get sessionId(): number {
		return this.#slot.session.id;
	}
	render(thumbnail: Thumbnail): Rendered {
		if (this.#slot.owner !== this.#token) throw new Error('lease inactive');
		const session = this.#slot.session;
		if (thumbnail.flipX !== undefined) session.flipX = thumbnail.flipX;
		if (thumbnail.fail) throw new Error('render failed'); // Settings may already have changed.
		return { name: thumbnail.name, sessionId: session.id, flipX: session.flipX };
	}
	release(): Release {
		if (this.#slot.owner !== this.#token) return 'inactive';
		const clean = this.#reset(this.#slot.session); // Still unavailable during cleanup.
		this.#slot.retired = !clean;
		this.#slot.owner = null;
		return clean ? 'released' : 'discarded';
	}
}

export function produce(pool: SessionPool, thumbnail: Thumbnail): Rendered | null {
	const lease = pool.tryAcquire();
	if (!lease) return null;
	try {
		return lease.render(thumbnail);
	} finally {
		lease.release();
	} // Runs on a return or a thrown render failure.
}

export const thumbnails: readonly Thumbnail[] = [
	{ name: 'A', flipX: true },
	{ name: 'B' },
	{ name: 'C', flipX: false },
	{ name: 'D', flipX: true },
	{ name: 'E' },
	{ name: 'F', flipX: true, fail: true },
	{ name: 'G' },
	{ name: 'H' }
];
export function runExample(): void {
	const pool = new SessionPool(3);
	// Acquire a batch before using it. A real dispatcher owns its own waiting policy.
	for (let offset = 0; offset < thumbnails.length; offset += 3) {
		const batch = thumbnails
			.slice(offset, offset + 3)
			.map((thumbnail) => ({ thumbnail, lease: pool.tryAcquire() }));
		for (const { thumbnail, lease } of batch) {
			if (!lease) {
				console.log(`${thumbnail.name}: pool exhausted`);
				continue;
			}
			try {
				const result = lease.render(thumbnail);
				console.log(
					`${result.name}: session ${result.sessionId}, ${result.flipX ? 'mirrored' : 'original'}`
				);
			} catch (error) {
				console.log(
					`${thumbnail.name}: ${error instanceof Error ? error.message : 'unknown error'}`
				);
			} finally {
				lease.release();
			}
		}
	}
	console.log(
		`available: ${pool.snapshot().filter((slot) => !slot.busy && !slot.retired).length}/3`
	);
}

runExample();

sessions.go

package main

import (
	"errors"
	"fmt"
	"sync"
)

type Thumbnail struct {
	Name  string
	FlipX *bool
	Fail  bool
}
type Rendered struct {
	Name      string
	SessionID int
	FlipX     bool
}
type Release string

const (
	Released  Release = "released"
	Inactive  Release = "inactive"
	Discarded Release = "discarded"
)

type Snapshot struct {
	ID                   int
	Busy, FlipX, Retired bool
}

// Session models a horizontal-flip setting; it does not process image files.
type Session struct {
	id    int
	flipX bool
}

func (s *Session) Reset() bool { s.flipX = false; return true }

type Reset func(*Session) bool

var (
	errCapacity      = errors.New("capacity must be from 0 through 8")
	errLeaseInactive = errors.New("lease inactive")
	errRenderFailed  = errors.New("render failed")
)

type slot struct {
	session Session
	owner   *Lease
	retired bool
}

type SessionPool struct {
	mu    sync.Mutex
	slots []slot
	reset Reset
}

func NewPool(capacity int, reset Reset) (*SessionPool, error) {
	if capacity < 0 || capacity > 8 {
		return nil, errCapacity
	}
	if reset == nil {
		reset = func(s *Session) bool { return s.Reset() }
	}
	p := &SessionPool{slots: make([]slot, capacity), reset: reset}
	for i := range p.slots {
		p.slots[i].session.id = i + 1
	}
	return p, nil
}
func (p *SessionPool) TryAcquire() *Lease {
	p.mu.Lock()
	defer p.mu.Unlock()
	for i := range p.slots {
		if p.slots[i].owner == nil && !p.slots[i].retired {
			lease := &Lease{pool: p, index: i}
			p.slots[i].owner = lease
			return lease
		}
	}
	return nil // Waiting or refusing belongs to the caller.
}
func (p *SessionPool) Snapshot() []Snapshot {
	p.mu.Lock()
	defer p.mu.Unlock()
	result := make([]Snapshot, len(p.slots))
	for i, s := range p.slots {
		result[i] = Snapshot{ID: s.session.id, Busy: s.owner != nil, FlipX: s.session.flipX, Retired: s.retired}
	}
	return result
}


type Lease struct {
	pool  *SessionPool
	index int
}

func (l *Lease) SessionID() int { return l.index + 1 }
func (l *Lease) Render(thumbnail Thumbnail) (Rendered, error) {
	p := l.pool
	p.mu.Lock()
	defer p.mu.Unlock()
	s := &p.slots[l.index]
	if s.owner != l {
		return Rendered{}, errLeaseInactive
	}
	if thumbnail.FlipX != nil {
		s.session.flipX = *thumbnail.FlipX
	}
	if thumbnail.Fail {
		return Rendered{}, errRenderFailed
	}
	return Rendered{Name: thumbnail.Name, SessionID: s.session.id, FlipX: s.session.flipX}, nil
}
func (l *Lease) Release() Release {
	p := l.pool
	p.mu.Lock()
	defer p.mu.Unlock()
	s := &p.slots[l.index]
	if s.owner != l {
		return Inactive
	}
	clean := p.reset(&s.session) // Keep the slot unavailable until synchronous cleanup returns.
	s.retired = !clean
	s.owner = nil
	if clean {
		return Released
	}
	return Discarded
}
func Produce(pool *SessionPool, thumbnail Thumbnail) (*Rendered, error) {
	lease := pool.TryAcquire()
	if lease == nil {
		return nil, nil
	}
	defer lease.Release()
	result, err := lease.Render(thumbnail)
	if err != nil {
		return nil, err
	}
	return &result, nil
}


func flag(value bool) *bool { return &value }
func finishThumbnail(lease *Lease, thumbnail Thumbnail) {
	defer lease.Release() // This helper's return ends one lease, including failure.
	result, err := lease.Render(thumbnail)
	if err != nil {
		fmt.Printf("%s: %s\n", thumbnail.Name, err)
		return
	}
	flip := "original"
	if result.FlipX {
		flip = "mirrored"
	}
	fmt.Printf("%s: session %d, %s\n", result.Name, result.SessionID, flip)
}
func main() {
	pool, err := NewPool(3, nil)
	if err != nil {
		panic(err)
	}
	thumbnails := []Thumbnail{
		{Name: "A", FlipX: flag(true)},
		{Name: "B"},
		{Name: "C", FlipX: flag(false)},
		{Name: "D", FlipX: flag(true)},
		{Name: "E"},
		{Name: "F", FlipX: flag(true), Fail: true},
		{Name: "G"},
		{Name: "H"},
	}
	for offset := 0; offset < len(thumbnails); offset += 3 {
		end := min(offset+3, len(thumbnails))
		leases := make([]*Lease, end-offset)
		for i := range leases {
			leases[i] = pool.TryAcquire()
		}
		for i, lease := range leases {
			thumbnail := thumbnails[offset+i]
			if lease == nil {
				fmt.Printf("%s: pool exhausted\n", thumbnail.Name)
			} else {
				finishThumbnail(lease, thumbnail)
			}
		}
	}
	available := 0
	for _, s := range pool.Snapshot() {
		if !s.Busy && !s.Retired {
			available++
		}
	}
	fmt.Printf("available: %d/3\n", available)
}

sessions.py

"""Borrow reusable thumbnail sessions through exclusive leases."""

from __future__ import annotations

from dataclasses import dataclass
from threading import Lock
from typing import Callable


@dataclass(frozen=True)
class Thumbnail:
    name: str
    flip_x: bool | None = None
    fail: bool = False


@dataclass(frozen=True)
class Rendered:
    name: str
    session_id: int
    flip_x: bool


Release = str


@dataclass(frozen=True)
class Snapshot:
    id: int
    busy: bool
    flip_x: bool
    retired: bool


class Session:
    """Models a retained horizontal-flip setting; it does not process image files."""

    def __init__(self, session_id: int) -> None:
        self._id = session_id
        self._flip_x = False

    @property
    def id(self) -> int:
        return self._id

    @property
    def flip_x(self) -> bool:
        return self._flip_x

    def reset(self) -> bool:
        self._flip_x = False
        return True


@dataclass
class _Slot:
    session: Session
    owner: object | None = None
    retired: bool = False


class SessionPool:
    def __init__(
        self, capacity: object, reset: Callable[[Session], bool] | None = None
    ) -> None:
        if isinstance(capacity, bool) or not isinstance(capacity, int) or not 0 <= capacity <= 8:
            raise ValueError("Capacity must be an integer from 0 through 8")
        self._slots = [_Slot(Session(index + 1)) for index in range(capacity)]
        self._reset = reset if reset is not None else lambda session: session.reset()
        self._lock = Lock()

    def try_acquire(self) -> Lease | None:
        with self._lock:
            for index, slot in enumerate(self._slots):
                if slot.owner is None and not slot.retired:
                    token = object()
                    slot.owner = token
                    return Lease(self, index, token)
        return None  # Waiting or refusing belongs to the caller.

    def snapshot(self) -> list[Snapshot]:
        with self._lock:
            return [
                Snapshot(
                    id=slot.session.id,
                    busy=slot.owner is not None,
                    flip_x=slot.session.flip_x,
                    retired=slot.retired,
                )
                for slot in self._slots
            ]




class Lease:
    def __init__(self, pool: SessionPool, index: int, token: object) -> None:
        self._pool = pool
        self._index = index
        self._token = token

    @property
    def session_id(self) -> int:
        return self._index + 1

    def render(self, thumbnail: Thumbnail) -> Rendered:
        with self._pool._lock:
            slot = self._pool._slots[self._index]
            if slot.owner is not self._token:
                raise RuntimeError("lease inactive")
            if thumbnail.flip_x is not None:
                slot.session._flip_x = thumbnail.flip_x
            if thumbnail.fail:
                raise RuntimeError("render failed")
            return Rendered(thumbnail.name, slot.session.id, slot.session.flip_x)

    def release(self) -> Release:
        with self._pool._lock:
            slot = self._pool._slots[self._index]
            if slot.owner is not self._token:
                return "inactive"
            clean = self._pool._reset(slot.session)
            slot.retired = not clean
            slot.owner = None
            return "released" if clean else "discarded"


def produce(pool: SessionPool, thumbnail: Thumbnail) -> Rendered | None:
    lease = pool.try_acquire()
    if lease is None:
        return None
    try:
        return lease.render(thumbnail)
    finally:
        lease.release()




thumbnails: tuple[Thumbnail, ...] = (
    Thumbnail("A", True),
    Thumbnail("B"),
    Thumbnail("C", False),
    Thumbnail("D", True),
    Thumbnail("E"),
    Thumbnail("F", True, True),
    Thumbnail("G"),
    Thumbnail("H"),
)


def run_example() -> None:
    pool = SessionPool(3)
    # Acquire a batch before using it. A real dispatcher owns its waiting policy.
    for offset in range(0, len(thumbnails), 3):
        batch = [
            (thumbnail, pool.try_acquire())
            for thumbnail in thumbnails[offset : offset + 3]
        ]
        for thumbnail, lease in batch:
            if lease is None:
                print(f"{thumbnail.name}: pool exhausted")
                continue
            try:
                result = lease.render(thumbnail)
                mode = "mirrored" if result.flip_x else "original"
                print(f"{result.name}: session {result.session_id}, {mode}")
            except RuntimeError as error:
                print(f"{thumbnail.name}: {error}")
            finally:
                lease.release()
    available = sum(not slot.busy and not slot.retired for slot in pool.snapshot())
    print(f"available: {available}/3")




if __name__ == "__main__":
    run_example()

Sessions.java

import java.util.ArrayList;
import java.util.List;

record Thumbnail(String name, Boolean flipX, boolean fail) {}
record Rendered(String name, int sessionId, boolean flipX) {}
enum Release { RELEASED, INACTIVE, DISCARDED }
record Snapshot(int id, boolean busy, boolean flipX, boolean retired) {}

// Models a retained horizontal-flip setting; it does not process image files.
final class Session {
    private final int id;
    private boolean flipX;

    Session(int id) { this.id = id; }
    int id() { return id; }
    boolean flipX() { return flipX; }
    void setFlipX(boolean value) { flipX = value; }
    boolean reset() { flipX = false; return true; }
}

interface Reset { boolean apply(Session session); }

final class Slot {
    final Session session;
    Lease owner;
    boolean retired;

    Slot(Session session) { this.session = session; }
}

final class SessionPool {
    private final Object lock = new Object();
    final List<Slot> slots;
    final Reset reset;

    SessionPool(int capacity, Reset reset) {
        if (capacity < 0 || capacity > 8) {
            throw new IllegalArgumentException("Capacity must be an integer from 0 through 8");
        }
        this.slots = new ArrayList<>();
        for (int index = 0; index < capacity; index++) slots.add(new Slot(new Session(index + 1)));
        this.reset = reset == null ? Session::reset : reset;
    }

    Object lock() { return lock; }

    Lease tryAcquire() {
        synchronized (lock) {
            for (int index = 0; index < slots.size(); index++) {
                Slot slot = slots.get(index);
                if (slot.owner == null && !slot.retired) {
                    Lease lease = new Lease(this, index);
                    slot.owner = lease;
                    return lease;
                }
            }
        }
        return null; // Waiting or refusing belongs to the caller.
    }

    List<Snapshot> snapshot() {
        synchronized (lock) {
            List<Snapshot> result = new ArrayList<>();
            for (Slot slot : slots) {
                result.add(new Snapshot(slot.session.id(), slot.owner != null, slot.session.flipX(), slot.retired));
            }
            return result;
        }
    }
}

final class Lease {
    private final SessionPool pool;
    private final int index;

    Lease(SessionPool pool, int index) {
        this.pool = pool;
        this.index = index;
    }

    int sessionId() { return index + 1; }

    Rendered render(Thumbnail thumbnail) {
        synchronized (pool.lock()) {
            Slot slot = pool.slots.get(index);
            if (slot.owner != this) throw new IllegalStateException("lease inactive");
            if (thumbnail.flipX() != null) slot.session.setFlipX(thumbnail.flipX());
            if (thumbnail.fail()) throw new IllegalStateException("render failed");
            return new Rendered(thumbnail.name(), slot.session.id(), slot.session.flipX());
        }
    }

    Release release() {
        synchronized (pool.lock()) {
            Slot slot = pool.slots.get(index);
            if (slot.owner != this) return Release.INACTIVE;
            boolean clean = pool.reset.apply(slot.session); // Still unavailable during cleanup.
            slot.retired = !clean;
            slot.owner = null;
            return clean ? Release.RELEASED : Release.DISCARDED;
        }
    }
}

final class SessionWork {
    private SessionWork() {}

    static Rendered produce(SessionPool pool, Thumbnail thumbnail) {
        Lease lease = pool.tryAcquire();
        if (lease == null) return null;
        try {
            return lease.render(thumbnail);
        } finally {
            lease.release();
        }
    }
}


public final class Sessions {
    static final List<Thumbnail> THUMBNAILS = List.of(
        new Thumbnail("A", true, false),
        new Thumbnail("B", null, false),
        new Thumbnail("C", false, false),
        new Thumbnail("D", true, false),
        new Thumbnail("E", null, false),
        new Thumbnail("F", true, true),
        new Thumbnail("G", null, false),
        new Thumbnail("H", null, false)
    );

    static List<String> runExample() {
        SessionPool pool = new SessionPool(3, null);
        List<String> lines = new ArrayList<>();
        for (int offset = 0; offset < THUMBNAILS.size(); offset += 3) {
            int end = Math.min(offset + 3, THUMBNAILS.size());
            List<Lease> leases = new ArrayList<>();
            for (int index = offset; index < end; index++) leases.add(pool.tryAcquire());
            for (int index = 0; index < leases.size(); index++) {
                Thumbnail thumbnail = THUMBNAILS.get(offset + index);
                Lease lease = leases.get(index);
                if (lease == null) {
                    lines.add(thumbnail.name() + ": pool exhausted");
                    continue;
                }
                try {
                    Rendered result = lease.render(thumbnail);
                    lines.add(result.name() + ": session " + result.sessionId() + ", "
                        + (result.flipX() ? "mirrored" : "original"));
                } catch (IllegalStateException error) {
                    lines.add(thumbnail.name() + ": " + error.getMessage());
                } finally {
                    lease.release();
                }
            }
        }
        long available = pool.snapshot().stream().filter(slot -> !slot.busy() && !slot.retired()).count();
        lines.add("available: " + available + "/3");
        return lines;
    }

    public static void main(String[] args) {
        for (String line : runExample()) System.out.println(line);
    }
}

sessions.rs

use std::cell::RefCell;
use std::rc::Rc;

pub struct Thumbnail<'a> {
    pub name: &'a str,
    pub flip_x: Option<bool>,
    pub fail: bool,
}
#[derive(Debug, PartialEq, Eq)]
pub struct Rendered {
    pub name: String,
    pub session_id: usize,
    pub flip_x: bool,
}
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Release {
    Released,
    Inactive,
    Discarded,
}
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Snapshot {
    pub id: usize,
    pub busy: bool,
    pub flip_x: bool,
    pub retired: bool,
}
// One retained horizontal-flip setting; no image files are processed.
pub struct Session {
    id: usize,
    flip_x: bool,
}
impl Session {
    pub fn reset(&mut self) -> bool {
        self.flip_x = false;
        true
    }
}
type Reset = fn(&mut Session) -> bool;
struct Slot {
    session: Session,
    owner: Option<Rc<()>>,
    retired: bool,
}
struct PoolState {
    slots: Vec<Slot>,
    reset: Reset,
}

pub struct SessionPool {
    state: Rc<RefCell<PoolState>>,
}
impl SessionPool {
    pub fn new(capacity: i64, reset: Reset) -> Result<Self, &'static str> {
        if !(0..=8).contains(&capacity) {
            return Err("capacity must be from 0 through 8");
        }
        let slots = (0..capacity as usize)
            .map(|i| Slot {
                session: Session {
                    id: i + 1,
                    flip_x: false,
                },
                owner: None,
                retired: false,
            })
            .collect();
        Ok(Self {
            state: Rc::new(RefCell::new(PoolState { slots, reset })),
        })
    }
    pub fn try_acquire(&self) -> Option<Lease> {
        let mut state = self.state.borrow_mut();
        let index = state
            .slots
            .iter()
            .position(|s| s.owner.is_none() && !s.retired)?;
        let token = Rc::new(());
        state.slots[index].owner = Some(Rc::clone(&token));
        Some(Lease {
            pool: Rc::clone(&self.state),
            index,
            token,
        })
    }
    pub fn snapshot(&self) -> Vec<Snapshot> {
        self.state
            .borrow()
            .slots
            .iter()
            .map(|s| Snapshot {
                id: s.session.id,
                busy: s.owner.is_some(),
                flip_x: s.session.flip_x,
                retired: s.retired,
            })
            .collect()
    }
}

pub struct Lease {
    pool: Rc<RefCell<PoolState>>,
    index: usize,
    token: Rc<()>,
}
impl Lease {
    pub fn session_id(&self) -> usize {
        self.index + 1
    }
    fn active(&self, slot: &Slot) -> bool {
        slot.owner
            .as_ref()
            .is_some_and(|token| Rc::ptr_eq(token, &self.token))
    }
    pub fn render(&self, thumbnail: &Thumbnail<'_>) -> Result<Rendered, &'static str> {
        let mut state = self.pool.borrow_mut();
        let slot = &mut state.slots[self.index];
        if !self.active(slot) {
            return Err("lease inactive");
        }
        if let Some(value) = thumbnail.flip_x {
            slot.session.flip_x = value;
        }
        if thumbnail.fail {
            return Err("render failed");
        }
        Ok(Rendered {
            name: thumbnail.name.to_owned(),
            session_id: slot.session.id,
            flip_x: slot.session.flip_x,
        })
    }
    pub fn release(&self) -> Release {
        let mut state = self.pool.borrow_mut();
        let reset = state.reset;
        let slot = &mut state.slots[self.index];
        if !self.active(slot) {
            return Release::Inactive;
        }
        let clean = reset(&mut slot.session);
        slot.retired = !clean;
        slot.owner = None;
        if clean {
            Release::Released
        } else {
            Release::Discarded
        }
    }
}
impl Drop for Lease {
    fn drop(&mut self) {
        self.release();
    }
}
pub fn produce(pool: &SessionPool, thumbnail: &Thumbnail<'_>) -> Result<Option<Rendered>, &'static str> {
    let Some(lease) = pool.try_acquire() else {
        return Ok(None);
    };
    Ok(Some(lease.render(thumbnail)?)) // Ordinary scope exit drops the guard, also on Err.
}

fn main() {
    let pool = SessionPool::new(3, Session::reset).unwrap();
    let thumbnails = [
        Thumbnail {
            name: "A",
            flip_x: Some(true),
            fail: false,
        },
        Thumbnail {
            name: "B",
            flip_x: None,
            fail: false,
        },
        Thumbnail {
            name: "C",
            flip_x: Some(false),
            fail: false,
        },
        Thumbnail {
            name: "D",
            flip_x: Some(true),
            fail: false,
        },
        Thumbnail {
            name: "E",
            flip_x: None,
            fail: false,
        },
        Thumbnail {
            name: "F",
            flip_x: Some(true),
            fail: true,
        },
        Thumbnail {
            name: "G",
            flip_x: None,
            fail: false,
        },
        Thumbnail {
            name: "H",
            flip_x: None,
            fail: false,
        },
    ];
    for batch in thumbnails.chunks(3) {
        let leases: Vec<_> = batch.iter().map(|_| pool.try_acquire()).collect();
        for (thumbnail, lease) in batch.iter().zip(leases) {
            let Some(lease) = lease else {
                println!("{}: pool exhausted", thumbnail.name);
                continue;
            };
            match lease.render(thumbnail) {
                Ok(result) => println!(
                    "{}: session {}, {}",
                    result.name,
                    result.session_id,
                    if result.flip_x {
                        "mirrored"
                    } else {
                        "original"
                    }
                ),
                Err(error) => println!("{}: {}", thumbnail.name, error),
            }
            // The non-Clone lease drops here, returning this session before the next batch.
        }
    }
    println!(
        "available: {}/3",
        pool.snapshot()
            .iter()
            .filter(|s| !s.busy && !s.retired)
            .count()
    );
}

The shared contract accepts a capacity from zero through eight. Zero is an empty pool; checkout returns no lease. Each session begins with flip off. A supplied flip setting replaces the setting, including explicit false; omission keeps the session’s current setting. Thumbnail F deliberately fails after changing it.

A release returns released, discarded after a reported reset failure, or inactive for an old or already-returned lease. Trying to render through an inactive lease fails. A repeated release cannot reset a new borrower’s session.

Reading the TypeScriptIdentity and finally

Each checkout creates a unique Symbol. The slot stores it as its owner; the lease keeps the same token. Comparing tokens distinguishes two successive leases of session 1. A public session number alone would not do that.

finally returns the lease whether rendering returns a result or throws an ordinary error. The flipX !== undefined check preserves an explicit false. Private fields keep the live slot out of the caller’s normal API, and snapshots copy scalar values for inspection.

Reading the GoA lease pointer, a mutex, and defer

The slot’s owner is a pointer to its current Lease. A different checkout gets a different lease. The pool’s mutex protects checkout, rendering, snapshots, and return in this synchronous model.

defer lease.Release() runs when the surrounding function returns. That is why the call site has a per-thumbnail finishThumbnail helper: putting every defer directly in main’s loop would keep those leases until main returned. *bool expresses omitted (nil) separately from explicit false. Read Go’s defer explanation.

Reading the PythonOwner locks, identity tokens, and finally

SessionPool keeps its slots and protects checkout, rendering, snapshots, and release with one lock. Each lease carries a private object token, so a later borrower cannot use or release an earlier lease for the same session.

Python uses None to distinguish an omitted flip setting from explicit False. produce uses try/finally for cleanup, and the concurrency check uses the same lock rather than implying that the pool grows when it is exhausted.

04 / Predict, borrow, inspect

Make the fourth thumbnail wait.

Watch one session pass from A to B, or step through the completed operations. In Try it, keep three sessions and choose a prediction. Fill the available sessions: A, B, and C now have leases. Try starting the next thumbnail. D stays pending because the pool has nothing available. Finish B and start again: D borrows that same session 2.

Now choose “Forget to return the lease,” fill the sessions, and finish all active thumbnails. Inspect the two counts: no jobs running, three sessions leased. Return one held session and D can finally start.

To expose dirty reuse, choose one session and “Return without resetting.” Start and finish A, then start and finish B. A requests horizontal flipping; B omits the setting. Predict B’s output before finishing it. Switching policy or capacity starts a fresh experiment.

Playback controls

Object pool

Return it ready.

1 retained session1 available

Session 1Available

Horizontal flipOFF

Ready for checkout

Thumbnail A

Not rendered

Requests flip on

Thumbnail B

Not rendered

Omits flip setting

01/ 05

Ready to borrow

One session is available.

Session 1 begins with horizontal flip off. Neither thumbnail has run.

Reduced motion: choose a scene to see its completed state.

Read this scene

Session 1 begins with horizontal flip off. Neither thumbnail has run.

Session 1: available; flip off.

Try the example by reading

A borrows session 1 and turns flip on. B cannot borrow it until A releases. Cleanup clears flip, so B reuses session 1 with a new lease and an original image. A’s result stays mirrored.

THUMBNAIL DISPATCHER / YOU CONTROL COMPLETION

Eight thumbnails. A few borrowed sessions.

Start a thumbnail to borrow a session. Finish it to run the source model.

Return policy

Session capacity

After a thumbnail finishes, what happens to its session?

Available3

Leased0

Jobs running0

3 session objects created · 8 thumbnails pending · 0 finished (including failures)

3 retained sessions3 available

Session 1Available

Horizontal flipOFF

Ready for checkout

Session 2Available

Horizontal flipOFF

Ready for checkout

Session 3Available

Horizontal flipOFF

Ready for checkout

Thumbnail A

Not rendered

Requests flip on

Thumbnail B

Not rendered

Omits flip setting

All sessions begin with flip off. Start A, or fill all available sessions to see the capacity limit.

The caller’s thumbnail list

A → H / input order

A
pending Horizontal flip requested
—
B
pending flip setting omitted
—
C
pending original explicitly requested
—
D
pending Horizontal flip requested
—
E
pending flip setting omitted
—
F
pending Horizontal flip requested · render will fail
—
G
pending flip setting omitted
—
H
pending flip setting omitted
—

Follow the acquire → render → return trace

Shows the most recent 24 actions.

Worked trace: one session, A followed by B
Return policy	After A finishes	What happens to B?
Reset, then return	Available; flip cleared.	B reuses session 1 and renders an original image.
Keep the lease	Still leased; no job running.	B stays pending until A’s owner returns it.
Return without reset	Available; flip remains on.	B inherits the flip despite omitting the setting.

The lab runs the displayed TypeScript pool with a small dispatcher around it. Broken modes deliberately retain completed leases or supply a no-op reset hook that falsely reports success.

Continue to F to see the error path. Its render fails after turning flip on. Clean mode still returns a session with flip off. The thumbnail result and the resource’s readiness are separate facts.

05 / Review the return

A completed thumbnail is only half the story.

Before adding capacity, check who still owns each lease and what happens on failure. These three reviews follow the points where ownership can get lost.

06 / Give the pool a real job

The dispatcher owns the waiting. The pool owns availability.

Imagine an image service adding thumbnail jobs to a dispatcher. The dispatcher chooses which pending job to admit. A thumbnail worker borrows a session, performs the work, stores the result or failure, and returns the lease. A service owner creates the pool when its worker service starts and eventually shuts it down.

Our pool knows nothing about thumbnail priority, request deadlines, or retry order. When checkout fails, the lab keeps the thumbnail in its own pending list. A production dispatcher needs a deliberate waiting policy: a bounded queue, cancellation while waiting, or an immediate refusal may each suit a different service.

Suppose failed sessions now need replacement. Put retirement and replacement under the pool owner so callers continue asking for usable leases. Decide what happens if creating the replacement also fails, and how waiting jobs learn that capacity changed. Quietly increasing the limit whenever acquisition fails would defeat the original resource bound.

The session’s identity can survive many thumbnails. Per-thumbnail data should not accidentally survive with it. Our baseline is one boolean. A real session might also retain pixel buffers, dimensions, clipping, or references to input data, and its reset contract must cover whatever the next borrower relies on.

From a synchronous model to real image workCleanup, cancellation, isolation, and shutdown

A real render and reset can be asynchronous. Keep the session unavailable until its current operation has stopped and cleanup has finished. Canceling a request does not by itself prove the worker stopped using its session. Do not return it while an old operation can still mutate it.

The Go sample holds a mutex during its tiny in-memory render and reset. A real implementation should design its lock boundaries around state changes, keeping long image operations outside a global bookkeeping lock while preserving exclusive ownership.

Reset hooks here must be synchronous, non-reentrant, and must not retain the session. They report failure by returning false. Hook exceptions, panics, process termination, and timeouts are outside this model’s contract. The small produce helper does not report a discarded cleanup outcome separately from the thumbnail result; a service needs cleanup observability too.

For shutdown, stop accepting new work, resolve waiting jobs, let active use stop, and dispose of the resources. Retired resources need disposal as well.

Build UIs?Every live feed you keep to one stream per page respects a pool the browser runs, and one day your own workers will need leases.

Where it already is in your components

You may already follow this rule if your app streams live updates: open one EventSource per page and share it between components, or serve the stream over HTTP/2. MDN warns that without HTTP/2 the browser allows only a few of these connections per domain, counted across all tabs. The reason is this lesson’s pool, run by the browser.

For HTTP/1.1, the browser keeps a bounded pool of connections to each host. A request borrows one connection for itself until its response ends, and then the connection goes back for the next request. Chromium allows six per host. A server-sent event stream is a response that does not end, so its lease does not end either. It is section 04’s kept lease, except that nobody forgot anything: the stream is still doing its job.

OrderStatus.svelte

<script lang="ts">
	let { orderId }: { orderId: string } = $props();
	let status = $state('Waiting for updates');

	// Each card opens its own stream. Over HTTP/1.1 that stream keeps one of the
	// browser's connections to this host until the card unmounts.
	$effect(() => {
		const source = new EventSource(`/api/orders/${orderId}/events`);
		source.onmessage = (event) => (status = event.data);
		return () => source.close();
	});
</script>

<article>
	<h3>Order {orderId}</h3>
	<p>{status}</p>
</article>

Render this card for six orders and the pool is empty. In Chromium 153, a Save button’s fetch to the same host then waited inside the browser. The server did not receive it until one card unmounted and closed its stream, and it arrived a few milliseconds later. With three tabs of the same site holding two streams each, a fourth tab did not even load its page until one of them closed. That is the fourth thumbnail with no lease, and the browser’s queue is the waiting policy. DevTools’ timing reference lists “six TCP connections open for this origin” as a reason a request is queued.

So share the lease. Open one stream per page and hand its events to the cards through context or a store. Over HTTP/2 the same page kept ten streams and a fetch moving on a single connection, because each request becomes a stream on it rather than a lease on a whole connection. React once ran a pool you could trip over, too: React 16 reused its event objects and cleared their fields after each handler, which is why older code calls e.persist(). React 17 removed that pooling.

When you have to own it

Now the pool is yours. A code review page shows forty changed files and syntax-highlights each diff in a Web Worker, so scrolling stays smooth. A worker per file would start forty threads, each loading the highlighter. A small pool, sized from navigator.hardwareConcurrency and capped, lends one worker to one file at a time. The review page owns it: create the workers when the page mounts and terminate them when it unmounts, rather than in each file’s component.

Exclusive use is your bookkeeping. A worker handles one message at a time and does not refuse a second: in Chromium, a file posted to a busy worker simply waited until the first file’s work finished. Mark a worker leased when you post to it and available when its reply arrives. Files beyond the pool wait in the page’s own queue, where you choose the order, such as visible files first.

Then reset before reuse. A worker’s module-scope variables survive between messages. If it keeps the current language there and a file with no detected language leaves it out, that file is highlighted as the previous file’s language, the way B inherited A’s flip. Send every setting with each job, or reset in the worker before it replies.

Cancellation is the hard return. Collapse a file mid-highlight and its worker is still busy; marking it available would lend it while the old job runs. Wait for the reply and discard it, or call terminate() and create a replacement. A terminated worker fails quietly: in Chromium, postMessage on it did not throw and no reply ever came. Take it out of the pool the moment you terminate it, as our pool retires a session whose cleanup failed.

07 / Recognize the contract

You may already borrow from a pool.

Look at what an API promises when it says “close,” “release,” or “return.” Ending your use of a handle can leave the underlying resource alive for someone else.

A dedicated database connection has a return point.

Go’s database/sql manages a connection pool. A dedicated DB.Conn gives a caller one connection; Conn.Close returns it to that pool and subsequent operations on the handle fail. That is the lease boundary in a familiar API. Ordinary DB queries usually manage the borrowing for you.

Read the Conn.Close contract ↗

Capacity and waiting are real policy choices.

DB.SetMaxOpenConns limits open connections; operations beyond the available capacity may wait. Go’s guide also discusses idle and lifetime limits. Our example’s immediate “no lease” result leaves that waiting to its caller.

Read Go’s connection-management guide ↗

Go’s sync.Pool has a different promise.

sync.Pool caches temporary objects for reuse, and its entries may disappear without notification. It does not itself provide this lesson’s fixed session limit, explicit lease ownership, or resource-disposal lifecycle. The similar name is a reason to inspect the contract.

Read the sync.Pool contract ↗

08 / Make the call

Reuse is useful when its cleanup contract is believable.

Consider a pool when creating the resource has meaningful cost, its supply needs a bound, and you can define when it is safe to lend again. Browser workers, dedicated connections, and some reusable buffers can have that shape. You still need measurements to establish a performance benefit.

Keep per-operation construction when it is cheap or when a fresh resource is the clearest isolation boundary. A pool retains idle objects, adds ownership rules, and creates exhaustion paths. Reusing tiny ordinary objects can cost more complexity than it saves.

Choose the responsibility you need
Need	Useful starting point
Reuse scarce resources with exclusive borrowers	A bounded object pool with a return contract.
Limit simultaneous work without retaining objects	A semaphore or concurrency limiter.
Decide which pending job runs next	A queue and dispatcher; these can use a pool.
Share stable data among many simultaneous users	Flyweight, with local context kept separate.
Give every operation a fresh baseline	Create, use, and dispose per operation.

Watch for a caller holding a lease while trying to acquire another from an exhausted pool. If everyone waits while keeping what everyone else needs, more elaborate waiting code will not fix the ownership cycle. Keep the borrowing scope as small as the work allows.

09 / Take the idea with you

Explain why “finished” does not mean “available.”

Try explaining the thumbnail desk without saying “object pool”: three sessions stay alive; each has at most one borrower; ending a lease cleans the session before another borrower can use it.

Then transfer the idea. A session fails its reset while five thumbnails are pending. Who retires it? Who creates its replacement? Who decides how long those thumbnails wait? Those answers define the system around the small acquire/use/return mechanism.

Connections to follow nextRelated lessons

Flyweight shares stable data among many live users. Ownership, aliasing, and lifetimes explains who can still use a resource. State machine helps make valid lifecycle transitions explicit. Here, those questions meet at the moment one borrower hands a reusable session to the next.