xref: /titanic_50/usr/src/lib/libtecla/common/chrqueue.c (revision c5c4113dfcabb1eed3d4bdf7609de5170027a794)
1 /*
2  * Copyright (c) 2000, 2001, 2002, 2003, 2004 by Martin C. Shepherd.
3  *
4  * All rights reserved.
5  *
6  * Permission is hereby granted, free of charge, to any person obtaining a
7  * copy of this software and associated documentation files (the
8  * "Software"), to deal in the Software without restriction, including
9  * without limitation the rights to use, copy, modify, merge, publish,
10  * distribute, and/or sell copies of the Software, and to permit persons
11  * to whom the Software is furnished to do so, provided that the above
12  * copyright notice(s) and this permission notice appear in all copies of
13  * the Software and that both the above copyright notice(s) and this
14  * permission notice appear in supporting documentation.
15  *
16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
17  * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
19  * OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
20  * HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
21  * INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
22  * FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
23  * NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
24  * WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
25  *
26  * Except as contained in this notice, the name of a copyright holder
27  * shall not be used in advertising or otherwise to promote the sale, use
28  * or other dealings in this Software without prior written authorization
29  * of the copyright holder.
30  */
31 
32 #pragma ident	"%Z%%M%	%I%	%E% SMI"
33 
34 #include <stdlib.h>
35 #include <stdio.h>
36 #include <string.h>
37 #include <errno.h>
38 
39 #include "ioutil.h"
40 #include "chrqueue.h"
41 #include "freelist.h"
42 #include "errmsg.h"
43 
44 /*
45  * Set the number of bytes allocated to each node of the list of
46  * character buffers. This facility is designed principally as
47  * an expandible I/O output buffer, so use the stdio buffer size
48  * where available.
49  */
50 #ifdef BUFSIZ
51 #define GL_CQ_SIZE BUFSIZ
52 #else
53 #define GL_CQ_SIZE 512
54 #endif
55 
56 /*
57  * The queue is contained in a list of fixed sized buffers. New nodes
58  * are appended to this list as needed to accomodate newly added bytes.
59  * Old nodes at the head of the list are removed as they are emptied.
60  */
61 typedef struct CqCharBuff CqCharBuff;
62 struct CqCharBuff {
63   CqCharBuff *next;          /* The next node in the list of buffers */
64   char bytes[GL_CQ_SIZE];    /* The fixed size buffer of this node */
65 };
66 
67 /*
68  * Define the structure that is used to contain a list of character
69  * buffers.
70  */
71 struct GlCharQueue {
72   ErrMsg *err;          /* A buffer in which to record error messages */
73   FreeList *bufmem;     /* A free-list of CqCharBuff structures */
74   struct {
75     CqCharBuff *head;   /* The head of the list of output buffers */
76     CqCharBuff *tail;   /* The tail of the list of output buffers */
77   } buffers;
78   int nflush;           /* The total number of characters that have been */
79                         /*  flushed from the start of the queue since */
80                         /*  _glq_empty_queue() was last called. */
81   int ntotal;           /* The total number of characters that have been */
82                         /*  appended to the queue since _glq_empty_queue() */
83                         /*  was last called. */
84 };
85 
86 /*.......................................................................
87  * Create a new GlCharQueue object.
88  *
89  * Output:
90  *  return  GlCharQueue *  The new object, or NULL on error.
91  */
92 GlCharQueue *_new_GlCharQueue(void)
93 {
94   GlCharQueue *cq;  /* The object to be returned */
95 /*
96  * Allocate the container.
97  */
98   cq = malloc(sizeof(GlCharQueue));
99   if(!cq) {
100     errno = ENOMEM;
101     return NULL;
102   };
103 /*
104  * Before attempting any operation that might fail, initialize the
105  * container at least up to the point at which it can safely be passed
106  * to del_GlCharQueue().
107  */
108   cq->err = NULL;
109   cq->bufmem = NULL;
110   cq->buffers.head = NULL;
111   cq->buffers.tail = NULL;
112   cq->nflush = cq->ntotal = 0;
113 /*
114  * Allocate a place to record error messages.
115  */
116   cq->err = _new_ErrMsg();
117   if(!cq->err)
118     return _del_GlCharQueue(cq);
119 /*
120  * Allocate the freelist of CqCharBuff structures.
121  */
122   cq->bufmem = _new_FreeList(sizeof(CqCharBuff), 1);
123   if(!cq->bufmem)
124     return _del_GlCharQueue(cq);
125   return cq;
126 }
127 
128 /*.......................................................................
129  * Delete a GlCharQueue object.
130  *
131  * Input:
132  *  cq     GlCharQueue *  The object to be deleted.
133  * Output:
134  *  return GlCharQueue *  The deleted object (always NULL).
135  */
136 GlCharQueue *_del_GlCharQueue(GlCharQueue *cq)
137 {
138   if(cq) {
139     cq->err = _del_ErrMsg(cq->err);
140     cq->bufmem = _del_FreeList(cq->bufmem, 1);
141     free(cq);
142   };
143   return NULL;
144 }
145 
146 /*.......................................................................
147  * Append an array of n characters to a character queue.
148  *
149  * Input:
150  *  cq        GlCharQueue *  The queue to append to.
151  *  chars      const char *  The array of n characters to be appended.
152  *  n                 int    The number of characters in chars[].
153  *  write_fn  GL_WRITE_FN *  The function to call to output characters,
154  *                           or 0 to simply discard the contents of the
155  *                           queue. This will be called whenever the
156  *                           buffer becomes full. If it fails to release
157  *                           any space, the buffer will be extended.
158  *  data             void *  Anonymous data to pass to write_fn().
159  * Output:
160  *  return        int    The number of characters successfully
161  *                       appended. This will only be < n on error.
162  */
163 int _glq_append_chars(GlCharQueue *cq, const char *chars, int n,
164 		      GlWriteFn *write_fn, void *data)
165 {
166   int ndone = 0;  /* The number of characters appended so far */
167 /*
168  * Check the arguments.
169  */
170   if(!cq || !chars) {
171     errno = EINVAL;
172     return 0;
173   };
174 /*
175  * The appended characters may have to be split between multiple
176  * buffers, so loop for each buffer.
177  */
178   while(ndone < n) {
179     int ntodo;     /* The number of characters remaining to be appended */
180     int nleft;     /* The amount of space remaining in cq->buffers.tail */
181     int nnew;      /* The number of characters to append to cq->buffers.tail */
182 /*
183  * Compute the offset at which the next character should be written
184  * into the tail buffer segment.
185  */
186     int boff = cq->ntotal % GL_CQ_SIZE;
187 /*
188  * Since we don't allocate a new buffer until we have at least one
189  * character to write into it, if boff is 0 at this point, it means
190  * that we hit the end of the tail buffer segment on the last append,
191  * so we need to allocate a new one.
192  *
193  * If allocating this new node will require a call to malloc(), as
194  * opposed to using a currently unused node in the freelist, first try
195  * flushing the current contents of the buffer to the terminal. When
196  * write_fn() uses blocking I/O, this stops the buffer size ever getting
197  * bigger than a single buffer node. When it is non-blocking, it helps
198  * to keep the amount of memory, but it isn't gauranteed to do so.
199  */
200     if(boff == 0 && _idle_FreeListNodes(cq->bufmem) == 0) {
201       switch(_glq_flush_queue(cq, write_fn, data)) {
202       case GLQ_FLUSH_DONE:
203 	break;
204       case GLQ_FLUSH_AGAIN:
205 	errno = 0;          /* Don't confuse the caller */
206 	break;
207       default:
208 	return ndone;       /* Error */
209       };
210       boff = cq->ntotal % GL_CQ_SIZE;
211     };
212 /*
213  * Since we don't allocate a new buffer until we have at least one
214  * character to write into it, if boff is 0 at this point, it means
215  * that we hit the end of the tail buffer segment on the last append,
216  * so we need to allocate a new one.
217  */
218     if(boff == 0) {
219 /*
220  * Allocate the new node.
221  */
222       CqCharBuff *node = (CqCharBuff *) _new_FreeListNode(cq->bufmem);
223       if(!node) {
224 	_err_record_msg(cq->err, "Insufficient memory to buffer output.",
225 			END_ERR_MSG);
226 	return ndone;
227       };
228 /*
229  * Initialize the node.
230  */
231       node->next = NULL;
232 /*
233  * Append the new node to the tail of the list.
234  */
235       if(cq->buffers.tail)
236 	cq->buffers.tail->next = node;
237       else
238 	cq->buffers.head = node;
239       cq->buffers.tail = node;
240     };
241 /*
242  * How much room is there for new characters in the current tail node?
243  */
244     nleft = GL_CQ_SIZE - boff;
245 /*
246  * How many characters remain to be appended?
247  */
248     ntodo = n - ndone;
249 /*
250  * How many characters should we append to the current tail node?
251  */
252     nnew = nleft < ntodo ? nleft : ntodo;
253 /*
254  * Append the latest prefix of nnew characters.
255  */
256     memcpy(cq->buffers.tail->bytes + boff, chars + ndone, nnew);
257     cq->ntotal += nnew;
258     ndone += nnew;
259   };
260 /*
261  * Return the count of the number of characters successfully appended.
262  */
263   return ndone;
264 }
265 
266 /*.......................................................................
267  * Discard the contents of a queue of characters.
268  *
269  * Input:
270  *  cq    GlCharQueue *  The queue to clear.
271  */
272 void _glq_empty_queue(GlCharQueue *cq)
273 {
274   if(cq) {
275 /*
276  * Return all list nodes to their respective free-lists.
277  */
278     _rst_FreeList(cq->bufmem);
279 /*
280  * Mark the lists as empty.
281  */
282     cq->buffers.head = cq->buffers.tail = NULL;
283     cq->nflush = cq->ntotal = 0;
284   };
285 }
286 
287 /*.......................................................................
288  * Return a count of the number of characters currently in the queue.
289  *
290  * Input:
291  *  cq    GlCharQueue *  The queue of interest.
292  * Output:
293  *  return        int    The number of characters in the queue.
294  */
295 int _glq_char_count(GlCharQueue *cq)
296 {
297   return (cq && cq->buffers.head) ? (cq->ntotal - cq->nflush) : 0;
298 }
299 
300 /*.......................................................................
301  * Write as many characters as possible from the start of a character
302  * queue via a given output callback function, removing those written
303  * from the queue.
304  *
305  * Input:
306  *  cq        GlCharQueue *  The queue to write characters from.
307  *  write_fn  GL_WRITE_FN *  The function to call to output characters,
308  *                           or 0 to simply discard the contents of the
309  *                           queue.
310  *  data             void *  Anonymous data to pass to write_fn().
311  * Output:
312  *  return   GlFlushState    The status of the flush operation:
313  *                             GLQ_FLUSH_DONE  -  The flush operation
314  *                                                completed successfully.
315  *                             GLQ_FLUSH_AGAIN -  The flush operation
316  *                                                couldn't be completed
317  *                                                on this call. Call this
318  *                                                function again when the
319  *                                                output channel can accept
320  *                                                further output.
321  *                             GLQ_FLUSH_ERROR    Unrecoverable error.
322  */
323 GlqFlushState _glq_flush_queue(GlCharQueue *cq, GlWriteFn *write_fn,
324 			       void *data)
325 {
326 /*
327  * Check the arguments.
328  */
329   if(!cq) {
330     errno = EINVAL;
331     return GLQ_FLUSH_ERROR;
332   };
333 /*
334  * If possible keep writing until all of the chained buffers have been
335  * emptied and removed from the list.
336  */
337   while(cq->buffers.head) {
338 /*
339  * Are we looking at the only node in the list?
340  */
341     int is_tail = cq->buffers.head == cq->buffers.tail;
342 /*
343  * How many characters more than an exact multiple of the buffer-segment
344  * size have been added to the buffer so far?
345  */
346     int nmodulo = cq->ntotal % GL_CQ_SIZE;
347 /*
348  * How many characters of the buffer segment at the head of the list
349  * have been used? Note that this includes any characters that have
350  * already been flushed. Also note that if nmodulo==0, this means that
351  * the tail buffer segment is full. The reason for this is that we
352  * don't allocate new tail buffer segments until there is at least one
353  * character to be added to them.
354  */
355     int nhead = (!is_tail || nmodulo == 0) ? GL_CQ_SIZE : nmodulo;
356 /*
357  * How many characters remain to be flushed from the buffer
358  * at the head of the list?
359  */
360     int nbuff = nhead - (cq->nflush % GL_CQ_SIZE);
361 /*
362  * Attempt to write this number.
363  */
364     int nnew = write_fn(data, cq->buffers.head->bytes +
365 			cq->nflush % GL_CQ_SIZE, nbuff);
366 /*
367  * Was anything written?
368  */
369     if(nnew > 0) {
370 /*
371  * Increment the count of the number of characters that have
372  * been flushed from the head of the queue.
373  */
374       cq->nflush += nnew;
375 /*
376  * If we succeded in writing all of the contents of the current
377  * buffer segment, remove it from the queue.
378  */
379       if(nnew == nbuff) {
380 /*
381  * If we just emptied the last node left in the list, then the queue is
382  * now empty and should be reset.
383  */
384 	if(is_tail) {
385 	  _glq_empty_queue(cq);
386 	} else {
387 /*
388  * Get the node to be removed from the head of the list.
389  */
390 	  CqCharBuff *node = cq->buffers.head;
391 /*
392  * Make the node that follows it the new head of the queue.
393  */
394 	  cq->buffers.head = node->next;
395 /*
396  * Return it to the freelist.
397  */
398 	  node = (CqCharBuff *) _del_FreeListNode(cq->bufmem, node);
399 	};
400       };
401 /*
402  * If the write blocked, request that this function be called again
403  * when space to write next becomes available.
404  */
405     } else if(nnew==0) {
406       return GLQ_FLUSH_AGAIN;
407 /*
408  * I/O error.
409  */
410     } else {
411       _err_record_msg(cq->err, "Error writing to terminal", END_ERR_MSG);
412       return GLQ_FLUSH_ERROR;
413     };
414   };
415 /*
416  * To get here the queue must now be empty.
417  */
418   return GLQ_FLUSH_DONE;
419 }
420 
421 /*.......................................................................
422  * Return extra information (ie. in addition to that provided by errno)
423  * about the last error to occur in any of the public functions of this
424  * module.
425  *
426  * Input:
427  *  cq     GlCharQueue *  The container of the history list.
428  * Output:
429  *  return  const char *  A pointer to the internal buffer in which
430  *                        the error message is temporarily stored.
431  */
432 const char *_glq_last_error(GlCharQueue *cq)
433 {
434   return cq ? _err_get_msg(cq->err) : "NULL GlCharQueue argument";
435 }
436