lib/pullwr.h

   1 /*
   2  * Pull-driven write event handler
   3  * Copyright (C) 2019  David Lamparter
   4  *
   5  * This program is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License as published by the Free
   7  * Software Foundation; either version 2 of the License, or (at your option)
   8  * any later version.
   9  *
  10  * This program is distributed in the hope that it will be useful, but WITHOUT
  11  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  12  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for
  13  * more details.
  14  *
  15  * You should have received a copy of the GNU General Public License along
  16  * with this program; see the file COPYING; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
  18  */
  19
  20 #ifndef _WRITEPOLL_H
  21 #define _WRITEPOLL_H
  22
  23 #include <stdbool.h>
  24 #include <stdint.h>
  25
  26 #include "thread.h"
  27 #include "stream.h"
  28
  29 #ifdef __cplusplus
  30 extern "C" {
  31 #endif
  32
  33 struct pullwr;
  34
  35 /* This is a "pull-driven" write event handler.  Instead of having some buffer
  36  * or being driven by the availability of data, it triggers on the space being
  37  * available on the socket for data to be written on and then calls fill() to
  38  * get data to be sent.
  39  *
  40  * pullwr_* maintains an "idle" vs. "active" state, going into idle when a
  41  * fill() call completes without feeing more data into it.  The overall
  42  * semantics are:
  43  * - to put data out, call pullwr_write().  This is possible from both inside
  44  *   fill() callbacks or anywhere else.  Doing so puts the pullwr into
  45  *   active state.
  46  * - in active state, the fill() callback will be called and should feed more
  47  *   data in.  It should NOT loop to push out more than one "unit" of data;
  48  *   the pullwr code handles this by calling fill() until it has enough data.
  49  * - if there's nothing more to be sent, fill() returns without doing anything
  50  *   and pullwr goes into idle state after flushing all buffered data out.
  51  * - when new data becomes available, pullwr_bump() should be called to put
  52  *   the pullwr back into active mode so it will collect data from fill(),
  53  *   or you can directly call pullwr_write().
  54  * - only calling pullwr_write() from within fill() is the cleanest way of
  55  *   doing things.
  56  *
  57  * When the err() callback is called, the pullwr should be considered unusable
  58  * and released with pullwr_del().  This can be done from inside the callback,
  59  * the pullwr code holds no more references on it when calling err().
  60  */
  61 extern struct pullwr *_pullwr_new(struct thread_master *tm, int fd,
  62                 void *arg,
  63                 void (*fill)(void *, struct pullwr *),
  64                 void (*err)(void *, struct pullwr *, bool eof));
  65 extern void pullwr_del(struct pullwr *pullwr);
  66
  67 /* type-checking wrapper.  makes sure fill() and err() take a first argument
  68  * whose type is identical to the type of arg.
  69  * => use "void fill(struct mystruct *arg, ...)" - no "void *arg"
  70  */
  71 #define pullwr_new(tm, fd, arg, fill, err) ({                                  \
  72         void (*fill_typechk)(typeof(arg), struct pullwr *) = fill;          \
  73         void (*err_typechk)(typeof(arg), struct pullwr *, bool) = err;      \
  74         _pullwr_new(tm, fd, arg, (void *)fill_typechk, (void *)err_typechk);   \
  75 })
  76
  77 /* max_spin_usec is the time after which the pullwr event handler will stop
  78  *   trying to get more data from fill() and yield control back to the
  79  *   thread_master.  It does reschedule itself to continue later; this is
  80  *   only to make sure we don't freeze the entire process if we're piping a
  81  *   lot of data to a local endpoint that reads quickly (i.e. no backpressure)
  82  *
  83  *   default: 2500 (2.5 ms)
  84  *
  85  * write_threshold is the amount of data buffered from fill() calls at which
  86  *   the pullwr code starts calling write().  But this is not a "limit".
  87  *   pullwr will keep poking fill() for more data until
  88  *   (a) max_spin_usec is reached; fill() will be called again later after
  89  *       returning to the thread_master to give other events a chance to run
  90  *   (b) fill() returns without pushing any data onto the pullwr with
  91  *       pullwr_write(), so fill() will NOT be called again until a call to
  92  *       pullwr_bump() or pullwr_write() comes in.
  93  *
  94  *   default: 16384 (16 kB)
  95  *
  96  * passing 0 for either value (or not calling it at all) uses the default.
  97  */
  98 extern void pullwr_cfg(struct pullwr *pullwr, int64_t max_spin_usec,
  99                        size_t write_threshold);
 100
 101 extern void pullwr_bump(struct pullwr *pullwr);
 102 extern void pullwr_write(struct pullwr *pullwr,
 103                 const void *data, size_t len);
 104
 105 static inline void pullwr_write_stream(struct pullwr *pullwr,
 106                 struct stream *s)
 107 {
 108         pullwr_write(pullwr, s->data, stream_get_endp(s));
 109 }
 110
 111 extern void pullwr_stats(struct pullwr *pullwr, uint64_t *total_written,
 112                          size_t *pending, size_t *kernel_pending);
 113
 114 #ifdef __cplusplus
 115 }
 116 #endif
 117
 118 #endif /* _WRITEPOLL_H */