Any chance for engine to use request context callback (if set) to collect all cached contexts (and release them right after), while informing application that it should NOT create new contexts if pool is empty? Alternatively, 3rd callback function could be added - context pool cleanup - which tells application that any and all cached contexts should be released, no questions asked.

What it would solve?

If application decides to keep context pool as engine's userdata, cleanup callback might never be called. Cached context(s) holds reference to engine → engine's destructor is not called → userdata cleanup callback is not called. In short, if context pool is userdata, it can't be cleaned inside userdata cleanup function :>

Additionally,`ShutdownAndRelease` promise of taking care of cleaning up as much as possible would be closer to reality.

Full scenario as old-style test:

#include "utils.h"

#include <list>

struct UserData
{
    std::list<asIScriptContext*> ContextPool;
};

bool engineData = false;

void CallbackEngineUserData(asIScriptEngine* engine)
{
    UserData* data = static_cast<UserData*>(engine->SetUserData(nullptr, 0));
    for(asIScriptContext* ctx : data->ContextPool)
    {
        ctx->Release();
    }
    data->ContextPool.clear();

    delete data;

    engineData = true;
}

asIScriptContext* CallbackContextRequest(asIScriptEngine* engine, void*)
{
    asIScriptContext* context    = nullptr;
    UserData* engineData = static_cast<UserData*>( engine->GetUserData() );

    if( engineData->ContextPool.empty() )
        context = engine->CreateContext();
    else
    {
        context = engineData->ContextPool.front();
        engineData->ContextPool.pop_front();
    }

    return context;
}

void CallbackContextReturn(asIScriptEngine* engine, asIScriptContext* context, void*)
{
    UserData* engineData  = static_cast<UserData*>(engine->GetUserData());
    context->Unprepare();
    engineData->ContextPool.push_back( context );
}

bool TestContextPoolAsUserData()
{
    asIScriptEngine* engine = asCreateScriptEngine();

    engine->SetContextCallbacks(CallbackContextRequest, CallbackContextReturn, nullptr);
    engine->SetEngineUserDataCleanupCallback(CallbackEngineUserData);
    engine->SetUserData(new UserData);

    asIScriptContext* ctx = engine->RequestContext();
    engine->ReturnContext(ctx);

    engine->ShutDownAndRelease();

    // validate

    if(!engineData)
    {
        PRINTF("TestContextPoolAsUserData: context pool leak\n");
        return true; // true = fail
    }

    return false;
}

You don't have to worry about memory leaks on a program that has exited. All memory the program was using is reallocated back to the OS after program has closed.

Write a function called HARD_CRASH(); and when the exit key is pressed, call it. ?

I'll have to think about this, but it seems to me that cleaning up the context pool before calling ShutDownAndRelease is the correct option. Not to create a separate callback for this specific case.

You wouldn't reduce any code by doing this clean-up from a callback called by the engine upon ShutDownAndRelease anyway. Both the engine and the application would need a bit more code than what you already have.

Maybe I can move the cleanup of engine's user data to the ShutDownAndRelease method so it happens even if there might still be some references holding on to the engine somewhere else.

WitchLord said:

(…) cleaning up the context pool before calling ShutDownAndRelease is the correct option.

Maybe docs could mention that somewhere near context pool example then? ?

“Application is responsible for cleaning up the context pool before shutting down engine” would make it bit more clear that userdata cleanup callback is not a good place for that.