From 6682f5ff8be4db7a8dd4d085562734f9d3bce939 Mon Sep 17 00:00:00 2001 From: Mohanson Date: Tue, 24 Sep 2024 13:39:10 +0800 Subject: [PATCH] Update spawn docs (#15) --- Makefile | 2 +- docs/syscalls.md | 140 ++++++++++++++++++++++++++++++++++++----------- 2 files changed, 108 insertions(+), 34 deletions(-) diff --git a/Makefile b/Makefile index de57ad7..c1b393b 100644 --- a/Makefile +++ b/Makefile @@ -97,7 +97,7 @@ fmt: quickjs/std_module.h install: - wget 'https://github.com/nervosnetwork/ckb-standalone-debugger/releases/download/v0.118.0-rc2/ckb-debugger-linux-x64.tar.gz' + wget 'https://github.com/nervosnetwork/ckb-standalone-debugger/releases/download/v0.118.0/ckb-debugger-linux-x64.tar.gz' tar zxvf ckb-debugger-linux-x64.tar.gz mv ckb-debugger ~/.cargo/bin/ckb-debugger make -f tests/ckb_js_tests/Makefile install-lua diff --git a/docs/syscalls.md b/docs/syscalls.md index 55a6639..cfe126a 100644 --- a/docs/syscalls.md +++ b/docs/syscalls.md @@ -334,75 +334,149 @@ context, without changing previous executable. Example: ```js let spawn_args = { - content_length: 1024, - memory_limit: 8, - offset: 0, - length: 0, + argv: ["arg1", "arg2"], + inherited_fds: [2, 3], }; -let value = ckb.spawn_cell(code_hash, hash_type, spawn_args, arg1, arg2, arg3); -let content = value.content; -let exit_code = value.exit_code; +let pid = ckb.spawn_cell(code_hash, hash_type, offset, length, spawn_args); ``` Arguments: - code_hash/hash_type(denote a cell to load JS code) +- offset, JS code offset, typically 0. +- length, JS code length, typically 0, means to read all. - spawn_args, extra spawn arguments - * content_length, optional, specify content length, default to 0 - * memory_limit, optional, specify memory limit (1~8), default to 8 - * offset, optional, JS code offset, default to 0 - * length, optional, JS code length, default to read all + * argv, argv is a one-dimensional array of strings + * inherited_fds, an array representing the file descriptors passed to the + child process. There is no need to add 0 to the end of inherited_fds as + a terminator. -- arg1,arg2,...(arguments passed to new executable) +Return values(s): process id. -Return values(s): exit code and content +See also: [`ckb_spawn` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) -See also: [`ckb_spawn` syscall](https://github.com/nervosnetwork/rfcs/pull/418/files) - -#### ckb.set_content -Description: set content. It can be fetched by `spawn` syscall. +#### ckb.pipe +Description: create a pipe with read-write pair of file descriptions. Example: ```js -let buf = Uint8Array([1,2,3]); -ckb.set_content(buf); +let fds = ckb.pipe(); ``` -Arguments: content(an ArrayBuffer contains content) +Arguments: none -Return value(s): none +Return value(s): file descriptor with read permission is located at `fds[0]`, +and the corresponding file descriptor with write permission is located +at `fds[1]`. -See also: [`set_content` syscall](https://github.com/nervosnetwork/rfcs/pull/418/files) +See also: [`pipe` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) -#### ckb.get_memory_limit -Description: Get the maximum available memory for the current script. +#### ckb.inherited_fds +Description: Retrieves the file descriptors available to the current process. Example: ```js -let size = ckb.get_memory_limit(); +let fds = ckb.inherited_fds(); ``` Arguments: none -Return value(s): memory size in bytes +Return value(s): File descriptors. + +See also: [`inherited_fds` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) + +#### ckb.read +Description: Reads data from a pipe via a file descriptor. + +Example: +```js +let txt = new Uint8Array(ckb.read(fds[0], 4)); +``` + +Arguments: +- fd: file descriptor. +- size: the size of the data to be read. + +Return value(s): an ArrayBuffer. + +See also: [`read` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) + +#### ckb.write +Description: writes data to a pipe via a file descriptor. + +Example: +```js +ckb.write(fds[1], new Uint8Array([0, 1, 2, 3])); +``` + +Arguments: +- fd: file descriptor. +- data: data to write. + +Return value(s): none. + +See also: [`write` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) + +#### ckb.close +Description: manually closes a file descriptor. + +Example: +```js +ckb.close(fds[0]); +``` + +Arguments: +- fd: file descriptor. -See also: [`ckb_get_memory_limit` syscall](https://github.com/nervosnetwork/rfcs/pull/418/files) +Return value(s): none. -#### ckb.current_memory -Description: Get the current memory usage. The result is the sum of the memory -usage of the parent script and the child script. +See also: [`close` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) + +#### ckb.wait +Description: pauses until the execution of a process specified by pid has ended. Example: ```js -let size = ckb.current_memory(); +let ret = ckb.wait(pid); +``` + +Arguments: +- pid: process id. + +Return value(s): exit code. + +See also: [`wait` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) + +#### ckb.process_id +Description: get the current process id. + +Example: +```js +let pid = ckb.process_id(); ``` Arguments: none -Return value(s): memory size in bytes +Return value(s): process id. + +See also: [`process_id` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) + +#### ckb.load_block_extension +Description: locate the extension field associated either with an input cell, a dep cell, or a header dep based on source and index value, then use the same step as documented in Partial Loading section to feed the serialized value into VM. + +Example: +```js +let buf = ckb.load_block_extension(index, source) +``` + +Arguments: index (the index of the cell), source (the source of the cell) + +Partial loading supported: yes + +Return value(s): buf (An ArrayBuffer that contains block extension) -See also: [`ckb_current_memory` syscall](https://github.com/nervosnetwork/rfcs/pull/418/files) +See also: [`load_block_extension` syscall](https://github.com/nervosnetwork/rfcs/pull/436/files) ## Exported Constants