Click or drag to resize

BlockArray Class

Implements an array of Block instances.
Inheritance Hierarchy
SystemObject
  Neon.CommonBlockArray

Namespace:  Neon.Common
Assembly:  Neon.Common (in Neon.Common.dll) Version: 2.10.0
Syntax
public sealed class BlockArray

The BlockArray type exposes the following members.

Constructors
  NameDescription
Public methodBlockArray
Constructs an empty list.
Public methodBlockArray(Byte)
Constructs a block array from a buffer.
Public methodBlockArray(Int32)
Constructs an array with the specified capacity.
Public methodBlockArray(Block)
Constructs an array from the blocks passed.
Public methodBlockArray(Int32, Int32)
Constructs an array with the specified capacity and block size.
Public methodBlockArray(Int32, Int32, Int32)
Constructs an array with the specified capacity, block size, and block offset.
Top
Properties
  NameDescription
Public propertyBlockOffset
The default offset to use when adding new blocks to the array.
Public propertyBlockSize
The size of new blocks added when extending the array.
Public propertyCount
Returns the number of blocks in the list.
Public propertyItem
Accesses the indexed byte in the logical array formed by concatentating all of the blocks.
Public propertySize
Returns the total size of all the blocks in bytes.
Top
Methods
  NameDescription
Public methodAppend(Byte)
Appends a block formed by a buffer to the array.
Public methodAppend(Block)
Appends a block to end of the array.
Public methodAppend(BlockArray)
Appends all blocks from a block array to this array.
Public methodAppend(BlockArray, Int32, Int32)
Appends blocks from a block array to this array.
Public methodClone
Returns a shallow copy of the block array.
Public methodCopyFrom
Copies bytes from the byte array passed into the blocks.
Public methodCopyTo
Copies bytes from the logical offset in the blocks to the target byte array.
Public methodEquals
Determines whether the specified object is equal to the current object.
(Inherited from Object.)
Public methodExtendTo
Adds blocks to the array as necessary to ensure that the total size of these blocks is at least equal to the value passed.
Public methodExtract(Int32)
Extracts a range of bytes from the array from the specified index to the end of the array into newly created block array.
Public methodExtract(Int32, Int32)
Extracts a range of bytes from the array into newly created block array.
Public methodGetBlock
Returns the indexed block in the list.
Public methodGetBlocks
Returns an array to the underlying blocks.
Public methodGetHashCode
Serves as the default hash function.
(Inherited from Object.)
Public methodGetType
Gets the Type of the current instance.
(Inherited from Object.)
Public methodReload
Reloads cached information about the blocks in the array.
Public methodReset
Used internally by unit tests to reset any internal positional optimization information maintained by the class.
Public methodSetExactSize
Adjusts the blocks in the array such that their sizes total exactly to the value passed.
Public methodToByteArray
Assembles the blocks referenced by the array into a contiguous byte array.
Public methodToString
Returns a string that represents the current object.
(Inherited from Object.)
Public methodTruncateTo
Removes blocks from the and of the array array such that only those blocks necessary to achieve the specified capacity remain.
Top
Operators
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(Int32), TruncateTo(Int32), or SetExactSize(Int32) 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 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.

See Also