Kalıcı Çalışanlar Oluşturma

Sorun bildirin Kaynağı göster Gece · 7,4 , 7.3 · 7,2 · 7,1 · 7,0 · 6,5

Kalıcı çalışanlar, derlemenizi hızlandırabilir. Eğer derlemenizde başlangıç maliyeti yüksek olan veya yüklenmeye yol açan işlemler alanlar arası önbelleğe alma özelliğinden yararlanıyorsanız, kendi kalıcı çalışanın bu işlemleri yapmasını sağlar.

Bazel sunucusu, çalışanla stdin/stdout üzerinden iletişim kurar. Google protokol arabelleklerinin veya JSON dizelerinin kullanımını destekler.

İşçi uygulaması iki bölümden oluşur:

Çalışanı oluşturma

Kalıcı çalışanlar birkaç koşulu karşılamalıdır:

  • Okuyor WorkRequests stdin ile başlayan fiyatlarla!
  • WorkResponses (ve yalnızca WorkResponse öğeleri) stdout alanına yazılır.
  • --persistent_worker işaretini kabul eder. Sarmalayıcı, --persistent_worker komut satırı işaretini tanımalıdır ve yalnızca bu işaret iletildiyse kendini kalıcı hale getirmelidir. Aksi takdirde tek seferlik bir derleme yapmalı ve çıkmalıdır.

Programınız bu koşulları karşılıyorsa kalıcı bir işleyici olarak kullanılabilir.

İş istekleri

WorkRequest, işçiye gönderilecek bağımsız değişkenler listesini, işçinin erişebileceği girişleri temsil eden yol-özet çiftleri listesini (bu zorunlu değildir ancak bu bilgileri önbelleğe alma için kullanabilirsiniz) ve tek kanallı işçiler için 0 olan bir istek kimliğini içerir.

NOT: Protokol arabellek spesifikasyonunda "yılan büyük/küçük harf" kullanılmasına rağmen (request_id), JSON protokolünde "deve büyük/küçük harf" kullanılır. (requestId). Bu dokümanda büyük/küçük harf kullanımı bu örnekte, alan hakkında konuşurken yılan şeklinde protokolü.

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

İsteğe bağlı verbosity alanı, ekstra hata ayıklama çıkışı istemek için kullanılabilir hakkından bahsedeceğiz. Nelerin ve nasıl yayınlanacağı tamamen çalışana bağlıdır. Daha yüksek değerler, daha ayrıntılı çıkış olduğunu gösterir. --worker_verbose işareti şu kullanıcıya iletiliyor: Bazel, verbosity alanını 10 olarak ayarlar ancak daha küçük veya daha büyük değerler kullanılabilir manuel olarak da yükleyebilirsiniz.

İsteğe bağlı sandbox_dir alanı yalnızca çoklu korumalı alan özelliğini destekleyen çalışanlar tarafından kullanılır.

İş yanıtları

WorkResponse, bir istek kimliği, sıfır veya sıfır olmayan bir çıkış kodu ve isteğin işlenmesinde veya yürütülmesinde karşılaşılan hataları açıklayan bir çıkış dizesi içerir. output alanında kısa bir açıklama yer alır; tüm günlükler çalışanın stderr öğesine yazılmalıdır. Çünkü çalışanlar yalnızca WorkResponses parametresinden stdout değerine ayarlanırsa çalışan, stdout yönergesini genellikle yönlendirir. stderr için kullandığı araçlardan biridir.

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

Protobuf'lar için geçerli olan kural uyarınca tüm alanlar isteğe bağlıdır. Ancak, Bazel için aynı isteğe sahip olması için WorkRequest ve ilgili WorkResponse idare eder, bu nedenle istek kimliği sıfır değilse belirtilmelidir. Bu geçerli bir WorkResponse

{
  "requestId" : 12,
}

0 değerine sahip bir request_id, "tek kanallı" bir isteği gösterir. Bu istek, diğer isteklerle paralel olarak işlenemediği durumlarda kullanılır. Sunucu, belirli bir çalışan yalnızca request_id 0 veya yalnızca 0 ile istek alır request_id sıfırdan büyük. Singleplex istekleri seri olarak gönderilir sunucu bir istek alana kadar başka bir istek göndermezse yanıtı (iptal istekleri dışında, aşağıya bakın).

Notlar

  • Her protokol arabelleğinden önce varint biçiminde bir uzunluk gelir (bkz. MessageLite.writeDelimitedTo()
  • JSON isteklerinin ve yanıtlarının önünde bir boyut göstergesi bulunmaz.
  • JSON istekleri, protobuf ile aynı yapıyı korur ancak standart API'yi kullanır Tüm alan adları için JSON ve büyük/küçük harf kullanın.
  • protobuf ile aynı geriye dönük ve ileriye dönük uyumluluk özelliklerini korumak için JSON işleyicilerinin bu mesajlardaki bilinmeyen alanları tolere etmesi ve eksik değerler için protobuf varsayılanlarını kullanması gerekir.
  • Bazel, istekleri protobuf olarak depolar ve protobuf'in JSON biçimini kullanarak JSON'a dönüştürür.

İptal

Çalışanlar, isteğe bağlı olarak iş isteklerinin tamamlanmadan önce iptal edilmesine izin verebilir. Bu, özellikle yerel yürütmenin daha hızlı bir uzak yürütme tarafından düzenli olarak kesintiye uğratılabileceği dinamik yürütmeyle bağlantılı olarak faydalıdır. İzin vermek için iptal etmek için şunu ekleyin: supports-worker-cancellation: 1 execution-requirements alanına (aşağıya bakın) gidin ve --experimental_worker_cancellation işareti.

İptal isteği, cancel alanının ayarlandığı bir WorkRequest'dir (benzer şekilde iptal yanıtı, was_cancelled alanının ayarlandığı bir WorkResponse'dir). İptal isteğinde veya iptal isteğinde olması gereken diğer tek alan yanıt, hangi isteğin iptal edileceğini gösteren request_id. request_id alanı, tek yönlü çalışanlar için 0 veya daha önceki bir yapılandırmanın 0 olmayan request_id değeri için Multiplex çalışanları için WorkRequest gönderildi. Sunucu, işleyicinin daha önce yanıtladığı istekler için iptal istekleri gönderebilir. Bu durumda iptal isteği yoksayılmalıdır.

İptal edilmeyen her WorkRequest mesajı, iptal edilip edilmediğine bakılmaksızın tam olarak bir kez yanıtlanmalıdır. Sunucu bir iptal isteği gönderdikten sonra işleyici, request_id ayarlanmış ve was_cancelled alanı doğru olarak ayarlanmış bir WorkResponse ile yanıt verebilir. Normal WorkResponse göndermek de kabul edilir, ancak output ve exit_code alanları yoksayılır.

Bir WorkRequest için yanıt gönderildikten sonra işleyici, çalışma dizinindeki dosyalara dokunmamalıdır. Sunucu, geçici dosyalar da dahil olmak üzere dosyaları temizleyebilir.

İşleyiciyi kullanan kuralı oluşturma

Ayrıca, bir kontrol noktası görevi görebilir. Çalışan kullanan bir Starlark kuralı oluşturmak, başka herhangi bir kural oluşturarak ekleyebilirsiniz.

Ayrıca, kuralın işçiye referans vermesi gerekir ve ürettiği işlemler için bazı koşullar vardır.

Çalışana atıfta bulunma

Çalışanı kullanan kuralın, çalışanın kendisine atıfta bulunan bir alan içermesi gerekir. Bu nedenle, çalışanınızı tanımlamak için bir \*\_binary kuralı örneği oluşturmanız gerekir. Çalışanınızın adı MyWorker.Java ise ilişkilendirilmiş kural:

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

Bu, "çalışan"ı oluşturur etiketidir. Bu, çalışan ikili programıdır. Bu durumda çalışanı kullanan bir kural tanımlayın. Bu kural, şu özelliklere sahip bir çalışan ikilisi anlamına gelir.

Derlediğiniz çalışan ikili programı, üstte yer alan "work" adlı bir paketteyse Örneğin, özellik tanımı şu olabilir:

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

cfg = "exec", çalışanın yürütme platformu (yani çalışan; araç olarak kullanabilirsiniz).

İş işlemi şartları

Çalışanı kullanan kural, çalışanın gerçekleştireceği işlemler oluşturur. Bu işlemler için birkaç koşul vardır.

  • "arguments" alanı. Bu, dizelerin bir listesini alır. Bunlar, başlatma sırasında çalışana iletilen bağımsız değişkenlerdir. "arguments" listesindeki son öğe, flag-file (@ işareti ile başlayan) bağımsız değişkenidir. Çalışanların okuması belirtilen işaret dosyasındaki bağımsız değişkenlerin WorkRequest bazında alınması için kullanılır. Sizin kuralı, bu işaret dosyasına çalışan için başlatma olmayan bağımsız değişkenler yazabilir.

  • "execution-requirements" alanı şunları içerir: "supports-workers" : "1", "supports-multiplex-workers" : "1" veya her ikisi.

    "arguments" ve "execution-requirements" alanları, çalışanlara gönderilen tüm işlemler için gereklidir. Ayrıca, JSON çalışanları tarafından yürütülmesi gereken işlemlerin yürütme koşulları alanına "requires-worker-protocol" : "json" eklenmelidir. "requires-worker-protocol" : "proto", geçerli bir yürütme koşuludur ancak varsayılan oldukları için proto çalışanlar için gerekli değildir.

    Yürütme şartlarında da bir worker-key-mnemonic ayarlayabilirsiniz. Bu, yürütülebilir dosyayı birden fazla işlem türü için yeniden kullanıyorsanız ve işlemleri bu işleyiciye göre ayırt etmek istiyorsanız yararlı olabilir.

  • İşlem sırasında oluşturulan geçici dosyalar dizinini oluşturur. Bu işlem, korumalı alana almayı etkinleştirir.

ziyaret edin.

Yukarıda açıklanan "işçi" özelliğine sahip bir kural tanımı varsayımıyla, girişleri temsil eden bir "srcs" özelliği, çıkışları temsil eden bir "output" özelliği ve işçi başlangıç bağımsız değişkenlerini temsil eden bir "args" özelliğinin yanı sıra ctx.actions.run çağrısı şu şekilde olabilir:

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"]
 )

Başka bir örnek için Kalıcı çalışanları uygulama başlıklı makaleyi inceleyin.

Örnekler

Bazel kod tabanı, entegrasyon testlerimizde kullanılan örnek JSON işleyicisinin yanı sıra Java derleyici işleyicileri kullanır.

Kullanıcılarınızın yapı doğru geri çağırmayı ileterek bir çalışana dönüştürmenizi sağlar.

Çalışan kullanan bir kural örneği için Bazel'in çalışan entegrasyon testi.

Kuruluş dışından katkıda bulunanlar çeşitli dillerde çalışanları hayata geçirdi; CANNOT TRANSLATE bakmak Bazel kalıcı çalışanlarının çok dilli uygulamaları. GitHub'da daha birçok örnek bulabilirsiniz.