Class BlockArray

Implements an array of Block instances.

Inheritance

object

BlockArray

Namespace: Neon.Common

Assembly: Neon.Common.dll

Syntax

public sealed class BlockArray

Remarks

The purpose of BlockArray is to avoid performance robbing buffer reallocations and copies and large obvject heap applications as can happen with extensive use of the MemoryStream class. Rather than doing I/O to a single large buffer, the BlockArray provides the underlying functionality for spreading I/O across multiple blocks. This avoids any need to reallocate and copy a large buffer as the stream grows an also tends to allocate consistently sized memory blocks, making life easier for the memory allocator.

This class is pretty flexible. Blocks can be explicitly added and removed from the class or the ExtendTo(int), TruncateTo(int), or SetExactSize(int) methods can be used have the class handle block management.

The BlockSize and BlockOffset properties are used by the internal block management methods when allocating new blocks. BlockSize defaults to 512 and specifies the size of new blocks. BlockOffset defaults to 0. New blocks will have their Offset field set to BlockOffset.

BlockOffset provides for some tricky performance optimizations. A common situation in network protocols is the need to fragment serialized data across multiple data packets with fixed sized headers. Setting BlockOffset to the size of the fixed header will reserve these bytes at the beginning of each block. The data can be serialized into the array and then afterwards, the headers can be written manually into each block. This technique can avoid lots of buffer copying.

note

You should call Reload() after directly modifying the Length or Offset properties of any of the blocks in the array. It is not necessary to call this for changes to the Block.Buffer array.

Constructors

BlockArray()

Constructs an empty list.

Declaration

public BlockArray()

BlockArray(params Block[])

Constructs an array from the blocks passed.

Declaration

public BlockArray(params Block[] blocks)

Parameters

Type	Name	Description
Block[]	blocks	The blocks.

BlockArray(byte[])

Constructs a block array from a buffer.

Declaration

public BlockArray(byte[] buffer)

Parameters

Type	Name	Description
byte[]	buffer	The buffer to append.

BlockArray(int)

Constructs an array with the specified capacity.

Declaration

public BlockArray(int capacity)

Parameters

Type	Name	Description
int	capacity	The capacity in bytes.

BlockArray(int, int)

Constructs an array with the specified capacity and block size.

Declaration

public BlockArray(int capacity, int blockSize)

Parameters

Type	Name	Description
int	capacity	The capacity in bytes.
int	blockSize	Size of blocks added when extending the array.

BlockArray(int, int, int)

Constructs an array with the specified capacity, block size, and block offset.

Declaration

public BlockArray(int capacity, int blockSize, int blockOffset)

Parameters

Type	Name	Description
int	capacity	The capacity in bytes.
int	blockSize	Size of blocks added when extending the array.
int	blockOffset	Bytes to be reserved at the beginning of each new block.

Properties

BlockOffset

The default offset to use when adding new blocks to the array.

Declaration

public int BlockOffset { get; set; }

Property Value

Type	Description
int

BlockSize

The size of new blocks added when extending the array.

Declaration

public int BlockSize { get; set; }

Property Value

Type	Description
int

Count

Returns the number of blocks in the list.

Declaration

public int Count { get; }

Property Value

Type	Description
int

this[int]

Accesses the indexed byte in the logical array formed by concatentating all of the blocks.

Declaration

public byte this[int index] { get; set; }

Parameters

Type	Name	Description
int	index

Property Value

Type	Description
byte

Size

Returns the total size of all the blocks in bytes.

Declaration

public int Size { get; }

Property Value

Type	Description
int

Methods

Append(Block)

Appends a block to end of the array.

Declaration

public void Append(Block block)

Parameters

Type	Name	Description
Block	block	The new block.

Append(BlockArray)

Appends all blocks from a block array to this array.

Declaration

public void Append(BlockArray blocks)

Parameters

Type	Name	Description
BlockArray	blocks	The source array.

Append(BlockArray, int, int)

Appends blocks from a block array to this array.

Declaration

public void Append(BlockArray blocks, int index, int count)

Parameters

Type	Name	Description
BlockArray	blocks	The source array.
int	index	Index of the first block to append.
int	count	Number of blocks to append.

Append(byte[])

Appends a block formed by a buffer to the array.

Declaration

public void Append(byte[] buffer)

Parameters

Type	Name	Description
byte[]	buffer	The buffer to add.

Clone()

Returns a shallow copy of the block array.

Declaration

public BlockArray Clone()

Returns

Type	Description
BlockArray	The cloned array.

Remarks

A new set of Block objects will be returned but they will point to the same underlying buffers.

CopyFrom(byte[], int, int, int)

Copies bytes from the byte array passed into the blocks.

Declaration

public void CopyFrom(byte[] source, int sourceOffset, int targetOffset, int length)

Parameters

Type	Name	Description
byte[]	source	The source byte array.
int	sourceOffset	Offset of the first byte to copy from the source array.
int	targetOffset	Logical offset of the first target byte in the buffer references.
int	length	Number of bytes to copy.

CopyTo(int, byte[], int, int)

Copies bytes from the logical offset in the blocks to the target byte array.

Declaration

public void CopyTo(int sourceOffset, byte[] target, int targetOffset, int length)

Parameters

Type	Name	Description
int	sourceOffset	Logical offset of the first byte to copy.
byte[]	target	The output byte array.
int	targetOffset	Target offset where the first byte is to be written.
int	length	The number of bytes to copy.

ExtendTo(int)

Adds blocks to the array as necessary to ensure that the total size of these blocks is at least equal to the value passed.

Declaration

public void ExtendTo(int capacity)

Parameters

Type	Name	Description
int	capacity	The minimum requested capacity in bytes.

Extract(int)

Extracts a range of bytes from the array from the specified index to the end of the array into newly created block array.

Declaration

public BlockArray Extract(int index)

Parameters

Type	Name	Description
int	index	Logical index of the first byte.

Returns

Type	Description
BlockArray	A new block array referencing the bytes.

Remarks

note

Although this method does create a new BlockArray and Block objects, it does not copy the underlying buffers. Instead, it adjusts the new Block objects to reference the requested portions of the original underlying buffers.

Extract(int, int)

Extracts a range of bytes from the array into newly created block array.

Declaration

public BlockArray Extract(int index, int length)

Parameters

Type	Name	Description
int	index	Logical index of the first byte.
int	length	Number of bytes to extract.

Returns

Type	Description
BlockArray	A new block array referencing the bytes.

Remarks

note

Although this method does create a new BlockArray and Block objects, it does not copy the underlying buffers. Instead, it adjusts the new Block objects to reference the requested portions of the original underlying buffers.

GetBlock(int)

Returns the indexed block in the list.

Declaration

public Block GetBlock(int index)

Parameters

Type	Name	Description
int	index	The index (0..Count-1).

Returns

Type	Description
Block	The block.

GetBlocks()

Returns an array to the underlying blocks.

Declaration

public Block[] GetBlocks()

Returns

Type	Description
Block[]	The block array.

Reload()

Reloads cached information about the blocks in the array.

Declaration

public void Reload()

Remarks

This should be called after making changes to the Length property of any blocks in the array.

Reset()

Used internally by unit tests to reset any internal positional optimization information maintained by the class.

Declaration

public void Reset()

SetExactSize(int)

Adjusts the blocks in the array such that their sizes total exactly to the value passed.

Declaration

public void SetExactSize(int capacity)

Parameters

Type	Name	Description
int	capacity	The desired size.

Remarks

The method removes or appends blocks onto the end of the array to reach the desired size. The method will also adjust the length of the final block if necessary.

ToByteArray()

Assembles the blocks referenced by the array into a contiguous byte array.

Declaration

public byte[] ToByteArray()

Returns

Type	Description
byte[]	A contiguous byte array.

TruncateTo(int)

Removes blocks from the and of the array array such that only those blocks necessary to achieve the specified capacity remain.

Declaration

public void TruncateTo(int capacity)

Parameters

Type	Name	Description
int	capacity	The desired capacity in bytes.

Remarks

The method does nothing if the requested capacity is larger than the current size of the blocks.

Operators

implicit operator BlockArray(Block[])

Implicit cast from and array of Blocks into a BlockArray.

Declaration

public static implicit operator BlockArray(Block[] blocks)

Parameters

Type	Name	Description
Block[]	blocks	The array of blocks to be converted.

Returns

Type	Description
BlockArray	The BlockArray.