เรียนรู้วิธีฝังโค้ด JavaScript ในไลบรารี WebAssembly ของคุณเพื่อสื่อสารกับโลกภายนอก
เมื่อต้องผสานรวม WebAssembly กับเว็บ คุณต้องมีวิธีเรียกใช้ API ภายนอก เช่น API ของเว็บและไลบรารีของบุคคลที่สาม จากนั้นคุณต้องมีวิธีจัดเก็บค่าและอินสแตนซ์ออบเจ็กต์ที่ API เหล่านั้นแสดงผล และวิธีส่งค่าที่เก็บไว้เหล่านั้นไปยัง API อื่นๆ ในภายหลัง สำหรับ API แบบอะซิงโครนัส คุณอาจต้องรอคำสัญญาในโค้ด C/C++ แบบซิงโครนัสที่ใช้ Asyncify และอ่านผลลัพธ์เมื่อการดำเนินการเสร็จสิ้น
Emscripten มีเครื่องมือมากมายสำหรับการโต้ตอบดังกล่าว ดังนี้
emscripten::val
สำหรับการจัดเก็บและเรียกใช้ค่า JavaScript ใน C++EM_JS
สำหรับการฝังข้อมูลโค้ด JavaScript และเชื่อมโยงเป็นฟังก์ชัน C/C++EM_ASYNC_JS
ซึ่งคล้ายกับEM_JS
แต่ช่วยให้ฝังข้อมูลโค้ด JavaScript แบบอะซิงโครนัสได้ง่ายขึ้นEM_ASM
สำหรับฝังข้อมูลโค้ดสั้นๆ และเรียกใช้ในหน้าโดยไม่ต้องประกาศฟังก์ชัน--js-library
สำหรับสถานการณ์ขั้นสูงที่คุณต้องการประกาศฟังก์ชัน JavaScript หลายรายการพร้อมกันเป็นไลบรารีเดียว
ในโพสต์นี้ คุณจะได้ทราบวิธีใช้ฟีเจอร์ทั้งหมดสำหรับงานที่คล้ายกัน
คลาส emscripten::val
คลาส emcripten::val
ให้บริการโดย Embind สามารถเรียกใช้ API ส่วนกลาง, เชื่อมโยงค่า JavaScript กับอินสแตนซ์ C++ และแปลงค่าระหว่างประเภท C++ กับ JavaScript
วิธีใช้ Asyncify กับ .await()
ของ Asyncify เพื่อดึงข้อมูลและแยกวิเคราะห์ JSON บางรายการมีดังนี้
#include <emscripten/val.h>
using namespace emscripten;
val fetch_json(const char *url) {
// Get and cache a binding to the global `fetch` API in each thread.
thread_local const val fetch = val::global("fetch");
// Invoke fetch and await the returned `Promise<Response>`.
val response = fetch(url).await();
// Ask to read the response body as JSON and await the returned `Promise<any>`.
val json = response.call<val>("json").await();
// Return the JSON object.
return json;
}
// Example URL.
val example_json = fetch_json("https://httpbin.org/json");
// Now we can extract fields, e.g.
std::string author = json["slideshow"]["author"].as<std::string>();
โค้ดนี้ใช้ได้ดี แต่มีหลายขั้นตอนระดับกลาง การดำเนินการแต่ละรายการใน val
จะต้องดำเนินการตามขั้นตอนต่อไปนี้
- แปลงค่า C++ ที่ส่งผ่านเป็นอาร์กิวเมนต์ให้เป็นรูปแบบระดับกลาง
- ไปที่ JavaScript อ่านและแปลงอาร์กิวเมนต์เป็นค่า JavaScript
- ดำเนินการฟังก์ชัน
- แปลงผลลัพธ์จาก JavaScript ให้อยู่ในรูปแบบระดับกลาง
- แสดงผลลัพธ์ที่แปลงแล้วให้ C++ และ C++ จะอ่านผลลัพธ์กลับในท้ายที่สุด
await()
แต่ละรายการต้องหยุดฝั่ง C++ ชั่วคราวด้วยการคลายชุดการเรียกใช้ทั้งหมดของโมดูล WebAssembly แล้วกลับมาที่ JavaScript รอ และกู้คืนสแต็ก WebAssembly เมื่อการดำเนินการเสร็จสมบูรณ์
โค้ดดังกล่าวไม่ต้องการสิ่งใดจาก C++ เนื่องจากโค้ด C++ ทำหน้าที่เป็นเพียงไดรเวอร์สำหรับชุดการดำเนินการ JavaScript เท่านั้น จะเกิดอะไรขึ้นหากคุณย้าย fetch_json
ไปใช้ JavaScript และลดค่าใช้จ่ายของขั้นตอนกลางได้ในเวลาเดียวกัน
มาโคร EM_JS
EM_JS macro
ช่วยให้คุณย้าย fetch_json
ไปที่ JavaScript ได้ EM_JS
ใน Emscripten ช่วยให้คุณประกาศฟังก์ชัน C/C++ ที่ข้อมูลโค้ด JavaScript ติดตั้งใช้งาน
โดยมีข้อจำกัดในการรองรับเฉพาะอาร์กิวเมนต์ตัวเลขและส่งกลับค่า เช่นเดียวกับ WebAssembly ในการส่งค่าอื่นๆ คุณต้องแปลงค่าดังกล่าวด้วยตนเองผ่าน API ที่เกี่ยวข้อง ต่อไปนี้เป็นตัวอย่างบางส่วน
โดยหมายเลขที่ส่งผ่านจะไม่ต้องมีการแปลงใดๆ
// Passing numbers, doesn't need any conversion.
EM_JS(int, add_one, (int x), {
return x + 1;
});
int x = add_one(41);
เมื่อส่งผ่านสตริงไปยังและจาก JavaScript คุณต้องใช้ฟังก์ชันการแปลงและการจัดสรรที่เกี่ยวข้องจาก preamble.js ดังนี้
EM_JS(void, log_string, (const char *msg), {
console.log(UTF8ToString(msg));
});
EM_JS(const char *, get_input, (), {
let str = document.getElementById('myinput').value;
// Returns heap-allocated string.
// C/C++ code is responsible for calling `free` once unused.
return allocate(intArrayFromString(str), 'i8', ALLOC_NORMAL);
});
ขั้นตอนสุดท้าย สำหรับประเภทค่าที่ซับซ้อนขึ้นเองและกำหนดเอง คุณสามารถใช้ JavaScript API สำหรับคลาส val
ที่กล่าวถึงก่อนหน้านี้ได้ ซึ่งคุณจะแปลงค่า JavaScript และคลาส C++ เป็นแฮนเดิลระดับกลางและแปลงกลับได้ดังนี้
EM_JS(void, log_value, (EM_VAL val_handle), {
let value = Emval.toValue(val_handle);
console.log(value);
});
EM_JS(EM_VAL, find_myinput, (), {
let input = document.getElementById('myinput');
return Emval.toHandle(input);
});
val obj = val::object();
obj.set("x", 1);
obj.set("y", 2);
log_value(obj.as_handle()); // logs { x: 1, y: 2 }
val myinput = val::take_ownership(find_input());
// Now you can store the `find_myinput` DOM element for as long as you like, and access it later like:
std::string value = input["value"].as<std::string>();
เมื่อคำนึงถึง API เหล่านั้นแล้ว ตัวอย่าง fetch_json
สามารถเขียนใหม่เพื่อให้ทำงานส่วนใหญ่ได้โดยไม่ต้องออกจาก JavaScript
EM_JS(EM_VAL, fetch_json, (const char *url), {
return Asyncify.handleAsync(async () => {
url = UTF8ToString(url);
// Invoke fetch and await the returned `Promise<Response>`.
let response = await fetch(url);
// Ask to read the response body as JSON and await the returned `Promise<any>`.
let json = await response.json();
// Convert JSON into a handle and return it.
return Emval.toHandle(json);
});
});
// Example URL.
val example_json = val::take_ownership(fetch_json("https://httpbin.org/json"));
// Now we can extract fields, e.g.
std::string author = json["slideshow"]["author"].as<std::string>();
เรายังมี Conversion ที่ชัดเจน 2-3 รายการอยู่ที่จุดเข้าและออกจากฟังก์ชัน แต่ที่เหลือจะเป็นโค้ด JavaScript ปกติ เครื่องมือ JavaScript สามารถเพิ่มประสิทธิภาพซึ่งต่างจาก val
ที่เทียบเท่ากัน เพียงแต่ต้องหยุดด้าน C++ ชั่วคราวเพียงครั้งเดียวสำหรับการดำเนินการแบบไม่พร้อมกันทั้งหมด
มาโคร EM_ASYNC_JS
สิ่งเดียวที่ดูไม่สวยเลยก็คือ Wrapper ของ Asyncify.handleAsync
จุดประสงค์เพียงอย่างเดียวคืออนุญาตให้เรียกใช้ฟังก์ชัน async
ของ JavaScript ด้วย Asyncify อันที่จริง กรณีการใช้งานนี้พบได้บ่อยมากจนตอนนี้มีมาโคร EM_ASYNC_JS
แบบพิเศษที่รวมเข้าด้วยกันแล้ว
ต่อไปนี้คือวิธีที่คุณสามารถใช้เพื่อสร้างตัวอย่าง fetch
เวอร์ชันสุดท้าย
EM_ASYNC_JS(EM_VAL, fetch_json, (const char *url), {
url = UTF8ToString(url);
// Invoke fetch and await the returned `Promise<Response>`.
let response = await fetch(url);
// Ask to read the response body as JSON and await the returned `Promise<any>`.
let json = await response.json();
// Convert JSON into a handle and return it.
return Emval.toHandle(json);
});
// Example URL.
val example_json = val::take_ownership(fetch_json("https://httpbin.org/json"));
// Now we can extract fields, e.g.
std::string author = json["slideshow"]["author"].as<std::string>();
EM_ASM
EM_JS
คือวิธีที่แนะนำในการประกาศข้อมูลโค้ด JavaScript ฟีเจอร์นี้มีประสิทธิภาพเพราะเชื่อมโยงข้อมูลโค้ดที่ประกาศไว้โดยตรงเหมือนกับการนำเข้าฟังก์ชัน JavaScript อื่นๆ นอกจากนี้ยังให้หลักการยศาสตร์ที่ดีโดยให้คุณประกาศประเภทและชื่อพารามิเตอร์ทั้งหมดได้อย่างชัดแจ้ง
แต่ในบางกรณี คุณต้องการแทรกข้อมูลโค้ดด่วนสำหรับการเรียก console.log
คำสั่ง debugger;
หรือคำอื่นที่คล้ายกัน และไม่ต้องการรบกวนการประกาศฟังก์ชันที่แยกต่างหากทั้งหมด ในบางกรณีที่พบไม่บ่อย EM_ASM macros family
(EM_ASM
, EM_ASM_INT
และ EM_ASM_DOUBLE
) อาจเป็นตัวเลือกที่ดีกว่า มาโครเหล่านี้คล้ายกับมาโคร EM_JS
แต่จะเรียกโค้ดแบบอินไลน์ในตำแหน่งที่ถูกแทรกแทนการกำหนดฟังก์ชัน
เนื่องจากไม่ได้ประกาศต้นแบบของฟังก์ชัน จึงต้องใช้วิธีการอื่นในการระบุประเภทผลลัพธ์และเข้าถึงอาร์กิวเมนต์
คุณต้องใช้ชื่อมาโครที่ถูกต้องเพื่อเลือกประเภทการแสดงผล การบล็อก EM_ASM
จะทำหน้าที่เหมือนฟังก์ชัน void
บล็อก EM_ASM_INT
สามารถแสดงค่าจำนวนเต็ม และบล็อก EM_ASM_DOUBLE
จะแสดงผลจำนวนจุดลอยตัวที่สอดคล้องกัน
อาร์กิวเมนต์ที่ส่งผ่านจะใช้ได้ภายใต้ชื่อ $0
, $1
และอื่นๆ ในส่วนเนื้อหาของ JavaScript เช่นเดียวกับ EM_JS
หรือ WebAssembly ทั่วไป อาร์กิวเมนต์จะจํากัดอยู่ที่ค่าตัวเลขเท่านั้น ได้แก่ จํานวนเต็ม ตัวเลขจุดลอยตัว ตัวชี้ และแฮนเดิล
ตัวอย่างวิธีใช้มาโคร EM_ASM
เพื่อบันทึกค่า JS ที่กำหนดเองไปยังคอนโซลมีดังนี้
val obj = val::object();
obj.set("x", 1);
obj.set("y", 2);
// executes inline immediately
EM_ASM({
// convert handle passed under $0 into a JavaScript value
let obj = Emval.fromHandle($0);
console.log(obj); // logs { x: 1, y: 2 }
}, obj.as_handle());
--js-library
สุดท้าย Emscripten รองรับการประกาศโค้ด JavaScript ในไฟล์แยกต่างหากในรูปแบบไลบรารีที่กำหนดเอง ดังนี้
mergeInto(LibraryManager.library, {
log_value: function (val_handle) {
let value = Emval.toValue(val_handle);
console.log(value);
}
});
จากนั้นคุณต้องประกาศต้นแบบที่เกี่ยวข้องด้วยตนเองในฝั่ง C++ ดังนี้
extern "C" void log_value(EM_VAL val_handle);
เมื่อประกาศทั้ง 2 ฝั่งแล้ว ไลบรารี JavaScript จะลิงก์เข้ากับโค้ดหลักผ่าน --js-library option
ซึ่งจะเชื่อมต่อต้นแบบกับการติดตั้งใช้งาน JavaScript ที่สัมพันธ์กัน
อย่างไรก็ตาม รูปแบบโมดูลนี้ไม่ใช่มาตรฐานและจำเป็นต้องมีคำอธิบายประกอบการอ้างอิงอย่างระมัดระวัง ด้วยเหตุนี้ ระบบจึงสงวนไว้สำหรับสถานการณ์ขั้นสูงเป็นส่วนใหญ่
บทสรุป
ในโพสต์นี้ เราพูดถึงวิธีต่างๆ ในการผสานรวมโค้ด JavaScript ลงใน C++ เมื่อทำงานกับ WebAssembly
การใส่ตัวอย่างดังกล่าวจะช่วยให้คุณแสดงลำดับการดำเนินการที่ยาวนานขึ้นได้อย่างสะอาดตาและมีประสิทธิภาพมากขึ้น และใช้ประโยชน์จากไลบรารีของบุคคลที่สาม, JavaScript API ใหม่ และแม้แต่ฟีเจอร์ไวยากรณ์ JavaScript ที่ยังไม่แสดงผ่าน C++ หรือ Embind ได้