License:
BSD style: see license.txt

Version:
Mar 2004: Initial release Dec 2006: Outback release

author:
Kris

  • class IBuffer : tango.io.model.IConduit.IConduit, tango.io.model.IBuffer.Buffered;
    • Buffer is central concept in Tango I/O. Each 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 implemented in various ways.

    Buffer can be read from and written to directly, though various data-converters and filters are often leveraged to apply structure to what might otherwise be simple raw data.

    Buffers may also be tokenized by applying an Iterator. This can be handy when one is dealing with text input, and/or the content suits a more fluid format than most typical converters support. Iterator tokens are mapped directly onto buffer content (sliced), making them quite efficient in practice. Like other types of buffer client, multiple iterators can be mapped onto one common buffer and access will be serialized.

    Buffers are sometimes memory-only, in which case there is nothing left to do when a client has consumed all the content. Other buffers are themselves bound to an external device called a conduit. When this is the case, a consumer will eventually cause a buffer to reload via its associated conduit and previous buffer content will be lost.

    A similar approach is applied to clients which populate a buffer, whereby the content of a full buffer will be flushed to a bound conduit before continuing. Another variation is that of a memory-mapped buffer, whereby the buffer content is mapped directly to virtual memory exposed via the OS. This can be used to address large files as an array of content.

    See tango.io.Buffer for more info.

  • abstract IBuffer buffer ();
    • implements Buffered interface

  • abstract void[] getContent ();
    • Return the backing array

  • abstract void[] slice ();
    • Return a void[] slice of the buffer up to the limit of valid content.

  • abstract IBuffer setContent (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).

  • abstract 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).

  • abstract IBuffer append (void* content, uint length);
    • Append 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.



  • abstract IBuffer append (void[] content);
    • Append 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.



  • abstract IBuffer append (IBuffer other);
    • Append another buffer to this one, 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.



  • abstract void consume (void[] src);
    • Consume content from a producer

    Params:

    Remarks:
    This is often used in lieu of a Writer, and enables simple classes, such as FilePath and Uri, to emit content directly into a buffer (thus avoiding potential heap activity)

    Examples:
                    auto path = new FilePath (somepath);

                path.produce (&buffer.consume);


  • abstract void[] slice (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).



  • abstract void[] readExact (void* dst, uint bytes);
    • Access buffer content

    Params:
    void* dst destination of the content
    uint bytes size of dst

    Returns:
    A reference to the populated content

    Remarks:
    Fill the provided array with content. We try to satisfy the request from the buffer content, and read directly from an attached conduit where more is required.



  • abstract uint fill (void[] dst);
    • Fill the provided buffer. Returns the number of bytes actually read, which will be less than dst.length when Eof has been reached and IConduit.Eof thereafter.

  • abstract uint write (uint delegate(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.



  • abstract uint read (uint delegate(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.



  • abstract 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.



  • abstract 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.



  • abstract bool next (uint delegate(void[]));
    • Support for tokenizing iterators.

    Upon success, the delegate should return the byte-based index of the consumed pattern (tail end of it). Failure to match a pattern should be indicated by returning an IConduit.Eof.

    Each pattern is expected to be stripped of the delimiter. An end-of-file condition causes trailing content to be placed into the token. Requests made beyond Eof result in empty matches (length == zero).

    Note that additional iterator and/or reader instances will stay in lockstep when bound to a common buffer.

    Returns true if a token was isolated, false otherwise.



  • abstract uint fill (InputStream src);
    • Try to fill the available buffer with content from the specified conduit. We try to read as much as possible by clearing the buffer when all current content has been eaten. If there is no space available, nothing will be read.

    Returns the number of bytes read, or Conduit.Eof.



  • abstract uint drain (OutputStream dst);
    • Write as much of the buffer that the associated conduit can consume.

    Returns the number of bytes written, or Conduit.Eof.



  • abstract bool truncate (uint extent);
    • Truncate the buffer within its extent. Returns true if the new 'extent' is valid, false otherwise.

  • abstract bool compress (bool yes);
    • Configure the compression strategy for iterators

    Remarks:
    Iterators will tend to compress the buffered content in order to maximize space for new data. You can disable this behaviour by setting this boolean to false



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

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

  • abstract uint limit ();
    • Returns the limit of readable content within this buffer.

  • abstract uint capacity ();
    • Returns the total capacity of this buffer.

  • abstract uint position ();
    • Returns the current position within this buffer.

  • abstract IBuffer 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.



  • abstract IBuffer output (OutputStream sink);
    • Set output stream

    Params:
    OutputStream sink the stream to attach to

    Remarks:
    Sets the external output stream associated with this buffer.

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



  • abstract IBuffer input (InputStream source);
    • Set input stream

    Params:
    InputStream source the stream to attach to

    Remarks:
    Sets the external input stream associated with this buffer.

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



  • abstract uint read (void[] dst);
    • Transfer content into the provided dst.

    Params:
    void[] dst destination of the content

    Returns:
    Return the number of bytes read , which may be less than dst.length. Eof is returned when no further content is available.

    Remarks:
    Populates the provided array with content. We try to satisfy the request from the buffer content, and read directly from an attached conduit when the buffer is empty.



  • abstract uint write (void[] src);
    • Emulate OutputStream. write ()

    Params:
    void[] src the content to write

    Returns:
    Return the number of bytes written, which will be Eof when the content cannot be written.

    Remarks:
    Appends all of dst to the buffer, flushing to an attached conduit as necessary.



  • abstract OutputStream output ();
    • Exposes configured output stream

    Returns:
    Returns the OutputStream associated with this buffer. Returns null if the buffer is not attached to an output ; that is, it's not backed by some external medium.

    Remarks:
    Buffers do not require an external stream to operate, but it can be convenient to associate them. For example, methods fill & drain use them to import/export content as necessary.



  • abstract InputStream input ();
    • Exposes configured input stream

    Returns:
    Returns the InputStream associated with this buffer. Returns null if the buffer is not attached to an input ; that is, it's not backed by some external medium.

    Remarks:
    Buffers do not require an external stream to operate, but it can be convenient to associate them. For example, methods fill & drain use them to import/export content as necessary.



  • abstract void error (char[] msg);
    • Throw an exception with the provided message

  • abstract IConduit conduit ();
    • Access configured conduit

    Returns:
    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.

    Remarks:
    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.



  • abstract uint bufferSize ();
    • Return a preferred size for buffering conduit I/O.

  • abstract char[] toString ();
    • Return the name of this conduit.

  • abstract bool isAlive ();
    • Is the conduit alive?

  • abstract OutputStream flush ();
    • Flush the contents of this buffer to the related conduit. Throws an IOException on premature eof.

  • abstract InputStream clear ();
    • Reset position and limit to zero.

  • abstract OutputStream copy (InputStream src);
    • Copy content via this buffer from the provided src conduit.

    Remarks:
    The src conduit has its content transferred through this buffer via a series of fill & drain operations, until there is no more content available. The buffer content should be explicitly flushed by the caller.

    Throws an IOException on premature Eof.



  • abstract void detach ();
    • Release external resources

  • abstract void close ();
    • Close the stream

    Remarks:
    Propagate request to an attached OutputStream (this is a requirement for the OutputStream interface)



  • interface Buffered ;
    • Supported by streams which are prepared to share an internal buffer instance. This is intended to avoid a situation whereby content is shunted unnecessarily from one buffer to another when "decorator" streams are connected together in arbitrary ways.

    Do not implement this if the internal buffer should not be accessed directly by another stream e.g. if wrapper methods manipulate content on the way in or out of the buffer.

    Copyright (c) 2004 Kris Bell. All rights reserved :: page rendered by CandyDoc