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

Buffer Class Reference

Inheritance diagram for Buffer:

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

Public Member Functions

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

Protected Member Functions

void[] getContent ()
bool grow (uint size)
void copy (void *src, uint size)

Protected Attributes

void[] data
Style style
uint limit
uint capacity
uint position
IConduit conduit

Private Types

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

Private Attributes

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

Static Private Attributes

static char[] overflow = "output buffer overflow"
static char[] underflow = "input buffer underflow"
static char[] eofRead = "end-of-file whilst reading"
static char[] eofWrite = "end-of-file whilst writing"

Detailed Description

The basic premise behind this IO package is as follows:

An example of how to append a buffer follows:

        char[] foo = "to write some D";

        // create a small buffer
        auto buf = new Buffer (256);

        // append some text directly to it
        buf.append("now is the time for all good men ").append(foo);

        // output the combined string
        Cout (buf.toString);

Alternatively, one might use a Writer to append the buffer:

        auto write = new Writer (new Buffer(256));
        write ("now is the time for all good men "c) (foo);

Or, using printf-like formatting:

        auto write = new DisplayWriter (new Buffer(256));
        write.print ("now is the time for %d good men %s", 3, foo);

You might use a GrowBuffer instead where you wish to append beyond a preset limit. One common usage of buffers is in conjunction with a conduit, such as FileConduit. Each conduit exposes a preferred-size for its associated buffers, utilized during Buffer construction:

        auto file = new FileConduit ("file.name");
        auto buf = new Buffer (file);

However, this is typically hidden by higher level constructors such as those of Reader and Writer derivitives. For example:

        auto file = new FileConduit ("file.name");
        auto read = new Reader (file);

There is indeed a buffer between the Reader and Conduit, but explicit construction is unecessary in most cases. See both Reader and Writer for examples of formatted IO.

Stdout is a predefined DisplayWriter, attached to a conduit representing the console. Thus, all conduit operations are legitimate on Stdout and Stderr:

        Stdout.conduit.copy (new FileConduit ("readme.txt"));

In addition to the standard writer facilities, Stdout also has support for formatted output:

        Stdout.println ("now is the time for %d good men %s", 3, foo);

Buffers are useful for many purposes within Mango, but there are times when it is more straightforward to avoid them. For such cases, conduit derivatives (such as FileConduit) support direct I/O via a pair of read() and write() methods. These alternate methods will also invoke any attached filters.

Definition at line 205 of file Buffer.d.


Member Typedef Documentation

typedef uint(* Converter)(void *dst, uint count, uint type) [inherited]
 

Definition at line 99 of file IBuffer.d.


Member Function Documentation

this IConduit  conduit  )  [inline]
 

Construct a Buffer upon the provided conduit

Definition at line 233 of file Buffer.d.

References IConduit::bufferSize(), conduit, IConduit::isTextual(), and setConduit().

this uint  capacity = 0  )  [inline]
 

Construct a Buffer with the specified number of bytes.

Reimplemented in GrowBuffer.

Definition at line 246 of file Buffer.d.

References capacity.

this void[]  data  )  [inline]
 

Prime buffer with an application-supplied array. There is no readable data present, and writing begins at position 0.

Definition at line 258 of file Buffer.d.

References data.

this void[]  data,
uint  readable
[inline]
 

Prime buffer with an application-supplied array, and indicate how much readable data is already there. A write operation will begin writing immediately after the existing content.

Definition at line 272 of file Buffer.d.

References data, readable(), and setContent().

void error char[]  msg  )  [inline]
 

Throw an exception with the provided message

Reimplemented from IBuffer.

Definition at line 283 of file Buffer.d.

Referenced by append(), drain(), RawCodec1::exporter(), fill(), flush(), get(), and makeRoom().

void [] getContent  )  [inline, protected]
 

Return the backing array

Reimplemented from IBuffer.

Definition at line 294 of file Buffer.d.

References data.

Style getStyle  )  [inline]
 

Return style of buffer

Reimplemented from IBuffer.

Definition at line 305 of file Buffer.d.

References style.

IBuffer setValidContent void[]  data  )  [inline]
 

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 from IBuffer.

Definition at line 319 of file Buffer.d.

References setContent().

Referenced by StartLine::VersionUseTokenizer::parse(), ResponseLine::parse(), and MappedBuffer::VersionWin32::this().

IBuffer setContent void[]  data,
uint  readable = 0
[inline]
 

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 from IBuffer.

Definition at line 333 of file Buffer.d.

References readable().

Referenced by setValidContent(), and this().

bool grow uint  size  )  [inline, protected]
 

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

Reimplemented from IBuffer.

Reimplemented in GrowBuffer.

Definition at line 352 of file Buffer.d.

Referenced by append(), and makeRoom().

void copy void *  src,
uint  size
[inline, protected]
 

Bulk copy of data from 'src'. Limit is adjusted by 'size' bytes.

Reimplemented in MappedBuffer.

Definition at line 364 of file Buffer.d.

References data, and limit.

Referenced by append().

void [] get uint  size,
bool  eat = true
[inline]
 

Read a chunk of data from the buffer, loading from the conduit as necessary. The specified number of bytes is 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 from IBuffer.

Definition at line 383 of file Buffer.d.

References capacity, compress(), conduit, data, eofRead, error(), fill(), position, readable(), underflow, and writable().

Referenced by RawCodec1::exporter(), Console::Input::opCall(), and skip().

IBuffer append void[]  src  )  [inline]
 

Append an array of data to 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 from IBuffer.

Definition at line 424 of file Buffer.d.

References capacity, conduit, copy(), error(), IConduit::flush(), flush(), grow(), overflow, and writable().

Referenced by RawCodec1::importer(), and Console::Output::opCall().

char [] toString  )  [inline]
 

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

Reimplemented from IBuffer.

Definition at line 457 of file Buffer.d.

References data, limit, and position.

Referenced by VirtualCache::put(), and HttpClient::read().

bool skip int  size  )  [inline]
 

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 from IBuffer.

Definition at line 474 of file Buffer.d.

References get(), and position.

uint readable  )  [inline]
 

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

Reimplemented from IBuffer.

Definition at line 496 of file Buffer.d.

References limit, and position.

Referenced by compress(), RawCodec1::exporter(), fill(), get(), Console::Input::opCall(), HttpClient::open(), HttpClient::read(), setContent(), and this().

uint writable  )  [inline]
 

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

Reimplemented from IBuffer.

Reimplemented in MappedBuffer.

Definition at line 508 of file Buffer.d.

References capacity, and limit.

Referenced by append(), fill(), and get().

uint write uint(*)(void[])  dg  )  [inline]
 

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 appropriate number of bytes if it writes valid content, or IConduit.Eof on error.

Returns whatever the delegate returns.

Reimplemented from IBuffer.

Reimplemented in MappedBuffer.

Definition at line 526 of file Buffer.d.

References assert(), capacity, data, and limit.

Referenced by fill(), RawCodec1::importer1(), and Console::Output::sink().

uint read uint(*)(void[])  dg  )  [inline]
 

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 from IBuffer.

Definition at line 552 of file Buffer.d.

References assert(), data, limit, and position.

Referenced by drain(), and RawCodec1::exporter1().

IBuffer compress  )  [inline]
 

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 from IBuffer.

Reimplemented in MappedBuffer.

Definition at line 577 of file Buffer.d.

References data, limit, position, and readable().

Referenced by drain(), fill(), and get().

uint fill  )  [inline]
 

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 from IBuffer.

Definition at line 602 of file Buffer.d.

References conduit, error(), and underflow.

Referenced by RawCodec1::exporter(), RawCodec1::exporter1(), get(), Console::Input::opCall(), and HttpClient::read().

uint fill IConduit  conduit  )  [inline]
 

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. We also try to read as much as possible by clearing the buffer when all current content has been eaten.

Returns the number of bytes read, or Conduit.Eof

Reimplemented from IBuffer.

Definition at line 622 of file Buffer.d.

References clear(), compress(), error(), IConduit::read(), readable(), writable(), and write().

void makeRoom int  space  )  [inline]
 

make some room in the buffer

Reimplemented from IBuffer.

Definition at line 640 of file Buffer.d.

References conduit, drain(), error(), grow(), and overflow.

Referenced by RawCodec1::importer1().

uint drain  )  [inline]
 

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

Returns the number of bytes written, or Conduit.Eof

Reimplemented from IBuffer.

Definition at line 658 of file Buffer.d.

References compress(), conduit, IConduit::Eof, eofWrite, error(), read(), and IConduit::write().

Referenced by makeRoom().

void flush  )  [inline]
 

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

Reimplemented from IBuffer.

Definition at line 675 of file Buffer.d.

References clear(), conduit, data, eofWrite, error(), IConduit::flush(), limit, and position.

Referenced by append(), Console::Output::opCall(), and ClusterThread::run().

IBuffer clear  )  [inline]
 

Reset 'position' and 'limit' to zero

Reimplemented from IBuffer.

Reimplemented in MappedBuffer.

Definition at line 690 of file Buffer.d.

References limit, and position.

Referenced by Cluster::broadcast(), fill(), flush(), VirtualCache::put(), HttpClient::read(), ClusterThread::run(), and HttpMessage::setConduit().

uint getLimit  )  [inline]
 

Returns the limit of readable content within this buffer

Reimplemented from IBuffer.

Definition at line 702 of file Buffer.d.

References limit.

uint getCapacity  )  [inline]
 

Returns the total capacity of this buffer

Reimplemented from IBuffer.

Definition at line 713 of file Buffer.d.

References capacity.

uint getPosition  )  [inline]
 

Returns the current read-position within this buffer

Reimplemented from IBuffer.

Definition at line 724 of file Buffer.d.

References position.

Referenced by Cluster::broadcast(), and ResponseLine::parse().

IConduit getConduit  )  [inline]
 

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

Buffers do not require an external conduit to operate, but it can be convenient to associate one. For example, methods fill() & drain() use it to import/export content as necessary.

Reimplemented from IBuffer.

Definition at line 741 of file Buffer.d.

References conduit.

Referenced by HttpMessage::getConduit(), and ClusterThread::run().

void setConduit IConduit  conduit  )  [inline]
 

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 fill() & drain() use it to import/export content as necessary.

Reimplemented from IBuffer.

Reimplemented in MappedBuffer.

Definition at line 756 of file Buffer.d.

Referenced by HttpMessage::setConduit(), Console::Output::this(), Console::Input::this(), ClusterThread::this(), and this().


Member Data Documentation

void [] data [protected]
 

Definition at line 207 of file Buffer.d.

Referenced by compress(), copy(), flush(), get(), getContent(), read(), this(), toString(), and write().

Style style [protected]
 

Definition at line 208 of file Buffer.d.

Referenced by getStyle().

uint limit [protected]
 

Definition at line 209 of file Buffer.d.

Referenced by clear(), compress(), copy(), flush(), getLimit(), read(), readable(), toString(), writable(), and write().

uint capacity [protected]
 

Definition at line 210 of file Buffer.d.

Referenced by append(), get(), getCapacity(), this(), writable(), and write().

uint position [protected]
 

Definition at line 211 of file Buffer.d.

Referenced by clear(), compress(), flush(), get(), getPosition(), read(), readable(), skip(), and toString().

IConduit conduit [protected]
 

Reimplemented in Console::Input, Console::Output, Console::Input, and Console::Output.

Definition at line 212 of file Buffer.d.

Referenced by append(), drain(), fill(), flush(), get(), getConduit(), makeRoom(), and this().

char [] overflow = "output buffer overflow" [static, private]
 

Definition at line 214 of file Buffer.d.

Referenced by append(), and makeRoom().

char [] underflow = "input buffer underflow" [static, private]
 

Definition at line 215 of file Buffer.d.

Referenced by fill(), and get().

char [] eofRead = "end-of-file whilst reading" [static, private]
 

Definition at line 216 of file Buffer.d.

Referenced by get().

char [] eofWrite = "end-of-file whilst writing" [static, private]
 

Definition at line 217 of file Buffer.d.

Referenced by drain(), and flush().

const Style Mixed = 0 [inherited]
 

Definition at line 103 of file IBuffer.d.

const Style Binary = 1 [inherited]
 

Definition at line 104 of file IBuffer.d.

const Style Text = 2 [inherited]
 

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:37 2005 for Mango by  doxygen 1.4.0