OSC-priority-queue.h

Go to the documentation of this file.
00001 /*
00002 Copyright  1998. The Regents of the University of California (Regents). 
00003 All Rights Reserved.
00004 
00005 Written by Matt Wright, The Center for New Music and Audio Technologies,
00006 University of California, Berkeley.
00007 
00008 Permission to use, copy, modify, distribute, and distribute modified versions
00009 of this software and its documentation without fee and without a signed
00010 licensing agreement, is hereby granted, provided that the above copyright
00011 notice, this paragraph and the following two paragraphs appear in all copies,
00012 modifications, and distributions.
00013 
00014 IN NO EVENT SHALL REGENTS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT,
00015 SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST PROFITS, ARISING
00016 OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF REGENTS HAS
00017 BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00018 
00019 REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
00020 THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
00021 PURPOSE. THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED
00022 HEREUNDER IS PROVIDED "AS IS". REGENTS HAS NO OBLIGATION TO PROVIDE
00023 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
00024 
00025 The OpenSound Control WWW page is 
00026     http://www.cnmat.berkeley.edu/OpenSoundControl
00027 */
00028 
00029 
00030 /* OSC-priority-queue.h
00031    Interface to priority queue used by OSC time tag scheduler
00032 
00033    Matt Wright, 3/13/98
00034 
00035 */
00036 
00037 /* include OSC-timetag.h before this file. */
00038 
00039 /* This queue manages pointers to data objects.  It doesn't care what's in the
00040    objects except that the first element has to be an OSCTimeTag.  So whatever
00041    data you want to store, cast your pointer to it to a pointer to this type. */
00042  
00043 typedef struct {
00044     OSCTimeTag timetag;
00045     /* There will be other stuff... */
00046 } *OSCSchedulableObject;
00047 
00048 typedef struct OSCQueueStruct *OSCQueue;
00049 
00050 /* Make a new queue, or return 0 for failure. */
00051 OSCQueue OSCNewQueue(int maxItems, void *(*InitTimeMalloc)(int numBytes));
00052 
00053 /* Put something into the queue.  Return FALSE if quque is full. */
00054 Boolean OSCQueueInsert(OSCQueue q, OSCSchedulableObject o);
00055 
00056 /* What's the time tag of the earliest item in the queue? 
00057    Return OSCTT_BiggestPossibleTimeTag() if queue is empty. */
00058 OSCTimeTag OSCQueueEarliestTimeTag(OSCQueue q);
00059 
00060 /* Remove the item from the front of the queue.  Fatal error
00061    if the queue is empty.  */
00062 OSCSchedulableObject OSCQueueRemoveEarliest(OSCQueue q);
00063 
00064 Boolean OSCQueueIsEmpty(OSCQueue q);
00065 
00066 /* Interface for examining items currently stored on the queue:  
00067 
00068    - To start, call OSCQueueScanStart().
00069 
00070    - Then each subsequent call to OSCQueueScanNext() returns a pointer to an
00071      OSCSchedulableObject that is stored on the queue, until
00072      OSCQueueScanNext() returns 0 to indicate that all objects on the queue
00073      have been scanned.
00074 
00075    The objects returned by OSCQueueScanNext() come in chronological order (or
00076    approximately chronological order, depending on the underlying queue data
00077    structure).
00078 
00079    If you call OSCQueueRemoveCurrentScanItem(), the object most recently
00080    returned by OSCQueueScanNext() will be removed from the queue.
00081 
00082    If there are any insertions or deletions to the queue, the sequence of
00083    scanned objects must still include every object in the queue.  This may
00084    cause a particular object to be returned more than once by
00085    OSCQueueScanNext().
00086 */
00087    
00088 
00089 void OSCQueueScanStart(OSCQueue q);
00090 OSCSchedulableObject OSCQueueScanNext(OSCQueue q);
00091 void OSCQueueRemoveCurrentScanItem(OSCQueue q);

Generated on Thu Sep 17 23:14:15 2009 for CSL by  doxygen 1.5.8