/* -*- Mode: C -*-
 *
 * $Header: /home/gene/library/website/docsrc/cloop/src/RCS/teq.h,v 395.1 2008/04/20 17:25:50 gene Exp $
 *
 * Copyright (c) 2001 Gene Michael Stover.  All rights reserved.
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as
 * published by the Free Software Foundation; either version 2 of the
 * License, or (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public
 * License along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
 * USA
 */

/*
 * A priority queue of TimeEvent.
 * Has a C interface, but the semantics resemble C++'s
 * std::priority_queue class template.
 */

/*
 * Maximum number of elements we allow in a Time Event Queue.
 * Clients should avoid accessing this because in the future,
 * we might use a dynamically sized queue.
 */
#define TEQ_LEN 100

/*
 */
typedef struct {
  char *tag;
  TimeEvent lst[TEQ_LEN];
  int count;
  unsigned long n;
  Boolean isUnsorted;
} TimeEventQueue;

/*
 * Return a pointer to a dynamically allocated & initialized
 * TimeEventQueue.
 * When you're done with the TEQ, get rid of it with TEQ_Destroy.
 */
C_API TimeEventQueue *TEQ_New ();

/*
 * Initializes the TimeEventQueue in place.
 * When you're done with the queue, get rid of it with
 * TEQ_Uninit.
 */
C_API void TEQ_Init (TimeEventQueue *);

/*
 * Return true if the TimeEventQueue is empty.
 */
C_API int TEQ_IsEmpty (TimeEventQueue *);

/*
 * Return the number of items in the TimeEventQueue.
 */
C_API int TEQ_Count (TimeEventQueue *);

/*
 * Return a pointer to the first item in the queue, if there is
 * one.  Return NULL if there isn't.
 * Assumes the queue is not empty.
 * Before calling this, you should ensure that the queue is not
 * empty by calling TEQ_IsEmpty or TEQ_Count.
 */
C_API TimeEvent *TEQ_Top (TimeEventQueue *);

/*
 * Remove the item from the top of the queue.
 * If the queue is empty, has no effect.  An empty queue is not
 * an error.
 */
C_API void TEQ_Pop (TimeEventQueue *);

/*
 * Add an item to the queue.
 * DELAY is the number of seconds until the even executes.
 * DELAY may be positive, zero, or negative.
 *
 * EXAMPLES of DELAY:
 *
 * DELAY = 3 means 3 seconds in the future.
 *
 * DELAY = 0 means ASAP.
 *
 * DELAY = -3 means 3 seconds ago, which is approximated by
 * ASAP, just like DELAY = 0.
 */
C_API void TEQ_Push (int delay, CLOOP_TimeFnType fn, void *, TimeEventQueue *);

/*
 * Disposes of a TEQ which was initialized with TEQ_Init.
 */
C_API void TEQ_Uninit (TimeEventQueue *);

/*
 * Destroy a TimeEventQueue.  Return NULL as convenience to caller.
 */
C_API TimeEventQueue *TEQ_Destroy (TimeEventQueue *);

/*
 * Print the TEQ to the stream for debugging.
 * Doesn't print it pretty, & doesn't print it in a way that
 * a program could read it later.  It's for debugging.
 */
C_API void TEQ_Dump (TimeEventQueue *teq, FILE *strm);

/* --- end of file --- */