#ifndef _OQ_H_f3145f9a_
#define _OQ_H_f3145f9a_

/* This file is in the public domain. */

/*
 * Code for output queues of data.
 */

/*
 * OQ is the exported type; OQE is an opaque internal type.  Clients
 *  are expected to allocate OQs somehow and then pass them to
 *  oq_init() to initialize them.  While the members of an OQ are
 *  visible, as because they must be for an object of that type to be
 *  declarable, they are not exported interfaces.  Their documentation
 *  here is in the nature of internals documentation which would
 *  normally be in oq.c.
 */
typedef struct oq OQ;
typedef struct oqe OQE;

/*
 * len is the total number of bytes queued.  head is the head of the
 *  queue of OQEs; tail is the tail of the list.
 */
struct oq {
  unsigned int len;
  OQE *head;
  OQE **tail;
  } ;

/*
 * Pass OQ_STRLEN as the length argument to the oq_queue_* functions to
 *  mean "use strlen of the buffer argument".
 *
 * This would be -1 except that that's too likely to occur by accident.
 */
#define OQ_STRLEN (-12345)

/*
 * Initialize an OQ.  This assumes nothing about the object (it will
 *  normally be freshly allocated) and sets it up as empty.  It is the
 *  only supported way to convert a newly allocated OQ into a valid OQ.
 */
extern void oq_init(OQ *);

/*
 * These all queue data to be output.  The differences are in the
 *  details.
 *
 * For the three that take a (sometimes const) void * and an int, you
 *  must pass a buffer pointer and length (though as a convenience the
 *  length may be OQ_STRLEN to make the oq_queue_* function get the
 *  length by calling strlen on the buffer argument for you).
 *
 * oq_queue_point just points to the supplied buffer; the buffer must
 *  remain valid until the data is completely flushed or discarded
 *  (which usually means approximately forever).  THis is appropriate
 *  when the buffer is a string literal, or a text string iwhich lasts
 *  at least as long as the structure containing the OQ, or some such.
 *
 * oq_queue_copy also takes a read-only buffer, but makes a copy of it;
 *  the buffer passed in need not remain valid once oq_queue_copy
 *  returns.  The copy will be freed automatically once it is no longer
 *  needed.
 *
 * oq_queue_free takes a mallocked buffer and adopts it.  It will be
 *  freed by the oq code once it's no longe rneeded; as far as the
 *  caller is concerned, it should usually be considered to go invalid
 *  as soon as the call to oq_queue_free is made.
 *
 * oq_queue_printf takes a printf-style argument list and puts the
 *  output in a mallocked temporary buffer which is queued for output;
 *  this temporary will be freed as soon as it's no longer needed.
 */
extern void oq_queue_point(OQ *, const void *, int);
extern void oq_queue_copy(OQ *, const void *, int);
extern void oq_queue_free(OQ *, void *, int);
extern void oq_queue_printf(OQ *, const char *, ...)
	__attribute__((__format__(__printf__,2,3)));

/*
 * Try to write queued data to the file descriptor passed as the second
 *  argument.  Return value semantics are as for writev: negative on
 *  error or a count of the number of bytes written.
 *
 * This call does not remove anything from the queue under any
 *  circumstances.  See oq_dropdata for that.
 */
extern int oq_writev(OQ *, int);

/*
 * Drop data from the head (oldest) end of the OQ.  The number of bytes
 *  to drop is the second argument.  Return value is nonzero if the
 *  queue is empty after the drop, zero if not.
 */
extern int oq_dropdata(OQ *, int);

/*
 * Return the number of bytes queued in an OQ.
 */
extern unsigned int oq_qlen(OQ *);

/*
 * Return true if the OQ is empty, false if not.  This is semantically
 *  equivalent to oq_qlen(·)==0.
 */
extern int oq_empty(OQ *);

/*
 * Return true if the OQ is nonempty, false if not.  This is
 *  semantically equivalent to oq_qlen(·)!=0.
 */
extern int oq_nonempty(OQ *);

/*
 * Throw away everything in the OQ.  This is suitable for use on, for
 *  example, a write error, before discarding the whole data structure.
 */
extern void oq_flush(OQ *);

#endif