From 7ef978c046412c932ffd98a114570769662b7d99 Mon Sep 17 00:00:00 2001 From: mohanson Date: Wed, 9 Oct 2024 18:24:30 +0800 Subject: [PATCH] Update docs --- docs/dylib.md | 106 +++++++++++++++++++++++++++++++++++++++++++++++++- docs/spawn.md | 13 ++----- 2 files changed, 108 insertions(+), 11 deletions(-) diff --git a/docs/dylib.md b/docs/dylib.md index 1ecc2e2..6519c98 100644 --- a/docs/dylib.md +++ b/docs/dylib.md @@ -12,7 +12,7 @@ if err == nil then end ``` -Of course, this example is not enough for real world usage, but this article should be enough to show how to use ckb-lua-vm shared library from the main contract program. You can unleash the potential of Lua with your creativity afterward. For the curious, see here for [an implementation of sudt in lua](https://github.com/nervosnetwork/ckb-lua-vm/blob/4e5375eb2a866595f89826db5510bc9d1f8e9510/contracts/sudt.lua). Also note that, the sample code is written in c. As an alternative, you can write test code in rust. Both [loading shared library](https://docs.rs/ckb-std/latest/ckb_std/dynamic_loading/index.html) and mocking transaction to do unit tests are easy in rust. +Of course, this example is not enough for real world usage, but this article should be enough to show how to use ckb-lua-vm shared library from the main contract program. You can unleash the potential of Lua with your creativity afterward. For the curious, see here for [an implementation of sudt in lua](https://github.com/nervosnetwork/ckb-lua-vm/blob/4e5375eb2a866595f89826db5510bc9d1f8e9510/contracts/sudt.lua). Also note that, the sample code is written in c. As an alternative, you can write test code in rust. Both [loading shared library](https://docs.rs/ckb-std/latest/ckb_std/dynamic_loading/index.html) and mocking transaction to do unit tests are easy in rust. I will now explain what this sample code does and how to run it. @@ -389,6 +389,110 @@ return values: buf (the buffer that contains the header field), err (may be nil see also: [`ckb_load_header_by_field` syscall](https://github.com/nervosnetwork/rfcs/blob/master/rfcs/0009-vm-syscalls/0009-vm-syscalls.md#load-header-by-field) +#### `ckb.spawn` +description: spawn + +calling example: [`ckb.spawn(index, source, place, bounds, argv, fds)`](../examples/spawn.lua) + +arguments: index (the index of the cell), source (the source of the cell), place (the place, 0: cell_dep, 1: witness), bounds (offset + length), argv (table of arguments), fds (file descriptors). + +return values: pid (process id), err (may be nil object to represent possible error) + +see also: [`spawn` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#spawn) + +#### `ckb.spawn_cell` +description: spawn cell from cell_dep. + +calling example: [`ckb.spawn(code_hash, hash_type, offset, length, argv, fds)`](../examples/spawn.lua) + +arguments: code_hash, hash_type, offset, length, argv (table of arguments), fds (file descriptors). + +return values: pid (process id), err (may be nil object to represent possible error) + +see also: [`spawn` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#spawn) + +#### `ckb.wait` +description: wait + +calling example: [`ckb.wait(pid)`](../examples/spawn.lua) + +arguments: pid + +return values: exit code, err (may be nil object to represent possible error) + +see also: [`wait` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#wait) + +#### `ckb.process_id` +description: process id + +calling example: [`ckb.process_id()`](../examples/spawn.lua) + +arguments: None + +return values: process id + +see also: [`process_id` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#process-id) + +#### `ckb.pipe` +description: pipe + +calling example: [`ckb.pipe()`](../examples/spawn.lua) + +arguments: None + +return values: fds, err (may be nil object to represent possible error) + +see also: [`pipe` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#pipe) + +#### `ckb.read` +description: read + +calling example: [`ckb.read(fd, size)`](../examples/spawn.lua) + +arguments: fd, read_size + +return values: buf, err (may be nil object to represent possible error) + +see also: [`read` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#read) + +#### `ckb.write` +description: write + +calling example: [`ckb.write(fd, buf)`](../examples/spawn.lua) + +arguments: fd, buf + +return values: write_size, err (may be nil object to represent possible error) + +see also: [`write` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#write) + +#### `ckb.inherited_fds` +description: inherited_fds + +calling example: [`ckb.inherited_fds()`](../examples/spawn.lua) + +arguments: None + +return values: fds, err (may be nil object to represent possible error) + +see also: [`inherited_fds` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#inherited-file-descriptors) + +#### `ckb.close` +description: close + +calling example: [`ckb.close(fd)`](../examples/spawn.lua) + +arguments: fd + +return values: err (may be nil object to represent possible error) + +see also: [`close` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#close) + +#### `ckb.load_block_extension` +description: load block extension + +see also: [`load_block_extension` syscall](https://github.com/nervosnetwork/rfcs/blob/d14c1598e1f932e9d56537c244bff0ebca0b533a/rfcs/0050-vm-syscalls-3/0050-vm-syscalls-3.md#load-block-extension) + #### `ckb.unpack_script` description: unpack the buffer that contains the molecule structure `Script` diff --git a/docs/spawn.md b/docs/spawn.md index 727da83..58b01ff 100644 --- a/docs/spawn.md +++ b/docs/spawn.md @@ -11,19 +11,12 @@ when the availablity of spawn syscall changes. There are quite a few benefits in running ckb-lua-vm as a subprocess to the main script. - The main script's context is saved, and can continue to run when ckb-lua-vm exits. - The ckb-lua-vm instances are called with command line arguments which can be used to differentiate different tasks. -- Ckb-lua may return data of any format by the function `ckb.set_content`. +- Ckb-lua may return data of any format by the function `ckb.write`. To demostrate how to extend the capabilities of a main script with ckb-lua-vm, we provide an example (an admittedly contrived one) that spawn a ckb-lua-vm subprocess which simply concatenate -the command line arguments and return the result to the main script. +the command line arguments and return the result to the main script. [The main script of this example](../examples/spawn.c) is written in c. This program can be built with `make all-via-docker`. Afterwards, you may run it -with `make -C tests/test_cases spawnexample` which requries [this branch of ckb-standalone-debugger](https://github.com/mohanson/ckb-standalone-debugger/tree/syscall_spawn). - -The main script first reserves some memory for the sub-contract, and then invokes ckb-lua-vm with -the command line arguments `"-e" "local m = arg[2] .. arg[3]; ckb.set_content(m)" "hello" "world"` -which evaluates the lua code `local m = arg[2] .. arg[3]; ckb.set_content(m)`. - -This Lua code will first concatenate the strings `hello` and `world`, and then return the result -to the main script with `ckb.set_content`. The main script may read the content on the subprocess exits. +with `make -C tests/test_cases spawnexample`.