Gpui Async

Master async operations and background tasks in GPUI applications

✨ The solution you've been looking for

Verified

Tested and verified by our team

9771 Stars

Async operations and background tasks in GPUI. Use when working with async, spawn, background tasks, or concurrent operations.

gpui async background-tasks ui-updates concurrency rust spawn threading

Repository

See It In Action

Interactive preview & real-world examples

Live Demo

AI Conversation Simulator

See how users interact with this skill

User Prompt

Show me how to fetch user data from an API and update my GPUI component when the response comes back

Skill Processing

Analyzing request...

Agent Response

Code example using cx.spawn() for foreground async tasks that can safely update UI entities

Quick Start (3 Steps)

Get up and running in minutes

Install

claude-code skill install gpui-async

claude-code skill install gpui-async

Config

First Trigger

@gpui-async help

Commands

Command	Description	Required Args
@gpui-async async-data-fetching-with-ui-updates	Fetch data from APIs while keeping the UI responsive and updating components when data arrives	None
@gpui-async cpu-intensive-background-processing	Offload heavy computations to background threads while coordinating results back to the UI thread	None
@gpui-async periodic-background-tasks	Set up recurring background operations like auto-save, data polling, or status updates	None

Typical Use Cases

Async Data Fetching with UI Updates

Fetch data from APIs while keeping the UI responsive and updating components when data arrives

CPU-Intensive Background Processing

Offload heavy computations to background threads while coordinating results back to the UI thread

Periodic Background Tasks

Set up recurring background operations like auto-save, data polling, or status updates

Overview

GPUI provides integrated async runtime for foreground UI updates and background computation.

Key Concepts:

Foreground tasks: UI thread, can update entities (cx.spawn)
Background tasks: Worker threads, CPU-intensive work (cx.background_spawn)
All entity updates happen on foreground thread

Quick Start

Foreground Tasks (UI Updates)

 1impl MyComponent {
 2    fn fetch_data(&mut self, cx: &mut Context<Self>) {
 3        let entity = cx.entity().downgrade();
 4
 5        cx.spawn(async move |cx| {
 6            // Runs on UI thread, can await and update entities
 7            let data = fetch_from_api().await;
 8
 9            entity.update(cx, |state, cx| {
10                state.data = Some(data);
11                cx.notify();
12            }).ok();
13        }).detach();
14    }
15}

Background Tasks (Heavy Work)

 1impl MyComponent {
 2    fn process_file(&mut self, cx: &mut Context<Self>) {
 3        let entity = cx.entity().downgrade();
 4
 5        cx.background_spawn(async move {
 6            // Runs on background thread, CPU-intensive
 7            let result = heavy_computation().await;
 8            result
 9        })
10        .then(cx.spawn(move |result, cx| {
11            // Back to foreground to update UI
12            entity.update(cx, |state, cx| {
13                state.result = result;
14                cx.notify();
15            }).ok();
16        }))
17        .detach();
18    }
19}

Task Management

 1struct MyView {
 2    _task: Task<()>,  // Prefix with _ if stored but not accessed
 3}
 4
 5impl MyView {
 6    fn new(cx: &mut Context<Self>) -> Self {
 7        let entity = cx.entity().downgrade();
 8
 9        let _task = cx.spawn(async move |cx| {
10            // Task automatically cancelled when dropped
11            loop {
12                tokio::time::sleep(Duration::from_secs(1)).await;
13                entity.update(cx, |state, cx| {
14                    state.tick();
15                    cx.notify();
16                }).ok();
17            }
18        });
19
20        Self { _task }
21    }
22}

Core Patterns

1. Async Data Fetching

1cx.spawn(async move |cx| {
2    let data = fetch_data().await?;
3    entity.update(cx, |state, cx| {
4        state.data = Some(data);
5        cx.notify();
6    })?;
7    Ok::<_, anyhow::Error>(())
8}).detach();

2. Background Computation + UI Update

 1cx.background_spawn(async move {
 2    heavy_work()
 3})
 4.then(cx.spawn(move |result, cx| {
 5    entity.update(cx, |state, cx| {
 6        state.result = result;
 7        cx.notify();
 8    }).ok();
 9}))
10.detach();

3. Periodic Tasks

1cx.spawn(async move |cx| {
2    loop {
3        tokio::time::sleep(Duration::from_secs(5)).await;
4        // Update every 5 seconds
5    }
6}).detach();

4. Task Cancellation

Tasks are automatically cancelled when dropped. Store in struct to keep alive.

Common Pitfalls

❌ Don’t: Update entities from background tasks

1// ❌ Wrong: Can't update entities from background thread
2cx.background_spawn(async move {
3    entity.update(cx, |state, cx| { // Compile error!
4        state.data = data;
5    });
6});

✅ Do: Use foreground task or chain

1// ✅ Correct: Chain with foreground task
2cx.background_spawn(async move { data })
3    .then(cx.spawn(move |data, cx| {
4        entity.update(cx, |state, cx| {
5            state.data = data;
6            cx.notify();
7        }).ok();
8    }))
9    .detach();

Reference Documentation

Complete Guides

API Reference: See api-reference.md
- Task types, spawning methods, contexts
- Executors, cancellation, error handling
Patterns: See patterns.md
- Data fetching, background processing
- Polling, debouncing, parallel tasks
- Pattern selection guide
Best Practices: See best-practices.md
- Error handling, cancellation
- Performance optimization, testing
- Common pitfalls and solutions