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

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