Namespace Akka.Serialization

Classes

ByteArraySerializer

This is a special Serializer that serializes and deserializes byte arrays only. Legacy byte-array APIs return the supplied array unchanged.

HyperionSerializer

This is a special Serializer that serializes and deserializes plain old CLR objects (POCOs).

HyperionSerializerSettings

A typed settings class for a HyperionSerializer.

NewtonSoftJsonSerializer

This is a special Serializer that serializes and deserializes javascript objects only. These objects need to be in the JavaScript Object Notation (JSON) format.

NewtonSoftJsonSerializerSettings

A typed settings for a NewtonSoftJsonSerializer class.

NewtonSoftJsonSerializerSetup

Setup for the NewtonSoftJsonSerializer serializer.

Constructor is INTERNAL API. Use the factory method Create(Action<JsonSerializerSettings>).

NOTE:

  • Newtonsoft.Json.JsonSerializerSettings.ObjectCreationHandling will always be overriden with Newtonsoft.Json.ObjectCreationHandling.Replace
  • Newtonsoft.Json.JsonSerializerSettings.ContractResolver will always be overriden with the internal contract resolver NewtonSoftJsonSerializer.AkkaContractResolver

NullSerializer

This is a special Serializer that serializes and deserializes nulls only

PayloadSizeExceededException

Thrown when a write to a PooledPayloadWriter -- via GetSpan(int), GetMemory(int), or Advance(int) -- would push the writer's total written byte count past its configured maxCapacity.

This is deliberate groundwork for deterministic oversized-payload failure (messagepack-sourcegen task 6.8): an oversized payload fails HERE, at encode time, with a typed exception carrying the attempted size and the configured cap -- it is never discovered downstream as a corrupt or truncated wire frame.

PooledPayloadWriter

A growable, pooled IBufferWriter<T> that plugs the gap between the bare IBufferWriter<T> contract and what a zero-copy transport actually needs: the ability to (a) read back the bytes already written, (b) patch already-written bytes at an absolute position (reserve-then-patch for length prefixes and headers whose value is only known once later bytes have been written), and (c) hand off pooled-buffer OWNERSHIP so a transport can complete an asynchronous socket write and only then return the memory to the pool, with no intermediate copy.

This contract was first invented privately, as Artery G1's internal PooledFrameWriter, because IBufferWriter<T> alone could not express it. It belongs on the core SerializerV2 surface: any V2 encode path -- Artery, a future sourcegen'd serializer, or a user transport -- needs the same reserve/patch/detach shape. Semantically it plays the same role as Pekko's EnvelopeBufferPool: a reusable wire buffer whose lifetime is decoupled from the encode call that filled it.

Ownership rules (read this before using the type):

  • A freshly constructed writer owns one array rented from its buffer source: the ArrayPool<T> passed to the constructor, or Shared when none is given. It grows by renting a bigger array, copying the already-written prefix, and returning the old array -- never by copying on every write. EVERY rent and return in the writer's lifetime -- the initial rent, growth, Dispose(), and the disposal of the owner returned by Detach() -- goes through that same pool.
  • Dispose() (without a prior Detach()) returns the current backing array to the pool. This is the "I'm done, nobody else needs these bytes" path -- e.g. an encode that threw partway through.
  • Detach() is the "hand the bytes to someone else" path: it returns an IMemoryOwner<T> whose Memory is exactly the written slice, and whose own Dispose() is what returns the array to the pool (e.g. once an async socket write against that memory has completed). After Detach(), this writer is SPENT: every member except Dispose() throws ObjectDisposedException, calling Detach() again throws, and this writer's own Dispose() becomes a no-op because ownership already moved.
  • Reset() reuses the current rented array for a new encode (no re-rent); it is only valid while the writer is still alive (neither disposed nor detached).

Why ArrayPool<T> and not a custom buffer-source abstraction (or MemoryPool<T>)? Deliberate: ArrayPool<T> is the narrowest standard type that covers every buffer-source strategy this writer needs -- the shared pool, a dedicated per-transport pool, and POH-pinned arrays via a custom ArrayPool<T> subclass (artery design.md, Decision 9: POH-pinned buffers only if pinning churn shows up in measurement). A bespoke interface would duplicate it; MemoryPool<T> would force Memory<T>-based internals and give up the raw array the patch/growth paths rely on.

Serialization

The serialization system used by Akka.NET to serialize and deserialize objects per the ActorSystem's serialization configuration.

SerializationSetup

Setup for the ActorSystem serialization subsystem.

Constructor is INTERNAL API. Use the factory method Create(Func<ExtendedActorSystem, ImmutableHashSet<SerializerDetails>>).

Serializer

A Serializer represents a bimap between an object and an array of bytes representing that object.

Serializers are loaded using reflection during ActorSystem start-up, where two constructors are tried in order:

  • taking exactly one argument of type ExtendedActorSystem; this should be the preferred one because all reflective loading of classes during deserialization should use ExtendedActorSystem.dynamicAccess (see [[akka.actor.DynamicAccess]]), and
  • without arguments, which is only an option if the serializer does not load classes using reflection.

Be sure to always use the PropertyManager for loading classes! This is necessary to avoid strange match errors and inequalities which arise from different class loaders loading the same class.

SerializerDetails

Constructor is internal API.

Use one of the Create factory methods instead

SerializerV1Adapter

Adapts legacy Serializer implementations to the SerializerV2 contract.

SerializerV2

A serializer that writes directly into caller-owned buffers and reads from sequence-backed input.

SerializerWithStringManifest

A specialized serializer that uses string manifests for type hinting during deserialization.

Interfaces

IKnownTypesProvider

Interface that can be implemented in order to determine some custom logic, that's going to provide a list of types that are known to be shared for all corresponding parties during remote communication.