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

IBuffer Struct Reference

Inheritance diagram for IBuffer:

Buffer FlushBuffer GrowableBuffer MappedBuffer FileConduit::VersionWin32::Win32MappedBuffer List of all members.

Public Member Functions

IBuffer create ()
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)
void * put (void *src, uint size)
int write (int(*writer)(void[]))
int read (int(*reader)(void[]))
IBuffer compress ()
bool skip (int size)
void flush ()
IBuffer clear ()
uint readable ()
uint writable ()
uint getLimit ()
uint getCapacity ()
uint getPosition ()
bool grow (uint size)
IConduit getConduit ()
void setConduit (IConduit conduit)

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 95 of file IBuffer.d.


Member Function Documentation

IBuffer create  ) 
 

Create an instance of an IBuffer. Use this when you don't know anything about the concrete implementation, and have only the IBuffer interface available

Reimplemented in Buffer.

Referenced by HybridToken::this().

void [] getContent  ) 
 

Return the backing array

Reimplemented in Buffer.

Referenced by BufferAllocator::isReadOnly().

char [] toString  ) 
 

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

Reimplemented in Buffer.

Referenced by HttpTokens::add(), HttpClient::read(), testHttpClient(), testHttpClient2(), 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(), Uri::encode(), FilePath::splice(), testAppend(), FilePath::toString(), 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(), HttpRequest::getInputParameters(), Reader::read(), and AbstractReader::wait().

void* put void *  src,
uint  size
 

Write a chunk of data into this buffer, and flush to the conduit as necessary. Returns true if all data was written, false otherwise (indicating eof, or eob).

This is typically used for streaming formatted data. Note that this should ideally have package visibility only, as it should be restricted to Writers etc.

Reimplemented in Buffer, and Buffer.

Referenced by Uri::encode(), and Writer::write().

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

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.

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

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 Scanner::next().

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.

Referenced by RegexTokenizer::next(), Scanner::next(), and BufferAllocator::reset().

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.

Referenced by RegexTokenizer::next(), and Scanner::next().

void flush  ) 
 

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

Reimplemented in Buffer, MappedBuffer, and FileConduit::VersionWin32::Win32MappedBuffer.

Referenced by AbstractWriter::flush(), ClusterThread::run(), and Writer::write().

IBuffer clear  ) 
 

Reset position and limit to zero.

Reimplemented in Buffer, and MappedBuffer.

Referenced by CacheServer::LoaderThread::load(), HttpClient::read(), HttpTokens::reset(), SocketListener::run(), ClusterThread::run(), testDirectIO(), testHttpClient(), and testHttpClient2().

uint readable  ) 
 

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

Reimplemented in Buffer.

Referenced by SocketConduit::flush(), Conduit::flush(), Scanner::next(), HttpClient::open(), Reader::read(), HttpClient::read(), HttpRequest::readHeaders(), testHttpClient(), and testMulticast().

uint writable  ) 
 

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

Reimplemented in Buffer, and MappedBuffer.

Referenced by Scanner::next(), BufferAllocator::reset(), and Writer::write().

uint getLimit  ) 
 

returns the limit of readable content within this buffer

Reimplemented in Buffer.

Referenced by HttpTokens::add().

uint getCapacity  ) 
 

returns the total capacity of this buffer

Reimplemented in Buffer.

uint getPosition  ) 
 

returns the current position within this buffer

Reimplemented in Buffer.

Referenced by RegexTokenizer::next(), and Scanner::next().

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 GrowableBuffer.

Referenced by Writer::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 Scanner::next(), Reader::read(), ClusterThread::run(), and Writer::write().

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 FileConduit::createBuffer(), CacheServer::LoaderThread::load(), testDirectIO(), and ClusterThread::this().


The documentation for this struct was generated from the following file:
Generated on Sun Nov 7 19:07:05 2004 for Mango by doxygen 1.3.6