Table of Contents

Class UpcastingPipeline

Namespace
Excalibur.Dispatch.Versioning
Assembly
Excalibur.Dispatch.dll

Thread-safe implementation of IUpcastingPipeline that resolves the shortest chain of upcasters between two message versions.

public sealed class UpcastingPipeline : IUpcastingPipeline, IDisposable
Inheritance
UpcastingPipeline
Implements
Inherited Members
Extension Methods

Remarks

Registry reads do not acquire the registration lock. Path-cache population may synchronize internally. The registered upcasters live in an immutable registry that a reader obtains with a single volatile read and then only inspects. Registration builds a wholly new registry and publishes it with one volatile write, so a reader sees either the registry before that registration or the one after it, never a half-built state.

The premise a future edit must not break: every public operation reads the registry field exactly once and threads that snapshot down — no helper re-reads the field, and no consumer code runs inside the registration lock — because two reads of the field in one operation can straddle a registration, measuring a message against one graph and traversing it against another.

The second half of that sentence is load-bearing and less obvious than the first. Re-entrant registration is safe today only because no consumer-supplied code executes while the registration lock is held: the message-type derivation happens before the lock is taken, and the registry is rebuilt from values already in hand. Move a consumer callback inside that lock and a nested registration would publish, return successfully, and then have its edge silently discarded by the outer publish.

Why not a reader-writer lock. This type previously guarded every read with a ReaderWriterLockSlim, so the commonest case in a long-lived system — a message already at the latest version, which needs no work at all — still paid lock acquisition on the dispatch path. Registration is rare and reads are constant, which is the shape FrozenDictionary<TKey, TValue> and copy-on-write publication exist for.

Visible ordering. A reader that obtained its registry before a concurrent registration completes its whole traversal against the pre-registration graph. That is the same answer it would have given had the registration happened immediately after the call returned, and it matches the behaviour of the lock-based design it replaces, where a writer waited for in-flight readers to leave.

Methods

CanUpcast(string, int, int)

Checks if a path exists between two versions for a message type.

public bool CanUpcast(string messageType, int fromVersion, int toVersion)

Parameters

messageType string

The logical message type name.

fromVersion int

The source version.

toVersion int

The target version.

Returns

bool

True if a path exists (including multi-hop); otherwise false.

Remarks

This method can be used to validate upcasting capability before attempting the operation, or to provide diagnostic information about registered paths.

Dispose()

Stops new registry-dependent operations; admitted traversals may finish.

public void Dispose()

Remarks

Repeated disposal is harmless. Consumer-owned upcasters are not disposed. Registry-independent identity and downcast checks retain their normal behavior. Cached CanUpcast queries now follow the same disposed-state check as uncached queries instead of exposing cache-dependent lifetime.

GetLatestVersion(string)

Gets the latest registered version for a message type.

public int GetLatestVersion(string messageType)

Parameters

messageType string

The logical message type name.

Returns

int

The highest version number, or 0 if no versions registered.

Register<TOld, TNew>(IMessageUpcaster<TOld, TNew>)

Registers a generic message upcaster for a specific version transition.

public void Register<TOld, TNew>(IMessageUpcaster<TOld, TNew> upcaster) where TOld : IDispatchMessage, IVersionedMessage where TNew : IDispatchMessage, IVersionedMessage

Parameters

upcaster IMessageUpcaster<TOld, TNew>

The upcaster instance.

Type Parameters

TOld

The old message type.

TNew

The new message type.

Remarks

Registration should typically happen during application startup via dependency injection. Multiple upcasters can be registered to form a chain (v1→v2→v3→v4).

After registration, paths are automatically computed using BFS.

Upcast(IDispatchMessage)

Upcasts a message to the latest registered version for its type.

public IDispatchMessage Upcast(IDispatchMessage message)

Parameters

message IDispatchMessage

The message to upcast (any version, any type).

Returns

IDispatchMessage

The message upcasted to the version that was latest when the call observed the registered upcasters, or the original message if it was already there.

Remarks

If no upcasters are registered for the message type, returns the original message unchanged.

"Latest" is observed once, at the start of the call. An implementation reads the registered upcasters a single time and both chooses the target version and resolves the chain against that one observation — which is what makes the result explicable by a single set of registrations. The visible consequence is that a Register<TOld, TNew>(IMessageUpcaster<TOld, TNew>) completing on another thread DURING this call does not retroactively raise this call's target: the returned message may be at a version that is no longer the latest by the time you inspect it. That is the correct and intended behaviour, equivalent to the registration having happened immediately after this call returned, and it is stated here because the method name alone implies otherwise.

Callers that need the newest version after a concurrent registration should call again. Callers that need a specific version should use UpcastTo(IDispatchMessage, int), which takes the target explicitly.

UpcastTo(IDispatchMessage, int)

Upcasts a message to a specific target version.

public IDispatchMessage UpcastTo(IDispatchMessage message, int targetVersion)

Parameters

message IDispatchMessage

The message to upcast.

targetVersion int

The desired version.

Returns

IDispatchMessage

The message at the target version.

Exceptions

InvalidOperationException

Thrown when no path exists to the target version, or when attempting to downcast (target version is lower than source version).