[mathieucarbou]

Summary

Give users full control over where handler objects live in memory (internal SRAM, PSRAM, static RAM) without allocator hooks or operator new overrides. This is a refactoring approach discussed in #468 as an alternative to the operator new override proposal.

Motivation

On ESP32 targets with PSRAM, internal SRAM is often the scarcest resource (lwIP segments, WiFi buffers, WS message queues all live there). Handler objects are long-lived: created once at setup, only read during request dispatch — never from ISR/DMA context. Moving them out of internal SRAM frees memory for networking.

API Changes

Handler registration

Call	Ownership
server.addHandler(new MyHandler())	Server owns (default, backward compatible)
server.addHandler(ptr, false)	Non-owning (pointer)
server.addHandler(myHandler)	Non-owning (reference)

Catch-all handler

Call	Ownership
AsyncWebServer server(80)	Server creates & owns default catch-all
AsyncWebServer server(80, catchAllPtr)	Server owns
AsyncWebServer server(80, catchAllPtr, false)	Non-owning (pointer)
AsyncWebServer server(80, catchAllRef)	Non-owning (reference)
AsyncWebServer server(80, nullptr)	No catch-all (unmatched → bare 501)
server.setCatchAllHandler(new ...())	Server owns (default)
server.setCatchAllHandler(ptr, false)	Non-owning (pointer)
server.setCatchAllHandler(ref)	Non-owning (reference)
server.setCatchAllHandler(nullptr)	Remove catch-all entirely

Safe accessor

Call	Behavior
server.catchAllHandlerPtr()	Returns pointer or nullptr — safe
server.catchAllHandler()	Deprecated — crashes if no catch-all installed

Usage Examples

Static RAM (no heap allocation)

static AsyncCallbackWebHandler handler;
handler.setUri(AsyncURIMatcher::exact("/status"));
handler.onRequest([](AsyncWebServerRequest *req) { req->send(200, "text/plain", "OK"); });
server.addHandler(handler);  // non-owning

PSRAM (ESP32)

#include <esp_heap_caps.h>

void *mem = heap_caps_malloc(sizeof(AsyncCallbackWebHandler), MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT);
auto *handler = new (mem) AsyncCallbackWebHandler();
handler->setUri(AsyncURIMatcher::exact("/status"));
handler->onRequest([](AsyncWebServerRequest *req) { req->send(200, "text/plain", "OK"); });
server.addHandler(handler, false);  // non-owning

Custom catch-all at construction

static AsyncCallbackWebHandler catchAll;
AsyncWebServer server(80, catchAll);  // non-owning, static RAM

Design Decisions

• No operator new override — avoids non-conforming C++ semantics (returning null instead of throwing std::bad_alloc)
• No build flags — purely additive API, zero risk to existing users
• No allocator hooks — users control allocation via placement new, static storage, or any custom strategy
• Explicit ownership model — HandlerEntry struct with unique_ptr for owned handlers, raw pointer for non-owned
• Works for all handler types — AsyncCallbackWebHandler, AsyncStaticWebHandler, AsyncWebSocket, AsyncEventSource, AsyncCallbackJsonWebHandler, and user-defined subclasses

Backward Compatibility

✅ 100% additive — all existing code compiles and runs identically:

• server.addHandler(new T()) — unchanged (ownership transfer)
• server.on(), serveStatic(), onNotFound(), onFileUpload(), onRequestBody() — unchanged
• AsyncWebServer(port) — unchanged (creates default owned catch-all)
• All existing examples compile without modification

Files Changed

File	Change
src/ESPAsyncWebServer.h	HandlerEntry struct, new constructors, addHandler overloads, setCatchAllHandler, catchAllHandlerPtr
src/WebServer.cpp	Implementation of all new APIs, null guards for catch-all
examples/arduino/CustomAllocation/CustomAllocation.ino	New example: static RAM, PSRAM, server-owned, custom catch-all
examples/arduino/SkipServerMiddleware/SkipServerMiddleware.ino	Migrated to catchAllHandlerPtr()
docs/routing.md	Handler Ownership and Memory Placement section
docs/configuration.md	PSRAM and static allocation section
docs/concepts.md	Handler ownership note
platformio.ini	CustomAllocation example entry

Related

• Closes discussion in feat: opt-in ASYNCWEBSERVER_USE_PSRAM - allocate handler objects in PSRAM (ESP32) #468 (alternative approach to the proposed ASYNCWEBSERVER_USE_PSRAM build flag)
• Addresses concerns raised by @willmmiles and @mathieucarbou about scope, C++ conformance, and API design

Checklist

• Fully backward compatible
• Compiles on host emulator (Arduino-Emulator + CMake)
• New example follows existing conventions (AP mode, ASYNCWEBSERVER_WIFI_SUPPORTED guards)
• Documentation updated (routing.md, configuration.md, concepts.md)
• Existing SkipServerMiddleware example migrated to safe API

[mathieucarbou]

Roadmap: Phase 2 (follow-up PR)

This PR implements Phase 1 — non-owning handler registration that gives users full control over handler allocation (static RAM, PSRAM, internal heap).

A follow-up PR will implement Phase 2 — a route table refactoring that moves URI matching out of handler objects into the server's routing table. This will enable:

• One handler object serving multiple routes (e.g. same handler for /foo and /bar)
• Decoupled route configuration from handler construction
• Cleaner separation of concerns between routing and request handling

Phase 2 is a larger, deeper refactoring and is intentionally kept separate to:

1. Ship Phase 1 quickly — it already solves the PSRAM allocation problem completely
2. Battle-test the ownership model before changing internal dispatch logic
3. Keep this PR reviewable and low-risk

Phase 1 is fully functional on its own — Phase 2 is purely additive on top.

[willmmiles]

A good extension, I think we can tighten up the implementation a bit.

[willmmiles]

We shouldn't be accepting a bool here. You've declared another, better API for non-owning binding: the reference form. Passing a reference is the C++ standard way of indicating a borrow. I don't think we should have two different ways to request a borrow instead of an adopt.

This is true even if you've manually heap allocated the object - using the reference form makes it 100% clear that the user is responsible for managing the life cycle of their object. Having to pass addHandler(*heap_handler) isn't a huge burden.

Last but not least - it may be worth noting that, on ESP32, regular delete does work on any object allocated with heap_caps_malloc(). This is because delete maps to free() which in turn maps to heap_caps_free(), which looks up the pool from the address.

[willmmiles]

Maybe I should suggest that ESP-IDF add operator new C++ extensions for heap_caps_malloc.

namespace esp {
struct with_heap_caps_t { 
    uint32_t flags;
    explicit constexpr with_heap_caps_t (uint32_t allocator_id) : id(allocator_id) {}
}

inline constexpr with_heap_caps_t with_heap_caps(uint32_t id) {
    return with_heap_caps(id);
}

// Some helpful constants
constexpr with_heap_caps_t in_psram {  MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT };
// ...
};

void* operator new(std::size_t size, const esp::with_heap_caps_t& alloc) {
    void* ptr = heap_caps_malloc(size, alloc.flags);
    if (!ptr) throw std::bad_alloc;
    return ptr; 
}

void operator delete(void* ptr, const esp::with_heap_caps_t& alloc) noexcept {
    heap_caps_free(ptr);
}

Usage:

auto* psram_obj = new (esp::with_heap_caps(MALLOC_CAP_SPIRAM | MALLOC_CAP_8BIT)) obj();
auto* psram_obj_convenient = new (esp::in_psram) obj();

It'd sure look cleaner, and makes it clearly and explicitly safe to delete.

[mathieucarbou]

This is because delete maps to free()

I didn't know that! I always though we had to use free() with malloc() and delete with new because malloc just allocates space when new also creates the object (constructor).

[willmmiles]

This is one of these general vs specific platform things. In the general case, the implementation of C++ new and delete is not required to have any relationship to C's malloc() and free(). In the specific case of Espressif's implementation, they run GNU libstdc++, which maps new to malloc(). malloc(), in turn, is actually a wrapper around heap_caps_malloc() in ESP-IDF libc.

So it'll work, technically, on ESP32 - there's just no guarantees on any other platform.

[mathieucarbou]

@willmmiles : comments addressed.
I didn't know about the convention about ref meaning borrowed (this is just so evident) but more importantly pointer being owned.
I came across a LOT of libraries that are doing the opposite: accepting pointers but they borrow, not own and caller is still responsible for the lifecycle.
I think that everyone should stick to this convention.

[willmmiles]

@willmmiles : comments addressed. I didn't know about the convention about ref meaning borrowed (this is just so evident) but more importantly pointer being owned. I came across a LOT of libraries that are doing the opposite: accepting pointers but they borrow, not own and caller is still responsible for the lifecycle. I think that everyone should stick to this convention.

It's definitely a "modern C++"-ism. Actually for "best practices" C++, passing a naked pointer is also typically non-owning, it differs from a reference only in that it permits nullptr if sending no object is a meaningful thing to do. Ownership is best passed directly with explicit usages of unique_ptr for single ownership or shared_ptr for shared ownership. Or, best of all, passing objects by value (ie. user std::move()s if they want to gift it). That lets the compiler check at build time instead of needing to validate non-emptiness at runtime.

In the case of this library, though, we have to support the existing interface; so IMO the next best thing is to treat naked pointers as a move (as this library has always done) and add a C++ reference interface for a borrow. And of course our users might want to keep a reference to the active object themselves, so we can't always accept them by value.

[mathieucarbou]

@willmmiles new comments addressed ;-)

[mathieucarbou]

In the case of this library, though, we have to support the existing interface; so IMO the next best thing is to treat naked pointers as a move (as this library has always done) and add a C++ reference interface for a borrow. And of course our users might want to keep a reference to the active object themselves, so we can't always accept them by value.

Thinking about that again... I am not a fan of the server taking ownership of the handler pointer if passed as an argument. If a pointer is passed as an argument it should means that its lifecycle is broader than the library using it. This should be up to the user to delete, not the library. Also, looking at the API, we don't have any use case in the lib where an object could be passed as a pointer with the library taking ownership. For middleware, rewrite and handlers, pointers passed do no become owned by the lib.

The only exceptions are the response object passed in the request because its scope is longer than the callback itself, and the internally created objects like the default catch all hander.

[willmmiles]

Thinking about that again... I am not a fan of the server taking ownership of the handler pointer if passed as an argument.

Neither am I, really, but that's the current API - it'd be a breaking change to the interface to do otherwise. (One could argue it's somewhat moot because few if any users destroy AsyncServer objects... but technically the current code takes ownership.)

[mathieucarbou]

In the case of this library, though, we have to support the existing interface; so IMO the next best thing is to treat naked pointers as a move (as this library has always done) and add a C++ reference interface for a borrow. And of course our users might want to keep a reference to the active object themselves, so we can't always accept them by value.

Thinking about that again... I am not a fan of the server taking ownership of the handler pointer if passed as an argument. If a pointer is passed as an argument it should means that its lifecycle is broader than the library using it. This should be up to the user to delete, not the library. ~~Also, looking at the API, we don't have any use case in the lib where an object could be passed as a pointer with the library taking ownership. For middleware, rewrite and handlers, pointers passed do no become owned by the lib. ~~

The only exceptions are the response object passed in the request because its scope is longer than the callback itself, and the internally created objects like the default catch all hander.

@willmmiles: My error: addHandler was moving the pointer to a unique_ptr so the handler was destroyed by the lib...

for rewrites, that's put in a shard ptr...

There is no consistency at all in our lib around pointer management, that is so ugly!

So let's keep the PR as-is, but do you think we have to fix others ?

in summary:

• ✅ catchAllHandler with pointer => adopted
• ❓ addRewrite with pointer => moved to a shared ptr (why ???) shouldn't it be a unique ptr also ? the shared_ptr is anyway not used!

I have checked the code, and here is what it was doing initially:

AsyncWebServer::~AsyncWebServer(){
  while(_rewrites != NULL){
    AsyncWebRewrite *r = _rewrites;
    _rewrites = r->next;
    delete r;
  }

So the lib had always adopted the rewrite ptr, but I dont understand why it is put in a shared_ptr instead of a unique ptr ?

[willmmiles]

So the lib had always adopted the rewrite ptr, but I dont understand why it is put in a shared_ptr instead of a unique ptr ?

The most common reason is someone still learning how to use unique_ptr. There are a lot of ways you can find yourself inadvertently attempting to copy-construct or assign, where unique_ptr errors out; switching to shared_ptr makes the compiler stop complaining.

I do think that's worth cleaning up, but I'd classify it as out of scope for this PR - it can be handled separately.

[mathieucarbou]

@willmmiles thanks! Were you able to look at the last fixes ? Let me know when if can merge :-)