BufferedOutputRange

BufferedOutputRange is a performance enhancement over writing directly to an output stream. It holds a File open for write or an OutputRange. Ouput is accumulated in an internal buffer and written to the output stream as a block.

Writing to stdout is a key use case. BufferedOutputRange is often dramatically faster than writing to stdout directly. This is especially noticable for outputs with short lines, as it blocks many writes together in a single write.

The internal buffer is written to the output stream after flushSize has been reached. This is checked at newline boundaries, when appendln is called or when put is called with a single newline character. Other writes check maxSize, which is used to avoid runaway buffers.

This scheme only flushes the internal buffer, it does not flush the output stream. Use flush() to flush both the internal buffer and the output stream. Specify flushSize as BufferedOutputRangeDefaults.lineBufferedFlushSize in the constructor to get line buffering with immediate flushes to the output stream.

The output stream type must be provided as a template argument during construction. E.g.

auto bufferedOutput = BufferedOutputRange!(typeof(stdout))(stdout)

BufferedOutputRange has a put method allowing it to be used an output range. It has a number of other methods providing additional control.

Methods:

this(outputStream [, flushSize, reserveSize, maxSize]) - Constructor. Takes the output stream, e.g. stdout. Other arguments are optional, defaults normally suffice.
this(outputStream, LineBuffered) - Alternate constructor for turning line-buffered mode on.
append(stuff) - Append to the internal buffer.
appendln(stuff) - Append to the internal buffer, followed by a newline. The buffer is flushed to the output stream if is has reached flushSize.
appendln() - Append a newline to the internal buffer. The buffer is flushed to the output stream if is has reached flushSize.
joinAppend(inputRange, delim) - An optimization of append(inputRange.joiner(delim)). For reasons that are not clear, joiner is quite slow.
flush() - Writes the internal buffer to the output stream and flush the output stream.
put(stuff) - Appends to the internal buffer. Acts as appendln() if passed a single newline character, '\n' or "\n".
flushBuffer() - This flushes both the internal buffers and the output stream.

The internal buffer is automatically flushed when the BufferedOutputRange goes out of scope.

struct BufferedOutputRange (

OutputTarget

) if (

isFileHandle!(Unqual!OutputTarget) ||

isOutputRange!(Unqual!OutputTarget, char)

) {

import std.array : appender;;

import std.format : format;;

alias C = char;

alias C = ubyte;

this(OutputTarget outputTarget, size_t flushSize, size_t reserveSize, size_t maxSize);

this(OutputTarget outputTarget, LineBuffered lineBuffered);

~this();

void flush();

void append(T stuff);

bool appendln(T stuff);

void joinAppend(InputRange inputRange, E delimiter);

void put(T stuff);

}

Constructors

this this(OutputTarget outputTarget, size_t flushSize, size_t reserveSize, size_t maxSize): Constructor. Takes the output stream, e.g. stdout. Optional arguments control buffering behavior, defaults normally suffice. The defaults are available from the BufferedOutputRangeDefault enum.
this this(OutputTarget outputTarget, LineBuffered lineBuffered): Alternate constuctor used to turn line-buffered mode on. Use Yes.lineBuffered to enable. Lines are flushed at newline boundaries when in line-buffered mode.

Destructor

~this ~this(): Undocumented in source.

Members

Aliases

C alias C = char: Undocumented in source.
C alias C = ubyte: Undocumented in source.

Functions

append void append(T stuff): Appends data to the output buffer. The output buffer is flushed if the appended data ends in a newline and the output buffer has reached flushSize.
appendln bool appendln(T stuff): Appends data plus a newline to the output buffer. The output buffer is flushed if it has reached flushSize.
flush void flush(): Writes the internal buffer to the output stream and flush the output stream.
joinAppend void joinAppend(InputRange inputRange, E delimiter): joinAppend is an optimization of append(inputRange.joiner(delimiter). This form is quite a bit faster, 40%+ on some benchmarks.
put void put(T stuff): The put method makes BufferOutputRange an OutputRange. It operates similarly to append.