Class BlockStream

Implements an in-memory stream based on a collection of Block buffers rather than a single byte buffer. This is more efficient than MemoryStream for large streams and also avoids allocations in the large object heap.

Inheritance

object

MarshalByRefObject

Stream

BlockStream

Namespace: Neon.IO

Assembly: Neon.Common.dll

Syntax

public sealed class BlockStream : Stream

Remarks

note

Buffer array streams cannot be greater than or equal to 2GiB in length.

Constructors

BlockStream()

Constructs a zero length stream with default block size.

Declaration

public BlockStream()

BlockStream(BlockArray)

Constructs a stream from the blocks passed.

Declaration

public BlockStream(BlockArray blocks)

Parameters

Type	Name	Description
BlockArray	blocks	The blocks.

Remarks

The stream size will be set to the size of the blocks.

BlockStream(params Block[])

Constructs a stream from the blocks passed.

Declaration

public BlockStream(params Block[] blocks)

Parameters

Type	Name	Description
Block[]	blocks	The blocks.

Remarks

The stream size will be set to the size of the blocks.

BlockStream(byte[])

Constructs a stream from a byte array.

Declaration

public BlockStream(byte[] buffer)

Parameters

Type	Name	Description
byte[]	buffer	The byte array.

BlockStream(int)

Constructs a stream of the specified size using the default block size.

Declaration

public BlockStream(int size)

Parameters

Type	Name	Description
int	size	The stream size in bytes.

BlockStream(int, int)

Constructs a stream of the specified size using the specified block size.

Declaration

public BlockStream(int size, int blockSize)

Parameters

Type	Name	Description
int	size	The stream size in bytes.
int	blockSize	The block size in bytes.

BlockStream(int, int, int)

Constructs a stream of the specified size using the specified block size and offset.

Declaration

public BlockStream(int size, int blockSize, int blockOffset)

Parameters

Type	Name	Description
int	size	The stream size in bytes.
int	blockSize	The block size in bytes.
int	blockOffset	Bytes to be reserved at the beginning of each new block.

Remarks

See BlockArray for more information on the value and use of the blockOffset prarmeter.

Properties

CanRead

Returns true if the stream supports read operations.

Declaration

public override bool CanRead { get; }

Property Value

Type	Description
bool

Overrides

Stream.CanRead

CanSeek

Returns true if the stream supports seek operations.

Declaration

public override bool CanSeek { get; }

Property Value

Type	Description
bool

Overrides

Stream.CanSeek

CanWrite

Returns true if the stream supports write operations.

Declaration

public override bool CanWrite { get; }

Property Value

Type	Description
bool

Overrides

Stream.CanWrite

Length

Returns the current size of the stream in bytes.

Declaration

public override long Length { get; }

Property Value

Type	Description
long

Overrides

Stream.Length

Position

The current stream position.

Declaration

public override long Position { get; set; }

Property Value

Type	Description
long

Overrides

Stream.Position

Remarks

note

It is valid to set a stream position beyond the current end of the stream. The stream will be extended to this position. The contents of the extended portion will be undefined.

RawBlockArray

Returns the underlying block array without modification.

Declaration

public BlockArray RawBlockArray { get; }

Property Value

Type	Description
BlockArray

Methods

Append(Block)

Appends a block to the end of the underlying BlockArray.

Declaration

public void Append(Block block)

Parameters

Type	Name	Description
Block	block	The block to append.

Remarks

The underyling block array's SetExactSize() method will be called before appending the block. The stream position will be set to the end of the stream before the method returns.

This method is a performance improvement over writing the a buffer to the stream via one of the write methods.

Append(BlockArray)

Appends a block array to the end of the underlying BlockArray.

Declaration

public void Append(BlockArray blocks)

Parameters

Type	Name	Description
BlockArray	blocks	The array to append.

Remarks

The underyling block array's SetExactSize() method will be called before appending the block. The stream position will be set to the end of the stream before the method returns.

This method is a performance improvement over writing the a buffer to the stream via one of the write methods.

Flush()

Flushes any stream buffers.

Declaration

public override void Flush()

Overrides

Stream.Flush()

Remarks

This is a NOP for this implementation.

Read(byte[], int, int)

Reads bytes from the current stream position, advancing the position past the data read.

Declaration

public override int Read(byte[] buffer, int offset, int count)

Parameters

Type	Name	Description
byte[]	buffer	The destination buffer.
int	offset	Offset where the read data is to be copied.
int	count	Number of bytes to read.

Returns

Type	Description
int	The number of bytes actually read.

Overrides

Stream.Read(byte[], int, int)

ReadAsync(byte[], int, int, CancellationToken)

Asynchronously reads from the stream.

Declaration

public override Task<int> ReadAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)

Parameters

Type	Name	Description
byte[]	buffer	The destination buffer.
int	offset	Offset where the read data is to be copied.
int	count	Number of bytes to read.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task<int>	The number of bytes actually read.

Overrides

Stream.ReadAsync(byte[], int, int, CancellationToken)

ReadBlocks(int)

Returns requested bytes from the underlying block array as as a new block array.

Declaration

public BlockArray ReadBlocks(int cb)

Parameters

Type	Name	Description
int	cb	The nunber of bytes to read.

Returns

Type	Description
BlockArray	A new block array referencing the requested bytes in the same underlying buffers as managed by then stream.

Remarks

This provides a high performance way for code that knows how to handle block arrays to extract a portion of a stream.

The array returned will be truncated to the length of the underlying stream. The stream position will be advanced past the requested bytes.

ReadByte()

Reads a byte from the current stream position, advancing the position by 1.

Declaration

public override int ReadByte()

Returns

Type	Description
int	The byte read or -1 if the end of the stream has been reached.

Overrides

Stream.ReadByte()

Seek(long, SeekOrigin)

Moves the current stream position relative to the specified origin.

Declaration

public override long Seek(long offset, SeekOrigin origin)

Parameters

Type	Name	Description
long	offset	The positional offset.
SeekOrigin	origin	Specifies the seek origin.

Returns

Type	Description
long	The stream position after the seek.

Overrides

Stream.Seek(long, SeekOrigin)

Remarks

It is valid to seek past the current stream length. In this case, the stream will be extended with the contents of the extended portion being undefined.

SetLength(long)

Sets the length of the stream.

Declaration

public override void SetLength(long value)

Parameters

Type	Name	Description
long	value	The new length in bytes.

Overrides

Stream.SetLength(long)

Remarks

The stream will be truncated if the new length is less than the current length. The stream will be extended if the new length is greater than the current length. In this case, the contents of the extended portion will be undefined.

SetLength(long, bool)

Sets the length of the stream.

Declaration

public void SetLength(long value, bool modifyBlocks)

Parameters

Type	Name	Description
long	value	The new length in bytes.
bool	modifyBlocks	true to modify the underlying block array if necessary.

Remarks

The modifyBlocks parameter specifies whether the underlying block array will be truncated or extended to the length specified.

ToArray()

Assembles a contiguous a byte array from the underlying buffer array.

Declaration

public byte[] ToArray()

Returns

Type	Description
byte[]	The assembled byte array.

ToBlocks(bool)

Returns the underlying buffer array.

Declaration

public BlockArray ToBlocks(bool truncate)

Parameters

Type	Name	Description
bool	truncate	true if the method will truncate the underlying BlockArray to the actual length of the stream before returning the array.

Returns

Type	Description
BlockArray	The BlockArray.

Write(byte[], int, int)

Writes bytes to the stream at the current position, advancing the position past the data written.

Declaration

public override void Write(byte[] buffer, int offset, int count)

Parameters

Type	Name	Description
byte[]	buffer	The source buffer.
int	offset	Offset of the first byte to write.
int	count	Number of bytes to read.

Overrides

Stream.Write(byte[], int, int)

WriteAsync(byte[], int, int, CancellationToken)

Asynchronously writes bytes to the stream at the current position, advancing the position past the data written.

Declaration

public override Task WriteAsync(byte[] buffer, int offset, int count, CancellationToken cancellationToken)

Parameters

Type	Name	Description
byte[]	buffer	The source buffer.
int	offset	Offset of the first byte to write.
int	count	Number of bytes to read.
CancellationToken	cancellationToken	The cancellation token.

Returns

Type	Description
Task	The tracking Task.

Overrides

Stream.WriteAsync(byte[], int, int, CancellationToken)

WriteByte(byte)

Writes a byte to the current stream position, advancing the position by 1.

Declaration

public override void WriteByte(byte value)

Parameters

Type	Name	Description
byte	value	The byte to write.

Overrides

Stream.WriteByte(byte)

Extension Methods

IOExtensions.DeflateTo(Stream, Stream)

IOExtensions.GunzipTo(Stream, Stream)

IOExtensions.GzipTo(Stream, Stream)

IOExtensions.InflateTo(Stream, Stream)

IOExtensions.ReadBytes(Stream, int)

IOExtensions.ReadToEnd(Stream)

IOExtensions.ReadToEndAsync(Stream)

IOExtensions.Write(Stream, byte[])

IOExtensions.WriteAsync(Stream, byte[])