tango.io.model.IConduit
License:
BSD style:
Version:
Initial release: March 2004
Outback release: December 2006
author:
Kris
- abstract interface IConduit: tango.io.model.IConduit.InputStream, tango.io.model.IConduit.OutputStream;
- Conduits provide virtualized access to external content, and
represent things like files or Internet connections. Conduits
expose a pair of streams, are modelled by tango.io.model.IConduit,
and are implemented via classes such as File & SocketConduit.
Additional kinds of conduit are easy to construct: one either
subclasses tango.io.device.Conduit, or implements tango.io.model.IConduit.
A conduit typically reads and writes from/to an IBuffer in large
chunks, typically the entire buffer. Alternatively, one can invoke
input.read(dst[]) and/or output.write(src[]) directly.
- abstract @property size_t bufferSize();
- Return a preferred size for buffering conduit I/O.
- abstract immutable(char)[] toString();
- Return the name of this conduit.
- abstract const const @property bool isAlive();
- Is the conduit alive?
- abstract void detach();
- Release external resources.
- abstract void error(const(char[]) msg);
- Throw a generic IO exception with the provided msg.
- interface Seek;
- All streams now support seek(), so this is used to signal
a seekable conduit instead.
- abstract interface Truncate;
- Indicates the conduit supports resize/truncation.
- abstract interface ISelectable;
- Describes how to make an IO entity usable with selectors.
- alias Handle;
- Opaque OS file-handle.
- abstract @property Handle fileHandle();
- Models a handle-oriented device.
TODO:
Figure out how to avoid exposing this in the general
case.
- abstract interface IOStream;
- The common attributes of streams.
- int Eof;
- the End-of-Flow identifer
- enum Anchor;
- The anchor positions supported by seek().
- abstract long seek(long offset, Anchor anchor = (Anchor).Begin);
- Move the stream position to the given offset from the
provided anchor point, and return adjusted position.
Those conduits which don't support seeking will throw
an IOException (and don't implement IConduit.Seek).
- abstract @property IConduit conduit();
- Return the host conduit.
- abstract IOStream flush();
- Flush buffered content. For InputStream this is equivalent
to clearing buffered content.
- abstract void close();
- Close the input.
- interface Mutator;
- Marks a stream that performs read/write mutation, rather than
generic decoration. This is used to identify those stream that
should explicitly not share an upstream buffer with downstream
siblings.
Many streams add simple decoration (such as DataStream) while
others are merely template aliases. However, streams such as
EndianStream mutate content as it passes through the read and
write methods, which must be respected. On one hand we wish
to share a single buffer instance, while on the other we must
ensure correct data flow through an arbitrary combinations of
streams.
There are two stream variations: one which operate directly
upon memory (and thus must have access to a buffer) and another
that prefer to have buffered input (for performance reasons) but
can operate without. EndianStream is an example of the former,
while DataStream represents the latter.
In order to sort out who gets what, each stream makes a request
for an upstream buffer at construction time. The request has an
indication of the intended purpose (array-based access, or not).
- abstract interface InputStream: tango.io.model.IConduit.IOStream;
- The Tango input stream.
- abstract size_t read(void[] dst);
- Read from stream into a target array. The provided dst
will be populated with content from the stream.
Returns the number of bytes read, which may be less than
requested in dst. Eof is returned whenever an end-of-flow
condition arises.
- abstract void[] load(size_t max = -1);
- Load the bits from a stream, and return them all in an
array. The optional max value indicates the maximum
number of bytes to be read.
Returns an array representing the content, and throws
IOException on error.
- abstract @property InputStream input();
- Return the upstream source.
- abstract interface OutputStream: tango.io.model.IConduit.IOStream;
- The Tango output stream.
- abstract size_t write(const(void)[] src);
- Write to stream from a source array. The provided src
content will be written to the stream.
Returns the number of bytes written from src, which may
be less than the quantity provided. Eof is returned when
an end-of-flow condition arises.
- abstract OutputStream copy(InputStream src, size_t max = -1);
- Transfer the content of another stream to this one. Returns
a reference to this class, and throws IOException on failure.
- abstract @property OutputStream output();
- Return the upstream sink.
- abstract interface InputBuffer: tango.io.model.IConduit.InputStream;
- A buffered input stream.
- abstract interface OutputBuffer: tango.io.model.IConduit.OutputStream;
- A buffered output stream.
Page generated by Ddoc. Copyright (c) 2004 Kris Bell. All rights reserved