Los trabajadores persistentes pueden acelerar tu compilación. Si tienes acciones repetidas en tu compilación que tienen un costo de inicio alto o que se beneficiarían del almacenamiento en caché entre acciones, es posible que desees implementar tu propio trabajador persistente para realizar estas acciones.
El servidor de Bazel se comunica con el trabajador mediante stdin/stdout. Admite
el uso de búferes de protocolo o cadenas JSON.
La implementación del trabajador tiene dos partes:
Cómo crear el trabajador
Un trabajador persistente cumple con algunos requisitos:
- Lee
WorkRequests
de su
stdin. - Escribe
WorkResponses
(y solo
WorkResponses) en sustdout. - Acepta la marca
--persistent_worker. El wrapper debe reconocer la--persistent_workermarca de línea de comandos y solo volverse 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 trabajador persistente .
Solicitudes de trabajo
Un WorkRequest contiene una lista de argumentos para el trabajador, una lista de
pares de ruta de acceso y resumen que representan las entradas a las que puede acceder el trabajador (esto no se
aplica, pero puedes usar esta información para el almacenamiento en caché) y un ID de solicitud, que es 0
para los trabajadores de un solo proceso.
NOTA: Si bien la especificación del búfer de protocolo usa "snake case" (request_id),
el protocolo JSON usa "camel case" (requestId). En este documento, se usa camel case
en los ejemplos de JSON, pero snake case cuando se habla del campo, independientemente del
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 verbosity opcional se puede usar para solicitar una salida de depuración adicional
del trabajador. Depende completamente del trabajador qué y cómo generar la salida. Los valores
más altos indican una salida más detallada. Si pasas la marca --worker_verbose a
Bazel, se establece el campo verbosity en 10, pero se pueden usar valores más pequeños o más grandes de forma
manual para diferentes cantidades de salida.
El campo sandbox_dir opcional solo lo usan los trabajadores que admiten
el aislamiento de procesos múltiples.
Respuestas de trabajo
Un WorkResponse contiene un ID de solicitud, un código de salida cero o distinto de cero y un
mensaje de salida que describe los errores que se produjeron durante el procesamiento o la ejecución
de la solicitud. Un trabajador debe capturar el stdout y el stderr de cualquier herramienta a la que
llame y notificarlos a través del WorkResponse. Escribirlo en el stdout de
l proceso de trabajo no es seguro, ya que interferirá con el protocolo de trabajo.
Escribirlo en el stderr del proceso de trabajo es seguro, pero el resultado se
recopila en un archivo de registro por trabajador en lugar de atribuirse a acciones individuales.
{
"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 búferes de protocolo, 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 el ID de solicitud si es distinto de cero. Este es un válido
WorkResponse.
{
"requestId" : 12,
}
Un request_id de 0 indica una solicitud "singleplex", 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 de un solo proceso 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 más abajo).
Notas
- Cada búfer de protocolo está precedido por su longitud en
varintformato (consultaMessageLite.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 búfer de protocolo, pero usan JSON estándar y camel case para todos los nombres de los campos.
- Para mantener las mismas propiedades de compatibilidad hacia atrás y hacia adelante que el búfer de protocolo, los trabajadores JSON deben tolerar campos desconocidos en estos mensajes, y usar los valores predeterminados del búfer de protocolo para los valores faltantes.
- Bazel almacena las solicitudes como búferes de protocolo y las convierte a JSON con el formato JSON del búfer de protocolo.
Cancelación
De manera opcional, los trabajadores pueden permitir que se cancelen las solicitudes de trabajo antes de que finalicen.
Esto es particularmente útil en relación con la ejecución dinámica, en la que la ejecución local
puede interrumpirse con regularidad mediante una ejecución remota más rápida. Para permitir
la cancelación, agrega supports-worker-cancellation: 1 al
execution-requirements campo (consulta más abajo) y establece la
--experimental_worker_cancellation marca.
Una solicitud de cancelación es un WorkRequest con el campo cancel establecido (y
de manera similar, una respuesta de cancelación es un WorkResponse con el campo was_cancelled
establecido). El único otro campo que debe estar en una solicitud de cancelación o respuesta de cancelación es request_id, que indica qué solicitud cancelar. El request_id
campo será 0 para los trabajadores de un solo proceso o el request_id distinto de 0 de un WorkRequest enviado anteriormente
para los trabajadores de procesos múltiples. El servidor puede enviar solicitudes de cancelación
para las solicitudes a las que el trabajador ya respondió, en cuyo caso se debe ignorar la solicitud de cancelación.
Cada mensaje que no sea de cancelación WorkRequest debe responderse exactamente una vez, ya sea que
se haya cancelado o no. Una vez que el servidor haya enviado una solicitud de cancelación, el trabajador puede
responder con un WorkResponse con el request_id establecido y el was_cancelled
campo establecido en verdadero. También se acepta enviar un WorkResponse normal, pero se ignorarán los campos
output y exit_code.
Una vez que se envía una respuesta para un WorkRequest, el trabajador no debe tocar los
archivos en su directorio de trabajo. El servidor puede limpiar los archivos,
incluidos los archivos temporales.
Cómo crear la regla que usa el trabajador
También deberás crear una regla que genere acciones para que las realice el trabajador. Crear una regla de Starlark que use un trabajador es como crear cualquier otra regla.
Además, la regla debe contener una referencia al trabajador en sí, 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
en sí, por lo que deberás crear una instancia de una regla \*\_binary para definir
tu trabajador. 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 del trabajador. Luego, definirás una regla que use el trabajador. Esta regla debe definir un atributo que haga referencia al objeto binario del trabajador.
Si el objeto binario del 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 tu
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 la acción de trabajo
La regla que usa el trabajador crea acciones para que las realice el trabajador. Estas acciones tienen un par de requisitos.
El campo "arguments". Esto toma una lista de cadenas, todas menos la última, que son argumentos que se pasan al trabajador cuando se inicia. El último elemento en la lista "arguments" es un
flag-fileargumento (precedido por @). Los trabajadores leen los argumentos del archivo de marcas especificado por WorkRequest. Tu regla puede escribir argumentos que no sean de inicio para el trabajador en este archivo de marcas.El campo "execution-requirements", que toma 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 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 obligatorio para los trabajadores de proto, ya que son los predeterminados.También puedes establecer un
worker-key-mnemonicen 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 el aislamiento de procesos.
Si se supone una definición de regla con el 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 Cómo implementar 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 scaffolding para convertir cualquier herramienta basada en Java en un trabajador pasando la devolución de llamada correcta.
Para ver un ejemplo de una regla que usa un trabajador, consulta la prueba de integración del trabajador de Bazel .
Los colaboradores externos implementaron trabajadores en una variedad de lenguajes. Consulta Implementaciones políglotas de trabajadores persistentes de Bazel. Puedes encontrar muchos más ejemplos en GitHub.