# Async and Effects
The pad saves experiments to the local filesystem, but so far it uses
synchronous file I/O directly in `update/2`. In this chapter we add
asynchronous commands for background work, platform effects for native
dialogs, and multi-window support. By the end, the pad will have
import/export via file dialogs, clipboard integration, and the ability to
detach an experiment into its own window.
## Async commands
`Plushie.Command.async/2` runs a function in a separate process and delivers
the result as an event:
```elixir
alias Plushie.Command
def update(model, %WidgetEvent{type: :click, id: "fetch"}) do
cmd = Command.async(fn ->
# This runs in a Task, not in the runtime process
{:ok, fetch_data_from_api()}
end, :data_loaded)
{%{model | status: :loading}, cmd}
end
```
The second argument, `:data_loaded`, is a **tag** that identifies this task.
The result arrives as a `Plushie.Event.AsyncEvent` struct with the same tag:
```elixir
alias Plushie.Event.AsyncEvent
def update(model, %AsyncEvent{tag: :data_loaded, result: {:ok, data}}) do
%{model | status: :done, data: data}
end
def update(model, %AsyncEvent{tag: :data_loaded, result: {:error, reason}}) do
%{model | status: :error, error: inspect(reason)}
end
```
A few things to know about async:
- **One task per tag.** Starting a new async with the same tag kills the
previous one. This prevents stale results from a superseded request.
- **Results are nonce-checked.** If a task is killed and its result arrives
late, the runtime discards it silently.
- **The function runs in a linked Task.** Exceptions in the function become
`{:error, reason}` results, where `reason` is the exception struct.
## Platform effects
Effects are asynchronous requests to the renderer for platform operations:
file dialogs, clipboard access, and notifications. Unlike async commands
(which run Elixir code), effects are handled by the renderer binary.
### File dialogs
Every effect takes an atom tag as its first argument. The tag identifies the
effect in result matching, so there is no need to store request IDs in your model.
```elixir
alias Plushie.Effect
def update(model, %WidgetEvent{type: :click, id: "import"}) do
{model, Effect.file_open(:import, title: "Import Experiment", filters: [{"Elixir", "*.ex"}])}
end
```
The result arrives as a `Plushie.Event.EffectEvent` struct. Match on the tag:
```elixir
alias Plushie.Event.EffectEvent
def update(model, %EffectEvent{tag: :import, result: {:ok, %{path: path}}}) do
source = File.read!(path)
# ... load the experiment
end
def update(model, %EffectEvent{tag: :import, result: :cancelled}) do
model # user closed the dialog
end
def update(model, %EffectEvent{tag: :import, result: {:error, reason}}) do
%{model | error: inspect(reason)}
end
```
Available file dialogs:
- `Effect.file_open/2` - single file selection
- `Effect.file_open_multiple/2` - multiple file selection
- `Effect.file_save/2` - save dialog
- `Effect.directory_select/2` - directory selection
- `Effect.directory_select_multiple/2` - multiple directories
### Clipboard
```elixir
# Copy text to clipboard
{model, Effect.clipboard_write(:copy, model.source)}
# Read from clipboard
{model, Effect.clipboard_read(:paste)}
# Result: %EffectEvent{tag: :paste, result: {:ok, %{text: content}}}
```
Also available: `clipboard_read_html/1`, `clipboard_write_html/3`,
`clipboard_clear/1`. On Linux, `clipboard_read_primary/1` and
`clipboard_write_primary/2` access the middle-click selection buffer.
### Notifications
```elixir
{model, Effect.notification(:exported, "Exported", "Experiment saved to #{path}")}
```
Options include `:icon`, `:timeout`, and `:urgency` (`:low`, `:normal`,
`:critical`).
### Effect timeouts
Effects have default timeouts: 120 seconds for file dialogs (the user may
browse for a while), 5 seconds for clipboard and notifications. If the
renderer does not respond in time, you get `{:error, :timeout}`.
### Applying it: import and export
Add import and export buttons to the pad toolbar:
```elixir
row padding: {4, 8}, spacing: 8 do
button("save", "Save", style: :primary)
button("import", "Import")
button("export", "Export")
checkbox("auto-save", model.auto_save)
text("auto-label", "Auto-save")
end
```
Handle the events. Each effect gets a distinct tag, so matching the
result is straightforward:
```elixir
def update(model, %WidgetEvent{type: :click, id: "import"}) do
{model, Effect.file_open(:import, title: "Import Experiment")}
end
def update(model, %WidgetEvent{type: :click, id: "export"}) do
{model, Effect.file_save(:export, title: "Export Experiment")}
end
def update(model, %EffectEvent{tag: :import, result: {:ok, %{path: path}}}) do
source = File.read!(path)
%{model | source: source}
end
def update(model, %EffectEvent{tag: :export, result: {:ok, %{path: path}}}) do
File.write!(path, model.source)
model
end
def update(model, %EffectEvent{tag: tag, result: :cancelled}) when tag in [:import, :export] do
model
end
```
### Applying it: copy code
Add a "Copy" button that copies the current experiment source to the
clipboard:
```elixir
def update(model, %WidgetEvent{type: :click, id: "copy"}) do
{model, Effect.clipboard_write(:copy, model.source)}
end
```
## Streaming and cancellation
For long-running work that produces intermediate results:
```elixir
cmd = Command.stream(fn emit ->
for {line, n} <- Enum.with_index(File.stream!("large.csv"), 1) do
emit.(%{line: n, data: parse(line)})
end
:done
end, :csv_import)
```
Each `emit.()` call delivers a `Plushie.Event.StreamEvent` struct. The final
return value arrives as a `Plushie.Event.AsyncEvent` struct, same as regular async.
To cancel a running async or stream:
```elixir
{model, Command.cancel(:csv_import)}
```
For one-shot delayed events (not recurring like subscriptions):
```elixir
{model, Command.send_after(3000, {:clear_status})}
```
See the [Commands reference](../reference/commands.md) for details.
## Batching
Combine multiple commands from a single update:
```elixir
{model, Command.batch([
Effect.clipboard_write(:copy, model.source),
Effect.notification(:copied, "Copied", "Source copied to clipboard"),
Command.focus("editor")
])}
```
Commands in a batch execute in order.
## Multi-window
A Plushie app can have multiple windows. Return a list of `window` nodes
from `view/1`:
```elixir
def view(model) do
windows = [
window "main", title: "Plushie Pad" do
# ... main pad UI
end
]
if model.detached do
windows ++ [
window "experiment", title: "Experiment: #{model.active_file}" do
container "detached-preview", padding: 16 do
model.preview
end
end
]
else
windows
end
end
```
A few important things about multi-window:
**Window IDs must be stable strings.** If a window ID changes between
renders, the renderer closes the old window and opens a new one. Use
consistent, predictable IDs.
**`exit_on_close_request`** is a per-window prop that controls whether
closing the window triggers app exit. There is no "primary window" concept --
each window independently decides its close behaviour:
```elixir
window "main", title: "App", exit_on_close_request: true do
# Closing this window exits the app
end
window "settings", title: "Settings", exit_on_close_request: false do
# Closing this window just closes the window
end
```
**`close_requested` vs `closed`:** When the user clicks the window's close
button, the renderer sends a `:close_requested` event, not a `:closed` event.
Your app decides whether to actually close. If `exit_on_close_request` is
true (the default), the runtime exits. Otherwise, the event arrives in
`update/2` and you handle it:
```elixir
alias Plushie.Event.WindowEvent
def update(model, %WindowEvent{type: :close_requested, window_id: "experiment"}) do
%{model | detached: false}
end
```
**Daemon mode** keeps the app running after the last window closes. Set
`:daemon` in `Plushie.start_link/2` options. When all windows close, you
receive `%SystemEvent{type: :all_windows_closed}` in `update/2`.
### Applying it: detach experiment
Add a "Detach" button that opens the experiment in its own window:
```elixir
def update(model, %WidgetEvent{type: :click, id: "detach"}) do
%{model | detached: true}
end
def update(model, %WindowEvent{type: :close_requested, window_id: "experiment"}) do
%{model | detached: false}
end
```
The view conditionally adds a second window when `model.detached` is true.
Closing the experiment window sets the flag back to false, and the experiment
returns to the preview pane.
## Error handling patterns
Always handle both success and failure for async and effects:
```elixir
def update(model, %AsyncEvent{tag: :export, result: {:ok, _}}) do
%{model | status: "Exported"}
end
def update(model, %AsyncEvent{tag: :export, result: {:error, reason}}) do
%{model | error: "Export failed: #{inspect(reason)}"}
end
def update(model, %EffectEvent{tag: _tag, result: :cancelled}) do
model # user cancelled the dialog, not an error
end
```
The `:cancelled` result is distinct from `{:error, reason}`. A user
cancelling a file dialog is expected behaviour, not a failure.
## Verify it
Effect stubs let you control what the renderer returns for platform
operations. Register a stub before triggering the effect, and the renderer
responds with your stub instead of executing the real operation:
```elixir
test "import loads experiment from file" do
register_effect_stub("file_open", {:ok, %{path: "/tmp/test.ex"}})
click("#import")
# The stub responds with the path; verify the source was loaded
assert model().source != ""
end
test "detach button opens second window" do
click("#detach")
assert model().detached == true
end
```
The full effect stubbing API is covered in [chapter 15](15-testing.md).
## Try it
Write experiments to try these concepts:
- Build a button that triggers `Command.async` with a simulated slow
operation (`Process.sleep(2000)`). Show a loading indicator while the
task runs, then display the result.
- Try `Command.stream` to deliver progress updates. Show a progress bar
that fills as chunks arrive.
- Try `Command.batch` to combine a clipboard write with a notification.
- Build a two-window experiment: a main window and a secondary window
that opens conditionally. Close the secondary window and see it disappear
from the view.
In the next chapter, we will explore the canvas system for custom 2D drawing.
---
Next: [Canvas](12-canvas.md)
