Output Streams ============== 'lib/ostream.h' describes Dovecot's output streams. Output streams can be stacked on top of each others as many times as wanted. Output streams actually writing data: * file: Write to given fd using 'pwrite()' for files and 'write()' for non-files. * unix: Write to given UNIX socket. Similar to file, but supports sending file descriptors. * buffer: Write to <buffer> [Design.Buffers.txt]. Output stream filters: * hash: Calculate hash of the ostream while it's being written. * escaped: Write output escaped via callback. Built-in support for HEX and JSON escaping. * multiplex: Multiplex-iostreams support multiple iostream channels inside a single parent istream. * null: All the output is discarded. * failure-at: Insert a failure at the specified offset. This can be useful for testing. * lib-mail/ostream-dot: Write SMTP-style DATA input where the output ends with an empty "." line. * lib-dcrypt/encrypt: Write encrypted data. * lib-compression/*: Write zlib/bzlib/lz4/lzma compressed data. A typical life cycle for an ostream can look like: * create * 'o_stream_cork()' * 'o_stream_nsend*()' one or more times * 'o_stream_uncork()' * If necessary, check errors with 'o_stream_flush()' * 'o_stream_cork()' * 'o_stream_nsend*()' one or more times * 'o_stream_uncork()' * finalize the ostream with 'o_stream_finish()' * optionally close the ostream with 'o_stream_close()' * unref or destroy Once the ostream is finished, it can't be written to anymore. The 'o_stream_finish()' call writes any potential trailer that the ostream may have (e.g. ostream-gz, ostream-encrypt, ostream-dot) while still allowing the caller to check if the trailer write failed. After 'o_stream_finish()' is called, any further write will panic. The ostreams that require a trailer will panic if 'o_stream_finish()' hasn't been called before the stream is destroyed, but other ostreams don't currently require this. Still, it's not always easy to know whether there might be ostreams that require the trailer, so if there's any doubt, it's preferred to call 'o_stream_finish()' just before destroying the ostream. Usually calling 'o_stream_finish()' will also finish its parent ostream. This may or may not be wanted depending on the situation. For example ostream-dot must be finished to write the last "." line, but ostream-dot is always a sub-stream of something else that must not be finished yet. This is why ostream-dot by default has called 'o_stream_set_finish_also_parent(FALSE)', so finishing the ostream-dot won't finish the parent stream. Similarly 'connection.c' API sets 'o_stream_set_finish_via_child(FALSE)' so none of the socket connections created via it will be finished even though one of their sub-streams is finished. These functions may need to be called explicitly in other situations. When doing a lot of writes, you can simplify the error handling by delaying the error checking. Use the 'o_stream_nsend*()' functions and afterwards check the error with 'o_stream_flush()' or 'o_stream_finish()'. If you forgot to do this check before the ostream is destroyed, it will panic with:'output stream %s is missing error handling' regardless of whether there is an error or not. If you don't care about errors for the ostream (e.g. because it's a client socket and there's nothing you can do about the write errors), you can use 'o_stream_set_no_error_handling()' to fully disable error checks. You can also use 'o_stream_ignore_last_errors()' to ignore the errors so far, but not for future writes. Writes are non-buffered by default. To add buffering, use 'o_stream_cork()' to start buffering and 'o_stream_uncork()' to stop/flush. When output buffer gets full, it's automatically flushed even while the stream is corked. The term "cork" is used because with TCP connections the call actually sets/removes TCP cork option. It's quite easy to forget to enable the corking with files, making the performance worse. The corking/uncorking is done automatically when flush callbacks are called. Using 'o_stream_uncork()' will trigger an automatic 'o_stream_flush()' but the error is ignored. This is why it acts similarly to 'o_stream_nsend*()', i.e. it requires another explicit 'o_stream_flush()', 'o_stream_finish()' or error ignoring before the ostream is destroyed. If output buffer's size isn't unlimited, the writes can also fail or be partial because there's no more space in the buffer and 'write()' syscall is returning 'EAGAIN'. This of course doesn't happen with blocking fds (e.g. files), but you need to handle this in some way with non-blocking network sockets. A common way in Dovecot to handle this is to just use unlimited buffer sizes and after each write check if the buffer size becomes too large, and when it does it stops writing until more space is available. (This file was created from the wiki on 2019-06-19 12:42)
