Avalonia 12 support: dispatcher strategy for Epoxy UIThread APIs

[supermomonga]

I'm plannning to submit a PR for Avalonia 12 supporting.
Can I discuss about Avalonia 12's multiple dispatcher?

Avalonia 12 support is being added based on the existing Epoxy.Avalonia11 / Epoxy.Core.Avalonia11 projects.

One migration question needs a design decision: how should Epoxy handle Avalonia 12's dispatcher model?

Avalonia 12 introduced multiple dispatcher support, with one dispatcher per thread. Dispatcher.UIThread is still acceptable for applications, but Avalonia recommends that library/control authors use AvaloniaObject.Dispatcher and Dispatcher.CurrentDispatcher where appropriate, instead of always relying on Dispatcher.UIThread.

Reference:
https://docs.avaloniaui.net/docs/avalonia12-breaking-changes#multiple-dispatchers-support

Current Epoxy behavior:

• UIThread.Bind() / UIThread.InvokeAsync() are targetless public APIs.
• Avalonia-specific UI-thread continuation currently uses Dispatcher.UIThread.
• Exception rethrow paths in async event/command handlers also route through the same targetless UI-thread continuation.
• Relevant files:
  • src/Epoxy/UIThread.cs
  • src/Epoxy/Supplemental/UIThreadAwaitable.cs
  • src/Epoxy.Core/Internal/InternalUIThread.cs
  • src/Epoxy.Core.Avalonia11/Internal/ContinueOnUIThread.cs
  • src/Epoxy.Core/Internal/InternalWell.cs
  • src/Epoxy.Core/Fountain.cs
  • src/Epoxy.Core/EventBinder.cs
  • src/Epoxy.Core/Command.cs

Possible directions:

1. Keep using Dispatcher.UIThread for Avalonia 12

   • Pros:
     • Preserves current public API semantics.
     • Smallest implementation change.
     • Multiple UI threads are currently still unsupported in Avalonia.
   • Cons:
     • Does not follow the Avalonia 12 library/control author recommendation.
     • Less future-proof for headless, embedded, or virtual-window scenarios.

2. Switch Avalonia 12 code to target-object dispatchers where possible

   • Pros:
     • Better aligned with Avalonia 12.
     • More correct when an AvaloniaObject is already available.
     • Better future compatibility.
   • Cons:
     • Targetless APIs such as UIThread.Bind() cannot be fully migrated without changing their semantics.
     • Using Dispatcher.CurrentDispatcher for targetless APIs may bind to the caller's current thread dispatcher, which is not necessarily the intended UI dispatcher.
     • May require new internal paths or public overloads.

3. Hybrid approach

   • Pros:
     • Preserves existing targetless UIThread.* API behavior by keeping it backed by Dispatcher.UIThread.
     • Better aligned with Avalonia 12 when an AvaloniaObject or control is already available.
     • Allows paths like Fountain / Well / EventBinder to use object-bound dispatching without requiring an immediate public API change.
     • Provides a conservative migration path: improve dispatcher correctness for attached-object flows now, and consider public overloads later only if real use cases require them.
     • Keeps Dispatcher.UIThread available as a fallback for existing targetless continuation and exception rethrow paths.
   • Cons:
     • Epoxy would have two dispatcher semantics in the Avalonia 12 implementation: targetless APIs continue to use Dispatcher.UIThread, while object-bound flows may use AvaloniaObject.Dispatcher.
     • In advanced multiple-dispatcher scenarios, control-bound Epoxy code and later targetless UIThread.* calls could switch to different dispatchers.
     • Ordering, reentrancy, and exception rethrow behavior may become harder to reason about when some continuations are object-bound and others fall back to Dispatcher.UIThread.
     • The implementation and test matrix become more complex because both dispatcher paths and their fallback behavior need to be covered.
     • Partial migration could create unclear expectations for users: Avalonia 12 support would be more dispatcher-aware in attached-object flows, but not uniformly dispatcher-aware across all Epoxy APIs.

What direction should Epoxy take for Avalonia 12?

[kekyo]

@supermomonga Thank you for considering this. I hadn’t been keeping up with Avalonia 12, so I did a little research.

I understand that the issue in Avalonia 12 is that multiple dispatchers are allowed, and since an AvaloniaObject belongs to a specific dispatcher, it’s unclear where UIThread.Bind() should be routed.

If we’re splitting the assembly like "Epoxy.Avalonia12" does,

await UIThread.Bind(aobj);

I felt it might be a good idea to add an overload like this.

However, since aobj cannot be accessed in the actual Avalonia 12 code where Bind() is used, I think we need to figure out a way to address that.

For example, the current Well handler cannot identify the AvaloniaObject from the arguments:

public static void Add<TEventArgs>(
    this Well well,
    string eventName,
    Func<TEventArgs, ValueTask> action) =>  // ...

I wonder if adding an overload here would make it practical to use.
(Overloading delegates might be a bit of a hassle for users.)

Alternatively, although the implementation is a bit messy, we could provide a way to retrieve aobj using TLS:

// The aobj returned by SenderObject is set to TLS just before Well or Command calls the handler
var aobj = UIThread.SenderObject;

//  :

await UIThread.Bind(aobj);

This is one possible approach.
I don’t think this is ideal because it’s unclear when TLS will be updated, but it’s not bad enough to rule it out as a candidate.

Or, to take a more radical approach: I think there’s also the difficult route of devising some method to break this problem down comprehensively, based on the premise that trying to identify an AvaloniaObject within a ViewModel is problematic in the first place (though I don’t have any ideas right now).

What detail approach are you currently considering?

[supermomonga]

@kekyo Thank you for your reply.

I looked into Avalonia 12 in more detail. As far as I could find, Avalonia 12 introduces multiple dispatcher support, but multiple UI threads support is not in a specific roadmap at this point. Also, Dispatcher.UIThread has not been deprecated yet.

So my current preference is to keep the existing semantics of targetless Epoxy APIs such as UIThread.Bind(): they continue to use Dispatcher.UIThread as the fallback/default UI dispatcher.

At the same time, where Epoxy already has a specific target UI object, I think the Avalonia 12 implementation should follow the Avalonia documentation and use AvaloniaObject.Dispatcher.

https://docs.avaloniaui.net/docs/avalonia12-breaking-changes#multiple-dispatchers-support

However, library and control authors should start using the AvaloniaObject.Dispatcher and Dispatcher.CurrentDispatcher properties to support multiple dispatchers properly.

For example:

• Well / Fountain: use the dispatcher of the bound target object where applicable, for example exception rethrow or any target-bound internal dispatching.
• Anchor / Pile: store the dispatcher of the bound target object.
• Pile.RentAsync: execute the rent callback on the target object's dispatcher, because this API is explicitly intended to operate on the target UI element.
• Pile.RentSync: avoid synchronous cross-dispatcher marshaling; it should probably only be valid when already running on the target dispatcher.

In other words, I would like to avoid requiring ViewModels to know about AvaloniaObject. UIThread.Bind(aobj) could still be considered as a low-level overload later, but I do not think it should become the main pattern.

---

I also considered another possible implementation.

For cases such as Unbind -> Bind inside a Well handler, it might be useful if UIThread.Bind() could return to the dispatcher associated with the Well target object rather than always using Dispatcher.UIThread.

One way to do that would be to add something like an AsyncLocal<Dispatcher?> inside InternalUIThread.

Conceptually:

OnFireEvent (Well)
  -> get the dispatcher from the bound target object
  -> push it into InternalUIThread's async dispatcher context
  -> await the user handler
  -> restore the previous dispatcher context in finally

Then this code would return to the dispatcher associated with the Well target:

well.Add("Click", async e =>
{
    await UIThread.Unbind();

    var result = FooBar();

    await UIThread.Bind();

    ResultText = result;
});

However, this would make the behavior of UIThread.Bind() more implicit and complex. Since there is currently no practical difference in current version of Avalonia 12, I think we should defer this part for now and keep the initial Avalonia 12 support simpler.

[supermomonga]

BTW I think I should post this topic to "Discussions" rather than "Issues". Should we move to?

[kekyo]

@supermomonga

BTW I think I should post this topic to "Discussions" rather than "Issues". Should we move to?

Thanks, let's continue here.

• Well / Fountain: use the dispatcher of the bound target object where applicable, for example exception rethrow or any target-bound internal dispatching.
• Anchor / Pile: store the dispatcher of the bound target object.
• Pile.RentAsync: execute the rent callback on the target object's dispatcher, because this API is explicitly intended to operate on the target UI element.
• Pile.RentSync: avoid synchronous cross-dispatcher marshaling; it should probably only be valid when already running on the target dispatcher.

In other words, I would like to avoid requiring ViewModels to know about AvaloniaObject. UIThread.Bind(aobj) could still be > considered as a low-level overload later, but I do not think it should become the main pattern.

Yes, agreed.

What caught my attention was why multi-dispatchers were introduced in Avalonia 12.
At first glance, this feature sounds convenient, but in reality, it didn’t seem to be put to effective use even in WinRT.

The first thing that came to mind was the approach where the target aobj is implicitly referenced within the handler (I was mistaken in writing TLS; as you pointed out, it’s AsyncLocalStorage). While this seems logical in that UIThread.Bind() allows returning to the aobj that launched the handler, it creates a constraint that prevents forwarding to another aobj’s dispatcher. I thought that if there is a demand for such control in Avalonia 12, implicitly determining the dispatcher might not be useful.

However, if we haven’t yet applied multi-dispatcher support to concrete UI designs in Avalonia 12, it would be best to keep the API interface as minimal as possible, as proposed.

OnFireEvent (Well)
  -> get the dispatcher from the bound target object
  -> push it into InternalUIThread's async dispatcher context
  -> await the user handler
  -> restore the previous dispatcher context in finally

I think this is nice idea. With this approach, it seems we can describe a unified model of continuous execution where the binding target is always determined based on the relevant aobj (or, more precisely, based on the dispatcher of the aobj stored in AsyncLocalStorage).

When implementing this, we may need to use a type like AsyncLocal<Stack<Dispatcher>> to account for the possibility of re-entrancy (as is also indicated in the concept).

If you agree, please submit a PR. If you feel we need to discuss this further, please continue the discussion.