Function prepare_container

ci/docker_utils/container_db.py:496–583

Prepare a container for use, ensuring clean state. This function implements the pre-run phase: 1. Checks if container name already exists in DB 2. If owner process is alive, raises error (container in use) 3. If owner process is dead, cleans up orphaned container 4. Removes any

(
    container_name: str,
    image_name: str,
    create_container_fn: Callable[[], str],
    db: Optional[ContainerDatabase] = None,
    config_hash: str = "",
    platform_type: str = "",
)

def prepare_container(
    container_name: str,
    image_name: str,
    create_container_fn: Callable[[], str],
    db: Optional[ContainerDatabase] = None,
    config_hash: str = "",
    platform_type: str = "",
) -> tuple[str, bool]:
    """Prepare a container for use, ensuring clean state.

    This function implements the pre-run phase:
    1. Checks if container name already exists in DB
    2. If owner process is alive, raises error (container in use)
    3. If owner process is dead, cleans up orphaned container
    4. Removes any untracked Docker containers with same name
    5. Creates fresh container using provided function
    6. Registers container in database

    Args:
        container_name: Name for the container
        image_name: Docker image name to use
        create_container_fn: Callable that creates and starts container, returns container ID
        db: Database instance (creates new if None)

    Returns:
        Tuple of (container_id, was_cleaned) where was_cleaned indicates if cleanup occurred

    Raises:
        RuntimeError: If container is already in use by another process
    """
    if db is None:
        db = ContainerDatabase()

    current_pid = os.getpid()
    was_cleaned = False

    # Check if container name already exists in DB
    existing = db.get_by_name(container_name)

    if existing:
        # Check if owner process is still alive
        if process_exists(existing.owner_pid):
            # Owner is alive - cannot proceed
            raise RuntimeError(
                f"Container '{container_name}' is already in use by PID {existing.owner_pid}. "
                f"Stop that process first or wait for it to complete.\n\n"
                f"To force cleanup:\n"
                f"  kill {existing.owner_pid}\n"
                f"  OR\n"
                f"  uv run python -m ci.docker.cleanup_orphans"
            )
        else:
            # Owner is dead - orphaned container, clean it up
            print(
                f"Cleaning up orphaned container from dead process {existing.owner_pid}"
            )
            success, error_msg = docker_force_remove_container(existing.container_id)
            if not success: