ustream.h

   1 /*
   2  * ustream - library for stream buffer management
   3  *
   4  * Copyright (C) 2012 Felix Fietkau <nbd@openwrt.org>
   5  *
   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.
   9  *
  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.
  17  */
  18
  19 #ifndef __USTREAM_H
  20 #define __USTREAM_H
  21
  22 #include <stdarg.h>
  23 #include "uloop.h"
  24
  25 struct ustream;
  26 struct ustream_buf;
  27
  28 enum read_blocked_reason {
  29         READ_BLOCKED_USER = (1 << 0),
  30         READ_BLOCKED_FULL = (1 << 1),
  31 };
  32
  33 struct ustream_buf_list {
  34         struct ustream_buf *head;
  35         struct ustream_buf *data_tail;
  36         struct ustream_buf *tail;
  37
  38         int (*alloc)(struct ustream *s, struct ustream_buf_list *l);
  39
  40         int data_bytes;
  41
  42         int min_buffers;
  43         int max_buffers;
  44         int buffer_len;
  45
  46         int buffers;
  47 };
  48
  49 struct ustream {
  50         struct ustream_buf_list r, w;
  51         struct uloop_timeout state_change;
  52         struct ustream *next;
  53
  54         /*
  55          * notify_read: (optional)
  56          * called by the ustream core to notify that new data is available
  57          * for reading.
  58          * must not free the ustream from this callback
  59          */
  60         void (*notify_read)(struct ustream *s, int bytes_new);
  61
  62         /*
  63          * notify_write: (optional)
  64          * called by the ustream core to notify that some buffered data has
  65          * been written to the stream.
  66          * must not free the ustream from this callback
  67          */
  68         void (*notify_write)(struct ustream *s, int bytes);
  69
  70         /*
  71          * notify_state: (optional)
  72          * called by the ustream implementation to notify that the read
  73          * side of the stream is closed (eof is set) or there was a write
  74          * error (write_error is set).
  75          * will be called again after the write buffer has been emptied when
  76          * the read side has hit EOF.
  77          */
  78         void (*notify_state)(struct ustream *s);
  79
  80         /*
  81          * write:
  82          * must be defined by ustream implementation, accepts new write data.
  83          * 'more' is used to indicate that a subsequent call will provide more
  84          * data (useful for aggregating writes)
  85          * returns the number of bytes accepted, or -1 if no more writes can
  86          * be accepted (link error)
  87          */
  88         int (*write)(struct ustream *s, const char *buf, int len, bool more);
  89
  90         /*
  91          * free: (optional)
  92          * defined by ustream implementation, tears down the ustream and frees data
  93          */
  94         void (*free)(struct ustream *s);
  95
  96         /*
  97          * set_read_blocked: (optional)
  98          * defined by ustream implementation, called when the read_blocked flag
  99          * changes
 100          */
 101         void (*set_read_blocked)(struct ustream *s);
 102
 103         /*
 104          * poll: (optional)
 105          * defined by the upstream implementation, called to request polling for
 106          * available data.
 107          * returns true if data was fetched.
 108          */
 109         bool (*poll)(struct ustream *s);
 110
 111         /*
 112          * ustream user should set this if the input stream is expected
 113          * to contain string data. the core will keep all data 0-terminated.
 114          */
 115         bool string_data;
 116         bool write_error;
 117         bool eof;
 118         uint8_t pending_cb;
 119
 120         enum read_blocked_reason read_blocked;
 121 };
 122
 123 struct ustream_fd {
 124         struct ustream stream;
 125         struct uloop_fd fd;
 126 };
 127
 128 struct ustream_buf {
 129         struct ustream_buf *next;
 130
 131         char *data;
 132         char *tail;
 133         char *end;
 134
 135         char head[];
 136 };
 137
 138 /* ustream_fd_init: create a file descriptor ustream (uses uloop) */
 139 void ustream_fd_init(struct ustream_fd *s, int fd);
 140
 141 /* ustream_free: free all buffers and data associated with a ustream */
 142 void ustream_free(struct ustream *s);
 143
 144 /* ustream_consume: remove data from the head of the read buffer */
 145 void ustream_consume(struct ustream *s, int len);
 146
 147 /*
 148  * ustream_read: read and consume data in read buffer into caller-specified
 149  * area.  Return length of data read.
 150  */
 151 int ustream_read(struct ustream *s, char *buf, int buflen);
 152 /* ustream_write: add data to the write buffer */
 153 int ustream_write(struct ustream *s, const char *buf, int len, bool more);
 154 int ustream_printf(struct ustream *s, const char *format, ...)
 155         __attribute__ ((format (printf, 2, 3)));
 156 int ustream_vprintf(struct ustream *s, const char *format, va_list arg)
 157         __attribute__ ((format (printf, 2, 0)));
 158
 159 /* ustream_get_read_buf: get a pointer to the next read buffer data */
 160 char *ustream_get_read_buf(struct ustream *s, int *buflen);
 161
 162 /*
 163  * ustream_set_read_blocked: set read blocked state
 164  *
 165  * if set, the ustream will no longer fetch pending data.
 166  */
 167 void ustream_set_read_blocked(struct ustream *s, bool set);
 168
 169 static inline bool ustream_read_blocked(struct ustream *s)
 170 {
 171         return !!(s->read_blocked & READ_BLOCKED_USER);
 172 }
 173
 174 static inline int ustream_pending_data(struct ustream *s, bool write)
 175 {
 176         struct ustream_buf_list *b = write ? &s->w : &s->r;
 177         return b->data_bytes;
 178 }
 179
 180 static inline bool ustream_read_buf_full(struct ustream *s)
 181 {
 182         struct ustream_buf *buf = s->r.data_tail;
 183         return buf && buf->data == buf->head && buf->tail == buf->end &&
 184                s->r.buffers == s->r.max_buffers;
 185 }
 186
 187 /*** --- functions only used by ustream implementations --- ***/
 188
 189 /* ustream_init_defaults: fill default callbacks and options */
 190 void ustream_init_defaults(struct ustream *s);
 191
 192 /*
 193  * ustream_reserve: allocate rx buffer space
 194  *
 195  * len: hint for how much space is needed (not guaranteed to be met)
 196  * maxlen: pointer to where the actual buffer size is going to be stored
 197  */
 198 char *ustream_reserve(struct ustream *s, int len, int *maxlen);
 199
 200 /* ustream_fill_read: mark rx buffer space as filled */
 201 void ustream_fill_read(struct ustream *s, int len);
 202
 203 /*
 204  * ustream_write_pending: attempt to write more data from write buffers
 205  * returns true if all write buffers have been emptied.
 206  */
 207 bool ustream_write_pending(struct ustream *s);
 208
 209 static inline void ustream_state_change(struct ustream *s)
 210 {
 211         uloop_timeout_set(&s->state_change, 0);
 212 }
 213
 214 static inline bool ustream_poll(struct ustream *s)
 215 {
 216         if (!s->poll)
 217                 return false;
 218
 219         return s->poll(s);
 220 }
 221
 222 #endif