Principle:CARLA simulator Carla Actor Lifecycle Cleanup

Knowledge Sources	CARLA Simulator CARLA Documentation
Domains	Simulation Resource Management, Actor Lifecycle
Last Updated	2026-02-15 00:00 GMT

Overview

Actor lifecycle cleanup is the disciplined process of stopping, unregistering, and destroying simulation actors and their associated subsystem registrations to prevent resource leaks and ensure stable long-running simulations.

Description

In a traffic generation workflow, the simulation creates many actors: NPC vehicles, pedestrian walkers, walker AI controllers, and sensors. Each of these actors consumes server-side resources including:

• Memory -- Physics state, mesh data, transform history
• CPU cycles -- Physics updates, AI processing, rendering
• Subsystem registrations -- Traffic Manager vehicle lists, crowd simulation agent slots, sensor callback queues

Proper cleanup requires more than simply deleting actors. Each actor type has specific cleanup requirements:

Vehicle Cleanup

Vehicles registered with the Traffic Manager must be unregistered before destruction. The TM maintains internal data structures (path buffers, collision caches, PID controller states) for each managed vehicle. Destroying a vehicle without unregistering it can leave orphaned entries in these structures.

The cleanup sequence for vehicles:

1. Disable autopilot (vehicle.set_autopilot(False)) or let the destroy command handle it
2. Destroy the vehicle actor

Walker Cleanup

Walkers with AI controllers require a two-step cleanup:

1. Stop the AI controller (unregisters the walker from the Detour crowd simulation)
2. Destroy the AI controller actor
3. Destroy the walker actor

Destroying a walker without first stopping its controller leaves a dangling agent in the crowd simulation, which can cause crashes or undefined behavior on subsequent ticks.

Batch Cleanup

For efficiency, cleanup of many actors should use the batch command system (DestroyActor commands via apply_batch). This mirrors the batch spawning pattern and ensures all actors are removed in a single server round-trip.

Usage

Perform cleanup when:

• A traffic scenario ends and you need to reset the simulation
• The script is interrupted (use try/finally blocks)
• Transitioning between different traffic configurations
• The simulation is shutting down

Theoretical Basis

Resource Lifecycle Pattern

Actor lifecycle management follows the RAII (Resource Acquisition Is Initialization) pattern, adapted for a client-server architecture:

Actor Lifecycle:
    ACQUIRE:
        1. Construct blueprint (template)
        2. Spawn actor (server allocates resources)
        3. Register with subsystems (TM, crowd sim, etc.)
        4. Actor is now ACTIVE

    USE:
        5. Actor participates in simulation ticks
        6. Configuration may change (speed, destination, etc.)

    RELEASE:
        7. Unregister from subsystems (stop controllers, disable autopilot)
        8. Destroy actor (server frees resources)
        9. Remove client-side references

Cleanup Ordering Constraints

The cleanup order is critical due to dependency relationships between actors:

Dependency Graph:
    WalkerAIController --> Walker (controller depends on walker)
    Vehicle --> TrafficManager (TM holds references to vehicle)

Correct Cleanup Order:
    1. Stop WalkerAIControllers (unregister from crowd sim)
    2. Destroy WalkerAIControllers (remove controller actors)
    3. Destroy Walkers (remove walker actors)
    4. Destroy Vehicles (TM automatically unregisters destroyed vehicles)

Incorrect Order (causes issues):
    - Destroy Walker before stopping its Controller
      => Controller references invalid actor, potential crash
    - Destroy all actors without stopping controllers
      => Crowd sim has dangling agent references

Defensive Cleanup Pattern

Robust traffic scripts use a try/finally pattern to guarantee cleanup even if exceptions occur:

vehicles = []
walkers = []
controllers = []

try:
    # Spawn and configure traffic...
    vehicles = spawn_vehicles(...)
    walkers, controllers = spawn_walkers(...)

    # Run simulation loop...
    while running:
        world.tick()

finally:
    # Guaranteed cleanup
    for controller in controllers:
        controller.stop()

    destroy_batch = []
    destroy_batch.extend([DestroyActor(c) for c in controllers])
    destroy_batch.extend([DestroyActor(w) for w in walkers])
    destroy_batch.extend([DestroyActor(v) for v in vehicles])
    client.apply_batch(destroy_batch)

    # Restore world settings if modified
    world.apply_settings(original_settings)

Memory Leak Prevention

Without proper cleanup, each run of a traffic script accumulates actors on the server. Over multiple script restarts:

Run	Spawned	Destroyed	Leaked	Total Server Actors
1	200	0	200	200
2	200	0	200	400
3	200	0	200	600

This leads to progressive performance degradation and eventual server crash. The cleanup pattern prevents this accumulation.

Related Pages

Implemented By

• Implementation:CARLA_simulator_Carla_Command_DestroyActor