feat(ops): V8 Fast Calls (#15122)

Co-authored-by: Bartek Iwańczuk <biwanczuk@gmail.com>

1 files changed, 28 insertions, 0 deletions

diff --git a/ops/README.md b/ops/README.md
index 02ee266f7..7b61704b5 100644
--- a/ops/README.md
+++ b/ops/README.md
@@ -14,3 +14,31 @@ Extension::builder()
   .ops(vec![op_add::decl()])
   .build();
 ```
+
+## Peformance
+
+The macro can optimize away code, short circuit fast paths and generate a Fast
+API impl.
+
+Cases where code is optimized away:
+
+- `-> ()` skips serde_v8 and `rv.set` calls.
+- `-> Result<(), E>` skips serde_v8 and `rv.set` calls for `Ok()` branch.
+- `-> ResourceId` or `-> [int]` types will use specialized method like
+  `v8::ReturnValue::set_uint32`. A fast path for SMI.
+- `-> Result<ResourceId, E>` or `-> Result<[int], E>` types will be optimized
+  like above for the `Ok()` branch.
+
+### Fast calls
+
+The macro will infer and try to auto generate V8 fast API call trait impl for
+`sync` ops with:
+
+- arguments: integers / `&mut OpState`
+- return_type: integers
+
+The `#[op(fast)]` attribute can be used to enforce fast call generation at
+compile time.
+
+Trait gen for `async` ops & a ZeroCopyBuf equivalent type is planned and will be
+added soon.