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 /*----- Revision history --------------------------------------------------*
  30  *
  31  * $Log: txport.h,v $
  32  * Revision 1.2  2002/01/30 09:27:10  mdw
  33  * Transport configuration overhaul.  Configuration string is now a list of
  34  * `;'-separated `key=value' strings, which can be handled either by the
  35  * core or the transport module.  The newline character(s) are a core
  36  * parameter now.
  37  *
  38  * Revision 1.1  2002/01/25 19:34:45  mdw
  39  * Initial revision
  40  *
  41  */
  42
  43 #ifndef TXPORTSW_H
  44 #define TXPORTSW_H
  45
  46 #ifdef __cplusplus
  47   extern "C" {
  48 #endif
  49
  50 /*----- Header files ------------------------------------------------------*/
  51
  52 #ifdef HAVE_CONFIG_H
  53 #  include "config.h"
  54 #endif
  55
  56 #include <stdarg.h>
  57 #include <stddef.h>
  58
  59 #include <pthread.h>
  60
  61 #include <mLib/darray.h>
  62 #include <mLib/lbuf.h>
  63
  64 /*----- Data structures ---------------------------------------------------*/
  65
  66 /* --- Vector of bytes --- */
  67
  68 #ifndef UCHAR_V
  69 #  define UCHAR_V
  70    DA_DECL(uchar_v, unsigned char);
  71 #endif
  72
  73 /* --- Node for lines --- */
  74
  75 typedef struct txline {
  76   struct txline *next, *prev;           /* Next node in the list */
  77   struct txport *tx;                    /* Owning transport */
  78   char *s;                              /* Pointer to the text */
  79   size_t len;                           /* Length of the string */
  80 } txline;
  81
  82 /* --- A transport context --- *
  83  *
  84  * The only members for which there is contention are the state @s@ and the
  85  * raw incoming buffer @buf@.  Other members may be accessed without locking
  86  * the structure.  Thus, the thread messing about is essentially isolated to
  87  * the data- fetching thread and the line buffering code.
  88  */
  89
  90 typedef struct txport {
  91   struct txport_ops *ops;               /* Operations table */
  92   pthread_t tid;                        /* Fetching thread id */
  93   pthread_mutex_t mx;                   /* Lock for this structure */
  94   pthread_cond_t cv;                    /* `New data has arrived' */
  95   unsigned s;                           /* State of this transport */
  96   uchar_v buf;                          /* Buffer of incoming data */
  97   lbuf lb;                              /* Buffer for extracting lines */
  98   txline *ll, *ll_tail;                 /* List of waiting lines, in order */
  99 } txport;
 100
 101 enum {
 102   TX_READY,                             /* More data may arrive */
 103   TX_CLOSE,                             /* No more data will arrive */
 104   TX_CLOSED                             /* Done the closure thing already */
 105 };
 106
 107 /* --- Transport operations --- */
 108
 109 struct txfile { const char *env; const char *name; };
 110
 111 typedef struct txport_ops {
 112   struct txport_ops *next;
 113   const char *name;
 114   const struct txfile *fv;
 115   const char *config;
 116   txport *(*create)(const char */*file*/);
 117   int (*configure)(txport */*tx*/, const char */*k*/, const char */*v*/);
 118   void *(*fetch)(void */*txv*/);
 119   ssize_t (*write)(txport */*tx*/, const void */*p*/, size_t /*sz*/);
 120   void (*destroy)(txport */*tx*/);
 121 } txport_ops;
 122
 123 /*----- Global variables --------------------------------------------------*/
 124
 125 extern txport_ops *txlist;
 126 extern const char *txname;
 127 extern const char *txfile;
 128 extern const char *txconf;
 129
 130 #define DIRVAR "JOGDIR"
 131
 132 /*----- Functions provided ------------------------------------------------*/
 133
 134 /* --- @tx_create@ --- *
 135  *
 136  * Arguments:   @const char *name@ = name of transport to instantiate
 137  *              @const char *file@ = filename for transport
 138  *              @const char *config@ = config string
 139  *
 140  * Returns:     A pointer to the transport context, or null on error.
 141  *
 142  * Use:         Creates a new transport.
 143  */
 144
 145 extern txport *tx_create(const char */*name*/, const char */*file*/,
 146                          const char */*config*/);
 147
 148 /* --- @tx_configure@ --- *
 149  *
 150  * Arguments:   @txport *tx@ = pointer to transport block
 151  *              @const char *config@ = config string
 152  *
 153  * Returns:     Zero if OK, nonzero on errors.
 154  *
 155  * Use:         Applies a configuration string to a transport.
 156  */
 157
 158 extern int tx_configure(txport */*tx*/, const char */*config*/);
 159
 160 /* --- @tx_write@ --- *
 161  *
 162  * Arguments:   @txport *tx@ = pointer to transport context
 163  *              @const void *p@ = pointer to buffer to write
 164  *              @size_t sz@ = size of buffer
 165  *
 166  * Returns:     Zero if OK, or @-1@ on error.
 167  *
 168  * Use:         Writes some data to a transport.
 169  */
 170
 171 extern int tx_write(txport */*tx*/, const void */*p*/, size_t /*sz*/);
 172
 173 /* --- @tx_printf@ --- *
 174  *
 175  * Arguments:   @txport *tx@ = pointer to transport context
 176  *              @const char *p@ = pointer to string to write
 177  *
 178  * Returns:     The number of characters printed, or @EOF@ on error.
 179  *
 180  * Use:         Writes a textual message to a transport.
 181  */
 182
 183 extern int tx_vprintf(txport */*tx*/, const char */*p*/, va_list */*ap*/);
 184
 185 extern int tx_printf(txport */*tx*/, const char */*p*/, ...);
 186
 187 /* --- @tx_newline@ --- *
 188  *
 189  * Arguments:   @txport *tx@ = pointer to transport context
 190  *
 191  * Returns:     Zero if OK, nonzero on error.
 192  *
 193  * Use:         Writes a newline (record boundary) to the output.
 194  */
 195
 196 int tx_newline(txport */*tx*/);
 197
 198 /* --- @tx_read@, @tx_readx@ --- *
 199  *
 200  * Arguments:   @txport *tx@ = pointer to transport context
 201  *              @unsigned long t@ = time to wait for data (ms)
 202  *              @int (*filter)(const char *s, void *p)@ = filtering function
 203  *              @void *p@ = pointer argument for filter
 204  *
 205  * Returns:     A pointer to a line block, which must be freed using
 206  *              @tx_freeline@.
 207  *
 208  * Use:         Fetches a line from the buffer.  Each line is passed to the
 209  *              filter function in oldest-to-newest order; the filter
 210  *              function returns nonzero to choose a line.  If no suitable
 211  *              line is waiting in the raw buffer, the program blocks while
 212  *              more data is fetched, until the time limit @t@ is exceeded,
 213  *              in which case a null pointer is returned.  A null filter
 214  *              function is equivalent to one which always selects its line.
 215  */
 216
 217 #define FOREVER (~0ul)
 218
 219 extern txline *tx_readx(txport */*tx*/, unsigned long /*t*/,
 220                         int (*/*filter*/)(const char */*s*/, void */*p*/),
 221                         void */*p*/);
 222
 223 extern txline *tx_read(txport */*tx*/, unsigned long /*t*/);
 224
 225 /* --- @tx_freeline@ --- *
 226  *
 227  * Arguments:   @txline *l@ = pointer to line
 228  *
 229  * Returns:     ---
 230  *
 231  * Use:         Frees a line block.
 232  */
 233
 234 extern void tx_freeline(txline */*l*/);
 235
 236 /* --- @tx_destroy@ --- *
 237  *
 238  * Arguments:   @txport *tx@ = transport context
 239  *
 240  * Returns:     ---
 241  *
 242  * Use:         Destroys a transport.
 243  */
 244
 245 extern void tx_destroy(txport */*tx*/);
 246
 247 /*----- That's all, folks -------------------------------------------------*/
 248
 249 #ifdef __cplusplus
 250   }
 251 #endif
 252
 253 #endif