diff --git a/context/getting-started.md b/context/getting-started.md index dec6beb0..c2c2b332 100644 --- a/context/getting-started.md +++ b/context/getting-started.md @@ -74,6 +74,42 @@ end puts "The number was: #{task.wait}" ``` +### Comparing `Async` and `Sync` + +If you are familiar with JavaScript's `async`/`await`, `Async{...}` is similar to calling an asynchronous function: it starts the work and returns a promise-like {ruby Async::Task} that you can wait on later. + +```ruby +task = Async do + bar +end + +task.wait # Returns the value of bar. +``` + +This is similar to JavaScript code that keeps the promise: + +```javascript +const promise = bar(); + +await promise; // Returns the value of bar. +``` + +`Sync{...}` is similar to immediately awaiting that work: it runs the block in an event loop and returns the block's value directly. + +```ruby +result = Sync do + bar +end +``` + +This is similar to: + +```javascript +const result = await bar(); +``` + +The main difference is that JavaScript starts with an event loop already available, while Ruby code needs one to be provided by a fiber scheduler. `Sync{...}` is the usual way to create or reuse that event loop when the caller wants a direct return value instead of a task. + ## Creating a Fiber Scheduler The first (top level) async block will also create an instance of {ruby Async::Reactor} which is a subclass of {ruby Async::Scheduler} to handle the event loop. You can also do this directly using {ruby Fiber.set_scheduler}: diff --git a/guides/getting-started/readme.md b/guides/getting-started/readme.md index dec6beb0..c2c2b332 100644 --- a/guides/getting-started/readme.md +++ b/guides/getting-started/readme.md @@ -74,6 +74,42 @@ end puts "The number was: #{task.wait}" ``` +### Comparing `Async` and `Sync` + +If you are familiar with JavaScript's `async`/`await`, `Async{...}` is similar to calling an asynchronous function: it starts the work and returns a promise-like {ruby Async::Task} that you can wait on later. + +```ruby +task = Async do + bar +end + +task.wait # Returns the value of bar. +``` + +This is similar to JavaScript code that keeps the promise: + +```javascript +const promise = bar(); + +await promise; // Returns the value of bar. +``` + +`Sync{...}` is similar to immediately awaiting that work: it runs the block in an event loop and returns the block's value directly. + +```ruby +result = Sync do + bar +end +``` + +This is similar to: + +```javascript +const result = await bar(); +``` + +The main difference is that JavaScript starts with an event loop already available, while Ruby code needs one to be provided by a fiber scheduler. `Sync{...}` is the usual way to create or reuse that event loop when the caller wants a direct return value instead of a task. + ## Creating a Fiber Scheduler The first (top level) async block will also create an instance of {ruby Async::Reactor} which is a subclass of {ruby Async::Scheduler} to handle the event loop. You can also do this directly using {ruby Fiber.set_scheduler}: