Um guia para StateMachines do Skyframe

Informar um problema Ver código-fonte Nightly · 7.4 . 7.3 · 7.2 · 7.1 · 7.0 · 6.5

Visão geral

Um StateMachine do Skyframe é um objeto de função desmontada que reside na pilha. Ele oferece suporte a avaliação flexível sem redundância¹ quando os valores necessários não estão disponíveis imediatamente, mas são calculados de forma assíncrona. O StateMachine não pode vincular um recurso de linha de execução enquanto aguarda, mas precisa ser suspenso e retomado. A desconstrução expõe pontos de reentrada explícitos para que as computações anteriores possam ser puladas.

StateMachines podem ser usados para expressar sequências, ramificações, consistência lógica estruturada e são adaptados especificamente para a interação do Skyframe. StateMachines podem ser compostos em StateMachines maiores e compartilhar sub-StateMachines. A simultaneidade é sempre hierárquica por construção e pura e simplesmente lógica. Cada subtarefa simultânea é executada na única linha de execução SkyFunction compartilhada.

Introdução

Esta seção motiva e introduz brevemente as StateMachines, encontradas no pacote java.com.google.devtools.build.skyframe.state.

Uma breve introdução às reinicializações do Skyframe

O Skyframe é um framework que realiza a avaliação paralela de gráficos de dependência. Cada nó no gráfico corresponde à avaliação de uma SkyFunction com uma SkyKey que especifica os parâmetros e a SkyValue que especifica o resultado. O modelo computacional é de tal forma que uma SkyFunction pode procurar SkyValues por SkyKey, acionando a avaliação paralela e recursiva de outras SkyFunctions. Em vez de bloquear, o que ocuparia uma linha de execução, quando um SkyValue solicitado ainda não estiver pronto porque algum subgrafo de computação está incompleto, a SkyFunction solicitante observa uma resposta getValue null e precisa retornar null em vez de um SkyValue, indicando que ele está incompleto devido a entradas ausentes. O Skyframe reinicia as SkyFunctions quando todos os SkyValues solicitados anteriormente ficam disponíveis.

Antes da introdução de SkyKeyComputeState, a maneira tradicional de lidar com uma reinicialização era executar a computação novamente. Embora isso tenha complexidade quadrada, as funções gravadas dessa maneira são concluídas porque, a cada nova execução, menos pesquisas retornam null. Com SkyKeyComputeState, é possível associar dados de verificação especificados manualmente a uma SkyFunction, economizando uma recomputação significativa.

StateMachines são objetos que ficam dentro de SkyKeyComputeState e eliminam praticamente toda a recomputação quando uma SkyFunction é reiniciada (assumindo que SkyKeyComputeState não sai do cache) expondo ganchos de execução de suspensão e retomada.

Cálculos com estado dentro de SkyKeyComputeState

Do ponto de vista do design orientado a objetos, faz sentido armazenar objetos computacionais dentro de SkyKeyComputeState em vez de valores de dados puros. Em Java, a descrição mínima de um objeto que carrega um comportamento é uma interface funcional e acaba sendo suficiente. Um StateMachine tem a seguinte definição curiosamente recursiva².

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

A interface Tasks é análoga a SkyFunction.Environment, mas foi projetada para assíncrono e adiciona suporte a subtarefas logicamente simultâneas³.

O valor de retorno de step é outro StateMachine, permitindo a especificação de uma sequência de etapas, indutivamente. step retorna DONE quando o StateMachine é concluído. Exemplo:

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;
  }
}

descreve um StateMachine com a saída a seguir.

hello
world

A referência de método this::step2 também é um StateMachine porque step2 atende à definição de interface funcional de StateMachine. As referências de método são a maneira mais comum de especificar o próximo estado em um StateMachine.

Intuitivamente, dividir uma computação em etapas StateMachine, em vez de uma função monolítica, fornece os hooks necessários para suspender e retomar uma computação. Quando StateMachine.step retorna, há um ponto de suspensão explícito. A continuação especificada pelo valor StateMachine retornado é um ponto de reinício explícito. A recomputação pode ser evitada porque a computação pode ser retomada exatamente de onde parou.

Callbacks, continuações e computação assíncrona

Em termos técnicos, um StateMachine serve como uma continuação, determinando a computação subsequente a ser executada. Em vez de bloquear, um StateMachine pode suspender voluntariamente retornando da função step, que transfere o controle de volta para uma instância Driver. O Driver pode mudar para um StateMachine pronto ou devolver o controle ao Skyframe.

Tradicionalmente, callbacks e continuações são mesclados em um conceito. No entanto, os StateMachines mantêm uma distinção entre os dois.

• Callback: descreve onde armazenar o resultado de uma computação assíncrona.
• Continuação: especifica o próximo estado de execução.

Os callbacks são necessários ao invocar uma operação assíncrona, o que significa que a operação real não ocorre imediatamente após a chamada do método, como no caso de uma pesquisa SkyValue. Os callbacks precisam ser mantidos o mais simples possível.

Cuidado: uma armadilha comum de callbacks é que a computação assíncrona precisa garantir que o callback seja chamado no final de cada caminho acessível. É possível ignorar algumas ramificações, e o compilador não emite avisos sobre isso.

As continuações são os valores de retorno StateMachine de StateMachines e encapsulam a execução complexa que ocorre depois que todas as computações assinháticas são resolvidas. Essa abordagem estruturada ajuda a manter a complexidade dos callbacks gerenciável.

Tarefas

A interface Tasks fornece StateMachines com uma API para pesquisar SkyValues por SkyKey e programar subtarefas 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.
}

Dica: quando qualquer estado usa a interface Tasks para realizar pesquisas ou criar subtarefas, essas pesquisas e subtarefas são concluídas antes do início do próximo estado.

Dica: (corolário) se as subtarefas forem StateMachines complexas ou criarem subtarefas recursivamente, todas elas serão transitivamente concluídas antes do início do próximo estado.

Consultas SkyValue

Os StateMachines usam sobrecargas de Tasks.lookUp para procurar SkyValues. Elas são análogas a SkyFunction.Environment.getValue e SkyFunction.Environment.getValueOrThrow e têm semântica de processamento de exceções semelhante. A implementação não executa a pesquisa imediatamente, mas em vez disso, agrupa⁴ o máximo de pesquisas possível antes de fazer isso. O valor pode não estar disponível imediatamente, por exemplo, exigindo uma reinicialização do Skyframe, para que o autor da chamada especifique o que fazer com o valor resultante usando um callback.

O processador StateMachine (Drivers e ponte para SkyFrame) garante que o valor esteja disponível antes do início do próximo estado. Confira um exemplo.

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;
  }
}

No exemplo acima, a primeira etapa faz uma pesquisa de new Key(), transmitindo this como consumidor. Isso é possível porque DoesLookup implementa Consumer<SkyValue>.

Dica: ao transmitir this como um valor de destino, é útil para os leitores fazer o upcast para o tipo do receptor para restringir o propósito da transmissão de this. O exemplo transmite (Consumer<SkyValue>) this.

Por contrato, antes que o próximo estado DoesLookup.processValue seja iniciado, todas as pesquisas de DoesLookup.step são concluídas. Portanto, value está disponível quando é acessado em processValue.

Subtarefas

Tasks.enqueue solicita a execução de subtarefas logicamente simultâneas. As subtarefas também são StateMachines e podem fazer tudo o que StateMachines normais podem fazer, incluindo a criação recursiva de mais subtarefas ou a pesquisa de SkyValues. Assim como lookUp, o driver da máquina de estado garante que todas as subtarefas sejam concluídas antes de prosseguir para a próxima etapa. Confira um exemplo.

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

Embora Subtask1 e Subtask2 sejam logicamente concorrentes, tudo é executado em uma única linha de execução. Portanto, a atualização "concorrente" de i não precisa de sincronização.

Simultaneidade estruturada

Como cada lookUp e enqueue precisa ser resolvido antes de avançar para o próximo estado, isso significa que a simultaneidade é naturalmente limitada a estruturas em árvore. É possível criar concorrência hierárquica⁵, conforme mostrado no exemplo a seguir.

É difícil dizer, com base no UML, que a estrutura de simultaneidade forma uma árvore. Há uma visualização alternativa que mostra melhor a estrutura da árvore.

A simultaneidade estruturada é muito mais fácil de entender.

Composição e padrões de fluxo de controle

Esta seção apresenta exemplos de como vários StateMachines podem ser compostos e soluções para determinados problemas de fluxo de controle.

Estados sequenciais

Esse é o padrão de fluxo de controle mais comum e simples. Um exemplo disso é mostrado em Cálculos com estado dentro de SkyKeyComputeState.

Ramificação

É possível alcançar estados de ramificação em StateMachines retornando valores diferentes usando o fluxo de controle Java normal, conforme mostrado no exemplo abaixo.

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;
  }
  …
}

É muito comum que algumas ramificações retornem DONE para a conclusão antecipada.

Composição sequencial avançada

Como a estrutura de controle StateMachine não tem memória, compartilhar definições de StateMachine como subtarefas pode ser estranho. Vamos supor que M₁ e M₂ sejam instâncias StateMachine que compartilham um StateMachine, S, com M₁ e M₂ sendo as sequências <A, S, B> e <X, S, Y>, respectivamente. O problema é que S não sabe se deve continuar para B ou Y após a conclusão, e StateMachines não mantêm uma pilha de chamadas. Esta seção analisa algumas técnicas para fazer isso.

StateMachine como elemento de sequência terminal

Isso não resolve o problema inicial apresentado. Ele só demonstra a composição sequencial quando o StateMachine compartilhado é terminal na sequência.

// 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();
  }
}

Isso funciona mesmo que S seja uma máquina de estados complexa.

Subtarefa para composição sequencial

Como as subtarefas enfileiradas são concluídas antes do próximo estado, às vezes é possível abusar um pouco do mecanismo de subtarefas.⁶

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;
  }
}

Injeção de runAfter

Às vezes, é impossível abusar de Tasks.enqueue porque há outras subtarefas paralelas ou chamadas Tasks.lookUp que precisam ser concluídas antes que S seja executado. Nesse caso, injetar um parâmetro runAfter em S pode ser usado para informar a S o que fazer a seguir.

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;
  }
}

Essa abordagem é mais limpa do que abusar das subtarefas. No entanto, aplicar isso de forma muito liberal, por exemplo, aninhando vários StateMachines com runAfter, é o caminho para o inferno de callbacks. É melhor dividir runAfters sequenciais com estados sequenciais comuns.

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

pode ser substituído pelo seguinte.

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

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

Observação: é possível transmitir DONE como o parâmetro runAfter quando não há nada a ser executado depois.

Dica: ao usar runAfter, sempre anote o parâmetro com /* runAfter= */ para que o leitor saiba o significado no local da chamada.

Alternativa proibida: runAfterUnlessError

Em um rascunho anterior, consideramos um runAfterUnlessError que abortaria antes dos erros. Isso foi motivado pelo fato de que os erros geralmente são verificados duas vezes, uma pelo StateMachine que tem uma referência runAfter e outra pela própria máquina runAfter.

Depois de algumas deliberações, decidimos que a uniformidade do código é mais importante do que a duplicação da verificação de erros. Seria confuso se o mecanismo runAfter não funcionasse de maneira consistente com o mecanismo tasks.enqueue, que sempre exige a verificação de erros.

Aviso: ao usar runAfter, a máquina que tem o runAfter injetado precisa invocá-lo incondicionalmente após a conclusão, mesmo em caso de erro, para manter a consistência.

Delegação direta

Sempre que há uma transição formal de estado, o loop principal de Driver avança. De acordo com o contrato, o avanço de estados significa que todas as pesquisas e subtarefas da SkyValue anteriormente enfileiradas são resolvidas antes da execução do próximo estado. Às vezes, a lógica de um StateMachine delegado torna um avanço de fase desnecessário ou contraproducente. Por exemplo, se a primeira step do delegado realizar pesquisas da SkyKey que podem ser paralelas às pesquisas do estado de delegação, um avanço de fase as tornará sequenciais. Pode ser mais sensato realizar a delegação direta, conforme mostrado no exemplo abaixo.

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;
  }
}

Fluxo de dados

O foco da discussão anterior foi gerenciar o fluxo de controle. Esta seção descreve a propagação de valores de dados.

Implementação de callbacks Tasks.lookUp

Há um exemplo de implementação de um callback Tasks.lookUp em pesquisas SkyValue. Esta seção fornece o raciocínio e sugere abordagens para processar vários SkyValues.

Callbacks Tasks.lookUp

O método Tasks.lookUp usa um callback, sink, como parâmetro.

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

A abordagem idiomática seria usar uma lambda Java para implementar isso:

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

em que myValue é uma variável de membro da instância StateMachine que faz a pesquisa. No entanto, o lambda requer uma alocação de memória extra em comparação com a implementação da interface Consumer<SkyValue> na implementação StateMachine. A lambda ainda é útil quando há várias pesquisas que seriam ambíguas.

Observação: aviso de bikeshed. Há uma diferença notável de aproximadamente 1% no uso da CPU de ponta a ponta ao implementar callbacks sistematicamente em implementações de StateMachine em comparação com o uso de lambdas, o que torna essa recomendação discutível. Para evitar debates desnecessários, é recomendável deixar a decisão para a pessoa que implementa a solução.

Há também sobrecargas de tratamento de erros de Tasks.lookUp, que são 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);
  }

Confira um exemplo de implementação abaixo.

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

Assim como nas pesquisas sem tratamento de erros, ter a classe StateMachine diretamente implementando o callback economiza uma alocação de memória para o lamba.

O tratamento de erros fornece um pouco mais de detalhes, mas, basicamente, não há muita diferença entre a propagação de erros e os valores normais.

Como consumir vários SkyValues

Muitas vezes, são necessárias várias pesquisas de SkyValue. Uma abordagem que funciona na maior parte do tempo é ativar o tipo de SkyValue. Confira a seguir um exemplo simplificado do código de produção do protótipo.

  @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);
  }

A implementação do callback Consumer<SkyValue> pode ser compartilhada de forma inequívoca porque os tipos de valor são diferentes. Caso contrário, é possível usar implementações baseadas em lambda ou instâncias de classe interna completas que implementam os callbacks apropriados.

Como propagar valores entre StateMachines

Até agora, este documento explicou apenas como organizar o trabalho em uma subtarefa, mas as subtarefas também precisam informar valores ao autor da chamada. Como as subtarefas são logicamente assíncronas, os resultados delas são comunicados de volta ao autor da chamada usando um callback. Para que isso funcione, a subtarefa define uma interface de sink que é injetada pelo construtor.

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;
  }
}

Dica: seria tentador usar a assinatura void accept(Bar value) mais concisa em vez da void acceptBarValue(Bar value) acima. No entanto, Consumer<SkyValue> é uma sobrecarga comum de void accept(Bar value), então isso geralmente leva a violações da regra do style guide Overloads: never split.

Dica: usar um tipo ResultSink personalizado em vez de um genérico de java.util.function facilita a localização de implementações na base de código, melhorando a legibilidade.

Um autor da chamada StateMachine vai ficar assim:

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;
  }
}

O exemplo anterior demonstra algumas coisas. O Caller precisa propagar os resultados de volta e definir o próprio Caller.ResultSink. Caller implementa os callbacks BarProducer.ResultSink. Após a retomada, processResult verifica se value é nulo para determinar se ocorreu um erro. Esse é um padrão de comportamento comum após aceitar a saída de uma pesquisa de subtarefa ou SkyValue.

A implementação de acceptBarError encaminha o resultado para Caller.ResultSink, conforme exigido pelo bolhamento de erros.

As alternativas para StateMachines de nível superior são descritas em Drivers e pontes para SkyFunctions.

Tratamento de erros

Há alguns exemplos de processamento de erros em chamadas de Tasks.lookUp e Propagação de valores entre StateMachines. As exceções, com exceção de InterruptedException, não são geradas, mas transmitidas por callbacks como valores. Esses callbacks geralmente têm semântica exclusiva, com exatamente um valor ou erro sendo transmitido.

A próxima seção descreve uma interação sutil, mas importante, com o processamento de erros do Skyframe.

Erro de bubbling (--nokeep_going)

Aviso: os erros precisam ser propagados com anseio até a SkyFunction para que o bubbling de erros funcione corretamente.

Durante a propagação de erros, uma SkyFunction pode ser reiniciada mesmo que nem todos os SkyValues solicitados estejam disponíveis. Nesses casos, o estado subsequente nunca será atingido devido ao contrato da API Tasks. No entanto, o StateMachine ainda precisa propagar a exceção.

Como a propagação precisa ocorrer independentemente de o próximo estado ser alcançado, o callback de tratamento de erros precisa realizar essa tarefa. Para um StateMachine interno, isso é feito invocando o callback pai.

No StateMachine de nível superior, que interage com a SkyFunction, isso pode ser feito chamando o método setException de ValueOrExceptionProducer. ValueOrExceptionProducer.tryProduceValue vai gerar a exceção, mesmo se houver SkyValues ausentes.

Se um Driver estiver sendo usado diretamente, é essencial verificar erros propagados da SkyFunction, mesmo que a máquina não tenha terminado o processamento.

Tratamento de eventos

Para SkyFunctions que precisam emitir eventos, um StoredEventHandler é injetado no SkyKeyComputeState e injetado em StateMachines que os exigem. Historicamente, o StoredEventHandler era necessário devido ao Skyframe descartar alguns eventos, a menos que eles fossem reproduzidos, mas isso foi corrigido posteriormente. A injeção de StoredEventHandler é preservada porque simplifica a implementação de eventos emitidos de callbacks de tratamento de erros.

Drivers e ponte para SkyFunctions

Um Driver é responsável por gerenciar a execução de StateMachines, começando com um StateMachine raiz especificado. Como as StateMachines podem colocar StateMachines de subtarefas na fila de forma recursiva, uma única Driver pode gerenciar várias subtarefas. Essas subtarefas criam uma estrutura em árvore, um resultado da Simultaneidade estruturada. O Driver agrupa as pesquisas de SkyValue em subtarefas para melhorar a eficiência.

Há várias classes criadas em torno do Driver, com a API a seguir.

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

Driver usa um único StateMachine raiz como parâmetro. A chamada Driver.drive executa o StateMachine o máximo possível sem uma reinicialização do Skyframe. Ele retorna verdadeiro quando o StateMachine é concluído e falso caso contrário, indicando que nem todos os valores estavam disponíveis.

O Driver mantém o estado simultâneo do StateMachine e é adequado para incorporação em SkyKeyComputeState.

Instância direta de Driver

As implementações de StateMachine normalmente comunicam os resultados por callback. É possível instanciar diretamente uma Driver, conforme mostrado no exemplo abaixo.

O Driver é incorporado à implementação do SkyKeyComputeState com uma implementação do ResultSink correspondente a ser definida um pouco mais abaixo. No nível superior, o objeto State é um receptor adequado para o resultado da computação, porque é garantido que ele vai sobreviver 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;
  }
}

O código abaixo mostra o 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;
  }
}

O código para calcular o resultado de maneira lenta pode ficar assim:

@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;
}

Incorporação de Driver

Se o StateMachine produzir um valor e não gerar exceções, a incorporação de Driver será outra implementação possível, conforme mostrado no exemplo a seguir.

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

A SkyFunction pode ter um código semelhante ao seguinte (em que State é o tipo específico de função 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;
}

A incorporação de Driver na implementação de StateMachine é mais adequada para o estilo de programação síncrona do Skyframe.

StateMachines que podem produzir exceções

Caso contrário, há ValueOrExceptionProducer e ValueOrException2Producer SkyKeyComputeState-embeddable que têm APIs síncronas para corresponder ao código síncrono da SkyFunction.

A classe abstrata ValueOrExceptionProducer inclui os seguintes 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. }
}

Ele inclui uma instância Driver incorporada e se assemelha muito à classe ResultProducer em Inserção de driver e se comunica com a SkyFunction de maneira semelhante. Em vez de definir um ResultSink, as implementações chamam setValue ou setException quando uma delas ocorre. Quando ambos ocorrem, a exceção tem prioridade. O método tryProduceValue faz a ponte entre o código de callback assíncrono e o código síncrono e gera uma exceção quando um é definido.

Como observado anteriormente, durante a propagação de erros, é possível que um erro ocorra mesmo que a máquina ainda não tenha sido concluída, porque nem todas as entradas estão disponíveis. Para acomodar isso, tryProduceValue gera exceções definidas, mesmo antes de a máquina terminar.

Epílogo: como remover callbacks

Os StateMachines são uma maneira altamente eficiente, mas com boilerplate intensivo, de realizar computação assíncrona. As continuações (principalmente na forma de Runnables transmitidos para ListenableFuture) são comuns em determinadas partes do código do Bazel, mas não são predominantes nas SkyFunctions de análise. A análise é principalmente vinculada à CPU e não há APIs assíncronas eficientes para E/S de disco. Eventualmente, seria bom otimizar os callbacks, já que eles têm uma curva de aprendizado e impedem a legibilidade.

Uma das alternativas mais promissoras é a linha de execução virtual do Java. Em vez de precisar escrever callbacks, tudo é substituído por chamadas síncronas e bloqueantes. Isso é possível porque vincular um recurso de linha de execução virtual, ao contrário de uma linha de execução da plataforma, deve ser barato. No entanto, mesmo com linhas de execução virtuais, substituir operações síncronas simples por primitivas de criação e sincronização de linhas de execução é muito caro. Realizamos uma migração de StateMachines para linhas de execução virtuais do Java, e elas eram ordens de magnitude mais lentas, levando a quase um aumento de três vezes na latência da análise de ponta a ponta. Como as linhas de execução virtuais ainda são um recurso de visualização, é possível que essa migração seja realizada em uma data posterior, quando o desempenho melhorar.

Outra abordagem a ser considerada é esperar pelas corrotinas Loom, se elas ficarem disponíveis. A vantagem aqui é que pode ser possível reduzir a sobrecarga de sincronização usando multitarefa cooperativa.

Se tudo mais falhar, a reescrita de bytecode de baixo nível também pode ser uma alternativa viável. Com otimização suficiente, talvez seja possível alcançar um desempenho próximo ao código de callback escrito manualmente.

Apêndice

Callback Hell

O inferno de callbacks é um problema notório em código assíncrono que usa callbacks. Isso ocorre porque a continuação de uma etapa subsequente é aninhada na etapa anterior. Se houver muitas etapas, esse aninhamento pode ser extremamente profundo. Se combinado com o fluxo de controle, o código se torna incontrolável.

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

Uma das vantagens das implementações aninhadas é que o frame da pilha da etapa externa pode ser preservado. Em Java, as variáveis lambda capturadas precisam ser efetivamente finais, portanto, o uso dessas variáveis pode ser complicado. O aninhamento profundo é evitado retornando referências de método como continuações em vez de lambdas, como mostrado abaixo.

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;
  }
}

O inferno de callbacks também pode ocorrer se o padrão de injeção de runAfter for usado com muita densidade, mas isso pode ser evitado intercalando injeções com etapas sequenciais.

Exemplo: pesquisas SkyValue conectadas

Muitas vezes, a lógica do aplicativo exige cadeias dependentes de pesquisas de SkyValue, por exemplo, se uma segunda SkyKey depende da primeira SkyValue. Pensando nisso de forma simplista, isso resultaria em uma estrutura de callback complexa e profundamente aninhada.

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;
}

No entanto, como as continuações são especificadas como referências de método, o código parece procedural em todas as transições de estado: step2 segue step1. Aqui, uma lambda é usada para atribuir value2. Isso faz com que a ordem do código corresponda à ordem da computação de cima para baixo.

Dicas gerais

Legibilidade: ordem de execução

Para melhorar a legibilidade, procure manter as implementações StateMachine.step na ordem de execução e as implementações de callback imediatamente após o local em que são transmitidas no código. Isso nem sempre é possível quando o fluxo de controle se ramifica. Nesses casos, comentários adicionais podem ser úteis.

No Exemplo: pesquisas de SkyValue conectadas, uma referência de método intermediária é criada para fazer isso. Isso troca uma pequena quantidade de desempenho pela legibilidade, o que provavelmente vale a pena aqui.

Hipótese de geração

Objetos Java de vida média quebram a hipótese de geração do coletor de lixo do Java, que foi projetado para processar objetos que vivem por um tempo muito curto ou que vivem para sempre. Por definição, os objetos em SkyKeyComputeState violam essa hipótese. Esses objetos, que contêm a árvore construída de todos os StateMachines ainda em execução, com raiz em Driver, têm uma vida útil intermediária à medida que são suspensos, aguardando a conclusão de cálculos assíncronos.

Parece menos ruim no JDK19, mas, ao usar StateMachines, às vezes é possível observar um aumento no tempo de GC, mesmo com reduções drásticas no lixo gerado. Como os StateMachines têm uma vida útil intermediária, eles podem ser promovidos para a geração antiga, fazendo com que ela se encha mais rapidamente, necessitando de GCs principais ou completos mais caros para limpar.

A precaução inicial é minimizar o uso de variáveis StateMachine, mas nem sempre é viável, por exemplo, se um valor for necessário em vários estados. Quando possível, as variáveis step da pilha local são variáveis de geração jovem e são GC de forma eficiente.

Para variáveis StateMachine, também é útil dividir as tarefas em subtarefas e seguir o padrão recomendado para propagar valores entre StateMachines. Observe que, ao seguir o padrão, apenas StateMachines filhos têm referências a StateMachines pais, e não vice-versa. Isso significa que, à medida que os filhos concluem e atualizam os pais usando callbacks de resultado, eles naturalmente saem do escopo e se tornam qualificados para GC.

Por fim, em alguns casos, uma variável StateMachine é necessária em estados anteriores, mas não em estados posteriores. Pode ser benéfico anular as referências de objetos grandes quando se sabe que elas não são mais necessárias.

Como nomear estados

Ao nomear um método, geralmente é possível nomear um método para o comportamento que ocorre nesse método. Não está claro como fazer isso em StateMachines porque não há pilha. Por exemplo, suponha que o método foo chame um submétodo bar. Em um StateMachine, isso pode ser traduzido para a sequência de estado foo, seguida por bar. foo não inclui mais o comportamento bar. Como resultado, os nomes de método para estados tendem a ter um escopo mais estreito, refletindo potencialmente o comportamento local.

Diagrama de árvore de simultaneidade

Confira a seguir uma visualização alternativa do diagrama em Concorrência estruturada que descreve melhor a estrutura da árvore. Os blocos formam uma pequena árvore.

---

1. Em contraste com a convenção do Skyframe de reiniciar do início quando os valores não estão disponíveis. ↩

2. step pode gerar InterruptedException, mas os exemplos omitem isso. Há alguns métodos de baixo nível no código do Bazel que geram essa exceção e a propagam até o Driver, que será descrito mais adiante, que executa o StateMachine. Não é necessário declarar que ele será gerado quando não for necessário. ↩

3. As subtarefas simultâneas foram motivadas pelo ConfiguredTargetFunction, que realiza trabalhos independentes para cada dependência. Em vez de manipular estruturas de dados complexas que processam todas as dependências de uma só vez, introduzindo ineficiências, cada dependência tem o próprio StateMachine independente. ↩

4. Várias chamadas tasks.lookUp em uma única etapa são agrupadas. É possível criar mais lotes com pesquisas que ocorrem em subtarefas simultâneas. ↩

5. Isso é conceitualmente semelhante à simultaneidade estruturada do Java jeps/428. ↩

6. Isso é semelhante a gerar uma linha de execução e mesclar para alcançar a composição sequencial. ↩