Loader: Add abort().

[Mugen87]

Fixed #20705.

Closes #23070, #29634.

Description

Aborting loading requests is a feature that has been requested more than once. Previous PRs weren't ideal though so this one is an attempt to find a good compromise.

The idea is to introduce Loader.abort() as an abstract method that can be implemented by concrete loaders. The loader implementation itself must decide how an abort operation is implemented. FileLoader and ImageBitmapLoader do this with AbortController but other loaders might use different strategies.

The PR also introduces LoadingManager.abort() that makes it easier to abort the loading process of more complex loaders like GLTFLoader. If you create an instance of LoadingManager, you can now set enableAbortManagement to true which enables abort management on loading manager level. Loaders using this manager will listen to an abort event that will trigger their abort() implementation.

[github-actions]

📦 Bundle size

Full ESM build, minified and gzipped.

	Before	After	Diff
WebGL	337.57 78.74	337.57 78.74	+0 B +0 B
WebGPU	556.8 154.16	556.8 154.16	+0 B +0 B
WebGPU Nodes	556.15 154	556.15 154	+0 B +0 B

🌳 Bundle size after tree-shaking

Minimal build including a renderer, camera, empty scene, and dependencies.

	Before	After	Diff
WebGL	468.75 113.42	468.75 113.42	+0 B +0 B
WebGPU	632.54 171.18	632.54 171.18	+0 B +0 B
WebGPU Nodes	587.59 160.53	587.59 160.53	+0 B +0 B

[gkjohnson]

I think this is great change but I'm wondering if the usage is going to be a bit out of sync with out users typically are using LoadingManager. Right now LoadingManager is often used to track the loading of a number of items being loaded so the same loading manager would then be passed to all the loaders to track that data. However with this "abort" model this means you would not be able to abort just a single load. I don't think this should block the PR but maybe something to consider for future changes to LoadingManager.

In past projects I've created a custom version of LoadingManager that dispatched the on* functions as events and allowed for "parenting" so events could be bubbled through other loading managers and each subset can be tracked separately for caching, cancelling, etc. Something like so:

const appLoadingManager = new LoadingManager();
const modelLoadingManager = new LoadingManager();

// "appLoadingManager" will consider all loads pushed to "modelLoadingManager".
appLoadingManager.subscribeTo( modelLoadingManager );

edit I suppose it should also be noted that even if "abort" is called on LoadingManager it's still the case that onComplete could be called by the loaders 🤔

[gkjohnson]

@linbingquan Can we elaborate on some practical use cases for this function? It seems more like a workaround for applications not managing their own event registration well.

It should be noted that adding this function means that EventDispatcher is becoming out of sync with the API of the browsers event system, which I believe was the original intent of the class. This might be okay but perhaps deserves some consideration.

[Mugen87]

Since the PR is not using removeEventListeners() anymore, I have removed the addition to EventDispatcher as well. If there is no compelling use case, it's indeed better to keep the API in sync with the browser event system.

[Mugen87]

I think this is great change but I'm wondering if the usage is going to be a bit out of sync with out users typically are using LoadingManager. Right now LoadingManager is often used to track the loading of a number of items being loaded so the same loading manager would then be passed to all the loaders to track that data. However with this "abort" model this means you would not be able to abort just a single load. I don't think this should block the PR but maybe something to consider for future changes to LoadingManager.

I've tried different approaches in the last days and I don't think there is an option to implement in a way that covers all potential use cases without introducing more fundamental changes to threes loader system. It's true that LoadingManager initial purpose was to manage the loading process of multiple loaders. But I think there is no reason to not use it for other use cases like the one from setURLModifier() or abort mechanism. Apart from that, I want to avoid to expose AbortController since it should depend on the loader how an abort operation is implemented.

[Mugen87]

edit I suppose it should also be noted that even if "abort" is called on LoadingManager it's still the case that onComplete could be called by the loaders

I'm not fully confident of how to classify "abort". I understand the argument that it should be an "OK" result since it's a controlled operation but on the other hand "abort" means the loaded asset can't be used for its intended purpose which sounds more like an error.

[Mugen87]

In past projects I've created a custom version of LoadingManager that dispatched the on* functions as events and allowed for "parenting" so events could be bubbled through other loading managers and each subset can be tracked separately for caching, cancelling, etc.

That sounds interesting. Deriving LoadingManager from EventDispatcher should be beneficial if we want to apply such changes to LoadingManager in the future. When using events for notifying about "start", "end" or "error", the existing usage shouldn't be affected.

[gkjohnson]

I've tried different approaches in the last days and I don't think there is an option to implement in a way that covers all potential use cases without introducing more fundamental changes to threes loader system.

Yeah I understand. To be clear, I think this approach is good. I just mean to suggest some further enhancements to LoadingManager for the future.

I understand the argument that it should be an "OK" result since it's a controlled operation but on the other hand "abort" means the loaded asset can't be used for its intended purpose which sounds more like an error.

Thinking about it more I feel the current behavior is fine. There will inevitably be cases where a Loader is already finished and then a user aborts. The browser's fetch behaves the same way:

fetch( url, { signal } )
  .then( res => {
    // fetch does not throw an error or abort
    controller.abort();
  } )

[gkjohnson]

What's the value of this? Why not always register for an abort command in the Loaders?

[Mugen87]

Think of a viewer application. If the app creates a loader instance every time an asset should be imported, the default loading manager will be polluted with callbacks. It seems more save to register abort handlers only with custom loading managers and if the app really wants that feature.

[gkjohnson]

Oh I see. This is something I'd expect loaders to unregister once the abort signal use was past. What if the LoadingManager provides an AbortSignal that is replaced when "abort" is called and then requests can use AbortSignal.any to listen to both:

class LoadingManager {
  // ...
  abort() {
    this.abortController.abort();
    this.abortController = new AbortSignal();
  }
}

class FileLoader {
  // ...
  load( /* ... */ ) {
    const req = new Request( url, {
      headers: new Headers( this.requestHeader ),
      credentials: this.withCredentials ? 'include' : 'same-origin',
      signal: AbortSignal.any( this._abortController.signal, manager.abortController.signal ),
    } );
    // ...
  }
}

This way "abort" will always work without the need for a separate flag, which I think would be expected.

[Mugen87]

I've tested this approach before I came up with the version of the PR. The major issue is that AbortController is now hardwired in LoadingManager.abort() which a problem for loaders which do not rely on fetch (like ImageLoader). We should head for a solution that makes no assumptions about how an abort operation in a loader is implemented. Hence, I vote for an event based mechanism.

[gkjohnson]

There's no requirement that AbortSignal only be used with fetch or Request. An "abort" event can be registered like so:

const controller = new AbortController();
controller.signal.addEventListener( 'abort', () => console.log( 'ABORTED!' );
controller.abort();

// ABORTED!

The difference is that the browser's GC logic can now clean up event callbacks whose scope has been GC'd. I think this can be used very broadly.

[Mugen87]

Or we simply do this:

signal: ( typeof AbortSignal.any === 'function' ) ? AbortSignal.any( [ this._abortController.signal, this.manager.abortController.signal ] ) : this._abortController.signal

And state aborting on manager level is only supported with latest browsers.

[Mugen87]

I have implemented this fallback now along with minor doc updates. Should we give the PR in the current state a try?

[gkjohnson]

I've been trying to think through solutions here - the first thing I've realized is that apparently even the built-in event listeners are not GC'd even when their scope and variables are otherwise no longer accessible and unused, which means listeners will accumulate on the abort signal if we add them.

The most popular polyfill for AbortSignal apparently doesn't address this, either, and just removes listeners when it's aborted which means it will also accumulate listeners unendingly, as you've mentioned, if the same signal is repeatedly used for the DefaultLoadingManager and never aborted. This polyfill claims to be "memory safe" by using WeakRefs but it's not so clear to understand, imo. Though I can dig into it more if there's interest.

Adding the caveat of LoadingManager.abort only working in latest browsers is interesting but I'm concerned that will make things more difficult for users. It would be best to have consistent behavior if possible. Some other possible options:

1. Use a flag on LoadingManager as you've originally suggested but keep AbortController on the class so we can easily transition to AbortSignal.any when it feels safe.
2. Only implement one of the two abort strategies (only on Loader or on LoadingManager)
3. Use or write a memory safe polyfill for "AbortSignal.any".
4. Unregister the event listeners when the loading work is complete (see below):

For number 4 this could be something like so. This behavior can be wrapped in a more reusable way but this hopefully demonstrates the behavior:

// register events
const managerSignal = this.manager.abortController.signal;
const loaderSignal = this.abortController.signal;
const abortController = new AbortController();
const abortCallback = e => abortController.abort( e.target.reason );
managerSignal.addEventListener( 'abort', abortCallback );
loaderSignal.addEventListener( 'abort', abortCallback );

const req = new Request( {
  // ...
  signal: abortController.signal,
} );

fetch( req )
  .then( () => {

    // ...

  } )
  .finally( () => {

    manager.itemEnd( url );

    // clean up events
    managerSignal.removeEventListener( 'abort', abortCallback );
    loaderSignal.removeEventListener( 'abort', abortCallback );

  } );

If it were my decision I would I would probably choose a variant of option 4. But I don't want to block this with discussion too much further. I can also try to make a follow up PR later that adjusts things to work like point 4 above at a later point.

[Mugen87]

I'm afraid this makes it all too complicated for me 😅 . I see no issues to state that LoadingManager.abort() only works with latest browsers which support AbortSignal.any(). For now, it's an experimental feature but support will automatically improve over time. Web developers should be familiar with this pattern since Web APIs behave exactly the same. We just built a lightweight layer on top of AbortController/AbortSignal. If the app provides a polyfill for AbortSignal.any(), LoadingManager.abort() runs everywhere.

[gkjohnson]

Taking a step back I think I agree. Even on new browsers users will have to guard against "onComplete" being called after "abort" has been called for the case where "abort" is fired after the fetch request has completed. All to say users running on an old browser with no AbortSignal.any won't experience apparent behavioral differences other than some more parallel downloads than expected which feels like a decently graceful fallback.

The only thing I might change is to pass the "LoadingManager" abortSignal to the fetch request rather than the FileLoader or ImageBitmapLoader abort signal since those "abort" functions won't be accessible in common cases such as when using GLTFLoader, for example:

const loader = new GLTFLoader();
loader.loadAsync( url ).then( () => {

  // ...

} );

// this does nothing when AbortSignal.any is not defined
loader.abort();

But I'll leave that decision up to you. Whichever you decide I think we should merge it!