tango.io.device.Conduit
License:
BSD style:
Version:
Mar 2004: Initial release
author:
Kris
- abstract class Conduit: tango.io.model.IConduit.IConduit;
- Conduit abstract base-class, implementing interface IConduit.
Only the conduit-specific read(), write(), detach() and
bufferSize() need to be implemented for a concrete conduit
implementation. See File for an example.
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: either subclass
tango.io.device.Conduit, or implement tango.io.model.IConduit. A
conduit typically reads and writes via a Buffer in large chunks,
typically the entire buffer. Alternatively, one can invoke method
read(dst[]) and/or write(src[]) directly.
- this();
- Test for asynchronous capability. This will be eligable
for scheduling where (a) it is created within a fiber and
(b) there is a scheduler attached to the fiber at the time
this is invoked.
Note that fibers may schedule just one outstanding I/O
request at a time.
- abstract string toString();
- Return the name of this conduit.
- abstract const const size_t bufferSize();
- Return a preferred size for buffering conduit I/O.
- abstract size_t read(void[] dst);
- Read from conduit into a target array. The provided dst
will be populated with content from the conduit.
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 size_t write(const(void)[] src);
- Write to conduit from a source array. The provided src
content will be written to the conduit.
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 void detach();
- Disconnect this conduit. Note that this may be invoked
both explicitly by the user, and implicitly by the GC.
Be sure to manage multiple detachment requests correctly:
set a flag, or sentinel value as necessary.
- final @property void timeout(uint millisec);
- Set the active timeout period for IO calls (in milliseconds.)
- const final const @property uint timeout();
- Get the active timeout period for IO calls (in milliseconds.)
- const const @property bool isAlive();
- Is the conduit alive? Default behaviour returns true.
- final @property IConduit conduit();
- Return the host. This is part of the Stream interface.
- IOStream flush();
- Emit buffered output or reset buffered input.
- void close();
- Close this conduit.
Both input and output are detached, and are no longer usable.
- final void error(const(char[]) msg);
- Throw an IOException, with the provided message.
- final @property InputStream input();
- Return the input stream.
- final @property OutputStream output();
- Return the output stream.
- final Conduit put(void[] src);
- Emit fixed-length content from 'src' into this conduit,
throwing an IOException upon Eof.
- final Conduit get(void[] dst);
- Consume fixed-length content into 'dst' from this conduit,
throwing an IOException upon Eof.
- final Conduit rewind();
- Rewind to beginning of file.
- OutputStream copy(InputStream src, size_t max = -1);
- Transfer the content of another conduit to this one. Returns
the dst OutputStream, or throws IOException on failure.
- long seek(long offset, Anchor anchor = (Anchor).Begin);
- Seek on this stream. Source conduits that don't support
seeking will throw an IOException.
- char[] text(T = char)(size_t max = -1);
- Load text from a stream, and return them all in an
array.
Returns an array representing the content, and throws
IOException on error.
- void[] load(size_t max = -1);
- Load the bits from a stream, and return them all in an
array. The dst array can be provided as an option, which
will be expanded as necessary to consume the input.
Returns an array representing the content, and throws
IOException on error.
- static void[] load(InputStream src, size_t max = -1);
- Load the bits from a stream, and return them all in an
array. The dst array can be provided as an option, which
will be expanded as necessary to consume input.
Returns an array representing the content, and throws
IOException on error.
- static void put(void[] src, OutputStream output);
- Emit fixed-length content from 'src' into 'output',
throwing an IOException upon Eof.
- static void get(void[] dst, InputStream input);
- Consume fixed-length content into 'dst' from 'input',
throwing an IOException upon Eof.
- static size_t transfer(InputStream src, OutputStream dst, size_t max = -1);
- Low-level data transfer, where max represents the maximum
number of bytes to transfer.
Returns Eof on failure, number of bytes copied on success.
- class InputFilter: tango.io.model.IConduit.InputStream;
- Base class for input stream filtering. The provided source stream
should generally never be null, though some filters have a need to
set this lazily.
- this(InputStream source);
- Attach to the provided stream. The provided source stream
should generally never be null, though some filters have a
need to set this lazily.
- @property IConduit conduit();
- Return the hosting conduit.
- size_t read(void[] dst);
- Read from conduit into a target array. The provided dst
will be populated with content from the conduit.
Returns the number of bytes read, which may be less than
requested in dst. Eof is returned whenever an end-of-flow
condition arises.
- void[] load(size_t max = -1);
- Load the bits from a stream, and return them all in an
array. The dst array can be provided as an option, which
will be expanded as necessary to consume the input.
Returns an array representing the content, and throws
IOException on error.
- IOStream flush();
- Clear any buffered content.
- long seek(long offset, Anchor anchor = (Anchor).Begin);
- Seek on this stream. Target conduits that don't support
seeking will throw an IOException.
- @property InputStream input();
- Return the upstream host of this filter.
- void close();
- Close the input.
- class OutputFilter: tango.io.model.IConduit.OutputStream;
- Base class for output stream filtering. The provided sink stream
should generally never be null, though some filters have a need to
set this lazily.
- this(OutputStream sink);
- Attach to the provided stream.
- @property IConduit conduit();
- Return the hosting conduit.
- size_t write(const(void)[] src);
- Write to conduit from a source array. The provided src
content will be written to the conduit.
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.
- OutputStream copy(InputStream src, size_t max = -1);
- Transfer the content of another conduit to this one. Returns
a reference to this class, or throws IOException on failure.
- IOStream flush();
- Emit/purge buffered content.
- long seek(long offset, Anchor anchor = (Anchor).Begin);
- Seek on this stream. Target conduits that don't support
seeking will throw an IOException.
- @property OutputStream output();
- Return the upstream host of this filter.
- void close();
- Close the output.
Page generated by Ddoc. Copyright (c) 2004 Kris Bell. All rights reserved