chiark - git - mdw - jog/blob - txport.h

   1 /* -*-c-*-
   2  *
   3  * $Id: txport.h,v 1.2 2002/01/30 09:27:10 mdw Exp $
   4  *
   5  * Transport switch glue
   6  *
   7  * (c) 2001 Mark Wooding
   8  */
   9
  10 /*----- Licensing notice --------------------------------------------------*
  11  *
  12  * This file is part of Jog: Programming for a jogging machine.
  13  *
  14  * Jog is free software; you can redistribute it and/or modify
  15  * it under the terms of the GNU General Public License as published by
  16  * the Free Software Foundation; either version 2 of the License, or
  17  * (at your option) any later version.
  18  *
  19  * Jog is distributed in the hope that it will be useful,
  20  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  21  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  22  * GNU General Public License for more details.
  23  *
  24  * You should have received a copy of the GNU General Public License
  25  * along with Jog; if not, write to the Free Software Foundation,
  26  * Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
  27  */
  28
  29 #ifndef TXPORTSW_H
  30 #define TXPORTSW_H
  31
  32 #ifdef __cplusplus
  33   extern "C" {
  34 #endif
  35
  36 /*----- Header files ------------------------------------------------------*/
  37
  38 #ifdef HAVE_CONFIG_H
  39 #  include "config.h"
  40 #endif
  41
  42 #include <stdarg.h>
  43 #include <stddef.h>
  44
  45 #include <pthread.h>
  46
  47 #include <mLib/darray.h>
  48 #include <mLib/lbuf.h>
  49
  50 /*----- Data structures ---------------------------------------------------*/
  51
  52 /* --- Vector of bytes --- */
  53
  54 #ifndef UCHAR_V
  55 #  define UCHAR_V
  56    DA_DECL(uchar_v, unsigned char);
  57 #endif
  58
  59 /* --- Node for lines --- */
  60
  61 typedef struct txline {
  62   struct txline *next, *prev;           /* Next node in the list */
  63   struct txport *tx;                    /* Owning transport */
  64   char *s;                              /* Pointer to the text */
  65   size_t len;                           /* Length of the string */
  66 } txline;
  67
  68 /* --- A transport context --- *
  69  *
  70  * The only members for which there is contention are the state @s@ and the
  71  * raw incoming buffer @buf@.  Other members may be accessed without locking
  72  * the structure.  Thus, the thread messing about is essentially isolated to
  73  * the data- fetching thread and the line buffering code.
  74  */
  75
  76 typedef struct txport {
  77   struct txport_ops *ops;               /* Operations table */
  78   pthread_t tid;                        /* Fetching thread id */
  79   pthread_mutex_t mx;                   /* Lock for this structure */
  80   pthread_cond_t cv;                    /* `New data has arrived' */
  81   unsigned s;                           /* State of this transport */
  82   uchar_v buf;                          /* Buffer of incoming data */
  83   lbuf lb;                              /* Buffer for extracting lines */
  84   txline *ll, *ll_tail;                 /* List of waiting lines, in order */
  85 } txport;
  86
  87 enum {
  88   TX_READY,                             /* More data may arrive */
  89   TX_CLOSE,                             /* No more data will arrive */
  90   TX_CLOSED                             /* Done the closure thing already */
  91 };
  92
  93 /* --- Transport operations --- */
  94
  95 struct txfile { const char *env; const char *name; };
  96
  97 typedef struct txport_ops {
  98   struct txport_ops *next;
  99   const char *name;
 100   const struct txfile *fv;
 101   const char *config;
 102   txport *(*create)(const char */*file*/);
 103   int (*configure)(txport */*tx*/, const char */*k*/, const char */*v*/);
 104   void *(*fetch)(void */*txv*/);
 105   ssize_t (*write)(txport */*tx*/, const void */*p*/, size_t /*sz*/);
 106   void (*destroy)(txport */*tx*/);
 107 } txport_ops;
 108
 109 /*----- Global variables --------------------------------------------------*/
 110
 111 extern txport_ops *txlist;
 112 extern const char *txname;
 113 extern const char *txfile;
 114 extern const char *txconf;
 115
 116 #define DIRVAR "JOGDIR"
 117
 118 /*----- Functions provided ------------------------------------------------*/
 119
 120 /* --- @tx_create@ --- *
 121  *
 122  * Arguments:   @const char *name@ = name of transport to instantiate
 123  *              @const char *file@ = filename for transport
 124  *              @const char *config@ = config string
 125  *
 126  * Returns:     A pointer to the transport context, or null on error.
 127  *
 128  * Use:         Creates a new transport.
 129  */
 130
 131 extern txport *tx_create(const char */*name*/, const char */*file*/,
 132                          const char */*config*/);
 133
 134 /* --- @tx_configure@ --- *
 135  *
 136  * Arguments:   @txport *tx@ = pointer to transport block
 137  *              @const char *config@ = config string
 138  *
 139  * Returns:     Zero if OK, nonzero on errors.
 140  *
 141  * Use:         Applies a configuration string to a transport.
 142  */
 143
 144 extern int tx_configure(txport */*tx*/, const char */*config*/);
 145
 146 /* --- @tx_write@ --- *
 147  *
 148  * Arguments:   @txport *tx@ = pointer to transport context
 149  *              @const void *p@ = pointer to buffer to write
 150  *              @size_t sz@ = size of buffer
 151  *
 152  * Returns:     Zero if OK, or @-1@ on error.
 153  *
 154  * Use:         Writes some data to a transport.
 155  */
 156
 157 extern int tx_write(txport */*tx*/, const void */*p*/, size_t /*sz*/);
 158
 159 /* --- @tx_printf@ --- *
 160  *
 161  * Arguments:   @txport *tx@ = pointer to transport context
 162  *              @const char *p@ = pointer to string to write
 163  *
 164  * Returns:     The number of characters printed, or @EOF@ on error.
 165  *
 166  * Use:         Writes a textual message to a transport.
 167  */
 168
 169 extern int tx_vprintf(txport */*tx*/, const char */*p*/, va_list */*ap*/);
 170
 171 extern int tx_printf(txport */*tx*/, const char */*p*/, ...);
 172
 173 /* --- @tx_newline@ --- *
 174  *
 175  * Arguments:   @txport *tx@ = pointer to transport context
 176  *
 177  * Returns:     Zero if OK, nonzero on error.
 178  *
 179  * Use:         Writes a newline (record boundary) to the output.
 180  */
 181
 182 int tx_newline(txport */*tx*/);
 183
 184 /* --- @tx_read@, @tx_readx@ --- *
 185  *
 186  * Arguments:   @txport *tx@ = pointer to transport context
 187  *              @unsigned long t@ = time to wait for data (ms)
 188  *              @int (*filter)(const char *s, void *p)@ = filtering function
 189  *              @void *p@ = pointer argument for filter
 190  *
 191  * Returns:     A pointer to a line block, which must be freed using
 192  *              @tx_freeline@.
 193  *
 194  * Use:         Fetches a line from the buffer.  Each line is passed to the
 195  *              filter function in oldest-to-newest order; the filter
 196  *              function returns nonzero to choose a line.  If no suitable
 197  *              line is waiting in the raw buffer, the program blocks while
 198  *              more data is fetched, until the time limit @t@ is exceeded,
 199  *              in which case a null pointer is returned.  A null filter
 200  *              function is equivalent to one which always selects its line.
 201  */
 202
 203 #define FOREVER (~0ul)
 204
 205 extern txline *tx_readx(txport */*tx*/, unsigned long /*t*/,
 206                         int (*/*filter*/)(const char */*s*/, void */*p*/),
 207                         void */*p*/);
 208
 209 extern txline *tx_read(txport */*tx*/, unsigned long /*t*/);
 210
 211 /* --- @tx_freeline@ --- *
 212  *
 213  * Arguments:   @txline *l@ = pointer to line
 214  *
 215  * Returns:     ---
 216  *
 217  * Use:         Frees a line block.
 218  */
 219
 220 extern void tx_freeline(txline */*l*/);
 221
 222 /* --- @tx_destroy@ --- *
 223  *
 224  * Arguments:   @txport *tx@ = transport context
 225  *
 226  * Returns:     ---
 227  *
 228  * Use:         Destroys a transport.
 229  */
 230
 231 extern void tx_destroy(txport */*tx*/);
 232
 233 /*----- That's all, folks -------------------------------------------------*/
 234
 235 #ifdef __cplusplus
 236   }
 237 #endif
 238
 239 #endif