Una guía para Skyframe StateMachines

Informar un problema Ver fuente Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Descripción general

Un StateMachine de Skyframe es un objeto de función deconstruido que reside en el montón. Admite flexibilidad y evaluación sin redundancia¹ cuando los valores necesarios no están disponibles de inmediato, pero se calculan de forma asíncrona. StateMachine no puede vincular un recurso de subproceso mientras espera, sino que debe suspenderse y reanudarse. Por lo tanto, la deconstrucción expone puntos de reentrada explícitos para que se puedan omitir los cálculos anteriores.

Los StateMachine se pueden usar para expresar secuencias, ramificaciones y concurrencia lógica estructurada, y se adaptan específicamente para la interacción con Skyframe. Los StateMachine se pueden componer en StateMachine más grandes y compartir subStateMachine. La simultaneidad siempre es jerárquica por construcción y puramente lógica. Cada subtarea simultánea se ejecuta en el único subproceso superior compartido de SkyFunction.

Introducción

En esta sección, se motivan y presentan brevemente los StateMachine, que se encuentran en el paquete java.com.google.devtools.build.skyframe.state.

Una breve introducción a los reinicios de Skyframe

Skyframe es un framework que realiza evaluaciones paralelas de grafos de dependencias. Cada nodo del gráfico corresponde a la evaluación de una SkyFunction con una SkyKey que especifica sus parámetros y SkyValue que especifica su resultado. El modelo computacional es tal que una SkyFunction puede buscar SkyValues por SkyKey, lo que activa una evaluación recursiva y paralela de SkyFunctions adicionales. En lugar de bloquear, lo que ataría un subproceso, cuando un SkyValue solicitado aún no está listo porque algún subgrafo de procesamiento está incompleto, la SkyFunction solicitante observa una respuesta getValue null y debe mostrar null en lugar de un SkyValue, lo que indica que está incompleto debido a que faltan entradas. Skyframe reinicia las SkyFunctions cuando todos los SkyValues solicitados anteriormente están disponibles.

Antes de la introducción de SkyKeyComputeState, la forma tradicional de controlar un reinicio era volver a ejecutar el procesamiento por completo. Aunque esto tiene una complejidad cuadrática, las funciones escritas de esta manera se completan con el tiempo porque, con cada nueva ejecución, menos búsquedas muestran null. Con SkyKeyComputeState, es posible asociar datos de puntos de control especificados de forma manual con una SkyFunction, lo que ahorra recomputación significativa.

Los StateMachine son objetos que viven dentro de SkyKeyComputeState y eliminan prácticamente todo el procesamiento cuando se reinicia una SkyFunction (suponiendo que SkyKeyComputeState no salga de la caché) exponiendo hooks de ejecución de suspensión y reanudación.

Cálculos con estado dentro de SkyKeyComputeState

Desde el punto de vista del diseño orientado a objetos, tiene sentido considerar almacenar objetos computacionales dentro de SkyKeyComputeState en lugar de valores de datos puros. En Java, la descripción mínima de un objeto portador de comportamiento es una interfaz funcional y resulta suficiente. Un StateMachine tiene la siguiente definición, curiosamente recursiva².

@FunctionalInterface
public interface StateMachine {
  StateMachine step(Tasks tasks) throws InterruptedException;
}

La interfaz Tasks es análoga a SkyFunction.Environment, pero está diseñada para la asíncrona y agrega compatibilidad con subtareas simultáneas de forma lógica.³

El valor que se muestra de step es otro StateMachine, lo que permite especificar una secuencia de pasos de forma inductiva. step muestra DONE cuando se completa StateMachine. Por ejemplo:

class HelloWorld implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    System.out.println("hello");
    return this::step2;  // The next step is HelloWorld.step2.
  }

  private StateMachine step2(Tasks tasks) {
     System.out.println("world");
     // DONE is special value defined in the `StateMachine` interface signaling
     // that the computation is done.
     return DONE;
  }
}

describe un StateMachine con el siguiente resultado.

hello
world

Ten en cuenta que la referencia del método this::step2 también es un StateMachine debido a que step2 cumple con la definición de la interfaz funcional de StateMachine. Las referencias de métodos son la forma más común de especificar el siguiente estado en un StateMachine.

De manera intuitiva, desglosar un cálculo en pasos StateMachine, en lugar de una función monolítica, proporciona los hooks necesarios para suspender y reanudar un cálculo. Cuando se muestra StateMachine.step, hay un punto de suspensión explícito. La Continuation especificada por el valor StateMachine que se muestra es un punto de reanudación explícito. Por lo tanto, se puede evitar el procesamiento nuevamente, ya que el procesamiento se puede reanudar exactamente donde se detuvo.

Devoluciones de llamada, continuaciones y procesamiento asíncrono

En términos técnicos, un StateMachine funciona como una continuación y determina el cálculo posterior que se ejecutará. En lugar de bloquear, un StateMachine puede suspenderse de forma voluntaria si se muestra la función step, que transfiere el control a una instancia de Driver. Luego, Driver puede cambiar a un StateMachine listo o ceder el control a Skyframe.

Tradicionalmente, las devoluciones de llamada y las continuaciones se combinan en un solo concepto. Sin embargo, los objetos StateMachine mantienen una distinción entre los dos.

• Devolución de llamada: Describe dónde almacenar el resultado de un procesamiento asíncrono.
• Continuation: Especifica el siguiente estado de ejecución.

Las devoluciones de llamada son obligatorias cuando se invoca una operación asíncrona, lo que significa que la operación real no se produce inmediatamente después de llamar al método, como en el caso de una búsqueda de SkyValue. Las devoluciones de llamada deben ser lo más sencillas posible.

Precaución: Un error común de las devoluciones de llamada es que el procesamiento asíncrono debe garantizar que se llame a la devolución de llamada al final de cada ruta de acceso alcanzable. Es posible pasar por alto algunas ramas, y el compilador no muestra advertencias sobre esto.

Las Continuations son los valores que se muestran de StateMachine de StateMachine y encapsulan la ejecución compleja que sigue una vez que se resuelven todos los cálculos asíncronos. Este enfoque estructurado ayuda a mantener la complejidad de las devoluciones de llamada manejable.

Tasks

La interfaz Tasks proporciona a los StateMachine una API para buscar SkyValues por SkyKey y programar subtareas simultáneas.

interface Tasks {
  void enqueue(StateMachine subtask);

  void lookUp(SkyKey key, Consumer<SkyValue> sink);

  <E extends Exception>
  void lookUp(SkyKey key, Class<E> exceptionClass, ValueOrExceptionSink<E> sink);

  // lookUp overloads for 2 and 3 exception types exist, but are elided here.
}

Sugerencia: Cuando cualquier estado usa la interfaz de Tasks para realizar búsquedas o crear subtareas, esas búsquedas y subtareas se completarán antes de que comience el siguiente estado.

Sugerencia: (corolario) Si las subtareas son StateMachine complejas o crean subtareas de forma recurrente, todas transitivamente se completan antes de que comience el siguiente estado.

Búsquedas de SkyValue

Los objetos StateMachine usan sobrecargas de Tasks.lookUp para buscar SkyValues. Son análogos a SkyFunction.Environment.getValue y SkyFunction.Environment.getValueOrThrow, y tienen una semántica de control de excepciones similar. La implementación no realiza la búsqueda de inmediato, sino que agrupa⁴ tantas búsquedas como sea posible antes de hacerlo. Es posible que el valor no esté disponible de inmediato, por ejemplo, que requiera un reinicio de Skyframe, por lo que el llamador especifica qué hacer con el valor resultante mediante una devolución de llamada.

El procesador StateMachine (Driver y el modo puente a SkyFrame) garantiza que el valor esté disponible antes de que comience el siguiente estado. A continuación, se muestra un ejemplo.

class DoesLookup implements StateMachine, Consumer<SkyValue> {
  private Value value;

  @Override
  public StateMachine step(Tasks tasks) {
    tasks.lookUp(new Key(), (Consumer<SkyValue>) this);
    return this::processValue;
  }

  // The `lookUp` call in `step` causes this to be called before `processValue`.
  @Override  // Implementation of Consumer<SkyValue>.
  public void accept(SkyValue value) {
    this.value = (Value)value;
  }

  private StateMachine processValue(Tasks tasks) {
    System.out.println(value);  // Prints the string representation of `value`.
    return DONE;
  }
}

En el ejemplo anterior, el primer paso busca new Key() y pasa this como consumidor. Eso es posible porque DoesLookup implementa Consumer<SkyValue>.

Sugerencia: Cuando se pasa this como un receptor de valores, es útil para los lectores elevarlo al tipo de receptor para reducir el propósito de pasar this. En el ejemplo, se pasa (Consumer<SkyValue>) this.

Por contrato, antes de que comience el siguiente estado DoesLookup.processValue, se completan todas las búsquedas de DoesLookup.step. Por lo tanto, value está disponible cuando se accede a él en processValue.

Subtareas

Tasks.enqueue solicita la ejecución de subtareas simultáneas de forma lógica. Las subtareas también son StateMachine y pueden hacer lo mismo que las StateMachine normales, como crear más subtareas de forma recurrente o buscar SkyValues. Al igual que lookUp, el controlador de la máquina de estados se asegura de que todas las subtareas se completen antes de pasar al siguiente paso. A continuación, se incluye un ejemplo.

class Subtasks implements StateMachine {
  private int i = 0;

  @Override
  public StateMachine step(Tasks tasks) {
    tasks.enqueue(new Subtask1());
    tasks.enqueue(new Subtask2());
    // The next step is Subtasks.processResults. It won't be called until both
    // Subtask1 and Subtask 2 are complete.
    return this::processResults;
  }

  private StateMachine processResults(Tasks tasks) {
    System.out.println(i);  // Prints "3".
    return DONE;  // Subtasks is done.
  }

  private class Subtask1 implements StateMachine {
    @Override
    public StateMachine step(Tasks tasks) {
      i += 1;
      return DONE;  // Subtask1 is done.
    }
  }

  private class Subtask2 implements StateMachine {
    @Override
    public StateMachine step(Tasks tasks) {
      i += 2;
      return DONE;  // Subtask2 is done.
    }
  }
}

Aunque Subtask1 y Subtask2 son lógicamente simultáneos, todo se ejecuta en un solo subproceso, por lo que la actualización "simultánea" de i no necesita ninguna sincronización.

Simultaneidad estructurada

Dado que cada lookUp y enqueue deben resolverse antes de avanzar al siguiente estado, significa que la simultaneidad se limita naturalmente a las estructuras de árbol. Es posible crear simultaneidad jerárquica⁵, como se muestra en el siguiente ejemplo.

Es difícil saber a partir del UML que la estructura de simultaneidad forma un árbol. Hay una vista alternativa que muestra mejor la estructura del árbol.

La simultaneidad estructurada es mucho más fácil de entender.

Patrones de composición y flujo de control

En esta sección, se presentan ejemplos de cómo se pueden componer varios StateMachine y soluciones a ciertos problemas de flujo de control.

Estados secuenciales

Este es el patrón de flujo de control más común y sencillo. Un ejemplo de esto se muestra en Cálculos con estado dentro de SkyKeyComputeState.

Ramificación

Los estados de ramificación en StateMachine se pueden lograr devolviendo diferentes valores con el flujo de control de Java normal, como se muestra en el siguiente ejemplo.

class Branch implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    // Returns different state machines, depending on condition.
    if (shouldUseA()) {
      return this::performA;
    }
    return this::performB;
  }
  …
}

Es muy común que ciertas ramas devuelvan DONE para una finalización anticipada.

Composición secuencial avanzada

Dado que la estructura de control de StateMachine no tiene memoria, compartir definiciones de StateMachine como subtareas a veces puede ser incómodo. Supongamos que M₁ y M₂ son instancias StateMachine que comparten un StateMachine, S, y M₁ y M₂ son las secuencias <A, S, B> y <X, S, Y> respectivamente. El problema es que S no sabe si continuar con B o Y después de que se complete, y los StateMachine no mantienen una pila de llamadas. En esta sección, se revisan algunas técnicas para lograrlo.

StateMachine como elemento de secuencia terminal

Esto no resuelve el problema planteado inicial. Solo demuestra la composición secuencial cuando el StateMachine compartido es la terminal de la secuencia.

// S is the shared state machine.
class S implements StateMachine { … }

class M1 implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    performA();
    return new S();
  }
}

class M2 implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    performX();
    return new S();
  }
}

Esto funciona incluso si S es una máquina de estados compleja.

Subtarea para la composición secuencial

Dado que se garantiza que las subtareas en cola se completen antes del siguiente estado, a veces es posible abusar un poco⁶ del mecanismo de subtareas.

class M1 implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    performA();
    // S starts after `step` returns and by contract must complete before `doB`
    // begins. It is effectively sequential, inducing the sequence < A, S, B >.
    tasks.enqueue(new S());
    return this::doB;
  }

  private StateMachine doB(Tasks tasks) {
    performB();
    return DONE;
  }
}

class M2 implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    performX();
    // Similarly, this induces the sequence < X, S, Y>.
    tasks.enqueue(new S());
    return this::doY;
  }

  private StateMachine doY(Tasks tasks) {
    performY();
    return DONE;
  }
}

Inyección de runAfter

A veces, es imposible abusar de Tasks.enqueue porque hay otras subtareas en paralelo o llamadas a Tasks.lookUp que se deben completar antes de que se ejecute S. En este caso, se puede usar la inserción de un parámetro runAfter en S para informarle a S qué hacer a continuación.

class S implements StateMachine {
  // Specifies what to run after S completes.
  private final StateMachine runAfter;

  @Override
  public StateMachine step(Tasks tasks) {
    … // Performs some computations.
    return this::processResults;
  }

  @Nullable
  private StateMachine processResults(Tasks tasks) {
    … // Does some additional processing.

    // Executes the state machine defined by `runAfter` after S completes.
    return runAfter;
  }
}

class M1 implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    performA();
    // Passes `this::doB` as the `runAfter` parameter of S, resulting in the
    // sequence < A, S, B >.
    return new S(/* runAfter= */ this::doB);
  }

  private StateMachine doB(Tasks tasks) {
    performB();
    return DONE;
  }
}

class M2 implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks) {
    performX();
    // Passes `this::doY` as the `runAfter` parameter of S, resulting in the
    // sequence < X, S, Y >.
    return new S(/* runAfter= */ this::doY);
  }

  private StateMachine doY(Tasks tasks) {
    performY();
    return DONE;
  }
}

Este enfoque es más limpio que abusar de las subtareas. Sin embargo, aplicar esto de forma demasiado liberal, por ejemplo, anidando varias StateMachine con runAfter, es el camino hacia el infierno de devoluciones de llamada. Es mejor dividir los runAfter secuenciales con estados secuenciales normales.

  return new S(/* runAfter= */ new T(/* runAfter= */ this::nextStep))

se puede reemplazar por lo siguiente.

  private StateMachine step1(Tasks tasks) {
     doStep1();
     return new S(/* runAfter= */ this::intermediateStep);
  }

  private StateMachine intermediateStep(Tasks tasks) {
    return new T(/* runAfter= */ this::nextStep);
  }

Nota: Es posible pasar DONE como el parámetro runAfter cuando no hay nada que ejecutar después.

Sugerencia: Cuando uses runAfter, siempre anota el parámetro con /* runAfter= */ para que el lector sepa el significado en el sitio de llamada.

Alternativa prohibida: runAfterUnlessError

En un borrador anterior, habíamos considerado un runAfterUnlessError que abortaría antes de los errores. Esto se debió al hecho de que los errores a menudo terminan verificándose dos veces, una por el StateMachine que tiene una referencia runAfter y una por la propia máquina runAfter.

Después de deliberar, decidimos que la uniformidad del código es más importante que la anulación de la verificación de errores. Sería confuso si el mecanismo runAfter no funcionara de manera coherente con el mecanismo tasks.enqueue, que siempre requiere comprobación de errores.

Advertencia: Cuando uses runAfter, la máquina que tiene el runAfter insertado debe invocarlo de forma incondicional cuando se complete, incluso si hay un error, para mantener la coherencia.

Delegación directa

Cada vez que hay una transición de estado formal, avanza el bucle principal de Driver. Según el contrato, avanzar los estados significa que todas las búsquedas y subtareas de SkyValue que se pusieron en cola anteriormente se resuelven antes de que se ejecute el siguiente estado. A veces, la lógica de un StateMachine delegado hace que un avance de fase sea innecesario o contraproducente. Por ejemplo, si el primer step del delegado realiza búsquedas de SkyKey que se podrían paralelizar con búsquedas del estado de delegación, un avance de fase las haría secuenciales. Podría ser más conveniente realizar la delegación directa, como se muestra en el siguiente ejemplo.

class Parent implements StateMachine {
  @Override
  public StateMachine step(Tasks tasks ) {
    tasks.lookUp(new Key1(), this);
    // Directly delegates to `Delegate`.
    //
    // The (valid) alternative:
    //   return new Delegate(this::afterDelegation);
    // would cause `Delegate.step` to execute after `step` completes which would
    // cause lookups of `Key1` and `Key2` to be sequential instead of parallel.
    return new Delegate(this::afterDelegation).step(tasks);
  }

  private StateMachine afterDelegation(Tasks tasks) {
    …
  }
}

class Delegate implements StateMachine {
  private final StateMachine runAfter;

  Delegate(StateMachine runAfter) {
    this.runAfter = runAfter;
  }

  @Override
  public StateMachine step(Tasks tasks) {
    tasks.lookUp(new Key2(), this);
    return …;
  }

  // Rest of implementation.
  …

  private StateMachine complete(Tasks tasks) {
    …
    return runAfter;
  }
}

Flujo de datos

El enfoque del debate anterior se centró en la administración del flujo de control. En esta sección, se describe la propagación de valores de datos.

Cómo implementar devoluciones de llamada de Tasks.lookUp

A continuación, se muestra un ejemplo de implementación de una devolución de llamada Tasks.lookUp en las búsquedas de SkyValue. En esta sección, se proporciona una justificación y se sugieren enfoques para controlar varios SkyValues.

Devoluciones de llamada de Tasks.lookUp

El método Tasks.lookUp toma una devolución de llamada, sink, como parámetro.

  void lookUp(SkyKey key, Consumer<SkyValue> sink);

El enfoque idiomático sería usar una lambda de Java para implementar esto:

  tasks.lookUp(key, value -> myValue = (MyValueClass)value);

en la que myValue es una variable miembro de la instancia StateMachine que realiza la búsqueda. Sin embargo, la lambda requiere una asignación de memoria adicional en comparación con la implementación de la interfaz Consumer<SkyValue> en la implementación de StateMachine. La lambda sigue siendo útil cuando hay varias búsquedas que serían ambiguas.

Nota: Advertencia de descuido. Hay una diferencia notoria de aproximadamente el 1% de uso de la CPU de extremo a extremo cuando se implementan devoluciones de llamada de manera sistemática en implementaciones de StateMachine, en comparación con el uso de lambdas, por lo que esta recomendación es discutible. Para evitar debates innecesarios, se recomienda dejar la decisión a la persona que implementa la solución.

También hay sobrecargas de manejo de errores de Tasks.lookUp, que son análogas a SkyFunction.Environment.getValueOrThrow.

  <E extends Exception> void lookUp(
      SkyKey key, Class<E> exceptionClass, ValueOrExceptionSink<E> sink);

  interface ValueOrExceptionSink<E extends Exception> {
    void acceptValueOrException(@Nullable SkyValue value, @Nullable E exception);
  }

A continuación, se muestra un ejemplo de implementación.

class PerformLookupWithError extends StateMachine, ValueOrExceptionSink<MyException> {
  private MyValue value;
  private MyException error;

  @Override
  public StateMachine step(Tasks tasks) {
    tasks.lookUp(new MyKey(), MyException.class, ValueOrExceptionSink<MyException>) this);
    return this::processResult;
  }

  @Override
  public acceptValueOrException(@Nullable SkyValue value, @Nullable MyException exception) {
    if (value != null) {
      this.value = (MyValue)value;
      return;
    }
    if (exception != null) {
      this.error = exception;
      return;
    }
    throw new IllegalArgumentException("Both parameters were unexpectedly null.");
  }

  private StateMachine processResult(Tasks tasks) {
    if (exception != null) {
      // Handles the error.
      …
      return DONE;
    }
    // Processes `value`, which is non-null.
    …
  }
}

Al igual que con las búsquedas sin manejo de errores, hacer que la clase StateMachine implemente directamente la devolución de llamada guarda una asignación de memoria para la lamba.

La manejo de errores proporciona un poco más de detalles, pero, en esencia, no hay mucha diferencia entre la propagación de errores y los valores normales.

Cómo consumir varios SkyValues

A menudo, se requieren varias búsquedas de SkyValue. Un enfoque que funciona la mayor parte del tiempo es activar el tipo de SkyValue. El siguiente es un ejemplo que se simplificó a partir del código de producción del prototipo.

  @Nullable
  private StateMachine fetchConfigurationAndPackage(Tasks tasks) {
    var configurationKey = configuredTarget.getConfigurationKey();
    if (configurationKey != null) {
      tasks.lookUp(configurationKey, (Consumer<SkyValue>) this);
    }

    var packageId = configuredTarget.getLabel().getPackageIdentifier();
    tasks.lookUp(PackageValue.key(packageId), (Consumer<SkyValue>) this);

    return this::constructResult;
  }

  @Override  // Implementation of `Consumer<SkyValue>`.
  public void accept(SkyValue value) {
    if (value instanceof BuildConfigurationValue) {
      this.configurationValue = (BuildConfigurationValue) value;
      return;
    }
    if (value instanceof PackageValue) {
      this.pkg = ((PackageValue) value).getPackage();
      return;
    }
    throw new IllegalArgumentException("unexpected value: " + value);
  }

La implementación de devolución de llamada Consumer<SkyValue> se puede compartir de forma inequívoca porque los tipos de valor son diferentes. Cuando no es así, es viable recurrir a implementaciones basadas en lambda o instancias de clase interna completas que implementen las devoluciones de llamada adecuadas.

Cómo propagar valores entre StateMachine

Hasta ahora, en este documento, solo se explicó cómo organizar el trabajo en una subtarea, pero las subtareas también deben informar un valor al llamador. Dado que las subtareas son asíncronas de forma lógica, sus resultados se vuelven a comunicar al llamador con una devolución de llamada. Para que esto funcione, la subtarea define una interfaz de receptor que se inyecta a través de su constructor.

class BarProducer implements StateMachine {
  // Callers of BarProducer implement the following interface to accept its
  // results. Exactly one of the two methods will be called by the time
  // BarProducer completes.
  interface ResultSink {
    void acceptBarValue(Bar value);
    void acceptBarError(BarException exception);
  }

  private final ResultSink sink;

  BarProducer(ResultSink sink) {
     this.sink = sink;
  }

  … // StateMachine steps that end with this::complete.

  private StateMachine complete(Tasks tasks) {
    if (hasError()) {
      sink.acceptBarError(getError());
      return DONE;
    }
    sink.acceptBarValue(getValue());
    return DONE;
  }
}

Sugerencia: Sería tentador usar el accept(Bar value) de nulidad de firma más conciso en lugar del void acceptBarValue(Bar value) entrecortado anterior. Sin embargo, Consumer<SkyValue> es una sobrecarga común de void accept(Bar value), por lo que, a menudo, esto genera incumplimientos de la regla del Guía de estilo: nunca dividir.

Sugerencia: Usar un tipo ResultSink personalizado en lugar de uno genérico de java.util.function facilita la búsqueda de implementaciones en la base de código, lo que mejora la legibilidad.

Un llamador StateMachine debería verse de la siguiente manera.

class Caller implements StateMachine, BarProducer.ResultSink {
  interface ResultSink {
    void acceptCallerValue(Bar value);
    void acceptCallerError(BarException error);
  }

  private final ResultSink sink;

  private Bar value;

  Caller(ResultSink sink) {
    this.sink = sink;
  }

  @Override
  @Nullable
  public StateMachine step(Tasks tasks) {
    tasks.enqueue(new BarProducer((BarProducer.ResultSink) this));
    return this::processResult;
  }

  @Override
  public void acceptBarValue(Bar value) {
    this.value = value;
  }

  @Override
  public void acceptBarError(BarException error) {
    sink.acceptCallerError(error);
  }

  private StateMachine processResult(Tasks tasks) {
    // Since all enqueued subtasks resolve before `processResult` starts, one of
    // the `BarResultSink` callbacks must have been called by this point.
    if (value == null) {
      return DONE;  // There was a previously reported error.
    }
    var finalResult = computeResult(value);
    sink.acceptCallerValue(finalResult);
    return DONE;
  }
}

En el ejemplo anterior, se demuestran algunos aspectos. Caller debe propagar sus resultados y definir su propio Caller.ResultSink. Caller implementa las devoluciones de llamada de BarProducer.ResultSink. Cuando se reanuda, processResult verifica si value es nulo para determinar si se produjo un error. Este es un patrón de comportamiento común después de aceptar el resultado de una subtarea o una búsqueda de SkyValue.

Ten en cuenta que la implementación de acceptBarError reenvía con anticipación el resultado a Caller.ResultSink, según lo requiera Error bubbling.

Las alternativas para StateMachine de nivel superior se describen en Driver y la vinculación a SkyFunctions.

Manejo de errores

Ya hay algunos ejemplos de control de errores en las llamadas a función de Tasks.lookUp y en la propagación de valores entre StateMachines. No se arrojan excepciones, excepto InterruptedException, sino que se pasan a través de devoluciones de llamada como valores. Estas devoluciones de llamada suelen tener semánticas de exclusivo o, en las que se pasa exactamente uno de un valor o un error.

En la siguiente sección, se describe una interacción sutil, pero importante, con el control de errores de Skyframe.

Burbuja de errores (--nokeep_going)

Advertencia: Los errores deben propagarse de forma inmediata hasta SkyFunction para que el burbujeo de errores funcione correctamente.

Durante la burbuja de errores, es posible que se reinicie una SkyFunction incluso si no todos los SkyValues solicitados están disponibles. En esos casos, nunca se llegará al estado posterior debido al contrato de la API de Tasks. Sin embargo, StateMachine debería propagar la excepción.

Dado que la propagación debe ocurrir independientemente de si se alcanza el estado siguiente, la devolución de llamada de manejo de errores debe realizar esta tarea. Para un StateMachine interno, esto se logra invocando la devolución de llamada superior.

En el StateMachine de nivel superior, que se comunica con SkyFunction, esto se puede hacer llamando al método setException de ValueOrExceptionProducer. Luego, ValueOrExceptionProducer.tryProduceValue arrojará la excepción, incluso si faltan SkyValues.

Si se usa un Driver directamente, es esencial verificar si hay errores propagados desde la SkyFunction, incluso si la máquina no terminó de procesarse.

Control de eventos

Para las SkyFunctions que necesitan emitir eventos, se inserta un StoredEventHandler en SkyKeyComputeState y, luego, en los StateMachine que los requieren. Históricamente, se necesitaba StoredEventHandler debido a que Skyframe descartaba ciertos eventos, a menos que se volvieran a reproducir, pero esto se corrigió posteriormente. La inserción de StoredEventHandler se conserva porque simplifica la implementación de eventos emitidos desde devoluciones de llamada de manejo de errores.

Driver y el modo puente a SkyFunctions

Un Driver es responsable de administrar la ejecución de StateMachine, comenzando con un StateMachine raíz especificado. Como los StateMachine pueden poner en cola de forma recursiva StateMachine de subtareas, un solo Driver puede administrar varias subtareas. Estas subtareas crean una estructura de árbol, un resultado de la simultaneidad estructurada. Driver agrupa las búsquedas de SkyValue en subtareas para mejorar la eficiencia.

Hay varias clases compiladas en torno a Driver, con la siguiente API.

public final class Driver {
  public Driver(StateMachine root);
  public boolean drive(SkyFunction.Environment env) throws InterruptedException;
}

Driver toma un solo elemento StateMachine raíz como parámetro. Llamar a Driver.drive ejecuta StateMachine todo lo que puede sin un reinicio de Skyframe. Muestra verdadero cuando se completa StateMachine y falso de lo contrario, lo que indica que no todos los valores estaban disponibles.

Driver mantiene el estado simultáneo de StateMachine y es adecuado para incorporarlo en SkyKeyComputeState.

Cómo crear instancias de Driver directamente

Las implementaciones de StateMachine comunican sus resultados de forma convencional a través de devoluciones de llamada. Es posible crear una instancia de Driver directamente, como se muestra en el siguiente ejemplo.

El Driver está incorporado en la implementación de SkyKeyComputeState junto con una implementación del ResultSink correspondiente que se definirá más adelante. En el nivel superior, el objeto State es un receptor adecuado para el resultado del cálculo, ya que se garantiza que durará más que Driver.

class State implements SkyKeyComputeState, ResultProducer.ResultSink {
  // The `Driver` instance, containing the full tree of all `StateMachine`
  // states. Responsible for calling `StateMachine.step` implementations when
  // asynchronous values are available and performing batched SkyFrame lookups.
  //
  // Non-null while `result` is being computed.
  private Driver resultProducer;

  // Variable for storing the result of the `StateMachine`
  //
  // Will be non-null after the computation completes.
  //
  private ResultType result;

  // Implements `ResultProducer.ResultSink`.
  //
  // `ResultProducer` propagates its final value through a callback that is
  // implemented here.
  @Override
  public void acceptResult(ResultType result) {
    this.result = result;
  }
}

En el siguiente código, se esboza ResultProducer.

class ResultProducer implements StateMachine {
  interface ResultSink {
    void acceptResult(ResultType value);
  }

  private final Parameters parameters;
  private final ResultSink sink;

  … // Other internal state.

  ResultProducer(Parameters parameters, ResultSink sink) {
    this.parameters = parameters;
    this.sink = sink;
  }

  @Override
  public StateMachine step(Tasks tasks) {
    …  // Implementation.
    return this::complete;
  }

  private StateMachine complete(Tasks tasks) {
    sink.acceptResult(getResult());
    return DONE;
  }
}

Luego, el código para calcular el resultado de forma diferida podría verse de la siguiente manera.

@Nullable
private Result computeResult(State state, Skyfunction.Environment env)
    throws InterruptedException {
  if (state.result != null) {
    return state.result;
  }
  if (state.resultProducer == null) {
    state.resultProducer = new Driver(new ResultProducer(
      new Parameters(), (ResultProducer.ResultSink)state));
  }
  if (state.resultProducer.drive(env)) {
    // Clears the `Driver` instance as it is no longer needed.
    state.resultProducer = null;
  }
  return state.result;
}

Incorporación de Driver

Si StateMachine produce un valor y no genera excepciones, la incorporación de Driver es otra implementación posible, como se muestra en el siguiente ejemplo.

class ResultProducer implements StateMachine {
  private final Parameters parameters;
  private final Driver driver;

  private ResultType result;

  ResultProducer(Parameters parameters) {
    this.parameters = parameters;
    this.driver = new Driver(this);
  }

  @Nullable  // Null when a Skyframe restart is needed.
  public ResultType tryProduceValue( SkyFunction.Environment env)
      throws InterruptedException {
    if (!driver.drive(env)) {
      return null;
    }
    return result;
  }

  @Override
  public StateMachine step(Tasks tasks) {
    …  // Implementation.
}

SkyFunction puede tener código que se vea como el siguiente (donde State es el tipo específico de la función de SkyKeyComputeState).

@Nullable  // Null when a Skyframe restart is needed.
Result computeResult(SkyFunction.Environment env, State state)
    throws InterruptedException {
  if (state.result != null) {
    return state.result;
  }
  if (state.resultProducer == null) {
    state.resultProducer = new ResultProducer(new Parameters());
  }
  var result = state.resultProducer.tryProduceValue(env);
  if (result == null) {
    return null;
  }
  state.resultProducer = null;
  return state.result = result;
}

La incorporación de Driver en la implementación de StateMachine es una mejor opción para el estilo de codificación síncrona de Skyframe.

StateMachines que pueden producir excepciones

De lo contrario, hay clases ValueOrExceptionProducer y ValueOrException2Producer integrables con SkyKeyComputeState que tienen APIs síncronas para que coincidan con el código síncrono de SkyFunction.

La clase abstracta ValueOrExceptionProducer incluye los siguientes métodos.

public abstract class ValueOrExceptionProducer<V, E extends Exception>
    implements StateMachine {
  @Nullable
  public final V tryProduceValue(Environment env)
      throws InterruptedException, E {
    …  // Implementation.
  }

  protected final void setValue(V value)  {  … // Implementation. }
  protected final void setException(E exception) {  … // Implementation. }
}

Incluye una instancia de Driver incorporada y se asemeja mucho a la clase ResultProducer en el controlador de incorporación y las interfaces con SkyFunction de manera similar. En lugar de definir un ResultSink, las implementaciones llaman a setValue o setException cuando se produce alguna de estas situaciones. Cuando ocurren ambas, la excepción tiene prioridad. El método tryProduceValue une el código de devolución de llamada asíncrono al código síncrono y arroja una excepción cuando se establece uno.

Como se señaló anteriormente, durante el burbujeo de errores, es posible que se produzca un error incluso si la máquina aún no está lista porque no todas las entradas están disponibles. Para adaptarse a esto, tryProduceValue arroja cualquier excepción establecida, incluso antes de que la máquina finalice.

Epílogo: Cómo quitar las devoluciones de llamada

Los objetos StateMachine son una forma muy eficiente, pero de uso intensivo de código estándar para realizar procesamiento asíncrono. Las continuaciones (en particular, en forma de Runnable que se pasan a ListenableFuture) están muy extendidas en ciertas partes del código de Bazel, pero no son frecuentes en el análisis de SkyFunctions. El análisis se basa, en su mayoría, en la CPU y no hay APIs asíncronas eficientes para la E/S del disco. Con el tiempo, sería bueno optimizar las devoluciones de llamada, ya que tienen una curva de aprendizaje y dificultan la legibilidad.

Una de las alternativas más prometedoras son los subprocesos virtuales de Java. En lugar de escribir callbacks, todo se reemplaza por llamadas síncronas de bloqueo. Esto es posible porque vincular un recurso de subproceso virtual, a diferencia de un subproceso de plataforma, se supone que es económico. Sin embargo, incluso con subprocesos virtuales, reemplazar operaciones síncronas simples con primitivas de creación y sincronización de subprocesos es demasiado costoso. Realizamos una migración de StateMachine a subprocesos virtuales de Java, que fueron órdenes de magnitud más lentos, lo que generó un aumento de casi 3 veces en la latencia del análisis de extremo a extremo. Dado que los subprocesos virtuales todavía son una función de versión preliminar, es posible que esta migración se pueda realizar más adelante, cuando mejore el rendimiento.

Otro enfoque que debes considerar es esperar las corrutinas de Loom, si alguna vez están disponibles. La ventaja aquí es que podría ser posible reducir la sobrecarga de sincronización mediante la realización de varias tareas a la vez de forma cooperativa.

Si todo lo demás falla, la reescritura de código de bytes de bajo nivel también podría ser una alternativa viable. Con suficiente optimización, es posible lograr un rendimiento que se acerque al código de devolución de llamada escrito a mano.

Apéndice

Infierno de devoluciones de llamada

El infierno de las devoluciones de llamadas es un problema infame en el código asíncrono que usa devoluciones de llamada. Se debe al hecho de que la continuación de un paso posterior está anidada dentro del paso anterior. Si hay muchos pasos, este anidamiento puede ser muy profundo. Si se combina con el flujo de control, el código se vuelve inmanejable.

class CallbackHell implements StateMachine {
  @Override
  public StateMachine step(Tasks task) {
    doA();
    return (t, l) -> {
      doB();
      return (t1, l2) -> {
        doC();
        return DONE;
      };
    };
  }
}

Una de las ventajas de las implementaciones anidadas es que se puede preservar el marco de pila del paso externo. En Java, las variables lambda capturadas deben ser efectivamente definitivas, por lo que su uso puede resultar engorroso. Se evita el anidamiento profundo mostrando referencias de métodos como continuaciones en lugar de lambdas, como se muestra a continuación.

class CallbackHellAvoided implements StateMachine {
  @Override
  public StateMachine step(Tasks task) {
    doA();
    return this::step2;
  }

  private StateMachine step2(Tasks tasks) {
    doB();
    return this::step3;
  }

  private StateMachine step3(Tasks tasks) {
    doC();
    return DONE;
  }
}

El infierno de devoluciones de llamada también puede ocurrir si el patrón de inyección de runAfter se usa con demasiada densidad, pero esto se puede evitar intercalando inyecciones con pasos secuenciales.

Ejemplo: Búsquedas de SkyValue encadenadas

A menudo, la lógica de la aplicación requiere cadenas dependientes de búsquedas de SkyValue, por ejemplo, si una segunda SkyKey depende del primer SkyValue. Si lo pensamos de forma ingenua, esto generaría una estructura de devolución de llamada compleja y anidada en profundidad.

private ValueType1 value1;
private ValueType2 value2;

private StateMachine step1(...) {
  tasks.lookUp(key1, (Consumer<SkyValue>) this);  // key1 has type KeyType1.
  return this::step2;
}

@Override
public void accept(SkyValue value) {
  this.value1 = (ValueType1) value;
}

private StateMachine step2(...) {
  KeyType2 key2 = computeKey(value1);
  tasks.lookup(key2, this::acceptValueType2);
  return this::step3;
}

private void acceptValueType2(SkyValue value) {
  this.value2 = (ValueType2) value;
}

Sin embargo, como las continuaciones se especifican como referencias de métodos, el código se ve procedimental en las transiciones de estado: step2 sigue a step1. Ten en cuenta que aquí se usa una expresión lambda para asignar value2. Esto hace que el orden del código coincida con el orden del procesamiento de arriba abajo.

Sugerencias varias

Legibilidad: Orden de ejecución

Para mejorar la legibilidad, intenta mantener las implementaciones de StateMachine.step en orden de ejecución y las implementaciones de devolución de llamada inmediatamente después de donde se pasan en el código. Esto no siempre es posible cuando el flujo de control se bifurca. En esos casos, los comentarios adicionales pueden ser útiles.

En Ejemplo: Búsquedas de SkyValue encadenadas, se crea una referencia de método intermedia para lograrlo. Esto cambia una pequeña cantidad de rendimiento por legibilidad, lo que probablemente valga la pena aquí.

Hipótesis generacional

Los objetos Java de vida media rompen la hipótesis generacional del recopilador de basura de Java, que está diseñado para controlar objetos que viven por un tiempo muy corto o objetos que viven para siempre. Por definición, los objetos en SkyKeyComputeState incumplen esta hipótesis. Estos objetos, que contienen el árbol construido de todos los StateMachine que aún se ejecutan, con raíz en Driver, tienen un ciclo de vida intermedio a medida que se suspenden, a la espera de que se completen los cálculos asíncronos.

Parece menos grave en JDK19, pero cuando se usan StateMachine, a veces es posible observar un aumento en el tiempo de GC, incluso con disminuciones drásticas en la basura generada. Dado que los elementos StateMachine tienen una vida útil intermedia, podrían ascenderse a versiones anteriores, lo que hace que se llene más rápido y, por lo tanto, se necesitarán recolecciones de elementos no utilizados mayores o completas más costosas para la limpieza.

La precaución inicial es minimizar el uso de variables StateMachine, pero no siempre es factible, por ejemplo, si se necesita un valor en varios estados. Cuando es posible, las variables step de la pila local son variables de generación joven y se eliminan de manera eficiente con el GC.

En el caso de las variables StateMachine, también es útil dividir el proceso en subtareas y seguir el patrón recomendado para propagar valores entre StateMachine. Observa que, cuando se sigue el patrón, solo los StateMachine secundarios tienen referencias a StateMachine superiores y no al revés. Esto significa que, a medida que los elementos secundarios completan y actualizan los elementos superiores con devoluciones de llamada de resultados, estos salen del alcance de forma natural y se vuelven aptos para la GC.

Por último, en algunos casos, se necesita una variable StateMachine en estados anteriores, pero no en estados posteriores. Puede ser beneficioso anular las referencias de objetos grandes una vez que se sepa que ya no son necesarias.

Cómo nombrar estados

Cuando se le asigna un nombre a un método, por lo general, es posible hacerlo para el comportamiento que ocurre dentro de ese método. No está claro cómo hacerlo en StateMachine porque no hay pila. Por ejemplo, supongamos que el método foo llama a un submétodo bar. En un StateMachine, esto podría traducirse a la secuencia de estado foo, seguida de bar. foo ya no incluye el comportamiento bar. Como resultado, los nombres de los métodos de los estados suelen tener un alcance más limitado, lo que podría reflejar el comportamiento local.

Diagrama de árbol de simultaneidad

La siguiente es una vista alternativa del diagrama en Concurrentismo estructurado que representa mejor la estructura del árbol. Los bloques forman un árbol pequeño.

---

1. A diferencia de la convención de Skyframe de reiniciar desde el principio cuando los valores no están disponibles. ↩

2. Ten en cuenta que step puede arrojar InterruptedException, pero los ejemplos omiten esto. Hay algunos métodos bajos en el código de Bazel que arrojan esta excepción y se propagan hasta Driver, que se describirá más adelante, que ejecuta StateMachine. Está bien no declarar que se arroje cuando no sea necesario. ↩

3. Las subtareas simultáneas se motivaron por el ConfiguredTargetFunction, que realiza un trabajo independiente para cada dependencia. En lugar de manipular estructuras de datos complejas que procesan todas las dependencias a la vez (lo que genera ineficiencias), cada dependencia tiene su propio StateMachine independiente.⬤

4. Varias llamadas tasks.lookUp en un solo paso se agrupan en lotes. Se pueden crear lotes adicionales a través de búsquedas que se producen dentro de subtareas simultáneas. ↩

5. Esto es conceptualmente similar a la concurrencia estructurada de Java jeps/428. ↩

6. Hacer esto es similar a crear un subproceso y unirlo para lograr una composición secuencial. ↩