Skip to main content

Unity.Netcode.BufferSerializer-1

Two-way serializer wrapping FastBufferReader or FastBufferWriter.

Implemented as a ref struct for two reasons:

  1. The BufferSerializer cannot outlive the FBR/FBW it wraps or using it will cause a crash
  2. The BufferSerializer must always be passed by reference and can't be copied

Ref structs help enforce both of those rules: they can't out live the stack context in which they were created, and they're always passed by reference no matter what.

BufferSerializer doesn't wrapp FastBufferReader or FastBufferWriter directly because it can't. ref structs can't implement interfaces, and in order to be able to have two different implementations with the same interface (which allows us to avoid an "if(IsReader)" on every call), the thing directly wrapping the struct has to implement an interface. So IReaderWriter exists as the interface, which is implemented by a normal struct, while the ref struct wraps the normal one to enforce the two above requirements. (Allowing direct access to the IReaderWriter struct would allow dangerous things to happen because the struct's lifetime could outlive the Reader/Writer's.)

Inherited Members#

ValueType.Equals(Object)

ValueType.GetHashCode()

ValueType.ToString()

Object.Equals(Object, Object)

Object.GetType()

Object.ReferenceEquals(Object, Object)

Namespace: System.Dynamic.ExpandoObject#
Assembly: MLAPI.dll#
Syntax#
public ref struct BufferSerializer<TReaderWriter>
where TReaderWriter : IReaderWriter
Type Parameters#
NameDescription
TReaderWriterThe implementation struct

IsReader#

Check if the contained implementation is a reader

Declaration#

public readonly bool IsReader { get; }

Property Value#

TypeDescription
System.Boolean

IsWriter#

Check if the contained implementation is a writer

Declaration#

public readonly bool IsWriter { get; }

Property Value#

TypeDescription
System.Boolean

#

GetFastBufferReader()#

Retrieves the FastBufferReader instance. Only valid if IsReader = true, throws InvalidOperationException otherwise.

Declaration#

public FastBufferReader GetFastBufferReader()

Returns#

TypeDescription
FastBufferReaderReader instance

GetFastBufferWriter()#

Retrieves the FastBufferWriter instance. Only valid if IsWriter = true, throws InvalidOperationException otherwise.

Declaration#

public FastBufferWriter GetFastBufferWriter()

Returns#

TypeDescription
FastBufferWriterWriter instance

PreCheck(Int32)#

Allows faster serialization by batching bounds checking. When you know you will be writing multiple fields back-to-back and you know the total size, you can call PreCheck() once on the total size, and then follow it with calls to SerializeValuePreChecked() for faster serialization. Write buffers will grow during PreCheck() if needed.

PreChecked serialization operations will throw OverflowException in editor and development builds if you go past the point you've marked using PreCheck(). In release builds, OverflowException will not be thrown for performance reasons, since the point of using PreCheck is to avoid bounds checking in the following operations in release builds.

To get the correct size to check for, use FastBufferWriter.GetWriteSize(value) or FastBufferWriter.GetWriteSize\<type>()

Declaration#

public bool PreCheck(int amount)

Parameters#

TypeNameDescription
System.Int32amountNumber of bytes you plan to read or write

Returns#

TypeDescription
System.BooleanTrue if the read/write can proceed, false otherwise.

SerializeNetworkSerializable\<T>(ref T)#

Serialize an INetworkSerializable

Throws OverflowException if the end of the buffer has been reached. Write buffers will grow up to the maximum allowable message size before throwing OverflowException.

Declaration#

public void SerializeNetworkSerializable<T>(ref T value)
where T : INetworkSerializable, new()

Parameters#

TypeNameDescription
TvalueValue to serialize

Type Parameters#

NameDescription
T

SerializeValue(ref Byte)#

Serialize a single byte

Throws OverflowException if the end of the buffer has been reached. Write buffers will grow up to the maximum allowable message size before throwing OverflowException.

Declaration#

public void SerializeValue(ref byte value)

Parameters#

TypeNameDescription
System.BytevalueValue to serialize

SerializeValue(ref String, Boolean)#

Serialize a string.

Note: Will ALWAYS allocate a new string when reading.

Throws OverflowException if the end of the buffer has been reached. Write buffers will grow up to the maximum allowable message size before throwing OverflowException.

Declaration#

public void SerializeValue(ref string s, bool oneByteChars = false)

Parameters#

TypeNameDescription
System.StringsValue to serialize
System.BooleanoneByteCharsIf true, will truncate each char to one byte. This is slower than two-byte chars, but uses less bandwidth.

SerializeValue\<T>(ref T)#

Serialize an unmanaged type. Supports basic value types as well as structs. The provided type will be copied to/from the buffer as it exists in memory.

Throws OverflowException if the end of the buffer has been reached. Write buffers will grow up to the maximum allowable message size before throwing OverflowException.

Declaration#

public void SerializeValue<T>(ref T value)
where T : struct

Parameters#

TypeNameDescription
TvalueValue to serialize

Type Parameters#

NameDescription
T

SerializeValue\<T>(ref T[])#

Serialize an array value.

Note: Will ALWAYS allocate a new array when reading. If you have a statically-sized array that you know is large enough, it's recommended to serialize the size yourself and iterate serializing array members.

(This is because C# doesn't allow setting an array's length value, so deserializing into an existing array of larger size would result in an array that doesn't have as many values as its Length indicates it should.)

Throws OverflowException if the end of the buffer has been reached. Write buffers will grow up to the maximum allowable message size before throwing OverflowException.

Declaration#

public void SerializeValue<T>(ref T[] array)
where T : struct

Parameters#

TypeNameDescription
T[]arrayValue to serialize

Type Parameters#

NameDescription
T

SerializeValuePreChecked(ref Byte)#

Serialize a single byte

Using the PreChecked versions of these functions requires calling PreCheck() ahead of time, and they should only be called if PreCheck() returns true. This is an efficiency option, as it allows you to PreCheck() multiple serialization operations in one function call instead of having to do bounds checking on every call.

Declaration#

public void SerializeValuePreChecked(ref byte value)

Parameters#

TypeNameDescription
System.BytevalueValue to serialize

SerializeValuePreChecked(ref String, Boolean)#

Serialize a string.

Note: Will ALWAYS allocate a new string when reading.

Using the PreChecked versions of these functions requires calling PreCheck() ahead of time, and they should only be called if PreCheck() returns true. This is an efficiency option, as it allows you to PreCheck() multiple serialization operations in one function call instead of having to do bounds checking on every call.

Declaration#

public void SerializeValuePreChecked(ref string s, bool oneByteChars = false)

Parameters#

TypeNameDescription
System.StringsValue to serialize
System.BooleanoneByteCharsIf true, will truncate each char to one byte. This is slower than two-byte chars, but uses less bandwidth.

SerializeValuePreChecked\<T>(ref T)#

Serialize an unmanaged type. Supports basic value types as well as structs. The provided type will be copied to/from the buffer as it exists in memory.

Using the PreChecked versions of these functions requires calling PreCheck() ahead of time, and they should only be called if PreCheck() returns true. This is an efficiency option, as it allows you to PreCheck() multiple serialization operations in one function call instead of having to do bounds checking on every call.

Declaration#

public void SerializeValuePreChecked<T>(ref T value)
where T : struct

Parameters#

TypeNameDescription
TvalueValue to serialize

Type Parameters#

NameDescription
T

SerializeValuePreChecked\<T>(ref T[])#

Serialize an array value.

Note: Will ALWAYS allocate a new array when reading. If you have a statically-sized array that you know is large enough, it's recommended to serialize the size yourself and iterate serializing array members.

(This is because C# doesn't allow setting an array's length value, so deserializing into an existing array of larger size would result in an array that doesn't have as many values as its Length indicates it should.)

Using the PreChecked versions of these functions requires calling PreCheck() ahead of time, and they should only be called if PreCheck() returns true. This is an efficiency option, as it allows you to PreCheck() multiple serialization operations in one function call instead of having to do bounds checking on every call.

Declaration#

public void SerializeValuePreChecked<T>(ref T[] array)
where T : struct

Parameters#

TypeNameDescription
T[]arrayValue to serialize

Type Parameters#

NameDescription
T