การสร้างผู้ปฏิบัติงานถาวร

รายงานปัญหา ดูซอร์สโค้ด

Nightly · 9.1 · 9.0 · 8.6 · 8.5 · 8.4 · 8.3 · 8.2 · 8.1

ผู้ปฏิบัติงานแบบถาวร ช่วยให้บิลด์เร็วขึ้นได้ หากคุณมีการดำเนินการซ้ำๆ ในบิลด์ที่มีต้นทุนเริ่มต้นสูงหรือได้รับประโยชน์จากการแคชข้ามการดำเนินการ คุณอาจต้องการใช้ผู้ปฏิบัติงานแบบถาวรของคุณเองเพื่อดำเนินการเหล่านี้

เซิร์ฟเวอร์ Bazel สื่อสารกับผู้ปฏิบัติงานโดยใช้ stdin/stdout และรองรับการใช้บัฟเฟอร์โปรโตคอลหรือสตริง JSON

การใช้งานผู้ปฏิบัติงานมี 2 ส่วน ได้แก่

• ผู้ปฏิบัติงาน
• กฎที่ใช้ผู้ปฏิบัติงาน

การสร้างผู้ปฏิบัติงาน

ผู้ปฏิบัติงานแบบถาวรต้องเป็นไปตามข้อกำหนดบางประการ ดังนี้

• อ่าน WorkRequests จาก stdin
• เขียน WorkResponses (และ WorkResponse เท่านั้น) ลงใน stdout
• ยอมรับแฟล็ก --persistent_worker แรปเปอร์ต้องจดจำแฟล็กบรรทัดคำสั่ง --persistent_worker และทำให้ตัวเองเป็นแบบถาวรก็ต่อเมื่อมีการส่งแฟล็กดังกล่าว ไม่เช่นนั้นจะต้องทำการคอมไพล์แบบครั้งเดียวและออก

หากโปรแกรมของคุณเป็นไปตามข้อกำหนดเหล่านี้ ก็สามารถใช้เป็นผู้ปฏิบัติงานแบบถาวรได้

คำขอทำงาน

WorkRequest มีรายการอาร์กิวเมนต์สำหรับผู้ปฏิบัติงาน รายการคู่เส้นทาง-ไดเจสต์ที่แสดงอินพุตที่ผู้ปฏิบัติงานเข้าถึงได้ (ระบบไม่ได้บังคับ แต่คุณใช้ข้อมูลนี้สำหรับการแคชได้) และรหัสคำขอ ซึ่งเป็น 0 สำหรับผู้ปฏิบัติงานแบบซิงเกิลเพล็กซ์

หมายเหตุ: แม้ว่าข้อกำหนดบัฟเฟอร์โปรโตคอลจะใช้ "snake case" (request_id) แต่โปรโตคอล JSON จะใช้ "camel case" (requestId) เอกสารนี้ใช้ camel case ในตัวอย่าง JSON แต่ใช้ snake case เมื่อพูดถึงช่องโดยไม่คำนึงถึงโปรโตคอล

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

ช่อง verbosity ที่ไม่บังคับสามารถใช้เพื่อขอเอาต์พุตการแก้ไขข้อบกพร่องเพิ่มเติมจากผู้ปฏิบัติงาน ผู้ปฏิบัติงานจะเป็นผู้กำหนดสิ่งที่ต้องเอาต์พุตและวิธีเอาต์พุต ค่าที่สูงขึ้นจะแสดงเอาต์พุตที่ละเอียดมากขึ้น การส่งแฟล็ก --worker_verbose ไปยัง Bazel จะตั้งค่าช่อง verbosity เป็น 10 แต่คุณสามารถใช้ค่าที่เล็กลงหรือใหญ่ขึ้นด้วยตนเองสำหรับเอาต์พุตจำนวนต่างๆ ได้

ช่อง sandbox_dir ที่ไม่บังคับใช้โดยผู้ปฏิบัติงานที่รองรับ แซนด์บ็อกซ์แบบมัลติเพล็กซ์เท่านั้น

การตอบกลับการทำงาน

WorkResponse มีรหัสคำขอ รหัสออกเป็น 0 หรือไม่ใช่ 0 และสตริงเอาต์พุตที่อธิบายข้อผิดพลาดที่พบในการประมวลผลหรือการดำเนินการคำขอ ช่อง output มีคำอธิบายสั้นๆ และระบบอาจเขียนบันทึกแบบสมบูรณ์ลงใน stderr ของผู้ปฏิบัติงาน เนื่องจากผู้ปฏิบัติงานเขียนได้เฉพาะ WorkResponses ลงใน stdout จึงเป็นเรื่องปกติที่ผู้ปฏิบัติงานจะเปลี่ยนเส้นทาง stdout ของเครื่องมือที่ใช้ไปยัง stderr

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

ตามมาตรฐานของ protobufs ช่องทั้งหมดไม่บังคับ อย่างไรก็ตาม Bazel กำหนดให้ WorkRequest และ WorkResponse ที่เกี่ยวข้องต้องมีรหัสคำขอเดียวกัน ดังนั้นจึงต้องระบุรหัสคำขอหากไม่ใช่ 0 นี่คือ WorkResponse ที่ถูกต้อง

{
  "requestId" : 12,
}

request_id ที่เป็น 0 แสดงถึงคำขอ "ซิงเกิลเพล็กซ์" ซึ่งใช้เมื่อไม่สามารถประมวลผลคำขอพร้อมกับคำขออื่นๆ ได้ เซิร์ฟเวอร์รับประกันว่าผู้ปฏิบัติงานที่กำหนดจะได้รับคำขอที่มี request_id เป็น 0 เท่านั้น หรือมี request_id มากกว่า 0 เท่านั้น ระบบจะส่งคำขอซิงเกิลเพล็กซ์แบบอนุกรม เช่น เซิร์ฟเวอร์จะไม่ส่งคำขออื่นจนกว่าจะได้รับการตอบกลับ (ยกเว้นคำขอให้ยกเลิก ดูด้านล่าง)

หมายเหตุ

• บัฟเฟอร์โปรโตคอลแต่ละรายการจะมีขนาดเป็นรูปแบบ varint นำหน้า (ดู MessageLite.writeDelimitedTo())
• คำขอและการตอบกลับ JSON จะไม่มีตัวบ่งชี้ขนาดนำหน้า
• คำขอ JSON มีโครงสร้างเหมือนกับ protobuf แต่ใช้ JSON มาตรฐานและใช้ camel case สำหรับชื่อช่องทั้งหมด
• เพื่อให้คงคุณสมบัติความเข้ากันได้แบบย้อนกลับและไปข้างหน้าเหมือนกับ protobuf ผู้ปฏิบัติงาน JSON ต้องยอมรับช่องที่ไม่รู้จักในข้อความเหล่านี้ และใช้ค่าเริ่มต้น protobuf สำหรับค่าที่ขาดหายไป
• Bazel จะจัดเก็บคำขอเป็น protobuf และแปลงเป็น JSON โดยใช้ รูปแบบ JSON ของ protobuf

การยกเลิก

ผู้ปฏิบัติงานสามารถเลือกที่จะอนุญาตให้ยกเลิกคำขอทำงานก่อนที่จะเสร็จสิ้น ซึ่งมีประโยชน์อย่างยิ่งในการเชื่อมต่อกับการดำเนินการแบบไดนามิก ซึ่งการดำเนินการในเครื่องอาจถูกขัดจังหวะเป็นประจำโดยการดำเนินการระยะไกลที่เร็วกว่า หากต้องการอนุญาตให้ยกเลิก ให้เพิ่ม supports-worker-cancellation: 1 ลงในช่อง execution-requirements (ดูด้านล่าง) และตั้งค่าแฟล็ก --experimental_worker_cancellation

**คำขอให้ยกเลิก** คือ WorkRequest ที่ตั้งค่าช่อง cancel (และในทำนองเดียวกัน **การตอบกลับการยกเลิก** คือ WorkResponse ที่ตั้งค่าช่อง was_cancelled) ช่องอื่นๆ ที่ต้องอยู่ในคำขอให้ยกเลิกหรือการตอบกลับการยกเลิกคือ request_id ซึ่งระบุคำขอที่จะยกเลิก ช่อง request_id จะเป็น 0 สำหรับผู้ปฏิบัติงานแบบซิงเกิลเพล็กซ์ หรือ request_id ที่ไม่ใช่ 0 ของ WorkRequest ที่ส่งก่อนหน้านี้สำหรับผู้ปฏิบัติงานแบบมัลติเพล็กซ์ เซิร์ฟเวอร์อาจส่งคำขอให้ยกเลิกสำหรับคำขอที่ผู้ปฏิบัติงานตอบกลับไปแล้ว ในกรณีนี้ต้องละเว้นคำขอให้ยกเลิก

ข้อความ WorkRequest ที่ไม่ใช่คำขอให้ยกเลิกแต่ละข้อความต้องได้รับการตอบกลับ 1 ครั้ง ไม่ว่าจะยกเลิกหรือไม่ก็ตาม เมื่อเซิร์ฟเวอร์ส่งคำขอให้ยกเลิกแล้ว ผู้ปฏิบัติงานอาจตอบกลับด้วย WorkResponse ที่ตั้งค่า request_id และตั้งค่าช่อง was_cancelled เป็น "จริง" ระบบยังยอมรับการส่ง WorkResponse ปกติด้วย แต่จะละเว้นช่อง output และ exit_code

เมื่อส่งการตอบกลับสำหรับ WorkRequest แล้ว ผู้ปฏิบัติงานต้องไม่แตะต้องไฟล์ในไดเรกทอรีการทำงาน เซิร์ฟเวอร์มีอิสระในการล้างไฟล์ รวมถึงไฟล์ชั่วคราว

การสร้างกฎที่ใช้ผู้ปฏิบัติงาน

คุณจะต้องสร้างกฎที่สร้างการดำเนินการให้ผู้ปฏิบัติงานดำเนินการด้วย การสร้างกฎ Starlark ที่ใช้ผู้ปฏิบัติงานก็เหมือนกับการสร้างกฎอื่นๆ

นอกจากนี้ กฎยังต้องมีการอ้างอิงถึงผู้ปฏิบัติงานเอง และการดำเนินการที่กฎสร้างขึ้นต้องเป็นไปตามข้อกำหนดบางประการ

การอ้างอิงถึงผู้ปฏิบัติงาน

กฎที่ใช้ผู้ปฏิบัติงานต้องมีช่องที่อ้างอิงถึงผู้ปฏิบัติงานเอง ดังนั้นคุณจะต้องสร้างอินสแตนซ์ของกฎ \*\_binary เพื่อกำหนดผู้ปฏิบัติงาน หากผู้ปฏิบัติงานชื่อ MyWorker.Java กฎที่เกี่ยวข้องอาจเป็นดังนี้

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

ซึ่งจะสร้างป้ายกำกับ "worker" ที่อ้างอิงถึงไบนารีของผู้ปฏิบัติงาน จากนั้นคุณจะกำหนดกฎที่ ใช้ ผู้ปฏิบัติงาน กฎนี้ควรกำหนดแอตทริบิวต์ที่อ้างอิงถึงไบนารีของผู้ปฏิบัติงาน

หากไบนารีของผู้ปฏิบัติงานที่คุณสร้างอยู่ในแพ็กเกจชื่อ "work" ซึ่งอยู่ที่ระดับบนสุดของบิลด์ คำจำกัดความแอตทริบิวต์อาจเป็นดังนี้

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

cfg = "exec" บ่งชี้ว่าควรสร้างผู้ปฏิบัติงานให้ทำงานบน แพลตฟอร์มการดำเนินการของคุณแทนที่จะเป็นแพลตฟอร์มเป้าหมาย (เช่น ใช้ผู้ปฏิบัติงานเป็นเครื่องมือระหว่างบิลด์)

ข้อกำหนดการดำเนินการทำงาน

กฎที่ใช้ผู้ปฏิบัติงานจะสร้างการดำเนินการให้ผู้ปฏิบัติงานดำเนินการ การดำเนินการเหล่านี้มีข้อกำหนด 2 ข้อ

• ช่อง "arguments" ช่องนี้ใช้รายการสตริง ซึ่งทั้งหมดแต่ไม่ใช่รายการสุดท้ายเป็นอาร์กิวเมนต์ที่ส่งไปยังผู้ปฏิบัติงานเมื่อเริ่มต้น องค์ประกอบสุดท้ายในรายการ "arguments" คืออาร์กิวเมนต์ flag-file (นำหน้าด้วย @) ผู้ปฏิบัติงานจะอ่านอาร์กิวเมนต์จากแฟล็กไฟล์ที่ระบุตาม WorkRequest แต่ละรายการ กฎของคุณสามารถเขียนอาร์กิวเมนต์ที่ไม่ใช่การเริ่มต้นสำหรับผู้ปฏิบัติงานลงในแฟล็กไฟล์นี้ได้

• ช่อง "execution-requirements" ซึ่งใช้พจนานุกรมที่มี "supports-workers" : "1", "supports-multiplex-workers" : "1", หรือทั้ง 2 อย่าง

  ช่อง "arguments" และ "execution-requirements" จำเป็นสำหรับการดำเนินการทั้งหมดที่ส่งไปยังผู้ปฏิบัติงาน นอกจากนี้ การดำเนินการที่ควรดำเนินการโดย ผู้ปฏิบัติงาน JSON ต้องมี "requires-worker-protocol" : "json" ใน ช่องข้อกำหนดการดำเนินการ "requires-worker-protocol" : "proto" ยังเป็น ข้อกำหนดการดำเนินการที่ถูกต้องด้วย แม้ว่าจะไม่จำเป็นสำหรับผู้ปฏิบัติงาน proto เนื่องจากเป็นค่าเริ่มต้น

  คุณยังตั้งค่า worker-key-mnemonic ในข้อกำหนดการดำเนินการได้ด้วย ซึ่งอาจมีประโยชน์หากคุณใช้ไฟล์ปฏิบัติการซ้ำสำหรับประเภทการดำเนินการหลายประเภทและต้องการแยกความแตกต่างของการดำเนินการตามผู้ปฏิบัติงานนี้

• ระบบควรบันทึกไฟล์ชั่วคราวที่สร้างขึ้นระหว่างการดำเนินการลงในไดเรกทอรีของผู้ปฏิบัติงาน ซึ่งจะช่วยให้ใช้แซนด์บ็อกซ์ได้

หมายเหตุ: หากต้องการส่งอาร์กิวเมนต์ที่ขึ้นต้นด้วย @ ตามตัวอักษร ให้ขึ้นต้นอาร์กิวเมนต์ด้วย @@ แทน หากอาร์กิวเมนต์เป็นป้ายกำกับที่เก็บภายนอกด้วย ระบบจะไม่ถือว่าเป็นอาร์กิวเมนต์แฟล็กไฟล์

สมมติว่ามีการกำหนดกฎที่มีแอตทริบิวต์ "worker" ที่อธิบายไว้ข้างต้น นอกเหนือจากแอตทริบิวต์ "srcs" ที่แสดงอินพุต แอตทริบิวต์ "output" ที่แสดงเอาต์พุต และแอตทริบิวต์ "args" ที่แสดงอาร์กิวเมนต์การเริ่มต้นของผู้ปฏิบัติงาน การเรียก ctx.actions.run อาจเป็นดังนี้

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

ดูอีกตัวอย่างได้ที่ การใช้ผู้ปฏิบัติงานแบบถาวร

ตัวอย่าง

ฐานของโค้ด Bazel ใช้ ผู้ปฏิบัติงานคอมไพเลอร์ Java, นอกเหนือจาก ผู้ปฏิบัติงาน JSON ตัวอย่าง ที่ใช้ในการทดสอบการผสานรวม

คุณสามารถใช้ โครงสร้างพื้นฐาน เพื่อเปลี่ยนเครื่องมือที่ใช้ Java ให้เป็นผู้ปฏิบัติงานได้โดยการส่งการเรียกกลับที่ถูกต้อง

ดูตัวอย่างกฎที่ใช้ผู้ปฏิบัติงานได้ที่การทดสอบการผสานรวมผู้ปฏิบัติงานของ Bazel's

ผู้มีส่วนร่วมภายนอกได้ใช้ผู้ปฏิบัติงานในภาษาต่างๆ มากมาย โปรดดูการใช้งานผู้ปฏิบัติงานแบบถาวรของ Bazel ในหลายภาษา ดูตัวอย่างอื่นๆ ได้อีกมากมายใน GitHub