Forem: shayan holakouee

Python's AsyncIO Internals, What Actually Happens When You Write await

shayan holakouee — Wed, 29 Apr 2026 03:31:01 +0000

You have written async def and await. You know the surface. At some point something deadlocked, or performed worse than expected, or behaved in a way that did not fit your mental model. This article is about building the mental model that makes those situations predictable rather than surprising.

Coroutines Are Not Threads and Not Callbacks

The two common async models before asyncio were threads and callbacks. Threads give you apparent concurrency with shared state and all the locking that entails. Callbacks give you non-blocking IO with inverted control flow that becomes unreadable at scale.

Coroutines are a third model. A coroutine is a function that can suspend its execution at specific points and resume from exactly that point later. The suspension is cooperative: the coroutine decides when to yield control, not a scheduler. The interpreter does not preempt it.

This is the first thing to internalize. Async Python is not parallel. It is concurrent in the sense that multiple coroutines can be in progress at the same time, but only one runs at any given moment. If a coroutine never yields, nothing else runs.

What async def Actually Produces

An async def function does not execute its body when called. It returns a coroutine object.

async def fetch(url):
    print(f"fetching {url}")
    return "data"

coro = fetch("https://example.com")
print(type(coro))   # <class 'coroutine'>
print(coro)         # <coroutine object fetch at 0x...>
# nothing printed yet, the body has not run

The coroutine object implements the coroutine protocol: it has send(), throw(), and close() methods. The event loop drives it by calling send(None) repeatedly until it raises StopIteration, at which point the return value is carried in the exception's value attribute.

You can drive a simple coroutine manually to see this:

async def simple():
    return 42

coro = simple()
try:
    coro.send(None)
except StopIteration as e:
    print(e.value)  # 42

This is exactly what the event loop does, wrapped in scheduling logic. The await keyword and the event loop are two sides of the same mechanism.

What await Actually Does

await can only appear inside async def. It takes an awaitable object (a coroutine, a Task, a Future, or any object implementing __await__) and suspends the current coroutine until the awaitable completes.

At the bytecode level, await expr compiles to GET_AWAITABLE followed by YIELD_FROM. YIELD_FROM repeatedly sends values into the inner coroutine and yields values out to the outer caller until the inner coroutine raises StopIteration. The value of the StopIteration exception becomes the result of the await expression.

The chain goes all the way down. When you await a coroutine that awaits a Future, the YIELD_FROM instructions chain together. The innermost Future is what actually suspends execution by yielding a non-StopIteration value up through the chain to the event loop. The event loop receives that value (typically the Future itself), registers a callback to resume the coroutine when the Future completes, and moves on to other work.

async def inner():
    await asyncio.sleep(1)  # eventually yields a Future to the event loop
    return "done"

async def outer():
    result = await inner()  # chains the yield through
    print(result)

The event loop never sees inner or outer directly during the sleep. It sees a Future. When the timer fires, it resolves the Future, which triggers the callback that resumes inner, which completes and triggers the callback that resumes outer.

The Event Loop Is a Scheduling Loop

The event loop is simpler than most people expect. At its core it is a loop that does three things: run ready callbacks, poll IO for completeness, and schedule callbacks for completed IO.

A simplified version of CPython's event loop logic looks like this:

while True:
    # Run all callbacks that are ready right now
    while self._ready:
        handle = self._ready.popleft()
        handle._run()

    # Poll IO with a timeout
    # (uses select/epoll/kqueue depending on platform)
    timeout = self._compute_timeout()
    event_list = self._selector.select(timeout)

    # Schedule callbacks for completed IO events
    self._process_events(event_list)

    # Run scheduled callbacks whose time has come
    self._run_once_scheduled()

asyncio.sleep(1) works by creating a Future, scheduling a callback to resolve it after one second via call_later, and returning the Future for the coroutine to await. When the event loop's timer fires, it resolves the Future, which schedules the coroutine's resumption as a ready callback. On the next iteration of the loop, the coroutine resumes.

No thread is involved. The OS timer is polled during selector.select(). The event loop handles the rest.

Tasks vs Futures vs Coroutines

These three are related but distinct and conflating them causes confusion.

A coroutine is a generator-like object produced by an async def call. It does nothing on its own. It must be driven by something calling send() on it.

A Future is a low-level object representing a value that will exist at some point. It has states: pending, cancelled, done. When done, it holds either a result or an exception. You can attach callbacks that fire when it completes. Most application code never creates Future objects directly.

A Task is a subclass of Future that wraps a coroutine and drives it. When you call asyncio.create_task(coro), you get a Task that is immediately scheduled on the event loop. The Task calls coro.send(None) to start the coroutine, catches StopIteration when it completes, and resolves itself with the result.

async def work():
    await asyncio.sleep(0.1)
    return 42

async def main():
    # coroutine: not scheduled yet
    coro = work()

    # Task: immediately scheduled, starts running on the next event loop iteration
    task = asyncio.create_task(work())

    # awaiting the coroutine directly: runs inline, no separate task
    result = await coro

    # awaiting the task: waits for the already-running task
    result = await task

The difference between await coro and await asyncio.create_task(coro) is whether the coroutine runs as a separate scheduled unit or inline in the current coroutine's execution. For concurrency, you need tasks. Two await statements in sequence run sequentially. Two tasks run concurrently.

Blocking the Event Loop Is the Canonical Mistake

Because async Python is single-threaded cooperative concurrency, any code that does not yield blocks everything else. There is no preemption.

import time

async def bad():
    time.sleep(2)  # blocks the OS thread for 2 seconds
    return "done"

async def also_running():
    await asyncio.sleep(0)
    print("I run eventually")

async def main():
    await asyncio.gather(bad(), also_running())
    # also_running does not run until bad() returns
    # because time.sleep never yields to the event loop

time.sleep is a syscall that parks the OS thread. The event loop cannot run while the thread is parked. asyncio.sleep schedules a timer and yields a Future to the event loop, allowing other tasks to run during the wait.

The same problem applies to CPU-heavy code. A tight loop does not yield. A large file read through blocking IO does not yield. Any call to a synchronous library that does IO internally does not yield.

The fix is asyncio.to_thread (Python 3.9+) or loop.run_in_executor, which run blocking code in a thread pool. The coroutine awaits the thread pool result, yielding to the event loop while the thread runs:

async def process_file(path):
    # runs in a thread pool, event loop remains free
    content = await asyncio.to_thread(open(path).read)
    return content

await and Custom Awaitables

Any object can be awaitable by implementing __await__, which must return an iterator. This is the extension point for writing your own low-level async primitives.

class SleepUntilNextSecond:
    def __await__(self):
        loop = asyncio.get_event_loop()
        future = loop.create_future()

        import time
        delay = 1.0 - (time.time() % 1.0)
        loop.call_later(delay, future.set_result, None)

        yield from future.__await__()
        return "woke up"


async def main():
    result = await SleepUntilNextSecond()
    print(result)  # "woke up"

yield from future.__await__() chains into the Future's awaitable protocol, which ultimately yields the Future object up to the event loop. This is the same mechanism asyncio.sleep uses internally. Writing custom awaitables is how libraries like aiohttp and asyncpg integrate with the event loop at a level below async def.

Cancellation Is Cooperative

task.cancel() does not kill a task. It schedules a CancelledError to be thrown into the coroutine at its next await point. The coroutine receives it, and if it does not catch and suppress it, the task is cancelled.

async def careful_work():
    try:
        await asyncio.sleep(10)
    except asyncio.CancelledError:
        # do cleanup here
        raise  # re-raise to actually cancel

async def main():
    task = asyncio.create_task(careful_work())
    await asyncio.sleep(0.1)
    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        print("task was cancelled")

The raise after cleanup is important. A coroutine that catches CancelledError and does not re-raise it has suppressed the cancellation. The task will appear to complete normally rather than being cancelled. This breaks asyncio.wait_for timeouts and structured concurrency patterns that depend on cancellation propagating correctly.

The Mental Model

Async Python is a single-threaded scheduler running coroutines that explicitly yield at await points. The event loop runs callbacks in order. IO completion and timers register callbacks. Coroutines are suspended at await and resumed when their awaited object resolves.

Everything that works correctly in async Python works because coroutines yield frequently. Everything that breaks does so because something held the thread without yielding. The event loop cannot fix that. It can only schedule what yields to it.

Python's Data Model Is an API. Here Is How to Use It Properly

shayan holakouee — Wed, 29 Apr 2026 03:24:13 +0000

Most Python developers know that __len__ makes len() work and __add__ makes + work. That is the surface. The actual story is that Python's data model is a coherent, documented protocol through which user-defined objects can participate in the language itself: not just operators, but truthiness, hashing, iteration, context management, attribute access, memory layout, and more. Using it well means understanding what CPython actually calls, in what order, and why.

The Interpreter Calls These, Not You

The first thing to internalize: dunder methods are called by the interpreter, not by user code. When you write len(obj), Python calls type(obj).__len__(obj). Not obj.__len__(). The lookup goes through the type, not the instance.

This matters for two reasons.

First, defining a dunder on an instance rather than the class does not work:

class MyClass:
    pass

obj = MyClass()
obj.__len__ = lambda: 42

len(obj)  # TypeError: object of type 'MyClass' has no len()

The interpreter checked type(obj).__len__, found nothing, and raised. The instance attribute was ignored entirely.

Second, it means metaclasses can define dunders that apply to the class itself as an object. __len__ on a metaclass makes len(MyClass) work. __iter__ on a metaclass makes for x in MyClass work. The class is an instance of the metaclass, so the metaclass's dunders are the class's dunders.

Truthiness, Equality, and Hashing Are a Triangle

These three are deeply connected and breaking the contract between them is one of the more common ways to introduce subtle bugs.

Truthiness is determined by __bool__. If not defined, Python falls back to __len__: an object with length zero is falsy. If neither is defined, the object is always truthy.

class Container:
    def __init__(self, items):
        self.items = items

    def __len__(self):
        return len(self.items)

c = Container([])
if not c:
    print("empty")  # prints, because __bool__ fell back to __len__

Equality is __eq__. The default is identity comparison (same as is). Override it to define value equality.

Hashing is __hash__. Here is the contract: objects that compare equal must have the same hash. If you define __eq__, Python automatically sets __hash__ to None, making your object unhashable. This is intentional. Mutable objects with value equality should not be hashable because their hash could change when they are mutated, silently breaking set and dict behavior.

class Point:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __eq__(self, other):
        return isinstance(other, Point) and self.x == other.x and self.y == other.y

    # Python set __hash__ = None automatically
    # Point is now unhashable

p = Point(1, 2)
{p}  # TypeError: unhashable type: 'Point'

If you want a hashable value type, define both:

    def __hash__(self):
        return hash((self.x, self.y))

The tuple hash is stable, consistent with equality, and composes well. Never define __hash__ without thinking about what makes two instances equal, and never define __eq__ without thinking about whether you also need __hash__.

Comparison Operators and the Reflected Protocol

__lt__, __le__, __gt__, __ge__, __eq__, __ne__ cover the six comparison operators. Python's mechanism for resolving them is more nuanced than most people realize.

When you write a < b, Python first tries type(a).__lt__(a, b). If that returns NotImplemented, Python tries the reflected operation: type(b).__gt__(b, a). This gives the right operand a chance to handle the comparison when the left operand does not know how.

class Celsius:
    def __init__(self, temp):
        self.temp = temp

    def __lt__(self, other):
        if isinstance(other, Fahrenheit):
            return self.temp < (other.temp - 32) * 5 / 9
        if isinstance(other, Celsius):
            return self.temp < other.temp
        return NotImplemented  # not NotImplemented(), the singleton


class Fahrenheit:
    def __init__(self, temp):
        self.temp = temp

    def __gt__(self, other):
        if isinstance(other, Celsius):
            return self.temp > other.temp * 9 / 5 + 32
        return NotImplemented

NotImplemented is a singleton, not an exception. Returning it tells Python to try the reflected operation. Raising TypeError or returning False are both wrong here: they prevent the fallback.

functools.total_ordering is worth knowing. Define __eq__ and one of the four ordering methods, and it derives the rest. It is slower than defining all four manually but saves considerable boilerplate for types where ordering is well-defined.

Arithmetic Operators and In-Place Variants

The arithmetic protocol has three layers: forward, reflected, and in-place.

a + b tries type(a).__add__(a, b) first. If that returns NotImplemented, it tries type(b).__radd__(b, a). The reflected methods (__radd__, __rsub__, __rmul__, etc.) exist so that user-defined types can work with built-in types on both sides of an operator.

class Vector:
    def __init__(self, x, y):
        self.x = x
        self.y = y

    def __add__(self, other):
        if isinstance(other, Vector):
            return Vector(self.x + other.x, self.y + other.y)
        return NotImplemented

    def __radd__(self, other):
        # called when other + self and other.__add__ returned NotImplemented
        return self.__add__(other)

    def __mul__(self, scalar):
        if isinstance(scalar, (int, float)):
            return Vector(self.x * scalar, self.y * scalar)
        return NotImplemented

    def __rmul__(self, scalar):
        return self.__mul__(scalar)

v = Vector(1, 2)
print(3 * v)  # works because int.__mul__(3, v) returns NotImplemented,
              # then Vector.__rmul__(v, 3) is tried

In-place operators (+=, -=, *=) call __iadd__, __isub__, __imul__ and so on. If the in-place method is not defined, Python falls back to the regular method and rebinds the name. For mutable types, define the in-place variants to mutate in place and return self. For immutable types, do not define them and let Python handle the fallback.

def __iadd__(self, other):
    if isinstance(other, Vector):
        self.x += other.x
        self.y += other.y
        return self  # must return self for in-place operations
    return NotImplemented

Attribute Access Is More Controllable Than You Think

The attribute access protocol has four hooks: __getattribute__, __getattr__, __setattr__, and __delattr__.

__getattribute__ is called on every attribute access, including dunders. Overriding it without calling super().__getattribute__ will break your class entirely. It is rarely the right hook.

__getattr__ is called only when normal attribute lookup has failed. It is the right hook for lazy loading, proxying, and dynamic attributes:

class LazyLoader:
    def __init__(self, module_name):
        self._module_name = module_name
        self._module = None

    def __getattr__(self, name):
        if self._module is None:
            import importlib
            self._module = importlib.import_module(self._module_name)
        return getattr(self._module, name)

__setattr__ is called on every attribute assignment, including in __init__. If you override it, you must use object.__setattr__(self, name, value) or super().__setattr__(name, value) to actually store the value, otherwise you get infinite recursion:

class Validated:
    def __setattr__(self, name, value):
        if name == "age" and not isinstance(value, int):
            raise TypeError("age must be int")
        super().__setattr__(name, value)  # not self.name = value

The Container Protocol in Full

To make a proper sequence, you need __len__ and __getitem__. Python derives a surprising amount from these two:

class Fibonacci:
    def __len__(self):
        return 100

    def __getitem__(self, index):
        if isinstance(index, slice):
            return [self[i] for i in range(*index.indices(len(self)))]
        if index < 0:
            index += len(self)
        if not 0 <= index < len(self):
            raise IndexError(index)
        a, b = 0, 1
        for _ in range(index):
            a, b = b, a + b
        return a

fib = Fibonacci()
print(fib[10])       # 55
print(fib[2:5])      # [1, 2, 3]
print(10 in fib)     # works: Python iterates using __getitem__
for n in fib:        # works: iteration falls back to __getitem__
    pass

in and for both fall back to __getitem__-based iteration if __contains__ and __iter__ are not defined. Python calls __getitem__ with increasing integer indices starting at 0 until it gets an IndexError. This fallback exists for backward compatibility but you should define __iter__ explicitly for anything you intend to be iterable.

For mappings, define __getitem__, __setitem__, __delitem__, __len__, and __iter__. Inheriting from collections.abc.MutableMapping and implementing those five methods gives you keys(), values(), items(), get(), update(), pop(), and the rest for free through mixin implementations.

slots: Memory Layout as a Data Model Feature

__slots__ is part of the data model. Defining it on a class prevents the creation of __dict__ on instances and instead allocates a fixed set of descriptors for the named attributes.

class Point:
    __slots__ = ("x", "y")

    def __init__(self, x, y):
        self.x = x
        self.y = y

p = Point(1, 2)
p.z = 3  # AttributeError: 'Point' object has no attribute 'z'

The memory savings are significant for classes with many instances. A regular instance carries a __dict__ (a hash table) and a __weakref__ slot. A slotted instance carries only the declared attributes. For a class like Point that might be instantiated millions of times, this matters.

__slots__ interacts with inheritance in ways that require care. If a subclass does not define __slots__, instances get a __dict__ again, defeating the purpose. Every class in the hierarchy needs to define __slots__ for the optimization to hold all the way down.

The One Rule That Ties Everything Together

Dunder methods are a protocol, not a feature list. Every method participates in a documented contract. __eq__ implies __hash__ constraints. __iter__ implies __next__. __enter__ implies __exit__. __get__ participating in the descriptor protocol implies understanding when obj is None.

The mistakes come from implementing part of a protocol and ignoring the rest. Define __eq__ without thinking about __hash__ and your objects silently break in sets. Define __iter__ without StopIteration handling and your loops never end. Define __enter__ without a matching __exit__ and resources leak.

Read the protocol documentation for any dunder you implement. The contracts are specified, they are not long, and violating them produces bugs that are difficult to reproduce and harder to trace. The data model is the most reliable part of Python. It rewards the developers who actually read it.

Python Metaclasses, What's Actually Happening When You Write class

shayan holakouee — Wed, 29 Apr 2026 03:19:01 +0000

Every Python developer knows that everything is an object. What fewer know is that classes are objects too, and like every other object, they are instances of something. That something is a metaclass. Understanding metaclasses means understanding how Python builds classes in the first place, which turns out to explain a lot of behavior that otherwise looks like magic.

Classes Are Instances of type

Start here:

class MyClass:
    pass

print(type(MyClass))    # <class 'type'>
print(type(int))        # <class 'type'>
print(type(str))        # <class 'type'>
print(type(type))       # <class 'type'>

type is the metaclass of every class you have ever written unless you said otherwise. It is the class of classes. It is also an instance of itself, which is one of those things that is true and also slightly uncomfortable to think about for too long.

Since type is a class, you can call it to create new classes at runtime. The three-argument form of type does exactly this:

# type(name, bases, namespace)
MyClass = type("MyClass", (object,), {"x": 42, "greet": lambda self: "hello"})

obj = MyClass()
print(obj.x)        # 42
print(obj.greet())  # hello

This is not a trick or an edge case. This is literally what happens when Python processes a class statement. The class syntax is a shorthand for calling type (or a custom metaclass) with the class name, base classes, and namespace.

The Class Creation Protocol, Step by Step

When Python encounters a class block, it does not just evaluate the body and hand it to type. It follows a specific protocol.

Step 1: Determine the metaclass.

Python looks for a metaclass keyword argument in the class definition. If not found, it checks the base classes for their metaclass. If no bases specify one, it defaults to type.

class Meta(type):
    pass

class MyClass(metaclass=Meta):
    pass

print(type(MyClass))  # <class '__main__.Meta'>

Step 2: Prepare the namespace.

Python calls metaclass.__prepare__(name, bases, **kwargs). This returns the dictionary that will be used as the class namespace while the body executes. By default it returns a plain dict, but you can return an OrderedDict or a custom mapping to do things like track definition order or intercept attribute assignments.

class OrderedMeta(type):
    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        return {}  # default, but you can return anything dict-like

Step 3: Execute the class body.

The class body runs as a function, with the namespace from step 2 as its local scope. Every name defined in the body becomes a key in that namespace. This is why you can do things like:

class MyClass:
    items = []
    for i in range(3):
        items.append(i)  # this runs at class definition time

Step 4: Call the metaclass.

Python calls metaclass(name, bases, namespace) with the populated namespace. This is where the class object is actually created. This is type.__call__, which internally calls type.__new__ to create the class object and type.__init__ to initialize it.

The full chain: Meta(name, bases, ns) → Meta.__call__ → Meta.__new__ + Meta.__init__.

Writing a Metaclass That Does Something Useful

The canonical example of a metaclass that earns its complexity is one that enforces an interface. Suppose you want an abstract base pattern without the abc module, where subclasses that forget to implement required methods fail at class definition time rather than at instantiation.

class RequiredMethodsMeta(type):
    required = []

    def __new__(mcs, name, bases, namespace):
        cls = super().__new__(mcs, name, bases, namespace)

        # skip the check for the base class itself
        if bases:
            missing = [
                method for method in mcs.required
                if method not in namespace
            ]
            if missing:
                raise TypeError(
                    f"{name} must implement: {', '.join(missing)}"
                )
        return cls


class Shape(metaclass=RequiredMethodsMeta):
    RequiredMethodsMeta.required = ["area", "perimeter"]


class Circle(Shape):
    def area(self):
        return 3.14 * self.radius ** 2

    def perimeter(self):
        return 2 * 3.14 * self.radius

# This class raises TypeError at definition time, not at use time
class Square(Shape):
    def area(self):
        return self.side ** 2
    # missing perimeter
# => TypeError: Square must implement: perimeter

The error happens when the class statement for Square is processed, before any instance is ever created. This is the key advantage of metaclass-level enforcement over runtime checks.

new vs init in a Metaclass

When you subclass type, the two methods you override are __new__ and __init__. The distinction matters.

__new__ creates and returns the class object. This is where you modify the class before it exists as a complete object. You can alter the namespace, add or remove attributes, change the bases. The class has not been fully constructed yet.

__init__ receives the already-created class object and can perform post-construction setup. The class exists at this point but has not been returned to the caller yet.

class TrackedMeta(type):
    registry = []

    def __new__(mcs, name, bases, namespace):
        # Modify namespace before class is created
        namespace["_created_by"] = "TrackedMeta"
        cls = super().__new__(mcs, name, bases, namespace)
        return cls

    def __init__(cls, name, bases, namespace):
        # Class exists, register it
        TrackedMeta.registry.append(cls)
        super().__init__(name, bases, namespace)


class Base(metaclass=TrackedMeta):
    pass

class Child(Base):
    pass

print(TrackedMeta.registry)  # [<class 'Base'>, <class 'Child'>]
print(Base._created_by)      # TrackedMeta

The practical rule: use __new__ when you need to alter what the class is. Use __init__ when you just need to register or observe it after it is created.

prepare and Definition Order

__prepare__ is underused and often the cleaner solution to problems people solve with __new__. Because it controls the namespace used during class body execution, it can observe the order in which things are defined.

A plain dict preserves insertion order in Python 3.7+, so you get definition order for free now. But __prepare__ lets you go further: you can use a custom mapping that intercepts assignments, rejects duplicates, or transforms values as they are added.

class NoDuplicatesMeta(type):
    @classmethod
    def __prepare__(mcs, name, bases, **kwargs):
        return NoDuplicatesDict()

    def __new__(mcs, name, bases, namespace):
        return super().__new__(mcs, name, bases, dict(namespace))


class NoDuplicatesDict(dict):
    def __setitem__(self, key, value):
        if key in self and not key.startswith("_"):
            raise TypeError(f"Duplicate attribute: {key}")
        super().__setitem__(key, value)


class MyClass(metaclass=NoDuplicatesMeta):
    x = 1
    y = 2
    x = 3  # raises TypeError: Duplicate attribute: x

This catches the duplicate at class body execution time, not after. The error message points at the right place.

Metaclass Conflict and the MRO Problem

If you use multiple inheritance and the base classes have different metaclasses, Python raises a TypeError unless one metaclass is a subclass of all the others.

class MetaA(type): pass
class MetaB(type): pass

class A(metaclass=MetaA): pass
class B(metaclass=MetaB): pass

class C(A, B): pass
# TypeError: metaclass conflict: the metaclass of a derived class
# must be a subclass of the metaclasses of all its bases

The fix is to create a combined metaclass that inherits from both:

class MetaC(MetaA, MetaB): pass

class C(A, B, metaclass=MetaC): pass  # works

In practice, metaclass conflicts are a strong signal that the design has gotten complicated. If you are writing three metaclasses that need to be composed, consider whether __init_subclass__ or a class decorator solves the same problem more simply.

init_subclass: The Metaclass You Did Not Have to Write

Python 3.6 added __init_subclass__, which handles the most common metaclass use case without requiring a metaclass at all. It is called on the base class whenever a subclass is created.

class Plugin:
    _registry = {}

    def __init_subclass__(cls, plugin_name=None, **kwargs):
        super().__init_subclass__(**kwargs)
        if plugin_name:
            Plugin._registry[plugin_name] = cls


class JSONPlugin(Plugin, plugin_name="json"):
    def process(self, data): ...

class XMLPlugin(Plugin, plugin_name="xml"):
    def process(self, data): ...

print(Plugin._registry)
# {'json': <class 'JSONPlugin'>, 'xml': <class 'XMLPlugin'>}

No metaclass, no __new__, no type subclass. __init_subclass__ is called automatically at class creation time with whatever keyword arguments were passed in the class definition. For registration patterns, interface enforcement, and configuration at definition time, this handles most cases cleanly.

When a Metaclass Is Actually the Right Tool

Metaclasses are the right tool in a narrow set of situations. They make sense when you need to transform or validate the class namespace before the class object exists, when you need behavior that __init_subclass__ cannot express because it does not run at all for the base class itself, and when you are building framework infrastructure that other developers will subclass without knowing the mechanics.

Django's ORM uses metaclasses. SQLAlchemy uses metaclasses. The abc module uses a metaclass. These are all framework-level concerns where the metaclass is invisible to the end user.

If you are writing application code and reaching for a metaclass, stop and ask whether a class decorator or __init_subclass__ solves the problem. They almost always do, and they are significantly easier to understand, test, and debug. A metaclass that the next developer has to spend an hour understanding is a liability. The best metaclass is usually the one you did not have to write.

The BEAM Is Not Like Other Runtimes (And That's Why Elixir Scales the Way It Does)

shayan holakouee — Mon, 27 Apr 2026 20:35:48 +0000

You have been writing Elixir for a while. You know GenServers. You know supervisors. You have hit the BEAM's concurrency model enough times to trust it. But there is a level below that which most Elixir developers never look at, and it explains a lot of behavior that otherwise seems like magic.

Why does spawning a hundred thousand processes not kill your system? Why is a process crash isolated but not silent? Why does garbage collection in Elixir not stop the world? The answers are all in the BEAM, and they are worth understanding properly.

The BEAM Is Not the JVM With a Different Language

This comparison comes up constantly and it misleads people. Both are virtual machines that run bytecode. That is roughly where the similarity ends.

The JVM was designed around threads. Concurrency on the JVM means OS threads, shared mutable state, locks, and a garbage collector that operates across the entire heap. The BEAM was designed around processes. Not OS processes. Not OS threads. Its own lightweight processes, each with isolated memory, independent garbage collection, and message passing as the only communication mechanism.

This is not an implementation detail. It is the fundamental design decision that every other property of the BEAM follows from.

Processes Are Cheaper Than You Think

When people hear "process" they think OS process: expensive, slow to start, heavy on memory. BEAM processes are none of those things.

A BEAM process starts with around 2KB of stack space. It grows as needed. Spawning one takes microseconds. The BEAM scheduler manages thousands of them across a small pool of OS threads, one per CPU core by default. You can run a million concurrent processes on a single machine without the OS knowing about most of them.

# This is not dangerous. It is idiomatic.
pids = Enum.map(1..100_000, fn i ->
  spawn(fn ->
    Process.sleep(:timer.seconds(10))
    IO.puts("Process #{i} done")
  end)
end)

IO.puts("Spawned #{length(pids)} processes")
# => Spawned 100000 processes

On most systems this runs without issue. Try the equivalent with OS threads in any language and you will run out of resources before you hit ten thousand. The difference is not hardware. It is the scheduler.

The Scheduler: Preemptive and Reduction-Based

The BEAM uses a preemptive scheduler, but not in the way most runtimes do it. It does not preempt based on time slices measured in milliseconds. It preempts based on reductions.

A reduction is roughly one unit of work: a function call, a pattern match, a message send. Each process gets a budget of 2000 reductions per scheduling turn. When the budget runs out, the scheduler suspends the process and runs another one. This happens regardless of what the process is doing. A tight loop does not starve other processes.

# This does not block the scheduler
defmodule Spinner do
  def spin(n) do
    spin(n + 1)  # each call consumes a reduction
  end
end

spawn(fn -> Spinner.spin(0) end)
spawn(fn -> IO.puts("I still run") end)
# => I still run

In Node.js, a synchronous tight loop blocks the event loop entirely. In the BEAM, the scheduler preempts it after 2000 reductions. Every other process continues running. The misbehaving process gets its turn again shortly, but it cannot monopolize the system.

This is why latency in Elixir systems tends to be consistent rather than spiky. No single process can hold the scheduler hostage.

Memory Isolation and Per-Process GC

Every BEAM process has its own heap. No sharing. When a process dies, its heap is reclaimed immediately. No coordination with other processes, no waiting for a global GC cycle.

This is the source of one of the BEAM's most important properties: garbage collection does not stop the world. There is no world to stop. Each process collects its own garbage independently, on its own schedule, without affecting any other process.

# Each process allocates and collects independently
spawn(fn ->
  large_list = Enum.to_list(1..1_000_000)
  # large_list is only in this process's heap
  # GC here affects nothing else
  :ok
end)

# This process is unaffected by the GC above
spawn(fn ->
  IO.puts("Running without pause")
end)

Compare this to the JVM's stop-the-world pauses, or Go's GC which, while incremental, still coordinates across the entire heap. In the BEAM, a process doing heavy allocation and collection does not introduce latency spikes in other processes. The isolation is complete.

The tradeoff is message passing. Because processes share no memory, sending data between them requires copying. Large messages are expensive not because of the send itself but because of the copy. This is why Elixir idioms tend toward small, frequent messages rather than large data transfers. The design pushes you toward the pattern that performs well.

How Message Passing Actually Works

Every process has a mailbox. Sending a message puts a copy of the message into the recipient's mailbox. The recipient reads from its mailbox using receive. This is asynchronous by default: sending does not block.

parent = self()

spawn(fn ->
  send(parent, {:result, 42})
end)

receive do
  {:result, value} -> IO.puts("Got: #{value}")
after
  5000 -> IO.puts("Timed out")
end

The receive block pattern matches against messages in the mailbox in order. If no message matches, the process blocks and waits. Unmatched messages stay in the mailbox. This is a subtle point: if you receive messages without handling all patterns, your mailbox grows unboundedly. A common bug in long-running processes is accumulating unmatched messages until memory pressure becomes a problem.

# Dangerous in a long-running process
receive do
  {:ok, value} -> handle(value)
  # no catch-all: anything else stays in mailbox forever
end

# Safer
receive do
  {:ok, value} -> handle(value)
  other -> Logger.warning("Unexpected message: #{inspect(other)}")
end

Preemption vs Cooperation: The NIF Problem

The BEAM's scheduler is preemptive for Elixir and Erlang code. It is not preemptive for NIFs.

A NIF (Native Implemented Function) is C code called directly from Elixir. When a NIF runs, the BEAM scheduler cannot preempt it. The OS thread running that NIF is blocked for the duration of the call. If your NIF takes 100ms, every process scheduled on that OS thread waits 100ms.

# If :my_nif.heavy_computation/1 takes 500ms,
# it blocks the scheduler thread for 500ms
result = :my_nif.heavy_computation(data)

This is why the BEAM documentation is so emphatic that NIFs must be fast. Anything over one millisecond should use a dirty scheduler: a separate pool of OS threads reserved for long-running native calls that runs outside the main scheduler.

# In your NIF definition (C side), mark it dirty:
# ERL_NIF_DIRTY_JOB_CPU_BOUND or ERL_NIF_DIRTY_JOB_IO_BOUND

Understanding this explains why some Elixir libraries that wrap C code (image processing, certain crypto operations, database drivers with native extensions) can introduce latency spikes that seem inconsistent with the BEAM's concurrency model. They are bypassing the model.

The Scheduler's Relationship With IO

IO in the BEAM is non-blocking at the scheduler level. When a process does a network read or a file operation, the BEAM does not block the OS thread. It suspends the process, registers the IO operation with an internal polling mechanism (built on epoll or kqueue depending on the OS), and runs other processes. When the IO completes, the process is rescheduled.

This is why Elixir handles tens of thousands of concurrent connections without a thread-per-connection model. Each connection maps to a process. Each process consumes a BEAM process worth of resources (a few kilobytes), not an OS thread. The IO multiplexing is handled by the runtime, not by the application code.

# Each of these connections is a lightweight process
# The BEAM handles the IO multiplexing
{:ok, socket} = :gen_tcp.accept(listen_socket)
pid = spawn(fn -> handle_connection(socket) end)

Phoenix handling millions of concurrent WebSocket connections is not a framework trick. It is the BEAM's process model applied to network IO with no special configuration required.

What This Means for How You Write Code

Once you understand the BEAM's process model, certain Elixir patterns stop looking like conventions and start looking like direct expressions of the runtime's capabilities.

Spawning a process per request is not wasteful, it is appropriate. Letting a process crash instead of handling every possible error is not lazy, it is correct: the process's isolated heap disappears cleanly, the supervisor restarts it in a known good state, and no other process was affected.

The things that are expensive in other runtimes (concurrency, isolation, failure recovery) are cheap in the BEAM because the runtime was built to make them cheap. The things that are expensive in the BEAM (large message copies, long-running NIFs) are expensive because they work against the model.

The more directly your code expresses the model, the more you get out of it.

Rust's Zero-Cost Abstractions, What Monomorphization Actually Does to Your Code

shayan holakouee — Mon, 27 Apr 2026 20:07:12 +0000

"Zero-cost abstractions" is one of Rust's core promises. You can write generic, composable, high-level code and the compiler will produce the same machine code as if you had written the low-level version by hand. Most people accept this claim and move on. It is worth actually understanding the mechanism behind it, because it has real consequences for compile times, binary size, and performance in ways that will eventually surprise you.

The Problem Abstractions Usually Create

In most languages with generics or polymorphism, the runtime pays for flexibility. Java's generics are erased at compile time and everything becomes Object, which means heap allocation and virtual dispatch. Python functions accept anything but pay for it with dynamic type lookups on every operation. Even C++ with templates avoids runtime cost, but the mechanism it uses is the same one Rust uses.

The question is: how do you write one function that works on many types, without inserting a layer of indirection at runtime?

What Monomorphization Is

Monomorphization means the compiler generates a separate, concrete copy of a generic function for each type it is actually called with. You write one function. The compiler writes many.

fn largest<T: PartialOrd>(a: T, b: T) -> T {
    if a > b { a } else { b }
}

fn main() {
    largest(1i32, 2i32);
    largest(1.0f64, 2.0f64);
}

After monomorphization, the compiler has effectively produced this:

fn largest_i32(a: i32, b: i32) -> i32 {
    if a > b { a } else { b }
}

fn largest_f64(a: f64, b: f64) -> f64 {
    if a > b { a } else { b }
}

Each version is fully concrete. The CPU never sees a generic type. There is no branching on type, no vtable lookup, no boxing. The generated assembly for largest_i32 is exactly what you would get if you had written it for i32 from the start.

You can verify this yourself. Run cargo build --release and inspect the output with cargo-show-asm or objdump. Each monomorphized version shows up as a distinct symbol in the binary.

How Traits Fit Into This

Traits are the constraint mechanism. When you write T: PartialOrd, you are telling the compiler what operations are available on T. At the call site, the compiler knows the concrete type, so it knows the exact implementation of PartialOrd to use. It inlines it directly.

This is what makes iterator chains fast:

let sum: i32 = (0..1000)
    .filter(|x| x % 2 == 0)
    .map(|x| x * x)
    .sum();

Each of filter, map, and sum is generic over the iterator type. After monomorphization, the entire chain collapses into a single loop with no intermediate allocation and no function call overhead. The compiler sees through every layer. It knows the concrete type at each step because you started with Range<i32>, and each adapter wraps the previous one in a new concrete type.

Compare this to how you would write the equivalent in a language without monomorphization. You would either materialize an intermediate collection at each step, or you would use some form of dynamic dispatch with its associated overhead.

The Actual Cost: Code Bloat and Compile Time

Zero-cost at runtime does not mean zero-cost overall. You pay elsewhere.

Binary size. Every unique combination of generic function and concrete type produces a new copy in the binary. If you call Vec::new::<String>(), Vec::new::<i32>(), and Vec::new::<MyStruct>(), you get three copies of the Vec::new implementation. In a large codebase with many generic types, this adds up. It is a real concern for embedded targets and WebAssembly where binary size matters.

Compile time. Monomorphization happens during code generation, which is one of the most expensive phases of Rust compilation. Every unique instantiation of a generic function is work the compiler has to do. This is a significant contributor to Rust's notoriously slow compile times. When you see a crate that takes thirty seconds to compile, a large part of that is the code generation phase expanding generics.

Instruction cache pressure. Multiple copies of similar functions means more machine code in memory. If those functions are all hot paths called in rapid succession, you can end up with instruction cache misses that would not exist with a single shared implementation.

Static Dispatch vs Dynamic Dispatch

Monomorphization is static dispatch. The call target is resolved at compile time. Rust also supports dynamic dispatch through trait objects, and the tradeoff is exactly what you would expect.

// static dispatch: monomorphized, zero runtime overhead
fn process_static<T: Draw>(item: T) {
    item.draw();
}

// dynamic dispatch: single function, vtable lookup at runtime
fn process_dynamic(item: &dyn Draw) {
    item.draw();
}

With &dyn Draw, the compiler generates one function. At runtime, a vtable pointer accompanies the reference, and the call goes through an indirect jump. This costs roughly one extra memory lookup per call. In exchange, you get a single copy of process_dynamic in the binary, and you can put different concrete types into the same collection.

The practical rule: use static dispatch (generics) for performance-critical code where all types are known at compile time. Use dynamic dispatch (dyn Trait) when you need heterogeneous collections, when the concrete type is only known at runtime, or when binary size and compile time matter more than the last bit of call overhead.

Where Monomorphization Gets Interesting: Trait Objects in Generic Contexts

A subtlety that catches people: trait objects themselves can be used as concrete types in generic contexts, which then get monomorphized.

fn process<T: Draw>(items: Vec<T>) { ... }

// This is one monomorphization
process::<Box<dyn Draw>>(vec![...]);

Here T is Box<dyn Draw>. The function is monomorphized for that concrete type. Inside the function, calls through T still go through the vtable because T is a trait object. You have static dispatch to the function, and dynamic dispatch inside it. Understanding this layering matters when you are trying to reason about where the overhead actually lives.

The impl Trait Shorthand

impl Trait in argument position is syntactic sugar for a generic parameter:

// these are equivalent
fn process(item: impl Draw) { ... }
fn process<T: Draw>(item: T) { ... }

Both are monomorphized. Each unique concrete type passed to process produces a new instantiation. impl Trait is not dynamic dispatch despite looking less generic at first glance.

impl Trait in return position is different:

fn make_drawable() -> impl Draw {
    Circle::new()
}

This tells the caller "you will get something that implements Draw, but I am not telling you the concrete type." The concrete type is fixed at compile time and the function is not generic over it. The caller cannot name the type but the compiler knows it, so there is no dynamic dispatch. It is a way to hide implementation details while keeping static dispatch.

Inspecting the Output

The best way to build intuition for what monomorphization produces is to look at actual assembly. The cargo-show-asm tool makes this straightforward:

cargo install cargo-show-asm
cargo asm --release your_crate::your_function

Run it on a generic function called with two different types and you will see two separate assembly listings with distinct symbol names. Run it on the iterator chain example and you will see a tight loop with no function calls. The gap between what you wrote and what the CPU executes is much smaller in Rust than in most languages, and this tool makes that concrete rather than theoretical.

The Mental Model to Carry Forward

When you write generic Rust code, think of yourself as writing a template that the compiler will stamp out once per concrete type. Each stamp is as fast as hand-written code for that type. The tradeoff you are making is compilation time and binary size in exchange for runtime performance and the ability to write the logic once.

This is why Rust can match C performance while supporting generics, iterators, and trait-based abstractions. The abstraction cost is paid at compile time, not runtime. Zero-cost does not mean free. It means the cost is moved to a place where it hurts less.

Python's Descriptor Protocol, The Feature Behind Everything You Use Daily

shayan holakouee — Mon, 27 Apr 2026 20:02:35 +0000

You use descriptors every day. Every time you write @property, every time you call a method, every time you use @staticmethod or @classmethod, you are using the descriptor protocol. Most Python developers have no idea it exists as a unified mechanism. Once you see it, you cannot unsee it.

What a Descriptor Is

A descriptor is any object that defines at least one of three methods: __get__, __set__, or __delete__. That is it. When an attribute lookup finds one of these objects sitting in a class's __dict__, Python hands control over to the descriptor instead of returning the object directly.

The minimal descriptor looks like this:

class MyDescriptor:
    def __get__(self, obj, objtype=None):
        print(f"__get__ called: obj={obj}, objtype={objtype}")
        return 42

class MyClass:
    attr = MyDescriptor()

instance = MyClass()
instance.attr   # prints: __get__ called: obj=<MyClass ...>, objtype=<class 'MyClass'>
MyClass.attr    # prints: __get__ called: obj=None, objtype=<class 'MyClass'>

When obj is None, the descriptor is being accessed from the class itself, not an instance. This distinction matters and you will use it constantly when writing real descriptors.

Data Descriptors vs Non-Data Descriptors

This split is the most important thing to understand about how descriptors interact with instance __dict__.

A data descriptor defines both __get__ and __set__ (or __delete__). It takes priority over the instance's own __dict__. You cannot shadow it by doing instance.attr = something because __set__ intercepts the assignment.

A non-data descriptor defines only __get__. The instance's __dict__ takes priority over it. If you assign to instance.attr, Python just stores the value in the instance dictionary and the descriptor is no longer called for that instance.

The lookup order for instance.attr is:

Data descriptors from the class (and its MRO)
Instance __dict__
Non-data descriptors and other class attributes

This ordering is not arbitrary. It is what makes @property work correctly. A property is a data descriptor because it defines __set__ (even if you only define a getter, the setter raises AttributeError), so it cannot be overridden by instance assignment. Functions, on the other hand, are non-data descriptors, which is why you can shadow a method by assigning to an instance attribute of the same name.

How Functions Become Methods

This is the part that clicks everything together. In Python, a plain function is a non-data descriptor. It only defines __get__. When you access a function through an instance, __get__ is called, and it returns a bound method object that already has the instance baked in as the first argument.

def greet(self):
    return f"Hello from {self}"

class Person:
    greet = greet

p = Person()

# These are equivalent
p.greet()
Person.greet(p)

# What actually happens
bound_method = Person.__dict__['greet'].__get__(p, Person)
bound_method()

function.__get__(instance, owner) returns a MethodType object that wraps the function and the instance together. There is no magic beyond this. The entire method binding mechanism in Python is the descriptor protocol applied to plain functions.

You can verify this:

print(type(greet))           # <class 'function'>
print(greet.__get__)         # <method-wrapper '__get__' of function object at ...>
print(type(p.greet))         # <class 'method'>

Writing a Real Descriptor: Typed Attributes

Here is where descriptors become practically useful. Suppose you want class attributes that enforce a type at assignment time without cluttering __init__ with validation logic.

class Typed:
    def __set_name__(self, owner, name):
        self.name = name
        self.private_name = f"_{name}"

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        return getattr(obj, self.private_name, None)

    def __set__(self, obj, value):
        if not isinstance(value, self.expected_type):
            raise TypeError(
                f"{self.name} must be {self.expected_type.__name__}, "
                f"got {type(value).__name__}"
            )
        setattr(obj, self.private_name, value)

class Integer(Typed):
    expected_type = int

class String(Typed):
    expected_type = str

class Person:
    name = String()
    age = Integer()

    def __init__(self, name, age):
        self.name = name
        self.age = age

p = Person("Alice", 30)   # works
p.age = "thirty"          # raises TypeError: age must be int, got str

Notice __set_name__. This is a hook Python calls automatically when the class is created, passing the descriptor the owner class and the attribute name it was assigned to. Without it, the descriptor would not know its own name and you would have to pass it manually. It was added in Python 3.6 and makes descriptors significantly cleaner to write.

classmethod and staticmethod Are Just Descriptors

Once you understand the protocol, classmethod and staticmethod stop being mysterious decorators and become straightforward descriptor implementations.

staticmethod wraps a function and its __get__ simply returns the function unchanged, with no binding:

class StaticMethod:
    def __init__(self, f):
        self.f = f

    def __get__(self, obj, objtype=None):
        return self.f  # no binding, just return the raw function

classmethod wraps a function and its __get__ binds the class instead of the instance:

class ClassMethod:
    def __init__(self, f):
        self.f = f

    def __get__(self, obj, objtype=None):
        if objtype is None:
            objtype = type(obj)
        return self.f.__get__(objtype)  # bind the class, not the instance

These are simplified but functionally accurate. The actual CPython implementations are in C for performance, but the logic is identical. You could replace @classmethod with your own descriptor and everything would work the same way.

The Caching Descriptor Pattern

One underused pattern is using descriptors to compute expensive values once and then cache them on the instance, bypassing the descriptor entirely on subsequent access.

class cached_property:
    def __init__(self, func):
        self.func = func
        self.attrname = None

    def __set_name__(self, owner, name):
        self.attrname = name

    def __get__(self, obj, objtype=None):
        if obj is None:
            return self
        val = self.func(obj)
        obj.__dict__[self.attrname] = val  # store directly on instance
        return val

This works because cached_property is a non-data descriptor (it only defines __get__). On first access, it calls the function and stores the result in the instance __dict__ under the same name. On second access, the instance __dict__ lookup wins and the descriptor is never called again.

Python ships functools.cached_property since 3.8 using exactly this technique. It is elegant because the caching mechanism falls directly out of the descriptor lookup order rather than requiring any explicit flag or sentinel.

When to Actually Use This

Descriptors are the right tool in specific situations. If you find yourself writing the same property logic across multiple attributes or classes (validation, unit conversion, access logging), a descriptor lets you define that logic once and attach it declaratively.

ORMs lean on this heavily. Django's Field classes and SQLAlchemy's Column objects are descriptors. When you write user.name, the ORM intercepts it through __get__ and can return a SQL expression rather than a plain value, depending on context.

Frameworks that do attribute access tracking for reactive programming (like Traitlets in Jupyter or any observable pattern) use descriptors to intercept reads and writes and fire callbacks.

If you are not building framework-level infrastructure, plain properties cover most cases. But understanding descriptors tells you exactly what @property is doing and why it behaves the way it does, which makes the edge cases much easier to reason about.

The Go Memory Model, Why Your Concurrent Code Might Be Lying to

shayan holakouee — Mon, 27 Apr 2026 19:58:42 +0000

You write two goroutines. One sets a variable, the other reads it. You run it a thousand times and it works fine. Then it breaks in production, on a different machine, under load. You stare at the code and nothing looks wrong.

It is not fine. You just got hit by the memory model.

The Problem Is Not Timing, It Is Visibility

Most developers think about concurrency bugs in terms of two operations colliding at the same moment. That framing is useful but it misses something deeper. The real question is not just when something happens. It is whether one goroutine can see what another goroutine did at all.

CPUs and compilers do not execute your code top to bottom. They reorder instructions, cache values in registers, and delay writes to main memory for performance reasons. On a single thread this is invisible because everything is consistent from your perspective. Across multiple goroutines, that consistency breaks down.

Go does not promise that goroutine A will see the writes made by goroutine B unless you establish a specific relationship between them. That relationship has a formal name: happens-before.

What Happens-Before Actually Means

Happens-before is a partial ordering of events in a concurrent program. If event A happens-before event B, then B is guaranteed to observe everything A did. If there is no happens-before relationship between A and B, the memory model makes no guarantees at all. B might see A's writes, or it might not. Both outcomes are valid from the spec's perspective.

This is the part that surprises people. The following code has a data race:

var ready bool
var data int

func main() {
    go func() {
        data = 42
        ready = true
    }()

    for !ready {
        runtime.Gosched()
    }

    fmt.Println(data)
}

Intuitively it looks safe. You wait until ready is true, then you read data. But there is no happens-before between the goroutine's writes and the main goroutine's reads. The compiler is allowed to reorder data = 42 and ready = true. The CPU is allowed to flush them to memory in any order. You might read ready == true and still see data == 0.

The Go race detector will catch this. Your eyes will not.

What Actually Establishes Happens-Before in Go

The Go memory model (updated formally in 2022) defines a specific set of synchronization operations that create happens-before edges. These are the ones you will use constantly.

Channel sends and receives

A send on a channel happens-before the corresponding receive from that channel completes. This is the most idiomatic way to synchronize in Go:

var data int
ch := make(chan struct{})

go func() {
    data = 42
    ch <- struct{}{} // send happens-before receive
}()

<-ch
fmt.Println(data) // guaranteed to see 42

For buffered channels, the rule is slightly different. The k*th receive from a channel with capacity *C happens-before the *k+C*th send completes. This is what makes buffered channels work as semaphores.

sync.Mutex

For a given sync.Mutex or sync.RWMutex variable, the *n*th call to Unlock happens-before the *n+1*th call to Lock returns. In plain terms: whatever you did inside a locked section is visible to whoever acquires the lock next.

var mu sync.Mutex
var data int

go func() {
    mu.Lock()
    data = 42
    mu.Unlock() // this unlock happens-before the next Lock
}()

mu.Lock()
fmt.Println(data) // safe
mu.Unlock()

sync.Once

The completion of the first call to f() inside once.Do(f) happens-before any other call to once.Do returns. This is why sync.Once is the standard pattern for safe lazy initialization. The guarantee is built into the type.

sync/atomic

The atomic package provides sequentially consistent operations. If you use atomic.StoreInt64 and atomic.LoadInt64, the store happens-before the load if the load observes the stored value. This makes atomics the right tool for simple flags and counters, but not for protecting compound state changes.

Goroutine creation

The go statement that starts a goroutine happens-before the goroutine itself begins executing. This means any writes done before the go statement are visible inside the new goroutine. However, the goroutine's completion does not happen-before anything in the parent unless you explicitly synchronize.

data := 42
go func() {
    fmt.Println(data) // safe, goroutine creation establishes happens-before
}()

The sync.WaitGroup Trap

sync.WaitGroup is correct but people frequently use it in ways that create subtle races. The rule is: wg.Done() happens-before wg.Wait() returns. That guarantee covers the goroutine's work up to the Done call. It does not cover anything that happens after.

var wg sync.WaitGroup
results := make([]int, 5)

for i := 0; i < 5; i++ {
    wg.Add(1)
    go func(i int) {
        defer wg.Done()
        results[i] = i * 2 // writing to separate indices is safe
    }(i)
}

wg.Wait()
fmt.Println(results) // safe to read here

This is fine because each goroutine writes to a distinct index and Wait returns only after all Done calls. But if you wrote to the same index from multiple goroutines, or read results inside another goroutine without additional synchronization, you would have a race.

When Atomic Is Not Enough

A common mistake is reaching for sync/atomic to protect state that involves more than one variable. Atomics give you per-operation guarantees. They do not give you transactional guarantees across multiple variables.

// dangerous
var count int64
var sum int64

go func() {
    atomic.AddInt64(&count, 1)
    atomic.AddInt64(&sum, value)
}()

go func() {
    c := atomic.LoadInt64(&count)
    s := atomic.LoadInt64(&sum)
    avg := s / c // s and c might not correspond to the same state
}()

Even though each individual load and store is atomic, there is no guarantee that c and s were read from a consistent snapshot. Between the two loads, another goroutine could have updated sum but not yet count, or vice versa. For this kind of compound state, use a mutex.

The Practical Mental Model

Here is a simple way to think about it when reviewing concurrent code. Ask two questions for every shared variable.

First: is there a write to this variable that could happen concurrently with a read or another write? If yes, you have a potential race. Then ask: is there a synchronization operation between the write and the read that creates a happens-before edge? If the answer is no, the code is wrong regardless of how many times it has worked in testing.

The race detector catches most of these at runtime, but only if the racy code path is actually exercised during the test run. The memory model is the tool for reasoning about whether a path is safe in the first place.

Minimal APIs in .NET Are Not a Toy, Start Treating Them That Way

shayan holakouee — Sun, 26 Apr 2026 19:49:25 +0000

When Minimal APIs landed in .NET 6, a lot of developers dismissed them. "That's for demos," they said. "Real APIs use controllers."

Two major .NET versions later, I think that take has aged badly. Minimal APIs aren't a stripped-down shortcut they're a deliberate design choice, and when used correctly, they produce cleaner, faster, and more maintainable code than the controller approach. But you have to actually use them correctly.

Let me show you what that looks like.

The Setup That Doesn't Embarrass You in Code Review

Everyone's seen the "hello world" version of Minimal APIs:

var app = WebApplication.Create(args);
app.MapGet("/", () => "Hello World!");
app.Run();

Cool. Now forget it. Nobody ships that.

Here's a foundation that scales:

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();
builder.Services.AddScoped<IOrderService, OrderService>();

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseSwagger();
    app.UseSwaggerUI();
}

app.UseHttpsRedirection();
app.MapOrderEndpoints();

app.Run();

That MapOrderEndpoints() call is where the real structure lives. We'll get there in a second.

Stop Putting Everything in Program.cs

This is the mistake that gives Minimal APIs a bad reputation. People dump 300 lines of endpoint definitions into Program.cs and then complain that it's unreadable. That's not the framework's fault.

The pattern that actually works is extension methods per feature:

// Endpoints/OrderEndpoints.cs
public static class OrderEndpoints
{
    public static void MapOrderEndpoints(this WebApplication app)
    {
        var group = app.MapGroup("/orders")
                       .WithTags("Orders")
                       .RequireAuthorization();

        group.MapGet("/", GetAllOrders);
        group.MapGet("/{id:int}", GetOrderById);
        group.MapPost("/", CreateOrder);
        group.MapPut("/{id:int}", UpdateOrder);
        group.MapDelete("/{id:int}", DeleteOrder);
    }

    private static async Task<IResult> GetAllOrders(
        IOrderService service, CancellationToken ct)
    {
        var orders = await service.GetAllAsync(ct);
        return Results.Ok(orders);
    }

    private static async Task<IResult> GetOrderById(
        int id, IOrderService service, CancellationToken ct)
    {
        var order = await service.GetByIdAsync(id, ct);
        return order is null ? Results.NotFound() : Results.Ok(order);
    }

    private static async Task<IResult> CreateOrder(
        CreateOrderRequest request, IOrderService service, CancellationToken ct)
    {
        var created = await service.CreateAsync(request, ct);
        return Results.CreatedAtRoute("GetOrderById", new { id = created.Id }, created);
    }

    // ... UpdateOrder, DeleteOrder follow the same pattern
}

One file per feature. Each file owns its routes, its handlers, its grouping. Program.cs stays clean. This is what maintainable looks like.

Route Groups Are Underused

MapGroup was added in .NET 7 and I still see people not using it. It lets you apply common configuration prefixes, auth, rate limiting, tags to a set of routes in one place instead of repeating it on every MapGet.

var api = app.MapGroup("/api/v1")
             .RequireAuthorization()
             .AddEndpointFilter<RequestLoggingFilter>();

var orders = api.MapGroup("/orders").WithTags("Orders");
var products = api.MapGroup("/products").WithTags("Products");

Now everything under /api/v1 requires auth and gets logged, without you touching each individual endpoint. When you add a new route to the group, it inherits everything automatically. That's the kind of thing that saves you from a bug where someone forgets to add .RequireAuthorization() to a new endpoint.

Validation Without the Ceremony

One legitimate criticism of Minimal APIs is that validation isn't as automatic as it is with controllers and [ApiController]. You have to handle it explicitly. Fine explicit is better than magic you can't find when something breaks.

Here's a clean approach using an endpoint filter:

public class ValidationFilter<T> : IEndpointFilter
{
    private readonly IValidator<T> _validator;

    public ValidationFilter(IValidator<T> validator)
    {
        _validator = validator;
    }

    public async ValueTask<object?> InvokeAsync(
        EndpointFilterInvocationContext ctx, EndpointFilterDelegate next)
    {
        var argument = ctx.Arguments.OfType<T>().FirstOrDefault();

        if (argument is not null)
        {
            var result = await _validator.ValidateAsync(argument);
            if (!result.IsValid)
                return Results.ValidationProblem(result.ToDictionary());
        }

        return await next(ctx);
    }
}

Attach it to any endpoint that takes a request body:

group.MapPost("/", CreateOrder)
     .AddEndpointFilter<ValidationFilter<CreateOrderRequest>>();

This uses FluentValidation, but the pattern works with any validation library. The point is: the filter runs before your handler, you return a proper ValidationProblem response, and your handler stays clean. No if (!ModelState.IsValid) noise inside every method.

TypedResults Over Results Always

You've probably seen both of these:

// Untyped
return Results.Ok(order);

// Typed
return TypedResults.Ok(order);

The difference isn't just aesthetics. TypedResults preserves the response type in the method signature, which means Swagger/OpenAPI can infer your response types without you manually decorating everything with Produces<T>().

private static async Task<Results<Ok<Order>, NotFound>> GetOrderById(
    int id, IOrderService service, CancellationToken ct)
{
    var order = await service.GetByIdAsync(id, ct);
    return order is null ? TypedResults.NotFound() : TypedResults.Ok(order);
}

That return type is self-documenting. The OpenAPI spec knows this endpoint returns either a 200 with an Order or a 404 — automatically, no attributes needed. Use TypedResults from day one on any project you care about.

Error Handling: One Place, Not Everywhere

Don't try-catch inside every handler. That's controller thinking leaking into Minimal APIs.

.NET 8 introduced IProblemDetailsService and the built-in exception handler middleware that pairs cleanly with Minimal APIs:

app.UseExceptionHandler(errApp =>
{
    errApp.Run(async ctx =>
    {
        var ex = ctx.Features.Get<IExceptionHandlerFeature>()?.Error;

        var problem = ex switch
        {
            NotFoundException => new ProblemDetails
            {
                Status = 404,
                Title = "Not Found",
                Detail = ex.Message
            },
            ValidationException => new ProblemDetails
            {
                Status = 400,
                Title = "Validation Failed",
                Detail = ex.Message
            },
            _ => new ProblemDetails
            {
                Status = 500,
                Title = "Server Error",
                Detail = "Something went wrong."
            }
        };

        ctx.Response.StatusCode = problem.Status ?? 500;
        await ctx.Response.WriteAsJsonAsync(problem);
    });
});

One place handles all unhandled exceptions. Your handlers throw, the middleware catches. Clean separation.

Performance: This Is Where Minimal APIs Win

It's not even close. Minimal APIs have measurably lower overhead than MVC controllers because they skip a lot of the pipeline — action filters, model binding infrastructure, the full MVC middleware stack.

In the TechEmpower benchmarks, ASP.NET Core with Minimal APIs consistently ranks among the fastest web frameworks across all languages. This isn't theoretical. If you're building high-throughput services, the choice matters.

That said — don't pick Minimal APIs only for performance if your team is deeply comfortable with controllers. The best architecture is the one your team can actually maintain. But if you're starting fresh, there's no reason to reach for the heavier option.

When to Stick With Controllers

I'd be doing you a disservice if I didn't say this: controllers still make sense in some situations.

Large teams where convention-based structure reduces decision fatigue
Legacy codebases where mixing patterns adds confusion
Heavy use of action filters and model binding customization that MVC handles better out of the box

Minimal APIs aren't the answer to every problem. They're the right tool for services where you want explicit, lightweight, testable endpoints — which is most of what I build these days.

The Bottom Line

Minimal APIs hit their stride in .NET 7 and .NET 8. The feature gaps that made people hesitant — proper grouping, filters, typed results, auth integration — are closed. What's left is a leaner, faster, more explicit alternative to controllers that scales fine as long as you structure it properly.

Stop putting everything in Program.cs. Use route groups. Use TypedResults. Handle errors in one place. Keep your handlers small and your services doing the actual work.

That's it. That's a clean Minimal API.

You're Probably Using async/await Wrong (And It's Costing You)

shayan holakouee — Sun, 26 Apr 2026 19:45:04 +0000

Let me be direct: most .NET developers I've seen , including myself, early on — treat async/await like a magic sprinkle. Slap it on a method, everything becomes non-blocking, ship it. Done.

Except it's not done. And the bugs that come from that mindset are the worst kind: the ones that only show up under load, in production, at 2am.

This article isn't an intro. I'm assuming you know what Task is and that you've written at least one async method before. What I want to do is get into the stuff that actually matters when you're building something real.

The Myth of "Just Add async"

Here's a pattern I see constantly:

public async Task<List<Order>> GetOrdersAsync()
{
    var orders = _db.Orders.ToList(); // synchronous, blocking
    return orders;
}

This method is async in name only. It doesn't await anything. The compiler will actually warn you about this — and then generate a state machine that wraps a synchronous operation for absolutely no benefit. You've added overhead without gaining anything.

If there's no genuine I/O or CPU-bound work to await, don't use async. Simple. Return Task.FromResult(value) if the interface demands it.

async void Is a Trap

// Don't do this
public async void LoadData()
{
    var data = await _service.FetchAsync();
    Display(data);
}

async void methods cannot be awaited. Exceptions thrown inside them will crash the process — they're not catchable from outside. The only legitimate use case is event handlers, and even then, I'd argue you should immediately delegate to an async Task method and keep the void shell as thin as possible.

private async void Button_Click(object sender, EventArgs e)
{
    await LoadDataAsync(); // delegate immediately
}

private async Task LoadDataAsync()
{
    var data = await _service.FetchAsync();
    Display(data);
}

This way you have a testable, awaitable, exception-safe path.

ConfigureAwait(false): Know When It Matters

You've probably seen this:

var result = await _httpClient.GetAsync(url).ConfigureAwait(false);

Here's what's actually happening. By default, await captures the current SynchronizationContext and resumes on it. In a UI app, that means resuming on the UI thread. In ASP.NET (pre-Core), it meant resuming on the request context thread.

.ConfigureAwait(false) tells the runtime: "I don't care which thread I resume on." This avoids a deadlock-prone pattern and removes the overhead of re-capturing the context.

Rule of thumb:

Library code? Always use .ConfigureAwait(false). You don't know what context your callers are in.
Application-level code (controllers, view models, UI handlers)? Skip it — you usually do care about the context.

ASP.NET Core doesn't have a SynchronizationContext the same way, so deadlocks from missing ConfigureAwait(false) are less common there. But the performance argument for library code still stands.

The Classic Deadlock (And Why It Still Happens)

// This will deadlock in certain contexts
public string GetData()
{
    return _service.GetDataAsync().Result; // blocking on async
}

Calling .Result or .Wait() on an async Task in a context with a SynchronizationContext is asking for trouble. The await inside GetDataAsync() tries to resume on the original context, but you're blocking that context waiting for the Task to finish. Stalemate.

The fix is: go async all the way. Async is infectious by design. Once you start, you have to follow through up the call chain. If you're finding yourself reaching for .Result to "escape" the async world, that's a sign something higher up in your design needs to change.

Parallelism vs. Concurrency — They're Not the Same Thing

This distinction matters a lot and gets blurred constantly.

Concurrency is about dealing with multiple things at once. Parallelism is about doing multiple things at once. async/await gives you concurrency; it doesn't automatically give you parallelism.

If you need to fire off three independent HTTP calls and wait for all of them:

// Concurrent — all three start immediately, not sequentially
var t1 = _client.GetAsync("/orders");
var t2 = _client.GetAsync("/products");
var t3 = _client.GetAsync("/users");

var results = await Task.WhenAll(t1, t2, t3);

Compare this to:

// Sequential — each waits for the previous
var r1 = await _client.GetAsync("/orders");
var r2 = await _client.GetAsync("/products");
var r3 = await _client.GetAsync("/users");

Same end result. Radically different performance. The first version is what you want when the calls are independent.

For CPU-bound work (image processing, heavy computation), use Task.Run to push it off the thread pool:

var result = await Task.Run(() => HeavyCpuWork(data));

Don't use Task.Run for I/O-bound work. That's what truly async APIs are for. Task.Run hands the work to a thread pool thread, which still blocks a thread. Truly async I/O doesn't block any thread at all while waiting.

CancellationToken: Stop Ignoring It

public async Task<Report> GenerateReportAsync(CancellationToken ct = default)
{
    var rawData = await _db.GetRawDataAsync(ct);
    ct.ThrowIfCancellationRequested();
    var processed = await ProcessAsync(rawData, ct);
    return BuildReport(processed);
}

If your async methods don't accept and propagate a CancellationToken, you are leaking resources. A user cancels a request, navigates away, or the server needs to shut down — without cancellation support, you're still chewing through CPU and I/O doing work for nobody.

Propagate the token everywhere you can. Pass it to every I/O method that accepts one. Add ct.ThrowIfCancellationRequested() at logical checkpoints in long operations.

In ASP.NET Core, the CancellationToken is built into HttpContext — just accept it as a method parameter in your controllers and the framework will wire it up automatically.

When Things Go Wrong: Exception Handling in Tasks

Task.WhenAll collects exceptions from all tasks. If multiple fail, you only see the first one by default:

try
{
    await Task.WhenAll(t1, t2, t3);
}
catch (Exception ex)
{
    // Only the first exception
}

To inspect all failures:

var allTasks = Task.WhenAll(t1, t2, t3);
try
{
    await allTasks;
}
catch
{
    if (allTasks.Exception != null)
    {
        foreach (var inner in allTasks.Exception.InnerExceptions)
        {
            // handle each
        }
    }
}

It's verbose, but it's the correct way to handle partial failures in a parallel batch.

One More Thing: Don't Over-Async

Not everything needs to be async. A pure in-memory calculation, a simple property lookup, a fast synchronous transformation — adding async overhead to these things doesn't make them faster. It makes them slower, with more allocations and state machine noise.

Async shines when you're waiting on something external: a database, an HTTP call, a file, a message queue. That's the domain. Stay in it.

Wrapping Up

async/await in .NET is genuinely one of the best concurrency models in any mainstream language. But "best" doesn't mean "foolproof." The foot-guns are real: async void, blocking on tasks, ignoring cancellation, confusing concurrency with parallelism.

Get these right and your async code becomes a superpower. Get them wrong and you get subtle, nasty bugs that only show up when it matters most.

Go refactor something.

Forem: shayan holakouee

Python's AsyncIO Internals, What Actually Happens When You Write await

Coroutines Are Not Threads and Not Callbacks

What async def Actually Produces

What await Actually Does

The Event Loop Is a Scheduling Loop

Tasks vs Futures vs Coroutines

Blocking the Event Loop Is the Canonical Mistake

await and Custom Awaitables

Cancellation Is Cooperative

The Mental Model

Further Reading

Python's Data Model Is an API. Here Is How to Use It Properly

The Interpreter Calls These, Not You

Truthiness, Equality, and Hashing Are a Triangle

Comparison Operators and the Reflected Protocol

Arithmetic Operators and In-Place Variants

Attribute Access Is More Controllable Than You Think

The Container Protocol in Full

slots: Memory Layout as a Data Model Feature

The One Rule That Ties Everything Together

Further Reading

Python Metaclasses, What's Actually Happening When You Write class

Classes Are Instances of type

The Class Creation Protocol, Step by Step

Writing a Metaclass That Does Something Useful

new vs init in a Metaclass

prepare and Definition Order

Metaclass Conflict and the MRO Problem

init_subclass: The Metaclass You Did Not Have to Write

When a Metaclass Is Actually the Right Tool

Further Reading

The BEAM Is Not Like Other Runtimes (And That's Why Elixir Scales the Way It Does)

The BEAM Is Not the JVM With a Different Language

Processes Are Cheaper Than You Think

The Scheduler: Preemptive and Reduction-Based

Memory Isolation and Per-Process GC

How Message Passing Actually Works

Preemption vs Cooperation: The NIF Problem

The Scheduler's Relationship With IO

What This Means for How You Write Code

Further Reading

Rust's Zero-Cost Abstractions, What Monomorphization Actually Does to Your Code

The Problem Abstractions Usually Create

What Monomorphization Is

How Traits Fit Into This

The Actual Cost: Code Bloat and Compile Time

Static Dispatch vs Dynamic Dispatch

Where Monomorphization Gets Interesting: Trait Objects in Generic Contexts

The impl Trait Shorthand

Inspecting the Output

The Mental Model to Carry Forward

Further Reading

Python's Descriptor Protocol, The Feature Behind Everything You Use Daily

What a Descriptor Is

Data Descriptors vs Non-Data Descriptors

How Functions Become Methods

Writing a Real Descriptor: Typed Attributes

classmethod and staticmethod Are Just Descriptors

The Caching Descriptor Pattern

When to Actually Use This

Further Reading

The Go Memory Model, Why Your Concurrent Code Might Be Lying to

The Problem Is Not Timing, It Is Visibility

What Happens-Before Actually Means

What Actually Establishes Happens-Before in Go

The sync.WaitGroup Trap

When Atomic Is Not Enough

The Practical Mental Model

Further Reading

Minimal APIs in .NET Are Not a Toy, Start Treating Them That Way

The Setup That Doesn't Embarrass You in Code Review

Stop Putting Everything in Program.cs

Route Groups Are Underused

Validation Without the Ceremony

TypedResults Over Results Always

Error Handling: One Place, Not Everywhere

Performance: This Is Where Minimal APIs Win

When to Stick With Controllers

The Bottom Line