clarification on Instance lifetime and surface ownership

[dagohan]

The docs for wgpu::Instance state:

Does not have to be kept alive.

This wording gives the impression that you can drop an Instance and create a new one elsewhere without side effects. However, that is not entirely correct in practice.

For example:

let instance_1 = wgpu::Instance::new(...);
let surface = instance_1.create_surface(window); // ex: winit window

let instance_2 = wgpu::Instance::new(...);
let adapter = instance_2.request_adapter(
    &wgpu::RequestAdapterOptions {
        compatible_surface: Some(&surface),
        ...
    }
);

The last call panics with:

Surface[Id(0,1)] does not exist

(from wgpu-core storage)

The reason is that Surfaces are tied to the Instance that created them. Internally, wgpu uses per-instance ID/epoch bookkeeping, so different instances cannot share surfaces.
Current docs do not make this restriction clear and might give the impression that instances are interchangeable.

PS: I'm opening this as a Q&A because I'm not sure if this counts as a bug (behavior is likely intended but the documentation could better explain this limitation)