Buffering of data occurs on input streams and output streams. When buffering output, OmniMark will collect data as it comes from the program and store it in RAM, in a buffer. Then OmniMark will send the data to output when the buffer is full. When buffering input, OmniMark will ask the source for a buffer full of data rather than a smaller amount (even though that may be all the program needs at the time).

Why buffer? I/O is a significant speed factor. Asking for data from a hard disk requires times in milliseconds. Getting it from a buffer in RAM takes tens of microseconds. That is why many programs, including OmniMark, seek to reduce the number of disk I/O requests by buffering both input and output.

For most programs, buffering is not an issue. The default for all streams except for #error is buffered, and that is appropriate for most circumstances.

When would you not buffer an input stream? If the input stream is not a file, there may be no natural end to the data, such as an end-of-file tag, to signal to OmniMark to stop waiting. But if there is only a small amount of data, the buffer never fills, and OmniMark continues to wait for data. If there is no more data, the program will appear to hang. This means that unbuffered input is more appropriate for these types of inputs, so that OmniMark only asks the input source for as much data as the program is asking for. For most circumstances, buffering is preferred.

When would you not buffer an output stream? If the output is to a real-time target, such as the console, or if #error and #main-output are going to the same target, you probably should not buffer your output. Usually, buffering is preferred.

One common issue involves mixing buffered and unbuffered output modes. For instance, both #process-output and #error can go to the same target, such as the console. Since #error is unbuffered by default, and #process-output defaults to buffered, error messages can appear on the console before text sent earlier to #process-output. If this causes a problem, the solution is to also make #process-output unbuffered, for example, at the start of your program:

  declare #process-output has unbuffered

Note that unbuffering a stream that has referents-allowed does not provide a method for forcing early resolution of the referents in that stream. The contents of the stream will simply be sent immediately to the referent resolution buffer, where it will be held until the referents are resolved in the normal fashion.

Prerequisite Concepts    Input

Related Syntax    #error    #main-input    #main-output    #process-input    #process-output    binary-mode    buffered, unbuffered    file    flush    open    text-mode

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]