Main Page | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Class Members | File Members | Related Pages

IBuffer Class Reference

Inheritance diagram for IBuffer:

Buffer Console::Input Console::Input Console::Output Console::Output GrowBuffer MappedBuffer List of all members.

Public Types

typedef uint(* Converter )(void *dst, uint count, uint type)

Public Member Functions

void[] getContent ()
char[] toString ()
IBuffer setValidContent (void[] data)
IBuffer setContent (void[] data, uint readable)
IBuffer append (void[] content)
void[] get (uint size, bool eat=true)
uint write (uint(*writer)(void[]))
uint read (uint(*reader)(void[]))
IBuffer compress ()
bool skip (int size)
uint fill ()
uint fill (IConduit conduit)
uint drain ()
void flush ()
IBuffer clear ()
uint readable ()
uint writable ()
uint getLimit ()
uint getCapacity ()
uint getPosition ()
bool grow (uint size)
void makeRoom (int space)
IConduit getConduit ()
void setConduit (IConduit conduit)
Style getStyle ()
void error (char[] msg)

Public Attributes

const Style Mixed = 0
const Style Binary = 1
const Style Text = 2

Private Types

typedef byte Style

Detailed Description

The basic premise behind this IO package is as follows:

1) the central concept is that of a buffer. The buffer acts as a queue (line) where items are removed from the front and new items are added to the back. Buffers are modeled by this interface, and mango.io.Buffer exposes a concrete implementation.

2) buffers can be written to directly, but a Reader and/or Writer are typically used to read & write formatted data. These readers & writers are bound to a specific buffer; often the same buffer. It's also perfectly legitimate to bind multiple writers to the same buffer; they will all behave serially as one would expect. The same applies to multiple readers on the same buffer. Readers and writers support two styles of IO: put/get, and the C++ style << and >> operators. All such operations can be chained.

3) Any class can be made compatable with the reader/writer framework by implementing the IReadable and/or IWritable interfaces. Each of these specify just a single method.

4) Buffers may also be tokenized. This is handy when one is dealing with text input, and/or the content suits a more fluid format than most typical readers & writers support. Tokens are mapped directly onto buffer content, so there is only minor overhead in using them. Tokens can be read and written by reader/writers also, using a more relaxed set of rules than those applied to integral IO.

5) buffers are sometimes memory-only, in which case there is nothing left to do when a reader (or tokenizer) hits end of buffer conditions. Other buffers are themselves bound to a Conduit. When this is the case, a reader will eventually cause the buffer to reload via its associated conduit. Previous buffer content will thus be lost. The same concept is applied to writers, whereby they flush the content of a full buffer to a bound conduit before continuing.

6) conduits provide virtualized access to external content, and represent things like files or Internet connections. They are just a different kind of stream. Conduits are modelled by mango.io.model.IConduit, and implemented via classes FileConduit and SocketConduit. Additional kinds of conduit are easy to construct: one either subclasses mango.io.Conduit, or implements mango.io.model.IConduit. A conduit reads and writes from/to a buffer in big chunks (typically the entire buffer).

Definition at line 97 of file IBuffer.d.


Member Typedef Documentation

typedef uint(* Converter)(void *dst, uint count, uint type)
 

Definition at line 99 of file IBuffer.d.

typedef byte Style [private]
 

Definition at line 101 of file IBuffer.d.


Member Function Documentation

void [] getContent  ) 
 

Return the backing array

Reimplemented in Buffer.

Referenced by BufferAllocator::isMutable().

char [] toString  ) 
 

Return a char[] slice of the buffer up to the limit of valid content.

Reimplemented in Buffer.

Referenced by HttpTokens::add(), and HttpTokens::toOutputString().

IBuffer setValidContent void[]  data  ) 
 

Set the backing array with all content readable. Writing to this will either flush it to an associated conduit, or raise an Eof condition. Use IBuffer.clear() to reset the content (make it all writable).

Reimplemented in Buffer.

Referenced by HybridToken::next(), HttpTokens::parse(), and HttpCookies::parse().

IBuffer setContent void[]  data,
uint  readable
 

Set the backing array with some content readable. Writing to this will either flush it to an associated conduit, or raise an Eof condition. Use IBuffer.clear() to reset the content (make it all writable).

Reimplemented in Buffer.

IBuffer append void[]  content  ) 
 

Write an array of data into this buffer, and flush to the conduit as necessary. Returns a chaining reference if all data was written; throws an IOException indicating eof or eob if not.

This is often used in lieu of a Writer.

Reimplemented in Buffer.

Referenced by HttpTokens::add(), SocketAppender::append(), Writer::encode(), Uri::encode(), Importer::encoder(), FilePath::splice(), Writer::write(), and Uri::write().

void [] get uint  size,
bool  eat = true
 

Read a chunk of data from the buffer, loading from the conduit as necessary. The requested number of bytes are loaded into the buffer, and marked as having been read when the 'eat' parameter is set true. When 'eat' is set false, the read position is not adjusted.

Returns the corresponding buffer slice when successful, or null if there's not enough data available (Eof; Eob).

Reimplemented in Buffer.

Referenced by BufferAllocator::allocate(), Exporter::decoder(), HttpRequest::getInputParameters(), Reader::read(), and Reader::wait().

uint write uint(*)(void[])  writer  ) 
 

Exposes the raw data buffer at the current write position, The delegate is provided with a void[] representing space available within the buffer at the current write position.

The delegate should return the approriate number of bytes if it writes valid content, or IConduit.Eof on error.

Returns whatever the delegate returns.

Reimplemented in Buffer, and MappedBuffer.

Referenced by EndianWriter::write().

uint read uint(*)(void[])  reader  ) 
 

Exposes the raw data buffer at the current read position. The delegate is provided with a void[] representing the available data, and should return zero to leave the current read position intact.

If the delegate consumes data, it should return the number of bytes consumed; or IConduit.Eof to indicate an error.

Returns whatever the delegate returns.

Reimplemented in Buffer.

Referenced by BufferAllocator::bind().

IBuffer compress  ) 
 

If we have some data left after an export, move it to front-of-buffer and set position to be just after the remains. This is for supporting certain conduits which choose to write just the initial portion of a request.

Limit is set to the amount of data remaining. Position is always reset to zero.

Reimplemented in Buffer, and MappedBuffer.

bool skip int  size  ) 
 

Skip ahead by the specified number of bytes, streaming from the associated conduit as necessary.

Can also reverse the read position by 'size' bytes. This may be used to support lookahead-type operations.

Returns true if successful, false otherwise.

Reimplemented in Buffer.

uint fill  ) 
 

Try to fill the available buffer with content from the specified conduit. In particular, we will never ask to read less than 32 bytes. This permits conduit-filters to operate within a known environment.

Returns the number of bytes read, or throws an underflow error if there nowhere to read from

Reimplemented in Buffer.

Referenced by Exporter::decoder(), SocketConduit::read(), and Reader::read().

uint fill IConduit  conduit  ) 
 

Try to fill the available buffer with content from the specified conduit. In particular, we will never ask to read less than 32 bytes. This permits conduit-filters to operate within a known environment.

Returns the number of bytes read, or Conduit.Eof

Reimplemented in Buffer.

uint drain  ) 
 

Write as much of the buffer that the associated conduit can consume.

Returns the number of bytes written, or Conduit.Eof

Reimplemented in Buffer.

void flush  ) 
 

flush the contents of this buffer to the related conduit. Throws an IOException on premature eof.

Reimplemented in Buffer.

Referenced by SocketAppender::append(), Writer::flush(), and Console::Output::opCall().

IBuffer clear  ) 
 

Reset position and limit to zero.

Reimplemented in Buffer, and MappedBuffer.

Referenced by CacheServer::LoaderThread::load(), and HttpTokens::reset().

uint readable  ) 
 

return count of readable bytes remaining in buffer. This is calculated simply as limit() - position()

Reimplemented in Buffer.

Referenced by Exporter::decoder(), Reader::read(), and HttpRequest::readHeaders().

uint writable  ) 
 

Return count of writable bytes available in buffer. This is calculated simply as capacity() - limit()

Reimplemented in Buffer, and MappedBuffer.

uint getLimit  ) 
 

returns the limit of readable content within this buffer

Reimplemented in Buffer.

Referenced by HttpTokens::add(), and FilePath::splice().

uint getCapacity  ) 
 

returns the total capacity of this buffer

Reimplemented in Buffer.

uint getPosition  ) 
 

returns the current position within this buffer

Reimplemented in Buffer.

bool grow uint  size  ) 
 

Overridable method to grow the buffer size when it becomes full. Default is to not grow at all.

Reimplemented in Buffer, and GrowBuffer.

void makeRoom int  space  ) 
 

make some room in the buffer

Reimplemented in Buffer.

Referenced by EndianWriter::write().

IConduit getConduit  ) 
 

Returns the conduit associated with this buffer. Returns null if the buffer is purely memory based; that is, it's not backed by some external conduit.

Buffers do not require a conduit to operate, but it can be convenient to associate one. For example, the IReader and IWriter classes use this to import/export content as necessary.

Reimplemented in Buffer.

Referenced by SocketAppender::close(), and Writer::conduit().

void setConduit IConduit  conduit  ) 
 

Sets the external conduit associated with this buffer.

Buffers do not require an external conduit to operate, but it can be convenient to associate one. For example, methods read and write use it to import/export content as necessary.

Reimplemented in Buffer, and MappedBuffer.

Referenced by CacheServer::LoaderThread::load().

Style getStyle  ) 
 

Return style of buffer

Reimplemented in Buffer.

Referenced by Writer::this(), and Reader::this().

void error char[]  msg  ) 
 

Throw an exception with the provided message

Reimplemented in Buffer.

Referenced by Exporter::decoder(), Writer::error(), Reader::read(), and Reader::this().


Member Data Documentation

const Style Mixed = 0
 

Definition at line 103 of file IBuffer.d.

const Style Binary = 1
 

Definition at line 104 of file IBuffer.d.

const Style Text = 2
 

Definition at line 105 of file IBuffer.d.


The documentation for this class was generated from the following file:
Generated on Sat Dec 24 17:28:39 2005 for Mango by  doxygen 1.4.0