3 * $Id: txport.h,v 1.2 2002/01/30 09:27:10 mdw Exp $
5 * Transport switch glue
7 * (c) 2001 Mark Wooding
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of Jog: Programming for a jogging machine.
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.
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.
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.
36 /*----- Header files ------------------------------------------------------*/
47 #include <mLib/darray.h>
48 #include <mLib/lbuf.h>
50 /*----- Data structures ---------------------------------------------------*/
52 /* --- Vector of bytes --- */
56 DA_DECL(uchar_v
, unsigned char);
59 /* --- Node for lines --- */
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 */
68 /* --- A transport context --- *
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.
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 */
88 TX_READY
, /* More data may arrive */
89 TX_CLOSE
, /* No more data will arrive */
90 TX_CLOSED
/* Done the closure thing already */
93 /* --- Transport operations --- */
95 struct txfile
{ const char *env
; const char *name
; };
97 typedef struct txport_ops
{
98 struct txport_ops
*next
;
100 const struct txfile
*fv
;
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*/
);
109 /*----- Global variables --------------------------------------------------*/
111 extern txport_ops
*txlist
;
112 extern const char *txname
;
113 extern const char *txfile
;
114 extern const char *txconf
;
116 #define DIRVAR "JOGDIR"
118 /*----- Functions provided ------------------------------------------------*/
120 /* --- @tx_create@ --- *
122 * Arguments: @const char *name@ = name of transport to instantiate
123 * @const char *file@ = filename for transport
124 * @const char *config@ = config string
126 * Returns: A pointer to the transport context, or null on error.
128 * Use: Creates a new transport.
131 extern txport
*tx_create(const char */
*name*/
, const char */
*file*/
,
132 const char */
*config*/
);
134 /* --- @tx_configure@ --- *
136 * Arguments: @txport *tx@ = pointer to transport block
137 * @const char *config@ = config string
139 * Returns: Zero if OK, nonzero on errors.
141 * Use: Applies a configuration string to a transport.
144 extern int tx_configure(txport */
*tx*/
, const char */
*config*/
);
146 /* --- @tx_write@ --- *
148 * Arguments: @txport *tx@ = pointer to transport context
149 * @const void *p@ = pointer to buffer to write
150 * @size_t sz@ = size of buffer
152 * Returns: Zero if OK, or @-1@ on error.
154 * Use: Writes some data to a transport.
157 extern int tx_write(txport */
*tx*/
, const void */
*p*/
, size_t /*sz*/);
159 /* --- @tx_printf@ --- *
161 * Arguments: @txport *tx@ = pointer to transport context
162 * @const char *p@ = pointer to string to write
164 * Returns: The number of characters printed, or @EOF@ on error.
166 * Use: Writes a textual message to a transport.
169 extern int tx_vprintf(txport */
*tx*/
, const char */
*p*/
, va_list */
*ap*/
);
171 extern int tx_printf(txport */
*tx*/
, const char */
*p*/
, ...);
173 /* --- @tx_newline@ --- *
175 * Arguments: @txport *tx@ = pointer to transport context
177 * Returns: Zero if OK, nonzero on error.
179 * Use: Writes a newline (record boundary) to the output.
182 int tx_newline(txport */
*tx*/
);
184 /* --- @tx_read@, @tx_readx@ --- *
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
191 * Returns: A pointer to a line block, which must be freed using
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.
203 #define FOREVER (~0ul)
205 extern txline
*tx_readx(txport */
*tx*/
, unsigned long /*t*/,
206 int (*/
*filter*/
)(const char */
*s*/
, void */
*p*/
),
209 extern txline
*tx_read(txport */
*tx*/
, unsigned long /*t*/);
211 /* --- @tx_freeline@ --- *
213 * Arguments: @txline *l@ = pointer to line
217 * Use: Frees a line block.
220 extern void tx_freeline(txline */
*l*/
);
222 /* --- @tx_destroy@ --- *
224 * Arguments: @txport *tx@ = transport context
228 * Use: Destroys a transport.
231 extern void tx_destroy(txport */
*tx*/
);
233 /*----- That's all, folks -------------------------------------------------*/