Una guía para Skyframe StateMachines

Informar un problema Ver fuente

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 subprocesos mientras espera, sino que debe suspenderse y reanudarse. Así, la deconstrucción expone puntos de reingreso explícitos para que se puedan omitir los procesamientos anteriores.

Los elementos StateMachine se pueden usar para expresar secuencias, ramificaciones y simultaneidad lógica estructurada, y están diseñados específicamente para la interacción de 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 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 un subproceso, que se vincularía 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 null getValue y debe mostrar null en lugar de SkyValue, lo que indica que está incompleto debido a entradas faltantes. 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 tiene una complejidad cuadrática, las funciones escritas de esta manera finalmente se completan porque, con cada repetición, menos búsquedas muestran null. Con SkyKeyComputeState, es posible asociar datos de puntos de control especificados a mano con una SkyFunction, lo que ahorra una repetición de procesamiento significativa.

Los StateMachine son objetos que se encuentran dentro de SkyKeyComputeState y eliminan prácticamente todo el procesamiento cuando se reinicia una SkyFunction (suponiendo que SkyKeyComputeState no queda fuera de la caché) mediante la exposición de 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 almacenar objetos computacionales dentro de SkyKeyComputeState en lugar de valores de datos puros. En Java, la descripción mínima de un comportamiento que transporta un objeto es una interfaz funcional, y es 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 lógicamente.³

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 finaliza 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 una StateMachine.

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

Devoluciones de llamada, continuaciones y procesamiento asíncrono

En términos técnicos, un StateMachine sirve como una continuation, que determina el procesamiento posterior que se ejecutará. En lugar de bloquear, un StateMachine puede suspend 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 dejar de controlar Skyframe.

Tradicionalmente, las callbacks y las callbacks 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.

Se requieren devoluciones de llamada cuando se invoca una operación asíncrona, lo que significa que la operación real no ocurre inmediatamente después de que se llama 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 los 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.

Tareas

La interfaz de 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 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 en lotes⁴ tantas búsquedas como sea posible antes de hacerlo. Es posible que el valor no esté disponible de inmediato, por ejemplo, porque requiere 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 incluye 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 realiza una búsqueda de new Key() y pasa this como el consumidor. Esto 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 estado garantiza que todas las subtareas estén completas antes de continuar con el 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 simultáneos desde el punto de vista lógico, 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 se deben resolver antes de pasar al siguiente estado, significa que la simultaneidad se limita de forma natural 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 de árbol.

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

Patrones de composición y flujo de control

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

Estados secuenciales

Este es el patrón de flujo de control más común y directo. 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 mostrando diferentes valores usando el flujo de control normal de Java, 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 muestren DONE para la 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 debe continuar con B o Y después de que se completa, y las StateMachine no mantienen una pila de llamadas. En esta sección, se revisan algunas técnicas para lograrlo.

StateMachine como elemento de secuencia de la 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 en sí misma una máquina de estados compleja.

Subtarea para la composición secuencial

Debido a que se garantiza que las subtareas en cola se completen antes del siguiente estado, a veces es posible que se abuse 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, el abuso de Tasks.enqueue es imposible porque hay otras subtareas o llamadas a Tasks.lookUp paralelas que deben completarse antes de que se ejecute S. En este caso, la inserción de un parámetro runAfter en S se puede usar para informar 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 subtareas. Sin embargo, aplicar esto de manera demasiado libre, por ejemplo, anidar varios StateMachine con runAfter, es la ruta al infierno de devolución de llamada. En su lugar, se recomienda romper objetos runAfter secuenciales con estados secuenciales comunes.

  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 para ejecutar después.

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

Alternativa Prohibida: runAfterUnlessError

En un borrador anterior, habíamos considerado un runAfterUnlessError que se anularía al principio de los errores. Esto se debe al hecho de que, a menudo, los errores se verifican dos veces, una vez por StateMachine que tiene una referencia runAfter y otra por la máquina runAfter.

Después de un poco de deliberación, decidimos que la uniformidad del código es más importante que anular 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, el bucle Driver principal avanza. Según el contrato, el avance de estados significa que todas las búsquedas y subtareas de SkyValue que se pusieron en cola antes 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 tener más sentido realizar una 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 ha estado 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 cómo implementar una devolución de llamada Tasks.lookUp en las búsquedas de SkyValue. En esta sección, se proporcionan motivos y se sugieren enfoques para controlar varios SkyValues.

Tasks.lookUp devoluciones de llamada

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 lo siguiente:

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

myValue es una variable de 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 podrían ser ambiguas.

Nota: Advertencia de desviación objetiva. 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 en manos de 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.

El manejo de errores proporciona un poco más de detalle, pero, en esencia, no hay mucha diferencia entre la propagación de los 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 cambiar 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 sin ambigüedades porque los tipos de valores son diferentes. Cuando ese no sea el caso, es viable recurrir a implementaciones basadas en lambda o a instancias completas de clase interna que implementen las devoluciones de llamada adecuadas.

Propaga valores entre StateMachine s

Hasta ahora, en este documento solo se explicó cómo organizar el trabajo en una subtarea, pero las subtareas también deben informar los valores al llamador. Dado que las subtareas son asíncronas lógicamente, sus resultados se comunican al emisor mediante 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;
  }
}

Nota: Sería tentador usar la firma vacía accept(Bar value), más concisa, en lugar de la void acceptBarValue(Bar value) entrecortada arriba. Sin embargo, Consumer<SkyValue> es una sobrecarga común de void accept(Bar value), por lo que hacer esto a menudo genera incumplimientos de la regla de la guía de estilo Sobrecargas: 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 algunas cosas. Caller debe propagar sus resultados y definir su propio Caller.ResultSink. Caller implementa las devoluciones de llamada BarProducer.ResultSink. Después de la reanudación, 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 resultados 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, como lo requiere Error bubbling.

Las alternativas para StateMachine de nivel superior se describen en Driver y cómo puentes a SkyFunctions.

Manejo de errores

Hay algunos ejemplos de manejo de errores que ya se encuentran en las devoluciones de llamada de Tasks.lookUp y Propaga valores entre StateMachines. No se arrojan excepciones distintas de InterruptedException, sino que se pasan a través de devoluciones de llamada como valores. Estas devoluciones de llamada a menudo tienen semánticas exclusivas o semánticas, y se pasa exactamente uno de un valor o error.

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

Error de burbuja (--nokeep_going)

Advertencia: Los errores se deben propagar con anticipación hasta la SkyFunction para que el burbuja 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 alcanzará el estado posterior debido al contrato de la API de Tasks. Sin embargo, StateMachine aún debe 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 interactúa con SkyFunction, esto se puede hacer llamando al método setException de ValueOrExceptionProducer. 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 funciones de SkyFunctions que necesitan emitir eventos, se inserta un StoredEventHandler en SkyKeyComputeState y, además, en los StateMachine que los requieren. Históricamente, se necesitaba StoredEventHandler debido a que Skyframe descartaba ciertos eventos, a menos que se vuelvan a reproducir, pero esto se corrigió posteriormente. La inyección de StoredEventHandler se conserva porque simplifica la implementación de eventos emitidos a partir de 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 por una raíz StateMachine especificada. Como los StateMachine pueden poner en cola StateMachine de subtareas de manera recurrente, un solo Driver puede administrar varias subtareas. Estas subtareas crean una estructura de árbol, un resultado de la simultaneidad estructurada. Driver agrupa en lotes las búsquedas de SkyValue en subtareas para mejorar la eficiencia.

Hay una serie de 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 una raíz única StateMachine como parámetro. Llamar a Driver.drive ejecuta el StateMachine todo lo que puede sin un reinicio de Skyframe. El resultado es 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 la incorporación en SkyKeyComputeState.

Crea una instancia de Driver directamente

Por lo general, las implementaciones de StateMachine comunican sus resultados a través de devoluciones de llamada. Es posible crear directamente una instancia de Driver, 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á un poco más abajo. En el nivel superior, el objeto State es un receptor apropiado para el resultado del cálculo, ya que se garantiza que sobreviva a 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 el 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;
  }
}

Entonces, el código para calcular de forma diferida el resultado 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;
}

Incorporando 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.
}

La SkyFunction puede tener un código similar al siguiente (en el que State es el tipo de función específico 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 parece mucho a la clase ResultProducer en el controlador de incorporaciones y, además, interactúa 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 se producen ambos casos, la excepción tiene prioridad. El método tryProduceValue conecta el código de devolución de llamada asíncrono con el código síncrono y muestra una excepción cuando se establece una.

Como se señaló antes, durante la burbuja 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: Con el tiempo, se quitan 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 (especialmente en la forma de Runnable que se pasan a ListenableFuture) se extienden en ciertas partes del código Bazel, pero no prevalecen 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 de ausencia, 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 tener que escribir devoluciones de llamada, todo se reemplaza por llamadas síncronas y de bloqueo. Esto es posible porque se supone que vincular un recurso de subproceso virtual, a diferencia de un subproceso de la plataforma, es económico. Sin embargo, incluso en el caso de los subprocesos virtuales, reemplazar las operaciones síncronas simples por las primitivas de creación y sincronización de subprocesos es demasiado costoso. Realizamos una migración de StateMachine a subprocesos virtuales de Java, que eran órdenes de magnitud más lentos, lo que generó casi un aumento del triple en la latencia del análisis de extremo a extremo. Dado que los subprocesos virtuales aún son una función de vista previa, es posible que la 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 devolución 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 basa en el hecho de que la continuación de un paso siguiente está anidada dentro del paso anterior. Si hay muchos pasos, este anidado puede ser extremadamente 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 conservar 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. Para evitar el anidamiento profundo, se muestran 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 devolución de llamada también puede ocurrir si el patrón de inyección runAfter se usa con demasiada densidad, pero esto se puede evitar si intercalas las 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 pensamos en esto de forma simple, esto generaría una estructura de devolución de llamada compleja y profundamente anidada.

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, dado que las continuaciones se especifican como referencias de métodos, el código se ve procedimental en todas las transiciones de estado: step2 sigue a step1. Ten en cuenta que aquí se usa una lambda para asignar value2. Esto hace que el orden del código coincida con el orden del cálculo de arriba hacia abajo.

Sugerencias varias

Legibilidad: orden de la ejecución

Para mejorar la legibilidad, esfuérzate por mantener las implementaciones de StateMachine.step en orden de ejecución y las implementaciones de devolución de llamada inmediatamente después de que se pasen en el código. Esto no siempre es posible donde se ramifica el flujo de control. Los comentarios adicionales pueden ser útiles en esos casos.

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

Hipótesis generacional

Los objetos Java de duración media rompen la hipótesis generacional del recolector de elementos no utilizados de Java, que está diseñado para manejar objetos que permanecen activos durante un período muy corto o aquellos que permanecen activos para siempre. Por definición, los objetos en SkyKeyComputeState infringen esta hipótesis. Estos objetos, que contienen el árbol construido de todos los StateMachine en ejecución, que tienen la raíz en Driver, tienen una vida útil intermedia mientras se suspenden, a la espera de que se completen los cálculos asíncronos.

Parece menos malo en JDK19, pero cuando se usan objetos StateMachine, a veces es posible observar un aumento en el tiempo de recolección de elementos no utilizados, incluso con disminuciones drásticas en los elementos no utilizados reales generados. 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 requieren GC principales 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 agrupan de manera eficiente.

En el caso de las variables StateMachine, también es útil dividirlo en subtareas y seguir el patrón recomendado para propagar valores entre StateMachines. Observa que, cuando sigues el patrón, solo los StateMachine secundarios tienen referencias a los StateMachine superiores y no al revés. Esto significa que a medida que los elementos secundarios completan y actualizan los elementos superiores mediante devoluciones de llamada de resultados, los elementos secundarios quedan naturalmente fuera del alcance y se vuelven aptos para la recolección de elementos no utilizados.

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

Estados de nombres

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 es tan claro cómo hacer esto en StateMachine porque no hay una pila. Por ejemplo, supongamos que el método foo llama a un submétodo bar. En un StateMachine, esto se podría traducir a la secuencia de estado foo, seguida de bar. foo ya no incluye el comportamiento bar. Como resultado, los nombres de métodos para 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 Simultaneidad estructurada que representa mejor la estructura de árbol. Los bloques forman un pequeño árbol.

---

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 propaga hasta el Driver, que se describirá más adelante, que ejecuta StateMachine. Es correcto no declarar que se arroje cuando no es necesario.↩

3. Las subtareas simultáneas se motivaron con la ConfiguredTargetFunction, que realiza trabajos independientes 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 simultaneidad estructurada de Java jeps/428. ↩

6. Esto es similar a generar un subproceso y unirlo para lograr la composición secuencial. ↩