libs.capnproto-dotnetcore_Runtime/Capnp.Net.Runtime/SerializerState.cs

using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using System.Text;

namespace Capnp
{
    /// <summary>
    /// Implements the heart of serialization. Exposes all functionality to encode serialized data.
    /// Although it is public, you should not use it directly. Instead, use the reader, writer, and domain class adapters which are produced
    /// by the code generator. Particularly, those writer classes are actually specializations of SerializerState, adding convenience methods
    /// for accessing the struct's fields.
    /// </summary>
    public class SerializerState : IStructSerializer, IDisposable
    {
        /// <summary>
        /// Constructs a SerializerState instance for use in RPC context.
        /// This particularly means that the capability table will be initialized.
        /// </summary>
        /// <typeparam name="T">Type of state (must inherit from SerializerState)</typeparam>
        /// <returns>root object state</returns>
        public static T CreateForRpc<T>() where T: SerializerState, new()
        {
            var mb = MessageBuilder.Create();
            mb.InitCapTable();
            var s = new T();
            s.Bind(mb);
            return s;
        }

        internal MessageBuilder? MsgBuilder { get; set; }
        internal ISegmentAllocator? Allocator => MsgBuilder?.Allocator;
        internal List<Rpc.ConsumedCapability>? Caps => MsgBuilder?.Caps;
        internal SerializerState? Owner { get; set; }
        internal int OwnerSlot { get; set; }
        internal uint SegmentIndex { get; set; }
        internal int Offset { get; set; }
        internal uint WordsAllocated { get; set; }
        internal int ListElementCount { get; set; }
        internal ushort StructDataCount { get; set; }
        internal ushort StructPtrCount { get; set; }
        internal uint CapabilityIndex { get; set; }

        SerializerState[]? _linkedStates;
        bool _disposed;

        /// <summary>
        /// Constructs an unbound serializer state.
        /// </summary>
        public SerializerState()
        {
            Offset = -1;
            ListElementCount = -1;
        }

        /// <summary>
        /// Constructs a serializer state which is bound to a particular message builder.
        /// </summary>
        /// <param name="messageBuilder">message builder to bind</param>
        public SerializerState(MessageBuilder messageBuilder)
        {
            MsgBuilder = messageBuilder ?? throw new ArgumentNullException(nameof(messageBuilder));
            Offset = -1;
            ListElementCount = -1;
        }

        internal void Bind(MessageBuilder messageBuilder)
        {
            MsgBuilder = messageBuilder ?? throw new ArgumentNullException(nameof(messageBuilder));
        }

        internal void Bind(SerializerState owner, int ownerSlot)
        {
            Owner = owner ?? throw new ArgumentNullException(nameof(owner));
            OwnerSlot = ownerSlot;
            MsgBuilder = owner.MsgBuilder;
        }

        internal void InheritFrom(SerializerState other)
        {
            SegmentIndex = other.SegmentIndex;
            Offset = other.Offset;
            WordsAllocated = other.WordsAllocated;
            ListElementCount = other.ListElementCount;
            StructDataCount = other.StructDataCount;
            StructPtrCount = other.StructPtrCount;
            Kind = other.Kind;
            CapabilityIndex = other.CapabilityIndex;
            _linkedStates = other._linkedStates;
        }

        /// <summary>
        /// Represents this state by a different serializer state specialization. This is similar to a type-cast: The underlying object remains the same,
        /// but the specialization adds a particular "view" on that data.
        /// </summary>
        /// <typeparam name="TS">target serializer state type</typeparam>
        /// <returns>serializer state instance</returns>
        /// <exception cref="InvalidOperationException">The target serializer state is incompatible to this instance, because the instances do not agree on the
        /// kind of underlying object (e.g. struct with particular data/pointer section size, list of something)</exception>
        public TS Rewrap<TS>() where TS: SerializerState, new()
        {
            if (this is TS ts)
                return ts;

            ts = new TS();

            if (Kind != ObjectKind.Nil)
            {
                static InvalidOperationException InvalidWrap() =>
                    new InvalidOperationException("Incompatible cast");

                switch (ts.Kind)
                {
                    case ObjectKind.Struct:
                    case ObjectKind.ListOfStructs:
                        if (ts.Kind != Kind ||
                            ts.StructDataCount != StructDataCount ||
                            ts.StructPtrCount != StructPtrCount)
                            throw InvalidWrap();
                        break;

                    case ObjectKind.Nil:
                        break;

                    default:
                        if (ts.Kind != Kind)
                            throw InvalidWrap();
                        break;
                }

                ts.InheritFrom(this);
            }

            if (Owner != null)
                ts.Bind(Owner, OwnerSlot);
            else
                ts.Bind(MsgBuilder ?? throw Unbound());

            return ts;
        }

        /// <summary>
        /// Whether storage space for the underlying object was already allocated. Note that allocation happens
        /// lazily, i.e. constructing a SerializerState and binding it to a MessageBuilder does NOT yet result in allocation.
        /// </summary>
        public bool IsAllocated => Offset >= 0;

        Span<ulong> SegmentSpan => IsAllocated && Allocator != null ? Allocator.Segments[(int)SegmentIndex].Span : Span<ulong>.Empty;
        Span<ulong> FarSpan(uint index) => Allocator!.Segments[(int)index].Span;

        /// <summary>
        /// Given this state describes a struct and is allocated, returns the struct's data section.
        /// </summary>
        public Span<ulong> StructDataSection => SegmentSpan.Slice(Offset, StructDataCount);

        /// <summary>
        /// Returns the allocated memory slice (given this state already is allocated). Note that this definition is somewhat
        /// non-symmetric to <code>DeserializerState.RawData</code>. Never mind: You should not use it directly, anyway.
        /// </summary>
        public Span<ulong> RawData => IsAllocated ? SegmentSpan.Slice(Offset, (int)WordsAllocated) : Span<ulong>.Empty;

        /// <summary>
        /// The kind of object this state currently represents.
        /// </summary>
        public ObjectKind Kind { get; internal set; }

        void AllocateWords(uint count)
        {
            if (count == 0)
            {
                SegmentIndex = 0;
                Offset = 0;
            }
            else
            {
                if (Allocator == null)
                    throw Unbound();

                SegmentIndex = Owner?.SegmentIndex ?? SegmentIndex;
                Allocator.Allocate(count, SegmentIndex, out var slice, false);
                SegmentIndex = slice.SegmentIndex;
                Offset = slice.Offset;
            }

            WordsAllocated = count;
        }

        /// <summary>
        /// Allocates storage for the underlying object. Does nothing if it is already allocated. From the point the object is allocated, its type cannot be changed
        /// anymore (e.g. changing from struct to list, or modifying the struct's section sizes).
        /// </summary>
        public void Allocate()
        {
            if (!IsAllocated)
            {
                switch (Kind)
                {
                    case ObjectKind.ListOfBits:
                        AllocateWords(checked((uint)ListElementCount + 63u) / 64);
                        break;

                    case ObjectKind.ListOfBytes:
                        AllocateWords(checked((uint)ListElementCount + 7u) / 8);
                        break;

                    case ObjectKind.ListOfInts:
                        AllocateWords(checked((uint)ListElementCount + 1u) / 2);
                        break;

                    case ObjectKind.ListOfLongs:
                    case ObjectKind.ListOfPointers:
                        AllocateWords(checked((uint)ListElementCount));
                        break;

                    case ObjectKind.ListOfShorts:
                        AllocateWords(checked((uint)ListElementCount + 3u) / 4);
                        break;

                    case ObjectKind.ListOfStructs:
                        AllocateWords(checked(1u + (uint)ListElementCount * (uint)(StructDataCount + StructPtrCount)));
                        var tag = default(WirePointer);
                        tag.BeginStruct(StructDataCount, StructPtrCount);
                        tag.ListOfStructsElementCount = ListElementCount;
                        SegmentSpan[Offset] = tag;
                        break;

                    case ObjectKind.Struct:
                        AllocateWords((uint)(StructDataCount + StructPtrCount));
                        break;

                    default:
                        AllocateWords(0);
                        break;
                }

                Owner?.Link(OwnerSlot, this);
            }
        }

        internal Rpc.ConsumedCapability DecodeCapPointer(int offset)
        {
            if (Caps == null)
                throw new InvalidOperationException("Capbility table not set");

            if (!IsAllocated)
            {
                return Rpc.NullCapability.Instance;
            }

            WirePointer pointer = RawData[offset];

            if (pointer.IsNull)
            {
                return Rpc.NullCapability.Instance;
            }

            if (pointer.Kind != PointerKind.Other)
            {
                throw new Rpc.RpcException("Expected a capability pointer, but got something different");
            }

            if (pointer.CapabilityIndex >= Caps.Count)
            {
                throw new Rpc.RpcException("Capability index out of range");
            }

            return Caps[(int)pointer.CapabilityIndex];
        }

        void EncodePointer(int offset, SerializerState target, bool allowCopy)
        {
            if (SegmentSpan[offset] != 0)
            {
                throw new InvalidOperationException("Won't replace an already allocated pointer to prevent memory leaks and security flaws");
            }

            if (target.Allocator != null &&
                target.Allocator != Allocator)
            {
                if (allowCopy)
                {
                    Allocate();

                    var targetCopy = new DynamicSerializerState(MsgBuilder!);
                    Reserializing.DeepCopy(target, targetCopy);
                    target = targetCopy;
                }
                else
                {
                    throw new InvalidOperationException("target was allocated on a different segment allocator");
                }
            }
            else
            {
                Allocate();
            }

            WirePointer targetPtr = default;

            switch (target.Kind)
            {
                case ObjectKind.ListOfBits:
                    targetPtr.BeginList(ListKind.ListOfBits, target.ListElementCount);
                    break;

                case ObjectKind.ListOfBytes:
                    targetPtr.BeginList(ListKind.ListOfBytes, target.ListElementCount);
                    break;

                case ObjectKind.ListOfEmpty:
                    targetPtr.BeginList(ListKind.ListOfEmpty, target.ListElementCount);
                    break;

                case ObjectKind.ListOfInts:
                    targetPtr.BeginList(ListKind.ListOfInts, target.ListElementCount);
                    break;

                case ObjectKind.ListOfLongs:
                    targetPtr.BeginList(ListKind.ListOfLongs, target.ListElementCount);
                    break;

                case ObjectKind.ListOfPointers:
                    targetPtr.BeginList(ListKind.ListOfPointers, target.ListElementCount);
                    break;

                case ObjectKind.ListOfShorts:
                    targetPtr.BeginList(ListKind.ListOfShorts, target.ListElementCount);
                    break;

                case ObjectKind.ListOfStructs:
                    int wordCount = target.ListElementCount * (target.StructDataCount + target.StructPtrCount);
                    targetPtr.BeginList(ListKind.ListOfStructs, wordCount);
                    break;

                case ObjectKind.Capability:
                    targetPtr.SetCapability(target.CapabilityIndex);
                    SegmentSpan[offset] = targetPtr;
                    return;

                case ObjectKind.Struct:
                    targetPtr.BeginStruct(target.StructDataCount, target.StructPtrCount);
                    if (target.StructDataCount == 0 && target.StructPtrCount == 0)
                    {
                        targetPtr.Offset = -1;
                        SegmentSpan[offset] = targetPtr;
                        return;
                    }
                    break;

                case ObjectKind.Nil:
                    SegmentSpan[offset] = 0;
                    return;

                default:
                    throw new NotImplementedException();
            }

            if (SegmentIndex != target.SegmentIndex)
            {
                WirePointer farPtr = default;

                if (Allocator!.Allocate(1, target.SegmentIndex, out var landingPadSlice, true))
                {
                    farPtr.SetFarPointer(target.SegmentIndex, landingPadSlice.Offset, false);
                    SegmentSpan[offset] = farPtr;
                    targetPtr.Offset = target.Offset - (landingPadSlice.Offset + 1);
                    FarSpan(target.SegmentIndex)[landingPadSlice.Offset] = targetPtr;
                }
                else
                {
                    Allocator.Allocate(2, 0, out landingPadSlice, false);
                    farPtr.SetFarPointer(landingPadSlice.SegmentIndex, landingPadSlice.Offset, true);
                    SegmentSpan[offset] = farPtr;
                    WirePointer farPtr2 = default;
                    farPtr2.SetFarPointer(target.SegmentIndex, target.Offset, false);
                    var farSpan = FarSpan(landingPadSlice.SegmentIndex);
                    farSpan[landingPadSlice.Offset] = farPtr2;
                    targetPtr.Offset = 0;
                    farSpan[landingPadSlice.Offset + 1] = targetPtr;
                }
            }
            else
            {
                targetPtr.Offset = target.Offset - (offset + 1);
                SegmentSpan[offset] = targetPtr;
            }
        }

        /// <summary>
        /// Links a sub-item (struct field or list element) of this state to another state. Usually, this operation is not necessary, since objects are constructed top-down.
        /// However, there might be some advanced scenarios where you want to reference the same object twice (also interesting for designing amplification attacks).
        /// The Cap'n Proto serialization intrinsically supports this, since messages are object graphs, not trees.
        /// </summary>
        /// <param name="slot">If this state describes a struct: Index into this struct's pointer table. 
        /// If this state describes a list of pointers: List element index.</param>
        /// <param name="target">state to be linked</param>
        /// <param name="allowCopy">Whether to deep copy the target state if it belongs to a different message builder than this state.</param>
        /// <exception cref="ArgumentNullException"><paramref name="target"/> is null</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="slot"/> out of range</exception>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>This state does neither describe a struct, nor a list of pointers</description></item>
        /// <item><description>Another state is already linked to the specified position (sorry, no overwrite allowed)</description></item>
        /// <item><description>This state and <paramref name="target"/> belong to different message builder, and<paramref name="allowCopy"/> is false</description></item>
        /// </list>
        /// </exception>
        protected void Link(int slot, SerializerState target, bool allowCopy = true)
        {
            if (target == null)
                throw new ArgumentNullException(nameof(target));

            if (slot < 0)
                throw new ArgumentOutOfRangeException(nameof(slot));

            if (!IsAllocated)
            {
                SegmentIndex = target.SegmentIndex;
                Allocate();
            }

            if (!target.IsAllocated)
            {
                target.Allocate();
            }

            switch (Kind)
            {
                case ObjectKind.Struct:
                    if (slot >= StructPtrCount)
                        throw new ArgumentOutOfRangeException(nameof(slot));

                    EncodePointer(Offset + StructDataCount + slot, target, allowCopy);

                    break;

                case ObjectKind.ListOfPointers:
                    if (slot >= ListElementCount)
                        throw new ArgumentOutOfRangeException(nameof(slot));

                    EncodePointer(Offset + slot, target, allowCopy);

                    break;

                default:
                    throw new InvalidOperationException("This object cannot own pointers to sub-objects");
            }

            _linkedStates![slot] = target;
        }

        /// <summary>
        /// Links a sub-item (struct field or list element) of this state to a capability.
        /// </summary>
        /// <param name="slot">If this state describes a struct: Index into this struct's pointer table. 
        /// If this state describes a list of pointers: List element index.</param>
        /// <param name="capabilityIndex">capability index inside the capability table</param>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>This state does neither describe a struct, nor a list of pointers</description></item>
        /// <item><description>Another state is already linked to the specified position (sorry, no overwrite allowed)</description></item></list>
        /// </exception>
        protected void LinkToCapability(int slot, uint? capabilityIndex)
        {
            var cstate = new SerializerState();
            cstate.SetCapability(capabilityIndex);
            Link(slot, cstate);
        }

        static InvalidOperationException AlreadySet() => new InvalidOperationException("The object type was already set");
        static InvalidOperationException Unbound() => new InvalidOperationException("This state is not bound to a MessageBuilder");

        void VerifyNotYetAllocated()
        {
            if (IsAllocated)
                throw new InvalidOperationException("Not permitted since the state is already allocated");
        }

        /// <summary>
        /// Determines the underlying object to be a struct.
        /// </summary>
        /// <param name="dataCount">Desired size of the struct's data section, in words</param>
        /// <param name="ptrCount">Desired size of the struct's pointer section, in words</param>
        /// <exception cref="InvalidOperationException">The object type was already set to something different</exception>
        protected void SetStruct(ushort dataCount, ushort ptrCount)
        {
            if (Kind == ObjectKind.Nil)
            {
                VerifyNotYetAllocated();

                Kind = ObjectKind.Struct;
                StructDataCount = dataCount;
                StructPtrCount = ptrCount;

                _linkedStates = new SerializerState[ptrCount];
            }
            else if (Kind != ObjectKind.Struct || StructDataCount != dataCount || StructPtrCount != ptrCount)
            {
                throw AlreadySet();
            }
        }

        /// <summary>
        /// Determines the underyling object to be a capability.
        /// </summary>
        /// <param name="capabilityIndex">Capability table index, or null to encode a null pointer</param>
        /// <exception cref="InvalidOperationException">The object type was already set to something different</exception>
        protected void SetCapability(uint? capabilityIndex)
        {
            if (capabilityIndex.HasValue)
            {
                if (Kind == ObjectKind.Nil)
                {
                    VerifyNotYetAllocated();

                    Kind = ObjectKind.Capability;
                    CapabilityIndex = capabilityIndex.Value;
                    Allocate();
                }
                else if (Kind != ObjectKind.Capability || CapabilityIndex != capabilityIndex)
                {
                    throw AlreadySet();
                }
            }
            else
            {
                if (Kind != ObjectKind.Nil)
                {
                    throw AlreadySet();
                }
            }
        }

        /// <summary>
        /// Determines the underlying object to be a list of (primitive) values.
        /// </summary>
        /// <param name="bitsPerElement">Element size in bits, must be 0 (void), 1 (bool), 8, 16, 32, or 64</param>
        /// <param name="totalCount">Desired element count</param>
        /// <exception cref="InvalidOperationException">The object type was already set to something different</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="bitsPerElement"/> outside allowed range, 
        /// <paramref name="totalCount"/> negative or exceeding 2^29-1</exception>
        protected void SetListOfValues(byte bitsPerElement, int totalCount)
        {
            var kind = bitsPerElement switch
            {
                0 => ObjectKind.ListOfEmpty,
                1 => ObjectKind.ListOfBits,
                8 => ObjectKind.ListOfBytes,
                16 => ObjectKind.ListOfShorts,
                32 => ObjectKind.ListOfInts,
                64 => ObjectKind.ListOfLongs,
                _ => throw new ArgumentOutOfRangeException(nameof(bitsPerElement)),
            };
            if (Kind == ObjectKind.Nil)
            {
                if (totalCount < 0)
                    throw new ArgumentOutOfRangeException(nameof(totalCount));

                VerifyNotYetAllocated();

                Kind = kind;
                ListElementCount = totalCount;

                Allocate();
            }
            else if (Kind != kind || ListElementCount != totalCount)
            {
                throw AlreadySet();
            }
        }

        /// <summary>
        /// Determines the underlying object to be a list of pointers.
        /// </summary>
        /// <param name="totalCount">Desired element count</param>
        /// <exception cref="InvalidOperationException">The object type was already set to something different</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="totalCount"/> negative or exceeding 2^29-1</exception>
        protected void SetListOfPointers(int totalCount)
        {
            if (Kind == ObjectKind.Nil)
            {
                if (totalCount < 0)
                    throw new ArgumentOutOfRangeException(nameof(totalCount));

                VerifyNotYetAllocated();

                Kind = ObjectKind.ListOfPointers;
                ListElementCount = totalCount;

                _linkedStates = new SerializerState[totalCount];

                Allocate();
            }
            else if (Kind != ObjectKind.ListOfPointers || ListElementCount != totalCount)
            {
                throw AlreadySet();
            }
        }

        /// <summary>
        /// Determines the underlying object to be a list of structs (fixed-width compound list).
        /// </summary>
        /// <param name="totalCount">Desired element count</param>
        /// <param name="dataCount">Desired size of each struct's data section, in words</param>
        /// <param name="ptrCount">Desired size of each struct's pointer section, in words</param>
        /// <exception cref="InvalidOperationException">The object type was already set to something different</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="totalCount"/> negative, or total word count would exceed 2^29-1</exception>
        protected void SetListOfStructs(int totalCount, ushort dataCount, ushort ptrCount)
        {
            if (Kind == ObjectKind.Nil)
            {
                if (totalCount < 0)
                    throw new ArgumentOutOfRangeException(nameof(totalCount));

                VerifyNotYetAllocated();

                Kind = ObjectKind.ListOfStructs;
                ListElementCount = totalCount;
                StructDataCount = dataCount;
                StructPtrCount = ptrCount;

                _linkedStates = new SerializerState[totalCount];

                Allocate();
            }
            else if (Kind != ObjectKind.ListOfStructs || 
                ListElementCount != totalCount ||
                StructDataCount != dataCount ||
                StructPtrCount != ptrCount)
            {
                throw AlreadySet();
            }
        }

        /// <summary>
        /// Determines the underlying object to be a list of bytes and encodes the given text.
        /// </summary>
        /// <param name="text">text to encode</param>
        /// <exception cref="ArgumentNullException"><paramref name="text"/> is null</exception>
        /// <exception cref="EncoderFallbackException">Trying to obtain the UTF-8 encoding might throw this exception.</exception>
        /// <exception cref="InvalidOperationException">The object type was already set to something different</exception>
        /// <exception cref="ArgumentOutOfRangeException">UTF-8 encoding exceeds 2^29-2 bytes</exception>
        protected void WriteText(string? text)
        {
            if (text == null)
            {
                VerifyNotYetAllocated();
            }
            else
            {
                byte[] srcBytes = Encoding.UTF8.GetBytes(text);
                SetListOfValues(8, srcBytes.Length + 1);
                var srcSpan = new ReadOnlySpan<byte>(srcBytes);
                var dstSpan = ListGetBytes();
                dstSpan = dstSpan.Slice(0, dstSpan.Length - 1);
                srcSpan.CopyTo(dstSpan);
            }
        }

        /// <summary>
        /// Writes data (up to 64 bits) into the underlying struct's data section. 
        /// The write operation must be aligned to fit within a single word.
        /// </summary>
        /// <param name="bitOffset">Start bit relative to the struct's data section, little endian</param>
        /// <param name="bitCount">Number of bits to write</param>
        /// <param name="value">Data bits to write</param>
        /// <exception cref="InvalidOperationException">The object was not determined to be a struct</exception>
        /// <exception cref="ArgumentOutOfRangeException">The data slice specified by <paramref name="bitOffset"/> and <paramref name="bitCount"/>
        /// is not completely within the struct's data section, misaligned, exceeds one word, or <paramref name="bitCount"/> is negative</exception>
        public void StructWriteData(ulong bitOffset, int bitCount, ulong value)
        {
            if (Kind != ObjectKind.Struct)
                throw new InvalidOperationException("This is not a struct");

            Allocate();

            int index = checked((int)(bitOffset / 64));
            int relBitOffset = (int)(bitOffset % 64);

            var data = StructDataSection;

            if (relBitOffset + bitCount > 64)
                throw new ArgumentOutOfRangeException(nameof(bitCount));

            if (bitCount == 64)
            {
                data[index] = value;
            }
            else
            {
                ulong mask = ~(((1ul << bitCount) - 1) << relBitOffset);
                data[index] = data[index] & mask | (value << relBitOffset);
            }
        }

        /// <summary>
        /// Reads data (up to 64 bits) from the underlying struct's data section. 
        /// The write operation must be aligned to fit within a single word.
        /// </summary>
        /// <param name="bitOffset">Start bit relative to the struct's data section, little endian</param>
        /// <param name="count">Number of bits to read</param>
        /// <returns>Data bits which were read</returns>
        /// <exception cref="InvalidOperationException">The object was not determined to be a struct</exception>
        /// <exception cref="ArgumentOutOfRangeException">The data slice specified by <paramref name="bitOffset"/> and <paramref name="count"/>
        /// is not completely within the struct's data section, misaligned, exceeds one word, or <paramref name="count"/> is negative</exception>
        public ulong StructReadData(ulong bitOffset, int count)
        {
            if (Kind != ObjectKind.Struct)
                throw new InvalidOperationException("This is not a struct");

            if (!IsAllocated)
                return 0;

            int index = checked((int)(bitOffset / 64));
            int relBitOffset = (int)(bitOffset % 64);

            var data = StructDataSection;

            if (index >= data.Length)
                return 0; // Assume backwards-compatible change

            if (count < 0)
                throw new ArgumentOutOfRangeException(nameof(count));

            if (relBitOffset + count > 64)
                throw new ArgumentOutOfRangeException(nameof(count));

            ulong word = data[index];

            if (count == 64)
            {
                return word;
            }
            else
            {
                ulong mask = (1ul << count) - 1;
                return (word >> relBitOffset) & mask;
            }
        }

        /// <summary>
        /// Constructs a new object at a struct field or list element, or returns the serializer state for an existing object.
        /// </summary>
        /// <typeparam name="TS">Target state type</typeparam>
        /// <param name="index">If the underlying object is a struct: index into the struct's pointer section.
        /// If the underlying object is a list of pointers: Element index</param>
        /// <returns>Bound serializer state instance</returns>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>The underlying object was not determined to be a struct or list of pointers.</description></item>
        /// <item><description>Object at given position was already built and is not compatible with the desired target serializer type.</description></item>
        /// </list></exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public TS BuildPointer<TS>(int index) where TS: SerializerState, new()
        {
            if (Kind != ObjectKind.Struct && Kind != ObjectKind.ListOfPointers)
                throw new InvalidOperationException("This is not a struct or list of pointers");

            ref var state = ref _linkedStates![index];

            if (state == null)
            {
                state = new TS();
                state.Bind(this, index);
            }

            return state.Rewrap<TS>();
        }

        /// <summary>
        /// Returns an existing serializer state for a struct field or list element, or null if no such object exists.
        /// </summary>
        /// <typeparam name="TS">Target state type</typeparam>
        /// <param name="index">If the underlying object is a struct: index into the struct's pointer section.
        /// If the underlying object is a list of pointers: Element index</param>
        /// <returns>Bound serializer state instance</returns>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>The underlying object was not determined to be a struct or list of pointers.</description></item>
        /// <item><description>Object at given position is not compatible with the desired target serializer type.</description></item>
        /// </list></exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public TS? TryGetPointer<TS>(int index) where TS : SerializerState, new()
        {
            if (Kind != ObjectKind.Struct && Kind != ObjectKind.ListOfPointers)
                throw new InvalidOperationException("This is not a struct or list of pointers");

            if (index < 0 || index >= _linkedStates!.Length)
                throw new ArgumentOutOfRangeException(nameof(index));

            var state = _linkedStates![index];

            if (state == null) return null;

            return state.Rewrap<TS>();
        }

        /// <summary>
        /// Convenience method for <code><![CDATA[BuildPointer<DynamicSerializerState>]]></code>
        /// </summary>
        /// <param name="index">If the underlying object is a struct: index into the struct's pointer section.
        /// If the underlying object is a list of pointers: Element index</param>
        /// <returns>Bound serializer state instance</returns>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>The underlying object was not determined to be a struct or list of pointers.</description></item>
        /// <item><description>Object at given position was already built and is not compatible with the desired target serializer type.</description></item>
        /// </list></exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public DynamicSerializerState BuildPointer(int index) => BuildPointer<DynamicSerializerState>(index);

        /// <summary>
        /// Convenience method for <code><![CDATA[TryGetPointer<SerializerState>]]></code>
        /// </summary>
        /// <param name="index">If the underlying object is a struct: index into the struct's pointer section.
        /// If the underlying object is a list of pointers: Element index</param>
        /// <returns>Bound serializer state instance</returns>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>The underlying object was not determined to be a struct or list of pointers.</description></item>
        /// <item><description>Object at given position is not compatible with the desired target serializer type.</description></item>
        /// </list></exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public SerializerState? TryGetPointer(int index) => TryGetPointer<SerializerState>(index);

        /// <summary>
        /// Reads text from a struct field or list element.
        /// </summary>
        /// <param name="index">If the underlying object is a struct: index into the struct's pointer section.
        /// If the underlying object is a list of pointers: Element index</param>
        /// <param name="defaultText">String to return in case of null</param>
        /// <returns>The decoded text</returns>
        public string? ReadText(int index, string? defaultText = null)
        {
            var b = BuildPointer(index);

            if (b.IsAllocated)
                return b.ListReadAsText();
            else
                return defaultText;
        }

        /// <summary>
        /// Encodes text into a struct field or list element.
        /// </summary>
        /// <param name="index">If the underlying object is a struct: index into the struct's pointer section.
        /// If the underlying object is a list of pointers: Element index</param>
        /// <param name="text">Text to encode</param>
        /// <exception cref="ArgumentNullException"><paramref name="text"/>is null</exception>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>The underlying object was not determined to be a struct or list of pointers.</description></item>
        /// <item><description>Object at given position was already set.</description></item>
        /// </list></exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void WriteText(int index, string? text)
        {
            BuildPointer(index).WriteText(text);
        }

        /// <summary>
        /// Encodes text into a struct field or list element, with fallback to a default text.
        /// </summary>
        /// <param name="index">If the underlying object is a struct: index into the struct's pointer section.
        /// If the underlying object is a list of pointers: Element index</param>
        /// <param name="text">Text to encode</param>
        /// <param name="defaultText">Default text if <paramref name="text"/>> is null</param>
        /// <exception cref="ArgumentNullException">Both <paramref name="text"/> and <paramref name="defaultText"/> are null</exception>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>The underlying object was not determined to be a struct or list of pointers.</description></item>
        /// <item><description>Object at given position was already set.</description></item>
        /// </list></exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void WriteText(int index, string? text, string? defaultText)
        {
            BuildPointer(index).WriteText(text ?? defaultText);
        }

        /// <summary>
        /// Returns a state which represents a fixed-width composite list element.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <returns>Bound serializer state</returns>
        /// <exception cref="InvalidOperationException">Underlying object was not determined to be a fixed-width composite list.</exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/>is out of bounds.</exception>
        public SerializerState ListBuildStruct(int index)
        {
            if (Kind != ObjectKind.ListOfStructs)
                throw new InvalidOperationException("This is not a list of structs");

            if (index < 0 || index >= _linkedStates!.Length)
                throw new ArgumentOutOfRangeException(nameof(index));

            ref var state = ref _linkedStates![index];

            if (state == null)
            {
                state = new SerializerState(MsgBuilder!);
                state.SetStruct(StructDataCount, StructPtrCount);
                state.SegmentIndex = SegmentIndex;
                state.Offset = Offset + 1 + index * (StructDataCount + StructPtrCount);
            }

            return _linkedStates[index];
        }

        /// <summary>
        /// Returns a state which represents a fixed-width composite list element.
        /// </summary>
        /// <typeparam name="TS">Target serializer state type</typeparam>
        /// <param name="index"></param>
        /// <returns>Bound serializer state</returns>
        /// <exception cref="InvalidOperationException">Underlying object was not determined to be a fixed-width composite list.</exception>
        /// <exception cref="IndexOutOfRangeException"><paramref name="index"/>is out of bounds.</exception>
        public TS ListBuildStruct<TS>(int index)
            where TS: SerializerState, new()
        {
            if (Kind != ObjectKind.ListOfStructs)
                throw new InvalidOperationException("This is not a list of structs");

            if (index < 0 || index >= _linkedStates!.Length)
                throw new ArgumentOutOfRangeException(nameof(index));

            ref var state = ref _linkedStates![index];

            if (state == null)
            {
                state = new TS();
                state.Bind(MsgBuilder!);
                state.SetStruct(StructDataCount, StructPtrCount);
                state.SegmentIndex = SegmentIndex;
                int stride = StructDataCount + StructPtrCount;
                state.Offset = Offset + stride * index + 1;
            }

            return (TS)state;
        }

        internal IReadOnlyList<TS> ListEnumerateStructs<TS>()
            where TS: SerializerState, new()
        {
            if (Kind != ObjectKind.ListOfStructs)
                throw new InvalidOperationException("This is not a list of structs");

            if (ListElementCount < 0)
                throw new InvalidOperationException("Define element count first");

            int minOffset = Offset + 1;
            int maxOffset = minOffset + ListElementCount;

            for (int offset = minOffset; offset < maxOffset; offset++)
            {
                ref var state = ref _linkedStates![offset - minOffset];

                if (state == null)
                {
                    state = new TS();
                    state.Bind(MsgBuilder!);
                    state.SetStruct(StructDataCount, StructPtrCount);
                    state.SegmentIndex = SegmentIndex;
                    state.Offset = offset;
                }
            }

            return _linkedStates!.LazyListSelect(ts => (TS)ts);
        }

        /// <summary>
        /// Sets an element of a list of bits.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of bits.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, bool value, bool defaultValue = false)
        {
            if (Kind != ObjectKind.ListOfBits)
                throw new InvalidOperationException("This is not a list of bits");

            if (index < 0 || index >= ListElementCount)
                throw new ArgumentOutOfRangeException(nameof(index));

            bool bit = value != defaultValue;
            int wordIndex = index / 64;
            int relBitOffset = index % 64;

            if (bit)
                SegmentSpan[Offset + wordIndex] |= (1ul << relBitOffset);
            else
                SegmentSpan[Offset + wordIndex] &= ~(1ul << relBitOffset);
        }

        /// <summary>
        /// Sets the list-of-bits' content.
        /// </summary>
        /// <param name="values">Content to set</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of bits.</exception>
        /// <exception cref="ArgumentNullException"><paramref name="values"/> is null.</exception>
        /// <exception cref="ArgumentOutOfRangeException">The given element count does not match the underlying list's element count.</exception>
        public void ListWriteValues(IReadOnlyList<bool> values, bool defaultValue = false)
        {
            if (Kind != ObjectKind.ListOfBits)
                throw new InvalidOperationException("This is not a list of bits");

            if (values == null)
                throw new ArgumentNullException(nameof(values));

            if (values.Count != ListElementCount)
                throw new ArgumentOutOfRangeException(nameof(values));

            int i, w = Offset;
            ulong v;

            for (i = 0; i < ListElementCount - 63; i += 64)
            {
                v = 0;

                for (int j = 63; j >= 0; j--)
                {
                    v <<= 1;
                    if (values[i + j]) v |= 1;
                }

                if (defaultValue) v = ~v;

                SegmentSpan[w++] = v;
            }

            if (i < ListElementCount)
            {
                v = 0;

                for (int k = ListElementCount - 1; k >= i; k--)
                {
                    v <<= 1;
                    if (values[k]) v |= 1;
                }

                if (defaultValue) v = ~v;

                SegmentSpan[w] = v;
            }
        }

        /// <summary>
        /// Sets an element of a list of bytes.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of bytes.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, byte value, byte defaultValue = 0)
        {
            if (Kind != ObjectKind.ListOfBytes)
                throw new InvalidOperationException("This is not a list of bytes");

            if (index < 0 || index >= ListElementCount)
                throw new ArgumentOutOfRangeException(nameof(index));

            byte x = (byte)(value ^ defaultValue);
            MemoryMarshal.Cast<ulong, byte>(SegmentSpan.Slice(Offset))[index] = x;
        }

        /// <summary>
        /// Returns the content of a list of bytes.
        /// </summary>
        /// <returns>The list bytes</returns>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of bytes.</exception>
        public Span<byte> ListGetBytes()
        {
            if (Kind != ObjectKind.ListOfBytes)
                throw new InvalidOperationException("This is not a list of bytes");

            return MemoryMarshal.Cast<ulong, byte>(SegmentSpan.Slice(Offset)).Slice(0, ListElementCount);
        }

        /// <summary>
        /// Decodes a list of bytes as text.
        /// </summary>
        /// <returns>The decoded text.</returns>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of bytes.</exception>
        /// <exception cref="DecoderFallbackException">Might theoretically be thrown during decoding.</exception>
        public string ListReadAsText()
        {
            var bytes = ListGetBytes();
            if (bytes.Length == 0) return string.Empty;
#if NETSTANDARD2_0
            return Encoding.UTF8.GetString(bytes.Slice(0, bytes.Length - 1).ToArray());
#else
            return Encoding.UTF8.GetString(bytes.Slice(0, bytes.Length - 1));
#endif
        }

        /// <summary>
        /// Sets an element of a list of (signed) bytes.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of bytes.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, sbyte value, sbyte defaultValue = 0)
        {
            ListWriteValue(index, unchecked((byte)value), unchecked((byte)defaultValue));
        }

        /// <summary>
        /// Sets an element of a list of 16 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 16 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, ushort value, ushort defaultValue = 0)
        {
            if (Kind != ObjectKind.ListOfShorts)
                throw new InvalidOperationException("This is not a list of 16-bit values");

            if (index < 0 || index >= ListElementCount)
                throw new ArgumentOutOfRangeException(nameof(index));

            Allocate();

            ushort x = (ushort)(value ^ defaultValue);
            MemoryMarshal.Cast<ulong, ushort>(SegmentSpan.Slice(Offset))[index] = x;
        }

        /// <summary>
        /// Sets an element of a list of 16 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 16 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, short value, short defaultValue = 0)
        {
            ListWriteValue(index, unchecked((ushort)value), unchecked((ushort)defaultValue));
        }

        /// <summary>
        /// Sets an element of a list of 32 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 32 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, uint value, uint defaultValue = 0)
        {
            if (Kind != ObjectKind.ListOfInts)
                throw new InvalidOperationException("This is not a list of 32-bit values");

            if (index < 0 || index >= ListElementCount)
                throw new ArgumentOutOfRangeException(nameof(index));

            Allocate();

            uint x = value ^ defaultValue;
            MemoryMarshal.Cast<ulong, uint>(SegmentSpan.Slice(Offset))[index] = x;
        }

        /// <summary>
        /// Sets an element of a list of 32 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 32 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, int value, int defaultValue = 0)
        {
            ListWriteValue(index, unchecked((uint)value), unchecked((uint)defaultValue));
        }

        /// <summary>
        /// Sets an element of a list of 32 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 32 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, float value, float defaultValue = 0)
        {
            int rcastValue = value.ReplacementSingleToInt32Bits();
            int rcastDefaultValue = defaultValue.ReplacementSingleToInt32Bits();
            ListWriteValue(index, rcastValue, rcastDefaultValue);
        }

        /// <summary>
        /// Sets an element of a list of 64 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 64 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, ulong value, ulong defaultValue = 0)
        {
            if (Kind != ObjectKind.ListOfLongs)
                throw new InvalidOperationException("This is not a list of 64-bit values");

            if (index < 0 || index >= ListElementCount)
                throw new ArgumentOutOfRangeException(nameof(index));

            Allocate();

            ulong x = value ^ defaultValue;
            SegmentSpan.Slice(Offset)[index] = x;
        }

        /// <summary>
        /// Sets an element of a list of 64 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 64 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, long value, long defaultValue = 0)
        {
            ListWriteValue(index, unchecked((ulong)value), unchecked((ulong)defaultValue));
        }

        /// <summary>
        /// Sets an element of a list of 64 bit words.
        /// </summary>
        /// <param name="index">Element index</param>
        /// <param name="value">Element value</param>
        /// <param name="defaultValue">Element default value (serialized value will be XORed with the default value)</param>
        /// <exception cref="InvalidOperationException">The underlying object was not set to a list of 64 bit words.</exception>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index"/> is out of bounds.</exception>
        public void ListWriteValue(int index, double value, double defaultValue = 0)
        {
            long rcastValue = BitConverter.DoubleToInt64Bits(value);
            long rcastDefaultValue = BitConverter.DoubleToInt64Bits(defaultValue);
            ListWriteValue(index, rcastValue, rcastDefaultValue);
        }

        /// <summary>
        /// Adds an entry to the capability table if the provided capability does not yet exist.
        /// </summary>
        /// <param name="capability">The low-level capability object to provide.</param>
        /// <returns>Index of the given capability in the capability table, null if capability is null</returns>
        /// <exception cref="InvalidOperationException">The underlying message builder was not configured for capability table support.</exception>
        public uint? ProvideCapability(Rpc.ConsumedCapability capability)
        {
            if (capability == null || capability == Rpc.NullCapability.Instance)
                return null;

            if (Caps == null)
                throw new InvalidOperationException("Underlying MessageBuilder was not enabled to support capabilities");

            int index = Caps.IndexOf(capability);

            if (index < 0)
            {
                index = Caps.Count;
                Caps.Add(capability);
                capability.AddRef();
            }

            return (uint)index;
        }

        /// <summary>
        /// Adds an entry to the capability table if the provided capability does not yet exist.
        /// </summary>
        /// <param name="capability">The capability to provide, in terms of its skeleton.</param>
        /// <returns>Index of the given capability in the capability table</returns>
        /// <exception cref="InvalidOperationException">The underlying message builder was not configured for capability table support.</exception>
        public uint? ProvideCapability(Rpc.Skeleton capability)
        {
            return ProvideCapability(capability.AsCapability());
        }

        /// <summary>
        /// Adds an entry to the capability table if the provided capability does not yet exist.
        /// </summary>
        /// <param name="obj">The capability, in one of the following forms:<list type="bullet">
        /// <item><description>Low-level capability (<see cref="Rpc.ConsumedCapability"/>)</description></item>
        /// <item><description>Proxy object (<see cref="Rpc.Proxy"/>). Note that the provision has "move semantics": SerializerState
        /// takes ownership, so the Proxy object will be disposed.</description></item>
        /// <item><description><see cref="Rpc.Skeleton"/> instance</description></item>
        /// <item><description>Capability interface implementation</description></item>
        /// </list></param>
        /// <returns>Index of the given capability in the capability table</returns>
        /// <exception cref="InvalidOperationException">The underlying message builder was not configured for capability table support.</exception>
        public uint? ProvideCapability(object? obj)
        {
            switch (obj)
            {
                case null:
                    return null;
                case Rpc.Proxy proxy: using (proxy)
                    return ProvideCapability(proxy.ConsumedCap);
                case Rpc.ConsumedCapability consumedCapability:
                    return ProvideCapability(consumedCapability);
                case Rpc.Skeleton providedCapability:
                    return ProvideCapability(providedCapability);
                default:
                    return ProvideCapability(Rpc.CapabilityReflection.CreateSkeletonInternal(obj));
            }
        }

        /// <summary>
        /// Links a sub-item (struct field or list element) of this state to another object. 
        /// In contrast to <see cref="Link(int, SerializerState, bool)"/>, this method also accepts deserializer states, domain objects, capabilites, and lists thereof.
        /// If necessary, it will perform a deep copy.
        /// </summary>
        /// <param name="slot">If this state describes a struct: Index into this struct's pointer table. 
        /// If this state describes a list of pointers: List element index.</param>
        /// <param name="obj">Object to be linked. Must be one of the following:<list type="bullet">
        /// <item><description>Another <see cref="SerializerState"/></description></item>
        /// <item><description>A <see cref="DeserializerState"/> (will always deep copy)</description></item>
        /// <item><description>An object implementing <see cref="ICapnpSerializable"/></description></item>
        /// <item><description>A low-level capability object (<see cref="Rpc.ConsumedCapability"/>)</description></item>
        /// <item><description>A proxy object (<see cref="Rpc.Proxy"/>)</description></item>
        /// <item><description>A skeleton object (<see cref="Rpc.Skeleton"/>)</description></item>
        /// <item><description>A capability interface implementation</description></item>
        /// <item><description>A <see cref="IReadOnlyList{T}"/> of one of the things listed here.</description></item>
        /// </list></param>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="slot"/> is out of range.</exception>
        /// <exception cref="InvalidOperationException"><list type="bullet">
        /// <item><description>Object neither describes a struct, nor a list of pointers, nor a capability</description></item>
        /// <item><description>Another state is already linked to the specified position (sorry, no overwrite allowed)</description></item></list>
        /// </exception>
        public void LinkObject<T>(int slot, T obj)
        {
            switch (obj)
            {
                case SerializerState s:
                    Link(slot, s);
                    break;

                case DeserializerState d:
                    Reserializing.DeepCopy(d, BuildPointer(slot));
                    break;

                case ICapnpSerializable serializable:
                    serializable.Serialize(BuildPointer(slot));
                    break;

                case IReadOnlyList<object> list:
                    {
                        var builder = BuildPointer(slot);
                        builder.SetListOfPointers(list.Count);
                        int i = 0;
                        foreach (var item in list)
                        {
                            builder.LinkObject(i++, item);
                        }
                    }
                    break;

                default:
                    try
                    {
                        LinkToCapability(slot, ProvideCapability(obj));
                    }
                    catch (Exception exception) when (
                        exception is Rpc.InvalidCapabilityInterfaceException ||
                        exception is InvalidOperationException)
                    {
                        throw new InvalidOperationException("Object neither describes a struct, nor a list of pointers, nor a capability", exception);
                    }
                    break;
            }
        }

        internal Rpc.ConsumedCapability StructReadRawCap(int index)
        {
            if (Kind != ObjectKind.Struct && Kind != ObjectKind.Nil)
                throw new InvalidOperationException("Allowed on structs only");

            if (index < 0 || index >= StructPtrCount)
                throw new ArgumentOutOfRangeException(nameof(index));

            return DecodeCapPointer(index + StructDataCount);
        }

        /// <summary>
        /// Reads a struct field as capability and returns a proxy to that capability. 
        /// </summary>
        /// <typeparam name="T">Desired capability interface</typeparam>
        /// <param name="slot">Index into this struct's pointer table.</param>
        /// <returns>The proxy instance</returns>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="slot"/> is out of range.</exception>
        /// <exception cref="ArgumentException">The desired interface does not qualify as capability interface (<see cref="Rpc.ProxyAttribute"/>)</exception>
        /// <exception cref="InvalidOperationException">This state does not represent a struct.</exception>
        public T ReadCap<T>(int slot) where T : class
        {
            var cap = StructReadRawCap(slot);
            return (Rpc.CapabilityReflection.CreateProxy<T>(cap) as T)!;
        }

        /// <summary>
        /// Reads a struct field as capability and returns a bare (generic) proxy to that capability. 
        /// </summary>
        /// <param name="slot">Index into this struct's pointer table.</param>
        /// <returns>The proxy instance</returns>
        /// <exception cref="ArgumentOutOfRangeException"><paramref name="slot"/> is out of range.</exception>
        /// <exception cref="InvalidOperationException">This state does not represent a struct.</exception>
        public Rpc.BareProxy ReadCap(int slot)
        {
            var cap = StructReadRawCap(slot);
            return new Rpc.BareProxy(cap);
        }

        /// <summary>
        /// Releases the capability table
        /// </summary>
        public void Dispose()
        {
            if (Caps != null && !_disposed)
            {
                foreach (var cap in Caps)
                {
                    cap.Release();
                }

                Caps.Clear();
                _disposed = true;
            }
        }
    }
}