2 * ustream - library for stream buffer management
4 * Copyright (C) 2012 Felix Fietkau <nbd@openwrt.org>
6 * Permission to use, copy, modify, and/or distribute this software for any
7 * purpose with or without fee is hereby granted, provided that the above
8 * copyright notice and this permission notice appear in all copies.
10 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
11 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
12 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
13 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
14 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
15 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
27 enum read_blocked_reason {
28 READ_BLOCKED_USER = (1 << 0),
29 READ_BLOCKED_FULL = (1 << 1),
32 struct ustream_buf_list {
33 struct ustream_buf *head;
34 struct ustream_buf *data_tail;
35 struct ustream_buf *tail;
37 int (*alloc)(struct ustream *s, struct ustream_buf_list *l);
49 struct ustream_buf_list r, w;
50 struct uloop_timeout state_change;
54 * called by the ustream core to notify that new data is available
56 * must not free the ustream from this callback
58 void (*notify_read)(struct ustream *s, int bytes_new);
61 * notify_write: (optional)
62 * called by the ustream core to notify that some buffered data has
63 * been written to the stream.
64 * must not free the ustream from this callback
66 void (*notify_write)(struct ustream *s, int bytes);
70 * called by the ustream implementation to notify that the read
71 * side of the stream is closed (eof is set) or there was a write
72 * error (write_error is set).
73 * will be called again after the write buffer has been emptied when
74 * the read side has hit EOF.
76 void (*notify_state)(struct ustream *s);
80 * must be defined by ustream implementation, accepts new write data.
81 * 'more' is used to indicate that a subsequent call will provide more
82 * data (useful for aggregating writes)
83 * returns the number of bytes accepted, or -1 if no more writes can
84 * be accepted (link error)
86 int (*write)(struct ustream *s, const char *buf, int len, bool more);
90 * defined by ustream implementation, tears down the ustream and frees data
92 void (*free)(struct ustream *s);
95 * set_read_blocked: (optional)
96 * defined by ustream implementation, called when the read_blocked flag
99 void (*set_read_blocked)(struct ustream *s);
102 * ustream user should set this if the input stream is expected
103 * to contain string data. the core will keep all data 0-terminated.
107 bool eof, eof_write_done;
109 enum read_blocked_reason read_blocked;
113 struct ustream stream;
118 struct ustream_buf *next;
127 /* ustream_fd_init: create a file descriptor ustream (uses uloop) */
128 void ustream_fd_init(struct ustream_fd *s, int fd);
130 /* ustream_free: free all buffers and data associated with a ustream */
131 void ustream_free(struct ustream *s);
133 /* ustream_consume: remove data from the head of the read buffer */
134 void ustream_consume(struct ustream *s, int len);
136 /* ustream_write: add data to the write buffer */
137 int ustream_write(struct ustream *s, const char *buf, int len, bool more);
138 int ustream_printf(struct ustream *s, const char *format, ...);
139 int ustream_vprintf(struct ustream *s, const char *format, va_list arg);
141 /* ustream_get_read_buf: get a pointer to the next read buffer data */
142 char *ustream_get_read_buf(struct ustream *s, int *buflen);
145 * ustream_set_read_blocked: set read blocked state
147 * if set, the ustream will no longer fetch pending data.
149 void ustream_set_read_blocked(struct ustream *s, bool set);
151 static inline bool ustream_read_blocked(struct ustream *s)
153 return !!(s->read_blocked & READ_BLOCKED_USER);
156 /*** --- functions only used by ustream implementations --- ***/
158 /* ustream_init_defaults: fill default callbacks and options */
159 void ustream_init_defaults(struct ustream *s);
162 * ustream_reserve: allocate rx buffer space
164 * len: hint for how much space is needed (not guaranteed to be met)
165 * maxlen: pointer to where the actual buffer size is going to be stored
167 char *ustream_reserve(struct ustream *s, int len, int *maxlen);
169 /* ustream_fill_read: mark rx buffer space as filled */
170 void ustream_fill_read(struct ustream *s, int len);
173 * ustream_write_pending: attempt to write more data from write buffers
174 * returns true if all write buffers have been emptied.
176 bool ustream_write_pending(struct ustream *s);
178 static inline void ustream_state_change(struct ustream *s)
180 uloop_timeout_set(&s->state_change, 0);