नियमित कर्मचारियों की मदद से आपका काम तेज़ी से हो सकता है. अगर आपने अपने बिल्ड में बार-बार ऐसी कार्रवाइयां की हैं जिनकी स्टार्टअप लागत ज़्यादा है या क्रॉस-ऐक्शन कैश मेमोरी से फ़ायदा होगा, तो हो सकता है कि इन कार्रवाइयों को करने के लिए, आप खुद अपने स्थायी कर्मचारी को लागू करना चाहें.
Babel सर्वर stdin/stdout का इस्तेमाल करके कर्मचारी से संपर्क करता है. यह प्रोटोकॉल बफ़र या JSON स्ट्रिंग का इस्तेमाल करने के साथ काम करता है.
वर्कर लागू करने के दो हिस्से होते हैं:
कर्मचारी को
लगातार काम करने वाला कर्मचारी कुछ ज़रूरी शर्तों को पूरा करता है:
- यह अपने
stdinसे WorkRequests को पढ़ता है. - यह अपने
stdoutपर WorkResponses (और सिर्फ़WorkResponses) लिखता है. - यह
--persistent_workerफ़्लैग को स्वीकार करता है. रैपर को--persistent_workerकमांड लाइन फ़्लैग को पहचानना होगा और उसे लगातार चलाना होगा, जब उस फ़्लैग को पास किया जा चुका हो. अगर ऐसा नहीं है, तो रैपर को एक शॉट को कंपाइल करके बाहर निकलना होगा.
अगर आपका प्रोग्राम इन शर्तों को पूरा करता है, तो इसका इस्तेमाल स्थायी कर्मचारी के तौर पर किया जा सकता है!
काम के अनुरोध
WorkRequest में वर्कर के लिए आर्ग्युमेंट की सूची होती है. साथ ही, पाथ-डाइजेस्ट पेयर की सूची होती है जो उन इनपुट को दिखाती है जिन्हें वर्कर ऐक्सेस कर सकता है (यह लागू नहीं है, लेकिन इस जानकारी का इस्तेमाल कैश मेमोरी में किया जा सकता है). साथ ही, एक अनुरोध आईडी होता है, जो सिंगलप्लेक्स वर्कर के लिए 0 होता है.
ध्यान दें: प्रोटोकॉल बफ़र स्पेसिफ़िकेशन में "स्नेक केस" (request_id) का इस्तेमाल किया जाता है. हालांकि, JSON प्रोटोकॉल में "कैमल केस" (requestId) का इस्तेमाल किया जाता है. इस दस्तावेज़ में JSON के उदाहरणों में, ऊंट के केस का इस्तेमाल किया गया है. हालांकि, फ़ील्ड के बारे में बात करते समय स्नेक केस का इस्तेमाल किया गया है, भले ही प्रोटोकॉल कोई भी हो.
{
"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 फ़्लैग को Basel में पास करने पर, verbosity फ़ील्ड को 10 पर सेट कर दिया जाता है. हालांकि, आउटपुट की अलग-अलग वैल्यू के लिए, छोटी या बड़ी वैल्यू को मैन्युअल तरीके से इस्तेमाल किया जा सकता है.
वैकल्पिक sandbox_dir फ़ील्ड का इस्तेमाल सिर्फ़ वे वर्कर करते हैं जो मल्टीप्लेक्स सैंडबॉक्सिंग के साथ काम करते हैं.
काम से जुड़े जवाब
WorkResponse में एक अनुरोध आईडी, एक शून्य या नॉन-ज़ीरो एक्ज़िट कोड, और एक
आउटपुट स्ट्रिंग शामिल होती है, जो अनुरोध को प्रोसेस या निष्पादित करते समय होने वाली किसी भी
गड़बड़ी के बारे में बताती है. 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
}
प्रोटोबफ़ के मानदंड के मुताबिक, सभी फ़ील्ड वैकल्पिक होते हैं. हालांकि, एक ही अनुरोध आईडी के लिए WorkRequest और उससे जुड़े WorkResponse की ज़रूरत होती है. इसलिए, अगर अनुरोध आईडी शून्य नहीं है, तो उसे बताना ज़रूरी है. यह एक मान्य
WorkResponse है.
{
"requestId" : 12,
}
0 का request_id, "सिंगलप्लेक्स" अनुरोध को दिखाता है. इसका इस्तेमाल तब किया जाता है, जब इस अनुरोध को अन्य अनुरोधों के साथ प्रोसेस नहीं किया जा सकता. सर्वर इस बात की गारंटी देता है कि किसी दिए गए वर्कर को सिर्फ़ request_id 0 वाले या शून्य से ज़्यादा के सिर्फ़ request_id वाले अनुरोध मिलेंगे. सिंगलप्लेक्स अनुरोध, सीरियल में भेजे जाते हैं. उदाहरण के लिए, अगर सर्वर कोई जवाब मिलने तक दूसरा अनुरोध नहीं भेजता (रद्द करने के अनुरोधों को छोड़कर, नीचे देखें).
ध्यान दें
- हर प्रोटोकॉल बफ़र से पहले, उसकी लंबाई
varintफ़ॉर्मैट में होती है (MessageLite.writeDelimitedTo()देखें. - JSON के अनुरोधों और उनके जवाबों के पहले, साइज़ दिखाने वाला संकेत नहीं होता.
- JSON अनुरोधों का स्ट्रक्चर, प्रोटोबफ़ की तरह बना होता है. हालांकि, स्टैंडर्ड JSON का इस्तेमाल किया जाता है. साथ ही, सभी फ़ील्ड के नामों के लिए ऊंट के केस का इस्तेमाल किया जाता है.
- प्रोटोबफ़ की तरह ही बैकवर्ड और फ़ॉरवर्ड के साथ काम करने वाली प्रॉपर्टी बनाए रखने के लिए, JSON कर्मियों को इन मैसेज में अज्ञात फ़ील्ड के लिए कोई परेशानी नहीं होनी चाहिए. साथ ही, छूटी हुई वैल्यू के लिए प्रोटोबफ़ डिफ़ॉल्ट का इस्तेमाल करना होगा.
- Basel, अनुरोधों को प्रोटोबफ़ के तौर पर सेव करता है और उन्हें protobuf के JSON फ़ॉर्मैट का इस्तेमाल करके, JSON में बदलता है
रद्द किया जाना
दूसरा तरीका यह है कि वर्कर, काम खत्म होने से पहले काम के अनुरोधों को रद्द करने की अनुमति दे सकते हैं.
यह खास तौर पर डाइनैमिक एक्ज़ीक्यूशन के मामले में मददगार होता है. इसमें, तेज़ी से रिमोट तरीके से एक्ज़ीक्यूट करने की वजह से, लोकल एक्ज़ीक्यूट करने की प्रोसेस में नियमित तौर पर रुकावट आ सकती है. रद्द करने की अनुमति देने के लिए, execution-requirements फ़ील्ड (नीचे देखें) में supports-worker-cancellation: 1 जोड़ें और --experimental_worker_cancellation फ़्लैग सेट करें.
रद्द करने का अनुरोध एक WorkRequest होता है, जिसमें cancel फ़ील्ड सेट होता है. इसी तरह रद्द करने का अनुरोध, was_cancelled फ़ील्ड सेट वाला WorkResponse होता है. रद्द करने के अनुरोध या रद्द करने के रिस्पॉन्स में, सिर्फ़ request_id फ़ील्ड होना चाहिए. इससे पता चलता है कि किस अनुरोध को रद्द करना है. सिंगलप्लेक्स वर्कर के लिए request_id फ़ील्ड 0 होगा या मल्टीप्लेक्स वर्कर के लिए, पहले भेजे गए WorkRequest का नॉन-0 request_id होगा. सर्वर, उन अनुरोधों को रद्द करने के अनुरोध भेज सकता है जिनका जवाब वर्कर ने पहले ही दे दिया है. इस स्थिति में, रद्द करने के अनुरोध को अनदेखा करना ज़रूरी है.
रद्द नहीं किए गए हर WorkRequest मैसेज का जवाब सिर्फ़ एक बार देना ज़रूरी है, भले ही उसे रद्द किया गया हो या नहीं. सर्वर से रद्द करने का अनुरोध भेजने के बाद, वर्कर request_id सेट और was_cancelled फ़ील्ड को 'सही' पर सेट करके, WorkResponse रिस्पॉन्स मिल सकता है. सामान्य WorkResponse भेजने को भी स्वीकार किया जाता है, लेकिन output और exit_code फ़ील्ड को अनदेखा कर दिया जाएगा.
किसी WorkRequest के लिए जवाब भेजे जाने के बाद, वर्कर को अपनी वर्किंग डायरेक्ट्री में मौजूद फ़ाइलों को नहीं छूना चाहिए. सर्वर, अस्थायी फ़ाइलों के साथ-साथ
फ़ाइलें भी साफ़ कर सकता है.
कर्मचारी का इस्तेमाल करने वाला नियम बनाना
आपको एक ऐसा नियम भी बनाना होगा जो कर्मचारी की कार्रवाइयों को जनरेट करे. स्टारलार्क के लिए कर्मचारी का इस्तेमाल करने वाला नियम बनाना, कोई दूसरा नियम बनाने जैसा ही है.
इसके अलावा, नियम में वर्कर का रेफ़रंस होना चाहिए. साथ ही, इससे किए जाने वाले कामों के लिए कुछ शर्तें भी तय की गई हैं.
कर्मचारी को रेफ़र किया जा रहा है
वर्कर का इस्तेमाल करने वाले नियम में एक ऐसा फ़ील्ड होना चाहिए जो खुद वर्कर के बारे में हो. इसलिए, आपको अपने वर्कर को तय करने के लिए, \*\_binary नियम का इंस्टेंस बनाना होगा. अगर आपके वर्कर को MyWorker.Java कहा जाता है, तो यह जुड़ा हुआ नियम हो सकता है:
java_binary(
name = "worker",
srcs = ["MyWorker.Java"],
)
इससे "कर्मचारी" लेबल बनता है, जो वर्कर बाइनरी के बारे में बताता है. इसके बाद, वर्कर का इस्तेमाल करने वाला नियम तय किया जाएगा. इस नियम से एक ऐसा एट्रिब्यूट तय होना चाहिए जो वर्कर बाइनरी से जुड़ा हो.
अगर आपकी बनाई हुई वर्कर बाइनरी, "work" नाम के किसी पैकेज में है, जो बिल्ड के टॉप लेवल पर है, तो इस एट्रिब्यूट की परिभाषा हो सकती है:
"worker": attr.label(
default = Label("//work:worker"),
executable = True,
cfg = "exec",
)
cfg = "exec" बताता है कि वर्कर को टारगेट प्लैटफ़ॉर्म के बजाय, आपके एक्ज़ीक्यूशन प्लैटफ़ॉर्म पर चलाने के लिए बनाया जाना चाहिए. जैसे, बिल्ड के दौरान वर्कर का इस्तेमाल टूल के तौर पर किया जाता है.
काम से जुड़ी कार्रवाई की ज़रूरी शर्तें
वर्कर का इस्तेमाल करने वाला नियम, वर्कर के लिए कार्रवाइयां बनाता है. इन कार्रवाइयों की कुछ ज़रूरी शर्तें होती हैं.
"तर्क" फ़ील्ड. यह स्ट्रिंग की एक सूची लेता है. इनमें से आखिरी आर्ग्युमेंट, स्टार्टअप पर वर्कर को भेजे जाते हैं. "तर्क" की सूची का आखिरी एलिमेंट,
flag-file(@-prefixed) आर्ग्युमेंट है. वर्कर, बताई गई फ़्लैगफ़ाइल के आर्ग्युमेंट को हर WorkRequest के आधार पर पढ़ते हैं. आपका नियम इस फ़्लैगफ़ाइल में वर्कर के लिए, नॉन-स्टार्टअप आर्ग्युमेंट लिख सकता है."execution-requirements" फ़ील्ड, जो
"supports-workers" : "1","supports-multiplex-workers" : "1"या दोनों वाले शब्दकोश लेता है.कर्मचारियों को भेजी गई सभी कार्रवाइयों के लिए "तर्क" और "लागू करने की ज़रूरी शर्तें" फ़ील्ड ज़रूरी हैं. इसके अलावा, जिन कार्रवाइयों को JSON वर्कर करना चाहिए उन्हें एक्ज़ीक्यूट करने से जुड़ी ज़रूरी शर्तों वाले फ़ील्ड में
"requires-worker-protocol" : "json"को शामिल करना होगा."requires-worker-protocol" : "proto"भी एक मान्य एक्ज़ीक्यूशन ज़रूरी है. हालांकि, प्रोटो वर्कर के लिए यह ज़रूरी नहीं है, क्योंकि वे डिफ़ॉल्ट होते हैं.प्रोग्राम चलाने की ज़रूरी शर्तों में
worker-key-mnemonicभी सेट किया जा सकता है. यह तब मददगार हो सकता है, जब एक से ज़्यादा ऐक्शन टाइप के लिए एक्ज़ीक्यूटेबल का फिर से इस्तेमाल किया जा रहा हो और आपको इस वर्कर की कार्रवाइयों में अंतर करना हो.कार्रवाई के दौरान, जनरेट की गई अस्थायी फ़ाइलों को कर्मचारी की डायरेक्ट्री में सेव किया जाना चाहिए. इससे सैंडबॉक्सिंग की सुविधा चालू हो जाती है.
अगर ऊपर बताए गए "कर्मचारी" एट्रिब्यूट वाले नियम की परिभाषा के साथ-साथ इनपुट की जानकारी देने वाले "srcs" एट्रिब्यूट, आउटपुट को दिखाने वाला "आउटपुट" एट्रिब्यूट, और वर्कर स्टार्टअप आर्ग के बारे में बताने वाला "आर्ग" एट्रिब्यूट शामिल है, तो 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"]
)
दूसरे उदाहरण के लिए, परसिस्टेंट वर्कर लागू करना देखें.
उदाहरण
बेज़ेल कोड बेस हमारे इंटिग्रेशन टेस्ट में इस्तेमाल किए जाने वाले उदाहरण JSON वर्कर के अलावा, Java कंपाइलर वर्कर का इस्तेमाल करता है.
आप सही कॉलबैक को पास करके, वर्कर में किसी भी Java-आधारित टूल को बनाने के लिए उनके स्कैफ़ोल्डिंग का इस्तेमाल कर सकते हैं.
कर्मचारी का इस्तेमाल करने वाले नियम के उदाहरण के लिए, बेज़ल का वर्कर इंटिग्रेशन टेस्ट देखें.
बाहरी योगदान देने वालों ने अलग-अलग भाषाओं में काम करने वाले लोगों को काम पर लगाया है. Babel में स्थायी काम करने वाले लोगों के लिए, कई भाषाओं में काम करने वाले कर्मचारियों को लागू करने के तरीके पर एक नज़र डालें. GitHub पर और भी कई उदाहरण देखे जा सकते हैं!