Para obtener documentación sobre versiones estables, usa el menú desplegable "Documentos con versiones". La vista predeterminada refleja la versión más reciente en el encabezado.

Se usó la API de Cloud Translation para traducir esta página.

Cómo crear trabajadores persistentes

Informar un problema Ver fuente

Los trabajadores persistentes pueden hacer que la compilación sea más rápida. Si tienes acciones repetidas en tu compilación que tienen un costo de inicio alto o se beneficiarían del almacenamiento en caché entre acciones, te recomendamos que implementes tu propio trabajador persistente para que realice estas acciones.

El servidor de Bazel se comunica con el trabajador mediante stdin/stdout. Admite el uso de búferes de protocolo o strings JSON.

La implementación de trabajadores consta de dos partes:

El trabajador.
La regla que usa el trabajador.

Cómo hacer que el trabajador

Un trabajador persistente cumple con algunos requisitos:

Lee WorkRequests de su stdin.
Escribe WorkResponses (y solo WorkResponse) en su stdout.
Acepta la marca --persistent_worker. El wrapper debe reconocer la marca de línea de comandos --persistent_worker y solo hacerse persistente si se pasa esa marca; de lo contrario, debe realizar una compilación única y salir.

Si tu programa cumple con estos requisitos, se puede usar como un trabajador persistente.

Solicitudes de trabajo

Un WorkRequest contiene una lista de argumentos para el trabajador, una lista de pares de resumen de ruta de acceso que representan las entradas a las que el trabajador puede acceder (esto no se aplica de manera forzosa, pero puedes usar esta información para el almacenamiento en caché) y un ID de solicitud, que es 0 para los trabajadores singleplex.

NOTA: Si bien la especificación del búfer de protocolo usa "mayúsculas y minúsculas" (request_id), el protocolo JSON usa "mayúsculas mediales" (requestId). En este documento, se usa mayúsculas mediales en los ejemplos de JSON, pero este tipo de letra se usa cuando se habla sobre el campo, sin importar el protocolo.

{
  "arguments" : ["--some_argument"],
  "inputs" : [
    { "path": "/path/to/my/file/1", "digest": "fdk3e2ml23d"},
    { "path": "/path/to/my/file/2", "digest": "1fwqd4qdd" }
 ],
  "requestId" : 12
}

El campo opcional verbosity se puede usar para solicitar una salida de depuración adicional del trabajador. Depende completamente del trabajador qué salida y cómo. Los valores más altos indican un resultado más detallado. Cuando se pasa la marca --worker_verbose a Bazel, se establece el campo verbosity en 10, pero los valores más pequeños o más grandes se pueden usar de forma manual para diferentes cantidades de resultados.

Solo los trabajadores que admiten la zona de pruebas multiplex usan el campo opcional sandbox_dir.

Respuestas de trabajo

Una WorkResponse contiene un ID de solicitud, un código de salida de cero o distinto de cero y una string de salida que describe los errores que se encontraron durante el procesamiento o la ejecución de la solicitud. El campo output contiene una descripción breve. Los registros completos se pueden escribir en el stderr del trabajador. Debido a que los trabajadores solo pueden escribir WorkResponses en stdout, es común que el trabajador redireccione el stdout de las herramientas que usa a stderr.

{
  "exitCode" : 1,
  "output" : "Action failed with the following message:\nCould not find input
    file \"/path/to/my/file/1\"",
  "requestId" : 12
}

Según la norma para los protobufs, todos los campos son opcionales. Sin embargo, Bazel requiere que WorkRequest y el WorkResponse correspondiente tengan el mismo ID de solicitud, por lo que se debe especificar ese ID si no es cero. Este es un WorkResponse válido.

{
  "requestId" : 12,
}

Una request_id de 0 indica una solicitud de “un soloplex”, que se usa cuando esta solicitud no se puede procesar en paralelo con otras solicitudes. El servidor garantiza que un trabajador determinado reciba solicitudes con solo request_id 0 o solo request_id mayor que cero. Las solicitudes singleplex se envían en serie, por ejemplo, si el servidor no envía otra solicitud hasta que recibe una respuesta (excepto las solicitudes de cancelación, consulta a continuación).

Notas

Cada búfer de protocolo está precedido por su longitud en formato varint (consulta MessageLite.writeDelimitedTo().
Las solicitudes y respuestas JSON no están precedidas por un indicador de tamaño.
Las solicitudes JSON mantienen la misma estructura que el protobuf, pero usan JSON estándar y usan mayúsculas mediales para todos los nombres de campos.
Para mantener las mismas propiedades de compatibilidad con versiones anteriores y posteriores que protobuf, los trabajadores de JSON deben tolerar campos desconocidos en estos mensajes y usar los valores predeterminados de protobuf para los valores faltantes.
Bazel almacena solicitudes como protobufs y las convierte a JSON con el formato JSON de protobuf.

Cancelación

De manera opcional, los trabajadores pueden permitir que se cancelen las solicitudes de trabajo antes de finalizar. Esto es particularmente útil en relación con la ejecución dinámica, en la que la ejecución local puede interrumpirse con frecuencia debido a una ejecución remota más rápida. Para permitir la cancelación, agrega supports-worker-cancellation: 1 al campo execution-requirements (consulta a continuación) y configura la marca --experimental_worker_cancellation.

Una solicitud de cancelación es una WorkRequest con el campo cancel configurado (y, de manera similar, una respuesta de cancelación es un WorkResponse con el campo was_cancelled configurado). El otro campo que debe estar en una solicitud de cancelación o en una respuesta de cancelación es request_id, que indica qué solicitud cancelar. El campo request_id será 0 para los trabajadores de un soloplex o el request_id que no sea 0 de un WorkRequest enviado con anterioridad para los trabajadores multiplex. El servidor puede enviar solicitudes de cancelación para solicitudes a las que el trabajador ya respondió. En ese caso, se debe ignorar la solicitud de cancelación.

Cada mensaje WorkRequest que no se cancele debe responderse exactamente una vez, sin importar si se canceló o no. Una vez que el servidor haya enviado una solicitud de cancelación, el trabajador puede responder con una WorkResponse con el request_id configurado y el campo was_cancelled configurado como verdadero. También se acepta el envío de un WorkResponse normal, pero se ignorarán los campos output y exit_code.

Una vez que se envía una respuesta para una WorkRequest, el trabajador no debe tocar los archivos de su directorio de trabajo. El servidor tiene la libertad de limpiar los archivos, incluidos los temporales.

Crea la regla que usa el trabajador

También deberás crear una regla que genere acciones que realizará el trabajador. Crear una regla de Starlark que usa un trabajador es igual que crear cualquier otra regla.

Además, la regla debe contener una referencia al trabajador y existen algunos requisitos para las acciones que produce.

Cómo hacer referencia al trabajador

La regla que usa el trabajador debe contener un campo que haga referencia al trabajador, por lo que deberás crear una instancia de una regla \*\_binary para definirlo. Si tu trabajador se llama MyWorker.Java, esta podría ser la regla asociada:

java_binary(
    name = "worker",
    srcs = ["MyWorker.Java"],
)

Esto crea la etiqueta "worker", que hace referencia al objeto binario de trabajador. Luego, deberás definir una regla que use al trabajador. Esta regla debe definir un atributo que haga referencia al objeto binario del trabajador.

Si el objeto binario de trabajador que compilaste está en un paquete llamado "work", que se encuentra en el nivel superior de la compilación, esta podría ser la definición del atributo:

"worker": attr.label(
    default = Label("//work:worker"),
    executable = True,
    cfg = "exec",
)

cfg = "exec" indica que el trabajador debe compilarse para ejecutarse en la plataforma de ejecución en lugar de en la plataforma de destino (es decir, el trabajador se usa como herramienta durante la compilación).

Requisitos de las acciones de trabajo

La regla que usa el trabajador crea acciones para que este las realice. Estas acciones tienen algunos requisitos.

El campo "arguments". Con esta acción, se toma una lista de cadenas, excepto la última, argumentos que se pasan al trabajador al inicio. El último elemento de la lista de "argumentos" es un argumento flag-file (@-preceded). Los trabajadores leen los argumentos del archivo marcador especificado por WorkRequest. La regla puede escribir argumentos que no sean de inicio para el trabajador en este archivo marcador.
El campo "execution-requirements", que incluye un diccionario que contiene "supports-workers" : "1", "supports-multiplex-workers" : "1" o ambos.

Los campos “arguments” y “execution-requirements” son obligatorios para todas las acciones que se envían a los trabajadores. Además, las acciones que deben ejecutar los trabajadores de JSON deben incluir "requires-worker-protocol" : "json" en el campo de requisitos de ejecución. "requires-worker-protocol" : "proto" también es un requisito de ejecución válido, aunque no es necesario para los trabajadores de proto, ya que son los predeterminados.

También puedes establecer un worker-key-mnemonic en los requisitos de ejecución. Esto puede ser útil si reutilizas el ejecutable para varios tipos de acciones y deseas distinguir las acciones de este trabajador.
Los archivos temporales generados durante la acción deben guardarse en el directorio del trabajador. Esto habilita la zona de pruebas.

Si suponemos una definición de regla con un atributo “worker” descrito anteriormente, además de un atributo “srcs” que representa las entradas, un atributo “output” que representa las salidas y un atributo “args” que representa los argumentos de inicio del trabajador, la llamada a ctx.actions.run podría ser la siguiente:

ctx.actions.run(
  inputs=ctx.files.srcs,
  outputs=[ctx.outputs.output],
  executable=ctx.executable.worker,
  mnemonic="someMnemonic",
  execution_requirements={
    "supports-workers" : "1",
    "requires-worker-protocol" : "json"},
  arguments=ctx.attr.args + ["@flagfile"]
 )

Para ver otro ejemplo, consulta Implementa trabajadores persistentes.

Ejemplos

La base de código de Bazel usa trabajadores del compilador de Java, además de un trabajador JSON de ejemplo que se usa en nuestras pruebas de integración.

Puedes usar su andamiaje para convertir cualquier herramienta basada en Java en un trabajador si pasas la devolución de llamada correcta.

Para ver un ejemplo de una regla que usa un trabajador, consulta la prueba de integración de trabajadores de Bazel.

Los colaboradores externos implementaron trabajadores en una variedad de lenguajes. Consulta las implementaciones de Polyglot de trabajadores persistentes de Bazel. Puedes encontrar muchos más ejemplos en GitHub.