C# Class ServiceStack.Text.RecyclableMemoryStream

MemoryStream implementation that deals with pooling and managing memory streams which use potentially large buffers.

This class works in tandem with the RecylableMemoryStreamManager to supply MemoryStream objects to callers, while avoiding these specific problems: 1. LOH allocations - since all large buffers are pooled, they will never incur a Gen2 GC 2. Memory waste - A standard memory stream doubles its size when it runs out of room. This leads to continual memory growth as each stream approaches the maximum allowed size. 3. Memory copying - Each time a MemoryStream grows, all the bytes are copied into new buffers. This implementation only copies the bytes when GetBuffer is called. 4. Memory fragmentation - By using homogenous buffer sizes, it ensures that blocks of memory can be easily reused. The stream is implemented on top of a series of uniformly-sized blocks. As the stream's length grows, additional blocks are retrieved from the memory manager. It is these blocks that are pooled, not the stream object itself. The biggest wrinkle in this implementation is when GetBuffer() is called. This requires a single contiguous buffer. If only a single block is in use, then that block is returned. If multiple blocks are in use, we retrieve a larger buffer from the memory manager. These large buffers are also pooled, split by size--they are multiples of a chunk size (1 MB by default). Once a large buffer is assigned to the stream the blocks are NEVER again used for this stream. All operations take place on the large buffer. The large buffer can be replaced by a larger buffer from the pool as needed. All blocks and large buffers are maintained in the stream until the stream is disposed (unless AggressiveBufferReturn is enabled in the stream manager).

Inheritance: System.IO.MemoryStream

Mostra file Open project: ServiceStack/ServiceStack.Text Class Usage Examples

Private Properties

Property	Type	Description
CheckDisposed	void
EnsureCapacity	void
GetBlockAndRelativeOffset	BlockAndOffset
InternalRead	int
RecyclableMemoryStream	System
ReleaseLargeBuffer	void
ToArray	byte[]

Public Methods

Method	Description
Close ( ) : void	Equivalent to Dispose
GetBuffer ( ) : byte[]	Returns a single buffer containing the contents of the stream. The buffer may be longer than the stream length. IMPORTANT: Doing a Write() after calling GetBuffer() invalidates the buffer. The old buffer is held onto until Dispose is called, but the next time GetBuffer() is called, a new buffer from the pool will be required.
Read ( byte buffer, int offset, int count ) : int	Reads from the current position into the provided buffer
ReadByte ( ) : int	Reads a single byte from the current position in the stream.
RecyclableMemoryStream ( RecyclableMemoryStreamManager memoryManager ) : System	Allocate a new RecyclableMemoryStream object.
RecyclableMemoryStream ( RecyclableMemoryStreamManager memoryManager, string tag ) : System	Allocate a new RecyclableMemoryStream object
RecyclableMemoryStream ( RecyclableMemoryStreamManager memoryManager, string tag, int requestedSize ) : System	Allocate a new RecyclableMemoryStream object
Seek ( long offset, SeekOrigin loc ) : long	Sets the position to the offset from the seek location
SetLength ( long value ) : void	Sets the length of the stream
ToString ( ) : string	Returns a useful string for debugging. This should not normally be called in actual production code.
Write ( byte buffer, int offset, int count ) : void	Writes the buffer to the stream
WriteByte ( byte value ) : void	Writes a single byte to the current position in the stream.
WriteTo ( Stream stream ) : void	Synchronously writes this stream's bytes to the parameter stream. Important: This does a synchronous write, which may not be desired in some situations

Protected Methods

Method	Description
Dispose ( bool disposing ) : void	Returns the memory used by this stream back to the pool. This method is not thread safe and it may not be called more than once.

Private Methods

Method	Description
CheckDisposed ( ) : void
EnsureCapacity ( int newCapacity ) : void
GetBlockAndRelativeOffset ( int offset ) : BlockAndOffset
InternalRead ( byte buffer, int offset, int count, int fromPosition ) : int
RecyclableMemoryStream ( RecyclableMemoryStreamManager memoryManager, string tag, int requestedSize, byte initialLargeBuffer ) : System	Allocate a new RecyclableMemoryStream object
ReleaseLargeBuffer ( ) : void	Release the large buffer (either stores it for eventual release or returns it immediately).
ToArray ( ) : byte[]

Method Details

Close() public method

Equivalent to Dispose

public Close ( ) : void
return	void

Dispose() protected method

Returns the memory used by this stream back to the pool.

This method is not thread safe and it may not be called more than once.

protected Dispose ( bool disposing ) : void
disposing	bool	Whether we're disposing (true), or being called by the finalizer (false)
return	void

GetBuffer() public method

Returns a single buffer containing the contents of the stream. The buffer may be longer than the stream length.

IMPORTANT: Doing a Write() after calling GetBuffer() invalidates the buffer. The old buffer is held onto until Dispose is called, but the next time GetBuffer() is called, a new buffer from the pool will be required.

Object has been disposed

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

Read() public method

Reads from the current position into the provided buffer

buffer is null offset or count is less than 0 offset subtracted from the buffer length is less than count Object has been disposed

public Read ( byte buffer, int offset, int count ) : int
buffer	byte	Destination buffer
offset	int	Offset into buffer at which to start placing the read bytes.
count	int	Number of bytes to read.
return	int

ReadByte() public method

Reads a single byte from the current position in the stream.

Object has been disposed

public ReadByte ( ) : int
return	int

RecyclableMemoryStream() public method

Allocate a new RecyclableMemoryStream object.

public RecyclableMemoryStream ( RecyclableMemoryStreamManager memoryManager ) : System
memoryManager	RecyclableMemoryStreamManager	The memory manager
return	System

RecyclableMemoryStream() public method

Allocate a new RecyclableMemoryStream object

public RecyclableMemoryStream ( RecyclableMemoryStreamManager memoryManager, string tag ) : System
memoryManager	RecyclableMemoryStreamManager	The memory manager
tag	string	A string identifying this stream for logging and debugging purposes
return	System

RecyclableMemoryStream() public method

Allocate a new RecyclableMemoryStream object

public RecyclableMemoryStream ( RecyclableMemoryStreamManager memoryManager, string tag, int requestedSize ) : System
memoryManager	RecyclableMemoryStreamManager	The memory manager
tag	string	A string identifying this stream for logging and debugging purposes
requestedSize	int	The initial requested size to prevent future allocations
return	System

Seek() public method

Sets the position to the offset from the seek location

Object has been disposed offset is larger than MaxStreamLength Invalid seek origin Attempt to set negative position

public Seek ( long offset, SeekOrigin loc ) : long
offset	long	How many bytes to move
loc	SeekOrigin	From where
return	long

SetLength() public method

Sets the length of the stream

value is negative or larger than MaxStreamLength Object has been disposed

public SetLength ( long value ) : void
value	long
return	void

ToString() public method

Returns a useful string for debugging. This should not normally be called in actual production code.

public ToString ( ) : string
return	string

Write() public method

Writes the buffer to the stream

buffer is null offset or count is negative buffer.Length - offset is not less than count Object has been disposed

public Write ( byte buffer, int offset, int count ) : void
buffer	byte	Source buffer
offset	int	Start position
count	int	Number of bytes to write
return	void

WriteByte() public method

Writes a single byte to the current position in the stream.

Object has been disposed

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

WriteTo() public method

Synchronously writes this stream's bytes to the parameter stream.

Important: This does a synchronous write, which may not be desired in some situations

public WriteTo ( Stream stream ) : void
stream	Stream	Destination stream
return	void