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
messageTypestringThe logical message type name.
fromVersionintThe source version.
toVersionintThe 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
messageTypestringThe 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
upcasterIMessageUpcaster<TOld, TNew>The upcaster instance.
Type Parameters
TOldThe old message type.
TNewThe 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
messageIDispatchMessageThe 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
messageIDispatchMessageThe message to upcast.
targetVersionintThe 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).