1 #ifndef OSTREAM_H
2 #define OSTREAM_H
3
4 #include "ioloop.h"
5
6 enum ostream_send_istream_result {
7 /* All of the istream was successfully sent to ostream. */
8 OSTREAM_SEND_ISTREAM_RESULT_FINISHED,
9 /* Caller needs to wait for more input from non-blocking istream. */
10 OSTREAM_SEND_ISTREAM_RESULT_WAIT_INPUT,
11 /* Caller needs to wait for output to non-blocking ostream.
12 o_stream_set_flush_pending() is automatically called. */
13 OSTREAM_SEND_ISTREAM_RESULT_WAIT_OUTPUT,
14 /* Read from istream failed. See istream->stream_errno. */
15 OSTREAM_SEND_ISTREAM_RESULT_ERROR_INPUT,
16 /* Write to ostream failed. See ostream->stream_errno. */
17 OSTREAM_SEND_ISTREAM_RESULT_ERROR_OUTPUT
18 };
19
20 enum ostream_create_file_flags {
21 /* without append, file is truncated */
22 OSTREAM_CREATE_FILE_FLAG_APPEND = BIT(0),
23 };
24
25 struct ostream {
26 /* Number of bytes sent via o_stream_send*() and similar functions.
27 This is counting the input data. For example with a compressed
28 ostream this is counting the uncompressed bytes. The compressed
29 bytes could be counted from the parent ostream's offset.
30
31 Seeking to a specified offset only makes sense if there is no
32 difference between input and output data sizes (e.g. there are no
33 wrapper ostreams changing the data). */
34 uoff_t offset;
35
36 /* errno for the last operation send/seek operation. cleared before
37 each call. */
38 int stream_errno;
39
40 /* overflow is set when some of the data given to send()
41 functions was neither sent nor buffered. It's never unset inside
42 ostream code. */
43 bool overflow:1;
44 /* o_stream_send() writes all the data or returns failure */
45 bool blocking:1;
46 bool closed:1;
47
48 struct ostream_private *real_stream;
49 };
50
51 /* Returns 1 if all data is sent (not necessarily flushed), 0 if not.
52 Pretty much the only real reason to return 0 is if you wish to send more
53 data to client which isn't buffered, eg. o_stream_send_istream(). */
54 typedef int stream_flush_callback_t(void *context);
55 typedef void ostream_callback_t(void *context);
56
57 /* Create new output stream from given file descriptor.
58 If max_buffer_size is 0, an "optimal" buffer size is used (max 128kB). */
59 struct ostream *o_stream_create_fd(int fd, size_t max_buffer_size);
60 /* The fd is set to -1 immediately to avoid accidentally closing it twice. */
61 struct ostream *o_stream_create_fd_autoclose(int *fd, size_t max_buffer_size);
62 /* Create an output stream from a regular file which begins at given offset.
63 If offset==UOFF_T_MAX, the current offset isn't known. */
64 struct ostream *
65 o_stream_create_fd_file(int fd, uoff_t offset, bool autoclose_fd);
66 struct ostream *o_stream_create_fd_file_autoclose(int *fd, uoff_t offset);
67 /* Create ostream for file. If append flag is not set, file will be truncated. */
68 struct ostream *o_stream_create_file(const char *path, uoff_t offset, mode_t mode,
69 enum ostream_create_file_flags flags);
70 /* Create an output stream to a buffer. Note that the buffer is treated as the
71 ostream's internal buffer. This means that o_stream_get_buffer_used_size()
72 returns buf->used, and _get_buffer_avail_size() returns how many bytes can
73 be written until the buffer's max size is reached. This behavior may make
74 ostream-buffer unsuitable for code that assumes that having bytes in the
75 internal buffer means that ostream isn't finished flushing its internal
76 buffer. Especially o_stream_flush_parent_if_needed() (used by
77 lib-compression ostreams) don't work with this. */
78 struct ostream *o_stream_create_buffer(buffer_t *buf);
79 /* Create an output streams that always fails the writes. */
80 struct ostream *o_stream_create_error(int stream_errno);
81 struct ostream *
82 o_stream_create_error_str(int stream_errno, const char *fmt, ...)
83 ATTR_FORMAT(2, 3);
84 /* Create an output stream that simply passes through data. This is mainly
85 useful as a wrapper when combined with destroy callbacks. */
86 struct ostream *o_stream_create_passthrough(struct ostream *output);
87
88 /* Set name (e.g. path) for output stream. */
89 void o_stream_set_name(struct ostream *stream, const char *name);
90 /* Get output stream's name. Returns "" if stream has no name. */
91 const char *o_stream_get_name(struct ostream *stream);
92
93 /* Return file descriptor for stream, or -1 if none is available. */
94 int o_stream_get_fd(struct ostream *stream);
95 /* Returns error string for the previous error. */
96 const char *o_stream_get_error(struct ostream *stream);
97 /* Returns human-readable reason for why ostream was disconnected.
98 The output is either "Connection closed" for clean disconnections or
99 "Connection closed: <error>" for unclean disconnections. This is an
100 alternative to o_stream_get_error(), which is preferred to be used when
101 logging errors about client connections. */
102 const char *o_stream_get_disconnect_reason(struct ostream *stream);
103
104 /* Close this stream (but not its parents) and unreference it. */
105 void o_stream_destroy(struct ostream **stream);
106 /* Reference counting. References start from 1, so calling o_stream_unref()
107 destroys the stream if o_stream_ref() is never used. */
108 void o_stream_ref(struct ostream *stream);
109 /* Unreferences the stream and sets stream pointer to NULL. */
110 void o_stream_unref(struct ostream **stream);
111 /* Call the given callback function when stream is destroyed. */
112 void o_stream_add_destroy_callback(struct ostream *stream,
113 ostream_callback_t *callback, void *context)
114 ATTR_NULL(3);
115 #define o_stream_add_destroy_callback(stream, callback, context) \
116 o_stream_add_destroy_callback(stream - \
117 CALLBACK_TYPECHECK(callback, void (*)(typeof(context))), \
118 (ostream_callback_t *)callback, context)
119 /* Remove the destroy callback. */
120 void o_stream_remove_destroy_callback(struct ostream *stream,
121 void (*callback)());
122
123 /* Mark the stream and all of its parent streams closed. Nothing will be
124 sent after this call. When using ostreams that require writing a trailer,
125 o_stream_finish() must be used before the stream is closed. When ostream
126 is destroyed, it's also closed but its parents aren't.
127
128 Closing the ostream (also via destroy) will first flush the ostream, and
129 afterwards requires one of: a) stream has failed, b) there is no more
130 buffered data, c) o_stream_set_no_error_handling() has been called. */
131 void o_stream_close(struct ostream *stream);
132
133 /* Set IO_WRITE callback. Default will just try to flush the output and
134 finishes when the buffer is empty. */
135 void o_stream_set_flush_callback(struct ostream *stream,
136 stream_flush_callback_t *callback,
137 void *context) ATTR_NULL(3);
138 #define o_stream_set_flush_callback(stream, callback, context) \
139 o_stream_set_flush_callback(stream - \
140 CALLBACK_TYPECHECK(callback, int (*)(typeof(context))), \
141 (stream_flush_callback_t *)callback, context)
142 void o_stream_unset_flush_callback(struct ostream *stream);
143 /* Change the maximum size for stream's output buffer to grow. */
144 void o_stream_set_max_buffer_size(struct ostream *stream, size_t max_size);
145 /* Returns the current max. buffer size. */
146 size_t o_stream_get_max_buffer_size(struct ostream *stream);
147
148 /* Delays sending as far as possible, writing only full buffers. Also sets
149 TCP_CORK on if supported. */
150 void o_stream_cork(struct ostream *stream);
151 /* Try to flush the buffer by calling o_stream_flush() and remove TCP_CORK.
152 Note that after this o_stream_flush() must be called, unless the stream
153 ignores errors. */
154 void o_stream_uncork(struct ostream *stream);
155 bool o_stream_is_corked(struct ostream *stream);
156 /* Try to flush the output stream. If o_stream_nsend*() had been used and
157 the stream had overflown, return error. Returns 1 if all data is sent,
158 0 there's still buffered data, -1 if error. */
159 int o_stream_flush(struct ostream *stream);
160 /* Wrapper to easily both uncork and flush. */
o_stream_uncork_flush(struct ostream * stream)161 static inline int o_stream_uncork_flush(struct ostream *stream)
162 {
163 o_stream_uncork(stream);
164 return o_stream_flush(stream);
165 }
166
167 /* Set "flush pending" state of stream. If set, the flush callback is called
168 when more data is allowed to be sent, even if the buffer itself is empty.
169 Note that if the stream is corked, the flush callback won't be called until
170 the stream is first uncorked. */
171 void o_stream_set_flush_pending(struct ostream *stream, bool set);
172 /* Returns the number of bytes currently in all the pending write buffers of
173 this ostream, including its parent streams. This function is commonly used
174 by callers to determine when they've filled up the ostream so they can stop
175 writing to it. Because of this, the return value shouldn't include buffers
176 that are expected to be filled up before they send anything to their parent
177 stream. Otherwise the callers may stop writing to the stream too early and
178 hang. Such an example could be a compression ostream that won't send
179 anything to its parent stream before an internal compression buffer is
180 full. */
181 size_t o_stream_get_buffer_used_size(const struct ostream *stream) ATTR_PURE;
182 /* Returns the (minimum) number of bytes we can still write without failing.
183 This is commonly used by callers to find out how many bytes they're
184 guaranteed to be able to send, and then generate that much data and send
185 it. */
186 size_t o_stream_get_buffer_avail_size(const struct ostream *stream) ATTR_PURE;
187
188 /* Seek to specified position from beginning of file. This works only for
189 files. Returns 1 if successful, -1 if error. */
190 int o_stream_seek(struct ostream *stream, uoff_t offset);
191 /* Returns number of bytes sent, -1 = error */
192 ssize_t o_stream_send(struct ostream *stream, const void *data, size_t size)
193 ATTR_WARN_UNUSED_RESULT;
194 ssize_t o_stream_sendv(struct ostream *stream, const struct const_iovec *iov,
195 unsigned int iov_count) ATTR_WARN_UNUSED_RESULT;
196 ssize_t o_stream_send_str(struct ostream *stream, const char *str)
197 ATTR_WARN_UNUSED_RESULT;
198 /* Send with delayed error handling. o_stream_flush() or
199 o_stream_ignore_last_errors() must be called after these functions before
200 the stream is destroyed. If any of the data can't be sent due to stream's
201 buffer getting full, all further nsends are ignores and o_stream_flush()
202 will fail. */
203 void o_stream_nsend(struct ostream *stream, const void *data, size_t size);
204 void o_stream_nsendv(struct ostream *stream, const struct const_iovec *iov,
205 unsigned int iov_count);
206 void o_stream_nsend_str(struct ostream *stream, const char *str);
207 /* Mark the ostream as finished and flush it. If the ostream has a footer,
208 it's written here. Any further write attempts to the ostream will
209 assert-crash. Returns the same as o_stream_flush(). Afterwards any calls to
210 this function are identical to o_stream_flush(). */
211 int o_stream_finish(struct ostream *stream);
212 /* Specify whether calling o_stream_finish() will cause the parent stream to
213 be finished as well. The default is yes. */
214 void o_stream_set_finish_also_parent(struct ostream *stream, bool set);
215 /* Specify whether calling o_stream_finish() on a child stream will cause
216 this stream to be finished as well. The default is yes. */
217 void o_stream_set_finish_via_child(struct ostream *stream, bool set);
218 /* Marks the stream's error handling as completed to avoid i_panic() on
219 destroy. */
220 void o_stream_ignore_last_errors(struct ostream *stream);
221 /* Abort writing to the ostream, also marking any previous error handling as
222 completed. If the stream hasn't already failed, sets the stream_errno=EPIPE.
223 This is necessary when aborting write to streams that require finishing. */
224 void o_stream_abort(struct ostream *stream);
225 /* If error handling is disabled, the i_panic() on destroy is never called.
226 This function can be called immediately after the stream is created.
227 When creating wrapper streams, they copy this behavior from the parent
228 stream. */
229 void o_stream_set_no_error_handling(struct ostream *stream, bool set);
230 /* Send all of the instream to outstream.
231
232 On non-failure instream is skips over all data written to outstream.
233 This means that the number of bytes written to outstream is always equal to
234 the number of bytes skipped in instream.
235
236 It's also possible to use this function to copy data within same file
237 descriptor, even if the source and destination overlaps. If the file must
238 be grown, you have to do it manually before calling this function. */
239 enum ostream_send_istream_result ATTR_WARN_UNUSED_RESULT
240 o_stream_send_istream(struct ostream *outstream, struct istream *instream);
241 /* Same as o_stream_send_istream(), but assume that reads and writes will
242 succeed. If not, o_stream_flush() will fail with the correct error
243 message (even istream's). */
244 void o_stream_nsend_istream(struct ostream *outstream, struct istream *instream);
245
246 /* Write data to specified offset. Returns 0 if successful, -1 if error. */
247 int o_stream_pwrite(struct ostream *stream, const void *data, size_t size,
248 uoff_t offset);
249
250 /* Return the last timestamp when something was successfully sent to the
251 ostream's internal buffers (no guarantees that anything was sent further).
252 The timestamp is 0 if nothing has ever been written. */
253 void o_stream_get_last_write_time(struct ostream *stream, struct timeval *tv_r);
254
255 /* If there are any I/O loop items associated with the stream, move all of
256 them to provided/current ioloop. */
257 void o_stream_switch_ioloop_to(struct ostream *stream, struct ioloop *ioloop);
258 void o_stream_switch_ioloop(struct ostream *stream);
259
260 #endif
261