Repository: ray-project/ray
File: python/ray/data/_internal/execution/interfaces/executor.py (Python)

Code before:
        StreamingExecutor
    """

    def __init__(self, options: ExecutionOptions):
        """Create the executor."""
        options.validate()
        self._options = options

    @abstractmethod
    def execute(
        self,
        dag: PhysicalOperator,
        initial_stats: Optional[DatasetStats] = None,
        callbacks: Optional[List] = None,
    ) -> OutputIterator:
        """Start execution.

        Args:
            dag: The operator graph to execute.
            initial_stats: The DatasetStats to prepend to the stats returned by the
                executor. These stats represent actions done to compute inputs.
            callbacks: List of ExecutionCallbacks to invoke during execution. Should
                be constructed eagerly (via ``get_execution_callbacks``) immediately
                before calling this method so that any callbacks added after executor
                construction (e.g. checkpointing) are included. The list reference is
                retained directly; do not pass a throwaway ``[]`` literal.
        """
        ...

    def shutdown(self, force: bool, exception: Optional[Exception] = None):
        """Shutdown an executor, which may still be running.

        This should interrupt execution and clean up any used resources.

        Args:
            force: Controls whether shutdown should forcefully terminate all execution
                   activity (making sure that upon returning from this method all
                   activities are stopped). When force=False, some activities could be
                   terminated asynchronously (ie this method won't provide guarantee
                   that they stop executing before returning from this method)
            exception: The exception that causes the executor to shut down, or None if
                the executor finishes successfully.
        """
        pass

    @abstractmethod
    def get_stats(self) -> DatasetStats:
        """Return stats for the execution so far.

        This is generally called after `execute` has completed, but may be called
        while iterating over `execute` results for streaming execution.

Review comment (suggestion):
"The list reference is retained directly; do not pass a throwaway ``[]`` literal." What does this mean in simple English? I didn't understand

Code after:
        StreamingExecutor
    """

    def __init__(self, options: ExecutionOptions):
        """Create the executor."""
        options.validate()
        self._options = options

    @abstractmethod
    def execute(
        self,
        dag: PhysicalOperator,
        initial_stats: Optional[DatasetStats] = None,
        callbacks: Optional[List] = None,
    ) -> OutputIterator:
        """Start execution.

        Args:
            dag: The operator graph to execute.
            initial_stats: The DatasetStats to prepend to the stats returned by the
                executor. These stats represent actions done to compute inputs.
            callbacks: A list of ExecutionCallbacks to run during execution.
                Create this list right before calling this method (for example,
                using ``get_execution_callbacks``) so that any callbacks added
                after the executor was created (such as checkpointing) are included.
                This method keeps and uses the exact list you pass in, so do not
                pass an empty list like ``[]`` directly. Create the list first,
                then pass it.
        """
        ...

    def shutdown(self, force: bool, exception: Optional[Exception] = None):
        """Shutdown an executor, which may still be running.

        This should interrupt execution and clean up any used resources.

        Args:
            force: Controls whether shutdown should forcefully terminate all execution
                   activity (making sure that upon returning from this method all
                   activities are stopped). When force=False, some activities could be
                   terminated asynchronously (ie this method won't provide guarantee
                   that they stop executing before returning from this method)
            exception: The exception that causes the executor to shut down, or None if
                the executor finishes successfully.
        """
        pass

    @abstractmethod
    def get_stats(self) -> DatasetStats:
        """Return stats for the execution so far.