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 "uloop.h"
  23
  24 struct ustream;
  25 struct ustream_buf;
  26
  27 enum read_blocked_reason {
  28         READ_BLOCKED_USER = (1 << 0),
  29         READ_BLOCKED_FULL = (1 << 1),
  30 };
  31
  32 struct ustream_buf_list {
  33         struct ustream_buf *head;
  34         struct ustream_buf *data_tail;
  35         struct ustream_buf *tail;
  36
  37         int (*alloc)(struct ustream *s, struct ustream_buf_list *l);
  38
  39         int data_bytes;
  40
  41         int min_buffers;
  42         int max_buffers;
  43         int buffer_len;
  44
  45         int buffers;
  46 };
  47
  48 struct ustream {
  49         struct ustream_buf_list r, w;
  50         struct uloop_timeout state_change;
  51
  52         /*
  53          * notify_read:
  54          * called by the ustream core to notify that new data is available
  55          * for reading.
  56          * must not free the ustream from this callback
  57          */
  58         void (*notify_read)(struct ustream *s, int bytes_new);
  59
  60         /*
  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
  65          */
  66         void (*notify_write)(struct ustream *s, int bytes);
  67
  68         /*
  69          * notify_state:
  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.
  75          */
  76         void (*notify_state)(struct ustream *s);
  77
  78         /*
  79          * write:
  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)
  85          */
  86         int (*write)(struct ustream *s, const char *buf, int len, bool more);
  87
  88         /*
  89          * free: (optional)
  90          * defined by ustream implementation, tears down the ustream and frees data
  91          */
  92         void (*free)(struct ustream *s);
  93
  94         /*
  95          * set_read_blocked: (optional)
  96          * defined by ustream implementation, called when the read_blocked flag
  97          * changes
  98          */
  99         void (*set_read_blocked)(struct ustream *s);
 100
 101         /*
 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.
 104          */
 105         bool string_data;
 106         bool write_error;
 107         bool eof, eof_write_done;
 108
 109         enum read_blocked_reason read_blocked;
 110 };
 111
 112 struct ustream_fd {
 113         struct ustream stream;
 114         struct uloop_fd fd;
 115 };
 116
 117 struct ustream_buf {
 118         struct ustream_buf *next;
 119
 120         char *data;
 121         char *tail;
 122         char *end;
 123
 124         char head[];
 125 };
 126
 127 /* ustream_fd_init: create a file descriptor ustream (uses uloop) */
 128 void ustream_fd_init(struct ustream_fd *s, int fd);
 129
 130 /* ustream_free: free all buffers and data associated with a ustream */
 131 void ustream_free(struct ustream *s);
 132
 133 /* ustream_consume: remove data from the head of the read buffer */
 134 void ustream_consume(struct ustream *s, int len);
 135
 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);
 140
 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);
 143
 144 /*
 145  * ustream_set_read_blocked: set read blocked state
 146  *
 147  * if set, the ustream will no longer fetch pending data.
 148  */
 149 void ustream_set_read_blocked(struct ustream *s, bool set);
 150
 151 static inline bool ustream_read_blocked(struct ustream *s)
 152 {
 153         return !!(s->read_blocked & READ_BLOCKED_USER);
 154 }
 155
 156 /*** --- functions only used by ustream implementations --- ***/
 157
 158 /* ustream_init_defaults: fill default callbacks and options */
 159 void ustream_init_defaults(struct ustream *s);
 160
 161 /*
 162  * ustream_reserve: allocate rx buffer space
 163  *
 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
 166  */
 167 char *ustream_reserve(struct ustream *s, int len, int *maxlen);
 168
 169 /* ustream_fill_read: mark rx buffer space as filled */
 170 void ustream_fill_read(struct ustream *s, int len);
 171
 172 /*
 173  * ustream_write_pending: attempt to write more data from write buffers
 174  * returns true if all write buffers have been emptied.
 175  */
 176 bool ustream_write_pending(struct ustream *s);
 177
 178 static inline void ustream_state_change(struct ustream *s)
 179 {
 180         uloop_timeout_set(&s->state_change, 0);
 181 }
 182
 183 #endif