C# Class GSF.IO.BlockAllocatedMemoryStream

Defines a stream whose backing store is memory. Externally this class operates similar to a MemoryStream, internally it uses dynamically allocated buffer blocks instead of one large contiguous array of data.

The BlockAllocatedMemoryStream has two primary benefits over a normal MemoryStream, first, the allocation of a large contiguous array of data in MemoryStream can fail when the requested amount of contiguous memory is unavailable - the BlockAllocatedMemoryStream prevents this; second, a MemoryStream will constantly reallocate the buffer size as the stream grows and shrinks and then copy all the data from the old buffer to the new - the BlockAllocatedMemoryStream maintains its blocks over its life cycle, unless manually cleared, thus eliminating unnecessary allocations and garbage collections when growing and reusing a stream.

Important: Unlike MemoryStream, the BlockAllocatedMemoryStream will not use a user provided buffer as its backing buffer. Any user provided buffers used to instantiate the class will be copied into internally managed reusable memory buffers. Subsequently, the BlockAllocatedMemoryStream does not support the notion of a non-expandable stream. If you are using a MemoryStream with your own buffer, the BlockAllocatedMemoryStream will not provide any immediate benefit.

Note that the BlockAllocatedMemoryStream will maintain all allocated blocks for stream use until the Clear method is called or the class is disposed.

No members in the BlockAllocatedMemoryStream are guaranteed to be thread safe. Make sure any calls are synchronized when simultaneously accessed from different threads.

Inheritance: Stream

Show file Open project: GridProtectionAlliance/gsf Class Usage Examples

Public Methods

Method	Description
BlockAllocatedMemoryStream ( ) : System	Initializes a new instance of BlockAllocatedMemoryStream.
BlockAllocatedMemoryStream ( byte buffer ) : System	Initializes a new instance of BlockAllocatedMemoryStream from specified buffer. Unlike MemoryStream, the BlockAllocatedMemoryStream will not use the provided buffer as its backing buffer. The buffer will be copied into internally managed reusable memory buffers. Subsequently, the notion of a non-expandable stream is not supported.
BlockAllocatedMemoryStream ( byte buffer, int startIndex, int length ) : System	Initializes a new instance of BlockAllocatedMemoryStream from specified region of buffer. Unlike MemoryStream, the BlockAllocatedMemoryStream will not use the provided buffer as its backing buffer. The buffer will be copied into internally managed reusable memory buffers. Subsequently, the notion of a non-expandable stream is not supported.
BlockAllocatedMemoryStream ( int capacity ) : System	Initializes a new instance of BlockAllocatedMemoryStream for specified capacity.
Clear ( ) : void	Clears the entire BlockAllocatedMemoryStream contents and releases any allocated memory blocks.
Flush ( ) : void	Overrides the Stream.Flush method so that no action is performed. This method overrides the Stream.Flush method. Because any data written to a BlockAllocatedMemoryStream object is written into RAM, this method is superfluous.
Read ( byte buffer, int startIndex, int length ) : int	Reads a block of bytes from the current stream and writes the data to buffer.
ReadByte ( ) : int	Reads a byte from the current stream.
ReadFrom ( Stream source, long length ) : void	Reads specified number of bytes from source stream into this BlockAllocatedMemoryStream starting at the current position.
Seek ( long offset, SeekOrigin origin ) : long	Sets the Position within the current stream to the specified value relative the origin.
SetLength ( long value ) : void	Sets the length of the current stream to the specified value. If this length is larger than the previous length, the data is initialized to 0's between the previous length and the current length.
ToArray ( ) : byte[]	Writes the stream contents to a byte array, regardless of the Position property. This may fail if there is not enough contiguous memory available to hold current size of stream. When possible use methods which operate on streams directly instead.
Write ( byte buffer, int startIndex, int length ) : void	Writes a block of bytes to the current stream using data read from buffer.
WriteByte ( byte value ) : void	Writes a byte to the current stream at the current position.
WriteTo ( Stream destination ) : void	Writes the entire stream into destination, regardless of Position, which remains unchanged.

Protected Methods

Method	Description
Dispose ( bool disposing ) : void	Releases the unmanaged resources used by the BlockAllocatedMemoryStream object and optionally releases the managed resources.

Private Methods

Method	Description
EnsureCapacity ( long length ) : void	Makes sure desired length can be accommodated by future data accesses.
InitializeToPosition ( long position ) : void	Initializes all of the bytes to zero.

Method Details

BlockAllocatedMemoryStream() public method

Initializes a new instance of BlockAllocatedMemoryStream.

public BlockAllocatedMemoryStream ( ) : System
return	System

BlockAllocatedMemoryStream() public method

Initializes a new instance of BlockAllocatedMemoryStream from specified buffer.

Unlike MemoryStream, the BlockAllocatedMemoryStream will not use the provided buffer as its backing buffer. The buffer will be copied into internally managed reusable memory buffers. Subsequently, the notion of a non-expandable stream is not supported.

is null.

public BlockAllocatedMemoryStream ( byte buffer ) : System
buffer	byte	Initial buffer to copy into stream.
return	System

BlockAllocatedMemoryStream() public method

Initializes a new instance of BlockAllocatedMemoryStream from specified region of buffer.

is null. /// or is less than 0 -or- /// and will exceed length. ///

public BlockAllocatedMemoryStream ( byte buffer, int startIndex, int length ) : System
buffer	byte	Initial buffer to copy into stream.
startIndex	int	0-based start index into the .
length	int	Valid number of bytes within from .
return	System

BlockAllocatedMemoryStream() public method

Initializes a new instance of BlockAllocatedMemoryStream for specified capacity.

public BlockAllocatedMemoryStream ( int capacity ) : System
capacity	int	Initial length of the stream.
return	System

Clear() public method

Clears the entire BlockAllocatedMemoryStream contents and releases any allocated memory blocks.

public Clear ( ) : void
return	void

Dispose() protected method

Releases the unmanaged resources used by the BlockAllocatedMemoryStream object and optionally releases the managed resources.

protected Dispose ( bool disposing ) : void
disposing	bool	true to release both managed and unmanaged resources; otherwise, false to release only unmanaged resources.
return	void

Flush() public method

Overrides the Stream.Flush method so that no action is performed.

This method overrides the Stream.Flush method.

Because any data written to a BlockAllocatedMemoryStream object is written into RAM, this method is superfluous.

public Flush ( ) : void
return	void

Read() public method

Reads a block of bytes from the current stream and writes the data to buffer.

is null. /// or is less than 0 -or- /// and will exceed length. /// The stream is closed.

public Read ( byte buffer, int startIndex, int length ) : int
buffer	byte	When this method returns, contains the specified byte array with the values between and ( + - 1) replaced by the characters read from the current stream.
startIndex	int	The byte offset in at which to begin reading.
length	int	The maximum number of bytes to read.
return	int

ReadByte() public method

Reads a byte from the current stream.

The stream is closed.

public ReadByte ( ) : int
return	int

ReadFrom() public method

Reads specified number of bytes from source stream into this BlockAllocatedMemoryStream starting at the current position.

The stream is closed.

public ReadFrom ( Stream source, long length ) : void
source	Stream	The stream containing the data to copy
length	long	The number of bytes to copy
return	void

Seek() public method

Sets the Position within the current stream to the specified value relative the origin.

Seeking was attempted before the beginning of the stream. The stream is closed.

public Seek ( long offset, SeekOrigin origin ) : long
offset	long	The new position within the stream. This is relative to the parameter, and can be positive or negative.
origin	SeekOrigin	A value of type , which acts as the seek reference point.
return	long

SetLength() public method

Sets the length of the current stream to the specified value.

If this length is larger than the previous length, the data is initialized to 0's between the previous length and the current length.

public SetLength ( long value ) : void
value	long	The value at which to set the length.
return	void

ToArray() public method

Writes the stream contents to a byte array, regardless of the Position property.

This may fail if there is not enough contiguous memory available to hold current size of stream. When possible use methods which operate on streams directly instead.

Cannot create a byte array with more than 2,147,483,591 elements. The stream is closed.

public ToArray ( ) : byte[]
return	byte[]

Write() public method

Writes a block of bytes to the current stream using data read from buffer.

is null. /// or is less than 0 -or- /// and will exceed length. /// The stream is closed.

public Write ( byte buffer, int startIndex, int length ) : void
buffer	byte	The buffer to write data from.
startIndex	int	The byte offset in at which to begin writing from.
length	int	The maximum number of bytes to write.
return	void

WriteByte() public method

Writes a byte to the current stream at the current position.

The stream is closed.

public WriteByte ( byte value ) : void
value	byte	The byte to write.
return	void

WriteTo() public method

Writes the entire stream into destination, regardless of Position, which remains unchanged.

The stream is closed.

public WriteTo ( Stream destination ) : void
destination	Stream	The stream onto which to write the current contents.
return	void