Skip to content

Commit afd8d5e

Browse files
crowlKatscrowlKats
authored
docs: update docs for recent op2 changes (#1290)
For #1262
1 parent 82df3e7 commit afd8d5e

File tree

3 files changed

+148
-49
lines changed

3 files changed

+148
-49
lines changed

‎ops/op2/README.md‎

Lines changed: 100 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,8 @@ function returns `Err`, an exception is thrown.
2323

2424
## `async` calls
2525

26-
Asynchronous calls are supported in two forms:
26+
Asynchronous calls are fully inferred from the function definition. Asynchronous
27+
calls are supported in two forms:
2728

2829
```rust,ignore
2930
async fn op_xyz(/* ... */) -> X {}
@@ -45,7 +46,7 @@ op system.
4546
fn op_xyz(promise_id: i32 /* ... */) -> Option<X> {}
4647
```
4748

48-
### Eager `async` calls: `async`
49+
### Eager `async` calls
4950

5051
By default, `async` functions are eagerly polled, which reduces the latency of
5152
the call dramatically if the async function is ready to return a value
@@ -91,6 +92,25 @@ over if the parameters are compatible. This is useful for a function that takes
9192
any buffer type in the slow path and wishes to use the very fast typed `u8`
9293
buffer for the fast path.
9394

95+
## Argument conversion
96+
97+
Arguments in non-fast ops use the `deno_core::convert::FromV8Scopeless` trait by
98+
default. This trait does not require a v8 scope for conversion, making it more
99+
efficient for many types.
100+
101+
To use the `FromV8` trait instead (which provides access to a v8 scope during
102+
conversion), add the `#[scoped]` attribute to the argument:
103+
104+
```rust,ignore
105+
fn op_xyz(#[scoped] arg: MyFromV8Type) -> X {}
106+
```
107+
108+
## Return value conversion
109+
110+
Return types use the `ToV8` trait by default in non-fast ops. Any type that
111+
implements `deno_core::convert::ToV8` can be returned directly without any
112+
attribute.
113+
94114
# Parameters
95115

96116
<!-- START ARGS -->
@@ -490,6 +510,48 @@ v8::Local<v8::...>
490510
<tr>
491511
<td>
492512

513+
```text
514+
FromV8Scopeless
515+
```
516+
517+
</td><td>
518+
519+
</td><td>
520+
any
521+
</td><td>
522+
Any type that implements `deno_core::covert::FromV8Scopeless`.
523+
</td></tr>
524+
<tr>
525+
<td>
526+
527+
```text
528+
#[scoped] FromV8Type
529+
```
530+
531+
</td><td>
532+
533+
</td><td>
534+
any
535+
</td><td>
536+
Any type that implements `deno_core::covert::FromV8`. ⚠️ May be slow.
537+
</td></tr>
538+
<tr>
539+
<td>
540+
541+
```text
542+
#[scoped] (Tuple, Tuple)
543+
```
544+
545+
</td><td>
546+
547+
</td><td>
548+
any
549+
</td><td>
550+
Any type that implements `deno_core::covert::FromV8`. ⚠️ May be slow.
551+
</td></tr>
552+
<tr>
553+
<td>
554+
493555
```text
494556
#[serde] SerdeType
495557
```
@@ -499,7 +561,7 @@ v8::Local<v8::...>
499561
</td><td>
500562
any
501563
</td><td>
502-
⚠️ May be slow.
564+
⚠️ May be slow. Legacy & not recommended, use `FromV8` trait and macros instead.
503565
</td></tr>
504566
<tr>
505567
<td>
@@ -513,7 +575,7 @@ any
513575
</td><td>
514576
any
515577
</td><td>
516-
⚠️ May be slow.
578+
⚠️ May be slow. Legacy & not recommended, use `FromV8` trait and macros instead.
517579
</td></tr>
518580
<tr>
519581
<td>
@@ -1429,31 +1491,63 @@ v8::Local<v8::...>
14291491
<td>
14301492

14311493
```text
1432-
#[serde] SerdeType
1494+
ToV8Type
14331495
```
14341496

14351497
</td><td>
14361498

14371499
</td><td>
14381500

1501+
</td><td>
1502+
Any type that implements `deno_core::covert::ToV8`.
1503+
</td><td>
1504+
1505+
</td></tr>
1506+
<tr>
1507+
<td>
1508+
1509+
```text
1510+
(ToV8Type, ToV8Type)
1511+
```
1512+
1513+
</td><td>
1514+
14391515
</td><td>
14401516

1517+
</td><td>
1518+
Any type that implements `deno_core::covert::ToV8`.
14411519
</td><td>
14421520

14431521
</td></tr>
14441522
<tr>
14451523
<td>
14461524

14471525
```text
1448-
#[serde] (Tuple, Tuple)
1526+
#[serde] SerdeType
14491527
```
14501528

14511529
</td><td>
14521530

14531531
</td><td>
14541532

1533+
</td><td>
1534+
⚠️ Legacy & not recommended, use `ToV8` trait and macros instead.
1535+
</td><td>
1536+
1537+
</td></tr>
1538+
<tr>
1539+
<td>
1540+
1541+
```text
1542+
#[serde] (SerdeType, SerdeType)
1543+
```
1544+
1545+
</td><td>
1546+
14551547
</td><td>
14561548

1549+
</td><td>
1550+
⚠️ Legacy & not recommended, use `ToV8` trait and macros instead.
14571551
</td><td>
14581552

14591553
</td></tr>

‎ops/op2/valid_args.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -22,8 +22,11 @@
2222
| X | &v8::**V8** | X | **V8** | |
2323
| X | v8::Local<v8::Value> | X | any | |
2424
| X | v8::Local<v8::**V8**> | X | **V8** | |
25-
| X | #[serde] SerdeType | | any | ⚠️ May be slow. |
26-
| X | #[serde] (Tuple, Tuple) | | any | ⚠️ May be slow. |
25+
| X | FromV8Scopeless | | any | Any type that implements `deno_core::covert::FromV8Scopeless`. |
26+
| X | #[scoped] FromV8Type | | any | Any type that implements `deno_core::covert::FromV8`. ⚠️ May be slow. |
27+
| X | #[scoped] (Tuple, Tuple) | | any | Any type that implements `deno_core::covert::FromV8`. ⚠️ May be slow. |
28+
| X | #[serde] SerdeType | | any | ⚠️ May be slow. Legacy & not recommended, use `FromV8` trait and macros instead. |
29+
| X | #[serde] (Tuple, Tuple) | | any | ⚠️ May be slow. Legacy & not recommended, use `FromV8` trait and macros instead. |
2730
| | #[anybuffer] &mut [u8] | X | ArrayBuffer, ArrayBufferView (resizable=true,false) | ⚠️ JS may modify the contents of the slice if V8 is called re-entrantly. |
2831
| | #[anybuffer] &[u8] | X | ArrayBuffer, ArrayBufferView (resizable=true,false) | ⚠️ JS may modify the contents of the slice if V8 is called re-entrantly. |
2932
| | #[anybuffer] *mut u8 | X | ArrayBuffer, ArrayBufferView (resizable=true,false) | ⚠️ JS may modify the contents of the slice if V8 is called re-entrantly. Because of how V8 treats empty arrays in fastcalls, they will always be passed as null. |

0 commit comments

Comments
 (0)