Interface IAkkaMessagePackFormatter<T>
A hand-written MessagePack formatter for a foreign type that the Akka.Serialization.V2
source generator cannot annotate with AkkaSerializableAttribute (for example, a
core Akka type such as Address, which cannot reference this assembly).
Namespace: Akka.Serialization.V2
Assembly: Akka.Serialization.V2.dll
Syntax
public interface IAkkaMessagePackFormatter<T>Type Parameters
| Name | Description |
|---|---|
| T | The foreign type this formatter reads and writes. |
Remarks
Register an implementation for a specific T on a generated serializer
using AkkaSerializerFormatterAttribute. The generator then routes every field of
type T (including Nullable<T> for value types) through this
formatter instead of requiring a nested AkkaSerializableAttribute definition.
Write(ref MessagePackWriter, T) and Read(ref MessagePackReader) must be symmetric: reading the bytes written by
Write(ref MessagePackWriter, T) must reproduce an equivalent T value.
The value passed to Write(ref MessagePackWriter, T) is never a representation of "absent" when the
declaring field is non-nullable. The generator owns MessagePack nil encoding for nullable
fields and only calls into the formatter for present values.
SizeOf(T) must return the exact number of bytes Write(ref MessagePackWriter, T) will produce for
the same value, or UnknownSize when the exact size
cannot be cheaply computed. Returning an incorrect non-negative value corrupts the enclosing
generated serializer's SizeHint contract.
Methods
| Edit this page View SourceRead(ref MessagePackReader)
Reads a T value previously written by Write(ref MessagePackWriter, T).
Declaration
T Read(ref MessagePackReader reader)Parameters
| Type | Name | Description |
|---|---|---|
| MessagePackReader | reader | The MessagePack reader cursor. |
Returns
| Type | Description |
|---|---|
| T |
SizeOf(T)
Returns the exact encoded byte count for value, or
UnknownSize when the exact size cannot be
cheaply computed.
Declaration
int SizeOf(T value)Parameters
| Type | Name | Description |
|---|---|---|
| T | value | The value whose encoded size is being computed. |
Returns
| Type | Description |
|---|---|
| int |
Remarks
For transport-sensitive formatters (anything whose encoding consults the thread-static transport context, such as ActorPathFormatter), SizeOf(T) and Write(ref MessagePackWriter, T) read that context independently: both calls must run under the same transport scope on the same thread for the exact-size contract to hold. The generated serializers and the Artery encode path satisfy this naturally by sizing and writing within one serialization scope.
Write(ref MessagePackWriter, T)
Writes value to writer.
Declaration
void Write(ref MessagePackWriter writer, T value)Parameters
| Type | Name | Description |
|---|---|---|
| MessagePackWriter | writer | The MessagePack writer cursor. |
| T | value | The value to write. Never null/absent for non-nullable fields. |
Remarks
Write MUST produce exactly ONE top-level MessagePack value; wrap multiple values in a
single array or map. The generated map framing and the unknown-field forward-compatibility
path (reader.Skip()) both depend on one field id mapping to one MessagePack value —
multiple top-level values desync older readers during rolling upgrades.
Edit this page