docs: update docs to reflect the new `async` flag

1 files changed, 22 insertions, 0 deletions

diff --git a/docs/program_syntax.md b/docs/program_syntax.md
index bf1775c4d..2b1fb3c0d 100644
--- a/docs/program_syntax.md
+++ b/docs/program_syntax.md
@@ -91,3 +91,25 @@ non-negative, a fault will be injected into the `N`-th occasion.
 r0 = openat$6lowpan_control(0xffffffffffffff9c, &(0x7f00000000c0), 0x2, 0x0)
 ioctl$LOOP_SET_FD(r0, 0x4c00, r0) (fail_nth: 5)
 ```
+
+#### Async
+Syntax: `async`.
+
+Instructs `syz-executor` not to wait until the call completes and
+to proceed immediately to the next call.
+
+```
+r0 = openat(0xffffffffffffff9c, &AUTO='./file1\x00', 0x42, 0x1ff)
+write(r0, &AUTO="01010101", 0x4) (async)
+read(r0, &AUTO=""/4, 0x4)
+close(r0)
+```
+
+When setting `async` flags be aware of the following considerations:
+* Such programs should only be executed in threaded mode (i.e. `-threaded`
+flag must be passed to `syz-executor`.
+* Each `async` call is executed in a separate thread and there's a
+limited number of available threads (`kMaxThreads = 16`).
+* If an `async` call produces a resource, keep in mind that some other call
+might take it as input and `syz-executor` will just pass 0 if the resource-
+producing call has not finished by that time.