Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(cs): show zero-allocation #342

Merged
merged 1 commit into from
Aug 5, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 43 additions & 0 deletions docs/src/content/docs/guide/getting-started-csharp.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -203,3 +203,46 @@ person.Switch(

Unions are particularly useful when you need to represent data that can be one of several types, providing a type-safe way to handle different cases in your application.


## Advanced Usage: Zero-Allocation Network Writing with EncodeIntoBuffer

For high-performance scenarios, especially when writing to a network stream, you can use the `EncodeIntoBuffer` method along with `System.Buffers.ArrayPool<T>` to achieve zero-allocation encoding. This approach is particularly useful in situations where you're sending many objects rapidly and want to avoid any overhead from memory allocations.

### Concept: Using EncodeIntoBuffer for Network Writing

Here's the core concept of how to use `EncodeIntoBuffer` with `ArrayPool<T>` to write directly to a network stream without allocations:

```csharp
try
{
if (_buffer == null || _buffer.Length < person.MaxByteCount)
{
if (_buffer != null)
ArrayPool<byte>.Shared.Return(_buffer);
_buffer = ArrayPool<byte>.Shared.Rent(person.MaxByteCount);
}

int bytesWritten = person.EncodeIntoBuffer(_buffer);
stream.Write(_buffer, 0, bytesWritten);
}
finally
{
// Ensure the buffer is returned to the pool if an exception occurs
// Note: In a real implementation, you'd want to be more careful about when to return the buffer
ArrayPool<byte>.Shared.Return(_buffer);
}
```

### Key Concepts

1. **Use of ArrayPool**: We rent a buffer from `ArrayPool<byte>.Shared` instead of allocating a new array each time.

2. **Sizing with MaxByteCount**: We use `person.MaxByteCount` to ensure our buffer is large enough for the current instance of the Person record. This value can vary between instances, especially for records with variable-length fields like strings or arrays.

3. **Zero-Allocation Encoding**: `EncodeIntoBuffer` writes directly into the rented buffer, avoiding additional allocations.

4. **Direct Stream Writing**: We write the exact number of bytes used in encoding directly to the stream.

5. **Resource Management**: The `finally` block ensures that the buffer is always returned to the pool, even if an exception occurs.

This pattern allows for efficient, zero-allocation serialization and network writing, which can significantly improve performance in high-throughput scenarios. It adapts to the specific size requirements of each record instance, ensuring optimal buffer usage.
Loading