Game.Serialization.ReadBuffer

Assembly:
Namespace: Game.Serialization

Type: public class ReadBuffer

Base: IReadBuffer

Summary:
ReadBuffer is a small helper used to provide a contiguous byte buffer and a position pointer for reading serialized data in jobs or on the main thread. It owns a NativeArray (the raw buffer) and a NativeReference (the current read position), both allocated with Allocator.TempJob. The class exposes explicit Done(...) methods to dispose the native allocations either immediately or after a scheduled job completes. Use Done(JobHandle) when the buffer is passed to a scheduled job; use Done() if you finish using the buffer on the calling thread.

Fields

This type does not define any private fields; it exposes its data through public properties (buffer and position).

Properties

public Unity.Collections.NativeArray<byte> buffer { get; private set; }
Buffer holding the raw serialized bytes. Allocated with Allocator.TempJob. When passed into jobs, respect proper aliasing and [ReadOnly] usage as appropriate. Do not access after calling Done().
public Unity.Collections.NativeReference<int> position { get; private set; }
A single int stored as a NativeReference representing the current read position (offset in bytes) within the buffer. Initialized to 0 in the constructor. When used from jobs, this is the convenient way to track and update a shared read cursor.

Constructors

public ReadBuffer(int size)
Creates a new ReadBuffer allocating a NativeArray of the specified size and a NativeReference initialized to 0. Both allocations use Allocator.TempJob, meaning they are intended for short-lived use and safe for use with Unity.Jobs. Example: new ReadBuffer(1024);

Methods

public void Done(Unity.Jobs.JobHandle handle)
Dispose of the buffer and position using the provided JobHandle. This schedules the disposals to occur after the job(s) represented by handle complete. Use this when the NativeArray/NativeReference are still referenced by scheduled jobs.
public void Done()
Dispose the buffer and position immediately on the calling thread. Use only when no scheduled jobs are using these natives.

Notes and cautions: - Because Allocator.TempJob was used, the allocations are intended for short lifetimes. Ensure you dispose them promptly via Done or they will leak or trigger safety checks. - When passing buffer/position into jobs, ensure the job's Burst and safety attributes reflect read/write access correctly (e.g., mark buffer as [ReadOnly] if only reading). - After calling either Done overload, do not access buffer or position — they are disposed.

Usage Example

// Example: create a ReadBuffer, schedule a job that reads from it,
// and dispose the natives after the job completes.

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;
using UnityEngine;
using Game.Serialization;

[BurstCompile]
struct ReadExampleJob : IJob
{
    // If job only reads, mark as ReadOnly in real code:
    public NativeArray<byte> buffer;
    public NativeReference<int> position;

    public void Execute()
    {
        // Example: read one byte if available
        int pos = position.Value;
        if (pos < buffer.Length)
        {
            byte b = buffer[pos];
            // process b...
            position.Value = pos + 1;
        }
    }
}

public class ExampleUsage
{
    public void Run()
    {
        var readBuffer = new ReadBuffer(1024);

        // Fill buffer with data (example)
        for (int i = 0; i < 10; i++) readBuffer.buffer[i] = (byte)i;

        var job = new ReadExampleJob
        {
            buffer = readBuffer.buffer,
            position = readBuffer.position
        };

        JobHandle handle = job.Schedule();

        // Dispose of the natives when the job completes:
        readBuffer.Done(handle);

        // If you instead read synchronously on the main thread:
        // byte b = readBuffer.buffer[readBuffer.position.Value];
        // readBuffer.position.Value++;
        // readBuffer.Done(); // immediate disposal
    }
}

Additional tips: - Prefer Done(JobHandle) for scheduled work to avoid accessing disposed memory. - Consider using Allocator.Persistent only if you need long-lived memory — then change disposal strategy accordingly. - This class implements IReadBuffer (from Colossal.Serialization.Entities) to integrate with the game's serialization infrastructure.